Technical Tip: Configuring SAML SSO login for FortiGate administrators with Entra ID acting as SAML IdP

[kiri]

Description

This article describes how to configure administrator login to FortiGate using the SAML standard for authentication and authorization.
SAML has been introduced as a new administrator authentication method in FortiOS 6.2. A FortiGate can act as an Identity Provider (IdP) for other FortiGates, or as a Service Provider (SP), utilizing other IdP.
This article provides an example for basic integration with Microsoft Entra ID (formerly known as Azure Active Directory (AD)) acting as the IdP.

Scope

FortiGate.

Solution

Below is a list of terms used in FortiGate GUI, and their equivalents in Azure, and the required SAML attributes:

FortiGate GUI	Azure
IdP entity ID	Entra ID Identifier
IdP single sign-on URL	Login URL
IdP single logout URL	Logout URL
SP entity ID	Identifier (Entity ID)
SP ACS (login) URL	Reply URL (Assertion Consumer Service URL)
SP SLS (logout) URL	Logout URL
SP portal URL	Sign on URL

The only mandatory attribute required to be sent in the SAML response is 'username', which is interpreted as the administrator’s username/account name.

STEP-BY-STEP GUIDE:

1. Create a new Enterprise application in Entra ID. Go to MicrosoftEntra ID -> Enterprise applications -> Create New Application -> FortiGate SSL VPN > Name -> Create.
   

2. In the newly created application, select Set up a single sign-on, and select SAML.

3. Start with sections #3 and #4. In section #3, download the certificate. In section #4 copy all three values (they will be used in step 5). Keep this page open, it is needed at a later step to finish the configuration.

4. Switch to the FortiGate. The first step is to import the Entra ID SAML certificate from the previous step.

• In GUI: System -> Certificates -> Import -> Remote Certificate.
• In CLI:

config vpn certificate remote

Optional:

The default name for an imported remote certificate is 'REMOTE_Cert_<number>'. To make it easier to distinguish from other certificates, it can be renamed in CLI.

Example: rename REMOTE_Cert_1 to Azure_SAML:

config vpn certificate remote
rename REMOTE_Cert_1 to Azure_SAML
end

5. FortiGate SAML configuration.
   

• GUI in version 6.2: Go to User & Device -> SAML SSO.
  
• GUI in version 6.2.3 and above. Go to Security Fabric -> Settings. Enable FortiGate Telemetry, choose a Fabric name and an IP for FortiAnalyzer (can be an unused address). Enable SAML Single Sign-On, and select Advanced Options.
  
• GUI in version 6.4 and above.
  Go to Security Fabric -> Fabric Connectors -> Security Fabric Setup -> Single Sign-On Settings.
• CLI:  

config system saml

Mode:

Service Provider (SP).
SP address: This is the address that will be used to process the SAML login and as the SAML SP identity. FQDN or an IP address can be used.

Since the redirects during the SAML authentication flow will go through this address, make sure that the administrators attempting log in are able to reach this address.

SP certificate:

Leave disabled. Azure does not check this.
Default login page: 'Normal' presents the standard login screen with an option to continue by SAML. 'Single Sign-On' automatically redirects all GUI logins to SAML. Recommended to leave it at 'Normal' at least for initial configuration and testing.

Default admin profile:

This option controls which admin profile is assigned to newly created SAML SSO administrators.

There is a special virtual profile available for a selection called 'admin_no_access'. This profile blocks access to the FortiGate GUI until a different administrator assigns a real profile to this administrator (useful for first-time logins, decide for the first time what profile to assign to a new administrator before allowing them in).

IdP settings.
IdP type: Custom.
IdP certificate: Select the certificate imported in step 4.
The last three options should be filled with values saved in step 3.
IdP entity ID: Entra ID Identifier.
IdP single sign-on URL: Login URL.
Idp single logout URL: Logout URL.

 

6. Select Apply to save the change.

Now expand the [+] SP details section to display the SP values that will be configured in Entra ID in the next step. These values contain the SP address set above, but they are only updated once select Apply to save the changes.

7. Go back to the SAML-based sign-on section in Azure.
   

Edit section #1 Basic SAML configuration.

Fill out the fields with the values from FortiGate SP in step 6 as follows:

Identifier (Entity ID): SP entity ID.
Reply URL (Assertion Consumer Service URL): SP ACS (login) URL.
Sign on URL: SP portal URL.
Relay State: leave blank.
Logout URL: SP SLS (logout) URL.
Close this panel by selecting Save.

