Differences

This shows you the differences between two versions of the page.

--- fortigate_-_entra_id_saml_sso [2025/12/12 21:25] – created oso
+++ fortigate_-_entra_id_saml_sso [2025/12/13 00:22] (current) – [SAML Claim Mapping (Azure → FortiGate)] oso
@@ Line 1: / Line 1: @@
 ====== Prerequisites ======
-  * Required subscriptions (FortiGate SSL VPN, Entra ID tenant)
+  * Required services: FortiGate with SSL VPN enabled, Microsoft Entra ID tenant
-  * Certificates and basic setup
+  * A valid public FQDN (sub.domain.tld) for the FortiGate SSL VPN certificate
+  * A working certificate on the FortiGate (Let’s Encrypt, public CA, etc.)
 ====== Add FortiGate SSL VPN in Entra ID ======
-  * Enterprise Applications → Add from Gallery → Select FortiGate SSL VPN
+  * Enterprise Applications → Add from Gallery → Select **FortiGate SSL VPN**
 ====== Configure Basic SAML Settings in Entra ID ======
   * Identifier (Entity ID)
-  * Reply URL
+  * Reply URL (ACS)
   * Sign-on URL
   * Logout URL
-  * Attribute & Claim mappings
+  * Attribute & Claim mappings (username, group)
-  * Download SAML Signing Certificate
+  * Download the **SAML Base64 Signing Certificate**
+===== SAML Claim Mapping (Azure → FortiGate) =====
+FortiGate is strict about SAML attribute names.
+The attributes defined in Azure **must match exactly** the attributes that FortiGate expects under:
+<code>
+set user-name
+set group-name
+</code>
+=== Required Claims in Entra ID ===
+Under **Single Sign-On → User Attributes & Claims**:
+**Add this claim** (FortiGate requires the literal name)
+  * Claim name: ''username'', source: ''user.userprincipalname''
+**Edit the existing “groups” claim** so that it sends **Group Object IDs** (not display names).
+  * The expected claim name must be ''group''
+{{:2024-01-15_14_16_40.png?nolink|}}
+This ensures that the SAML token contains:
+<code>
+username = user@domain
+group    = <Azure AD Group Object ID>
+</code>
+=== Why this matters ===
+FortiGate matches SAML attributes using the `user-name` and `group-name` fields in the IdP configuration:
+<code>
+set user-name "username"
+set group-name "group"
+</code>
+If the Azure claim sends the wrong attribute or the Object ID doesn't match exactly, FortiGate will not associate the session with the group, and the VPN connection will be denied.
+https://learn.microsoft.com/en-us/entra/identity/saas-apps/fortigate-ssl-vpn-tutorial
 ====== Create Test User and Security Group in Entra ID ======
-  * New user creation
+  * Create test user
-  * Assign user to FortiGate SSL VPN app
+  * Assign user to the FortiGate SSL VPN enterprise app
-  * Create Security Group (e.g., FortiGateAccess)
+  * Create Security Group (e.g., *FortiGateAccess*)
-  * Note Object ID
+  * Copy the **Object ID** (used later in FortiGate group matching)
 ====== Upload Certificate to FortiGate ======
-  * Import Base64 certificate into FortiGate
+  * Import the SAML IdP certificate into FortiGate
-  * Rename certificate if needed
+  * Rename the certificate if needed for clarity
 ====== Configure FortiGate SAML Settings (CLI) ======
-  * Define SAML IdP (`config user saml`)
+  * Define the SAML IdP (`config user saml`)
-  * Map entity-id, single-sign-on-url, logout-url, IdP URLs, certificate, attributes
+  * Configure entity-id, SSO URLs, IdP URLs, certificate, and attribute mapping
+<code>
+config user saml
+  edit azure
+    set cert "<FortiGate VPN Server Certificate Name>"
+    set entity-id "https://vpn.my.org:10443/remote/saml/metadata"
+    set single-sign-on-url "https://vpn.my.org:10443/remote/saml/login"
+    set single-logout-url "https://vpn.my.org:10443/remote/saml/logout"
+    set idp-entity-id <Azure AD Identifier>
+    set idp-single-sign-on-url <Azure Login URL>
+    set idp-single-logout-url <Azure Logout URL>
+    set idp-cert <Azure SAML Base64 Certificate Name>
+    set user-name username
+    set group-name group
+  next
+end
+</code>
 ====== Configure FortiGate User Group ======
