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

kiri · ‎08-16-2019

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.

Useful links.

Fortinet Documentation.

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.

External.
Microsoft documentation for setting up SAML non-gallery application: Quickstart: View enterprise applications.

Useful browser plugins for analyzing SAML communication:

Google Chrome.
SAML chrome panel
SAML Message Decoder

Mozilla Firefox.
SAML-tracer
SAML Message Decoder

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

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

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

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.

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

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.

Important Note: 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.

Note: 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.

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.

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.

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.

Access authorization

There are several options that 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.

Assigning admin profiles to SAML SSO administrators.

Admin accounts can be manually created in GUI:

Go to System -> Administrators -> Create new -> SSO Admin.
It is possible to set the username, and admin profile to be assigned and allowed VDOMs if VDOMs are enabled on the unit.

CLI configuration example:

config system sso-admin
edit 'username@domain.com'
set accprofile '<admin_profile_name>'
set vdom '<VDOM-name>'
end

If a matching administrator account does not exist on the FortiGate yet, it will be automatically created and assigned the default admin access profile as set in the SAML SSO configuration above (step 5).

Troubleshooting.

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

Usage:

diagnose debug application httpsd -1

diagnose debug application samld -1

diagnose debug console timestamp enable (optionally).

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:

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).

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.

ERROR: 'AADSTS50105: The signed in user '<username>' is not assigned to a role for the application <application-ID>'(fortigate-saml-sso).'.

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.

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).

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).

ERROR: 'Response validation failed. SAML Response rejected.'.

Fix 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 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).

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).

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

From version 6.2.2 and above, refer to the link in the description.