8. Edit attributes sent by AzureFortiGate expect to receive the username of the administrator in the 'username' attribute. Entra ID does not send an attribute with this name by default.
   

Still in the Single Sign-on with SAML menu in Azure, edit section #2 (User Attributes & Claims) and add a new claim:
Name: username.
Namespace: leave blank.
Source: Attribute.
Source attribute: user.userprincipalname (The value of this attribute has to match the username the administrator will be using to log in).

Select the Save button to add this new claim.
The other unused claims can be deleted.
Select the close button in the top right to return.

9. Access authorization

Several options control access to a SAML SP (FortiGate) on the Azure side.

Switch to the Properties section of the SAML application in Azure.'

'Enabled for users so sign-in': When set to 'No', access is completely disabled for everyone.
'User assignment required': When set to 'Yes', only users/groups configured in the section 'Users and groups' are allowed access. When set to 'No', any valid user from this directory is allowed to use this SAML SP and authenticate to FortiGate admin GUI.

10. Right now, there is no any options to configure SAML SSO-admin authentication per VDOM based. As a workaround these steps could be performed (if it fits):
    1. If possible, set FortiGate's SSO URL to a FQDN and use DNS to point to different vdom's IP to make some user hit the FortiGate with different IP using same FQDN.
    2. Add vdom to user's VDOM list, (not ideal if permission is a problem).
    3. Change SSO URL to the VDOM's IP that's needed.  Refer to this article how to resovle two different IPs per FQDN.
    
11. If there is a requirement to bind admin users to the Entra ID accounts, and provide access to the specific VDOM, then these follow these steps:
    1. There should be Windows NPS Server acting as Radius Server.
    2. FortiGate configured as a radius client, and with remote admin wildcard groups.

TROUBLESHOOTING

Useful debug commands - httpsd (general admin GUI debugging), samld (SAML-specific debugs).

Usage:

Step 1:

diagnose debug application httpsd -1

diagnose debug application samld -1

diagnose debug console timestamp enable

diagnose debug enable

In the case of SSL VPN above debug would include the application SSL VPN.
Run tests now. When done, stop debugs and reset them with:

Step 2:

diagnose debug disable
diagnose debug reset

The SAML request message sent from the FortiGate SP to the Azure IdP is visible in the '**** Auth Req URL ****' section:

2019-08-14 10:04:49 [httpsd 8170 - 1565769889     info] ap_invoke_handler[569] -- new request (handler='saml-sp-login-handler', uri='/saml/login/', method='GET')

2019-08-14 10:04:49 [httpsd 8170 - 1565769889     info] ap_invoke_handler[573] -- User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36

2019-08-14 10:04:49 [httpsd 8170 - 1565769889     info] ap_invoke_handler[576] -- Source: 10.5.63.254:58486 Destination: 10.5.60.60:443

__update_sp_sig_opt [251]: SP no sig is required.

__samld_sp_create_auth_req [381]:

**** Auth Req URL ****

https://login.microsoftonline.com/<tenant-ID>/saml2?SAMLRequest=<-###SAML-REQUEST-HERE-###>&RelayState=%2Fng

***********************

The SAMLRequest value contains the URL-encoded version of the request. If it is decoded, it will give the base64 encoded version of the request message, which can be further decoded and inflated to show the actual XML content of the request message.

Similarly, the IdP response forwarded from the IdP back to the FortiGate SP is visible in the following section:

2019-08-14 10:05:06 [httpsd 8170 - 1565769906     info] ap_invoke_handler[569] -- new request (handler='saml-sp-handler', uri='/saml/', method='POST')
2019-08-14 10:05:06 [httpsd 8170 - 1565769906     info] ap_invoke_handler[573] -- User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36
2019-08-14 10:05:06 [httpsd 8170 - 1565769906     info] ap_invoke_handler[576] -- Source: 10.5.63.254:58504 Destination: 10.5.60.60:443
__samld_sp_login_resp [723]:
Message Body
<###-base64-encoded-message-###>  <--

This can also be base64-decoded and inflated to get the XML content of the SAML response.

Error examples and possible remedies (non-exhaustive)

1. ERROR: 'username is missing in SAML assertion attributes.':

FIX: SAML assertion attributes are misconfigured and do not contain the 'username' attribute/claim. Refer to step 8 on how to add this in Entra ID.

2.  

FIX: The user was not given access to the FortiGate SAML SP in Azure. Refer to step 9 to properly set up authorization for the user in Azure.

3. ERROR: 'AADSTS700016: Application with identifier '<SP-entity-ID>' was not found in the directory <tenant-ID'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. The authentication request might have been sent to the wrong tenant.'.