-  * Create group (`config user group`)
+  * Create a user group mapped to Azure SAML IdP
-  * Match against Azure Security Group Object ID
+  * Match against the Azure AD Security Group **Object ID**
+<code>
+config user group
+  edit AAD-FortiVPN
+    set member azure
+    config match
+      edit 1
+        set server-name azure
+        set group-name 343744cd---GROUP-ID---67bb7e68
+      next
+    end
+  next
+end
+</code>
 ====== Configure SSL VPN Portals and Firewall Policy ======
-  * Create VPN portal(s)
+  * Create SSL VPN portal(s)
-  * Apply firewall rules for SAML group
+  * Assign the portal to the SAML group
+  * Add firewall policies allowing access from the SAML user group
 ====== Optional: Multiple SSL VPN Realms ======
-  * Enable SSL-VPN Realms feature
+  * Enable the **SSL-VPN Realms** feature
-  * Create multiple realms (e.g., FullTunnel, SplitTunnel)
+  * Create multiple realms (e.g., *FullTunnel*, *SplitTunnel*)
-  * Configure portals and policies per realm
+  * Assign specific portals and firewall policies per realm
 ====== FortiClient Setup (Optional) ======
-  * Configure FortiClient for SSL VPN with SAML SSO
+  * Configure FortiClient for SSL VPN using SAML SSO
+  * Ensure FQDN and port match the FortiGate SAML configuration
 ====== Testing and Validation ======
-  * Test SSO via Azure “Test” button
+  * Use Azure → “Test” SSO functionality
-  * Direct login to FortiGate VPN portal
+  * Direct login to FortiGate VPN portal Web UI
-  * Use My Apps tile
+  * Launch from MyApps portal tile
-  * Debugging commands (`diagnose debug application samld`)
+  * Use FortiGate debugging commands:
+<code>
+diagnose debug application sslvpn -1
+diagnose debug application samld -1
+diagnose debug console timestamp enable
+diagnose debug enable
+</code>
+To stop debugging:
+<code>
+diagnose debug reset
+diagnose debug disable
+</code>
+FortiClient connection stages:
+  * **20%** – TCP connection
+  * **40%** – SAML authentication
+  * **80%** – Tunnel negotiation
+  * **100%** – Connected
+For example, if it fails at **40%**, SAML assertion is not validated.
 ====== Troubleshooting Notes ======
-  * Certificate re-download after FQDN changes
+  * Re-download metadata/cert when FQDN or port changes
-  * Signature verification requirements in FortiOS 7.2.12 / 7.4.9 / 7.6.4
+  * Signature validation requirements changed in FortiOS 7.2.12 / 7.4.9 / 7.6.4
-  * Common errors (e.g., “Signature element not found”)
+  * Common errors (e.g., *"Signature element not found"* from FortiGate)
+  * Adjust group claim: ensure the Azure AD group appears in the SAML assertion
+====== References ======
+  * https://learn.microsoft.com/en-us/entra/identity/saas-apps/fortigate-ssl-vpn-tutorial
+  * https://community.fortinet.com/t5/FortiGate/Troubleshooting-Tip-400-Bad-Request-error-when-trying-to-connect/ta-p/365087
+  * https://community.fortinet.com/t5/FortiGate/Technical-Tip-Create-SSL-VPN-with-Azure-SAML-SSO-Authentication/ta-p/200812
+  * https://www.youtube.com/watch?v=nDH2wvveLrI