FIX: Verify what the currently configured SP entity ID is on the FortiGate, and then make sure the exact same value is set in Azure (step 7).

4. ERROR: After authentication succeeds with Azure IdP, the FortiGate page does not load, or 'Error' is shown by FortiGate.
   FIX: This may be a misconfigured Reply URL (Assertion Consumer Service URL) in Azure. Make sure this value matches the SP ACS (login) URL from FortiGate (step 7).
   
   
   
5. ERROR: 'Response validation failed. SAML Response rejected.'.

FIX 5.1: This may be caused by selecting an incorrect IdP certificate in the FortiGate configuration. Make sure it matches the certificate used by Azure (steps 3,4,7).
FIX 5.2: This may also be due to an incorrect IdP entity ID in the FortiGate configuration. Make sure this matches the Entra ID Identifier (steps 3,5).

FIX 5.3: This may be also if the time in Fortigate and Azure is not in synced, which will cause to authentication fail with below error seen in saml debug:

__samld_sp_login_resp [843]: Clock skew tolerance: 0 
__samld_sp_login_resp [848]: Clock skew issue. <----
samld_send_common_reply [91]: Code: 5, id: 1, pid: 24566, len: 53, data_len 37
samld_send_common_reply [99]: Attr: 22, 12,
samld_send_common_reply [99]: Attr: 23, 25, Undefined error.
2024-10-21 16:26:11 [httpsd 24566 - 1729520771 error] saml_sp_acs_handler[823] -- Error in SP ACS handler. Response validation failed
. SAML Response rejected.

Make sure that time is in sync between FortiGate and Azure side.

6. ERROR: 'AADSTS90002: Tenant '<tenant-ID>' not found. This may happen if there are no active subscriptions for the tenant. Check with subscription administrator.'.

FIX: The tenant ID included in the IdP single sign-on URL configured on FortiGate is not correct. Make sure this value matches the Login URL from Azure (steps 3,5).

7. ERROR : 'No group info in SAML response' or 'No user name info in SAML response'.

The logs from the debug by following the troubleshooting 'step 1' and 'step 2' will show output similar to the following:

2024-12-04 13:24:10 [xxx]fsv_saml_login_response:697 No user name info in SAML response. Please check saml configuration.
2024-12-04 13:24:10 [xxxx]fsv_saml_login_resp_cb:225 SAML response error: 4.

Ensure step 8 is configured correctly. See Microsoft documentation on how to add claims  

8. ERROR: Unable to log into FortiGate GUI because SAML SSO is the default login, and it is not functional.

FIX: If SAML login is the default method and fails before a user is redirected back to the FortiGate, an administrator may not be given a chance to perform a standard local logon.

To get around this, log in by manually opening the SP ACS (login) URL ( https://<fortigate>/saml/?acs ). Ignore the error displayed and proceed with 'select here to login locally'. Afterward, the default login page can be switched to 'Normal' in GUI.

It is possible to make this change directly from SSH:

config system saml

    set default-login-page normal
end

9. Error Invalid HTTP request

An invalid HTTP request error occurs when a misconfiguration or typo error occurs in the login or logout URL. Double-check the step-7 configuration and make sure the URLs match exactly on both sides. A sample configuration from the CLI looks like the below config user saml.

   edit "ssl-azure-saml"
       set entity-id "https://<test-domain>:65443/remote/saml/metadata"
       set single-sign-on-url "https://<test-domain>:65443/remote/saml/login"
       set single-logout-url "https://<test-domain>:65443/remote/logout"

Related documents:
SAML overview and configuration (in the context of authentication between FortiGates in Security Fabric) version 6.2: Cookbook SAML.
SAML overview and configuration (in the context of authentication between FortiGates in Security Fabric) version 6.2.3: Configuring the Security Fabric with SAML.
SAML overview and configuration (in the context of authentication between FortiGates in Security Fabric) version 6.4.2: Configuring the Security Fabric with SAML.

SAML overview and configuration (in the context of authentication between FortiGates in Security Fabric) version 7.0.2: Configuring single-sign-on in the Security Fabric.

SAML overview and configuration (in the context of authentication between FortiGates in Security Fabric) version 7.2.2: Configuring single-sign-on in the Security Fabric.

SAML overview and configuration (in the context of authentication between FortiGates in Security Fabric) version 7.4.1: Configuring single-sign-on in the Security Fabric.

Microsoft documentation for setting up SAML non-gallery application: Quickstart: View enterprise applications.
SAML chrome panel
SAML Message Decoder
SAML-tracer
SAML Message Decoder