SAML v2
Overview
SAML is an XML based authentication protocol developed and released in 2005. While OpenID Connect is the newest single sign-on solution, many backends and applications still rely solely on SAML. FusionAuth provides both a SAML identity provider interface as well as a SAML service provider interface. If you are unfamiliar with these SAML terms, they are defined as follows:
- Identity provider - the entity that is performing the authentication of a user. Essentially, this is the thing that is providing the login page. Also known as an IdP.
- Service provider - the entity that needs a user to login with an identity provider in order to provide some service. Essentially, this is the app the user wants to use. Also known as an SP.
As a concrete example, you might have an app called Payroll Zen
that manages your company’s payroll. This app requires that employees who have access to use it log in using the credentials stored in your company’s Active Directory. Payroll Zen
is therefore the service provider and Active Directory is the identity provider.
This document covers configuration for FusionAuth’s SAML v2 identity provider, where FusionAuth is the system of record for users, and other applications federate with FusionAuth.
If, on the other hand, you are looking for instructions on setting up FusionAuth as a SAML v2 service provider (i.e. you want to allow users to log into either FusionAuth’s UI or your applications via a third party SAML v2 identity provider), consult the SAML v2 Identity Provider documentation.
A bit confusing, we know. But in FusionAuth, Identity Providers are third party sources of record for user data.
FusionAuth’s SAML identity provider uses the OAuth workflow under the hoods. When a service provider starts a SAML workflow by sending a SAML request to FusionAuth, FusionAuth will forward the browser to the hosted login pages. This is an important concept if you are interested in using FusionAuth’s themes to customize the look and feel of your SAML identity provider user interface.
Single Sign-on and Logout
SAML is widely used to offer Single Sign-on across applications. When enabled, a user can sign in to an IdP such as FusionAuth, and then other correctly configured applications will not require authentication from that same user.
SAML also offers Single Logout, which is the inverse of Single Sign-on. With Single Logout, a user logs out of the IdP and all other applications are notified of the logout and should end the user’s session.
Configure FusionAuth as a SAML Identity Provider
In order to configure FusionAuth to act as a SAML identity provider, you need to enable and configure SAML for an Application. When properly configured, FusionAuth, the IdP, will consume Authentication requests from an application, the SP, and, after a user logs in, return proper Authentication responses.
Navigate to Applications -> Your application -> SAML to configure this functionality. In the screenshot below, you can see that we are configuring SAML for the Pied Piper application:
Form Fields
Issuer
requiredThis is the issuer string that the service provider will send in the SAML request to FusionAuth. FusionAuth uses this issuer value to look up this FusionAuth application in order to start the SAML login process.
The issuer string is used by service providers (e.g. Google, Zendesk, etc.) to identify themselves to FusionAuth’s SAML identity provider. Often you cannot set this to a custom value in the service provider and need to read their documentation or test the integration and use the error messages to determine the correct value.
Audience
Some service providers, such as Zendesk, require a different audience in the SAML response than the Issuer set above. If you are configuring a service provider that requires a different audience, enter the audience name, otherwise leave it blank.
If this isn’t specified, FusionAuth will set the audience to the same value as the Issuer .
Authorized redirect URLs
requiredOne or more URLs that FusionAuth may redirect to after the user has successfully logged in.
This is also known as the Assertion Consumer Service URL or ACS.
Logout URL
The URL used to perform the 302
redirect as the response from the /samlv2/logout
endpoint. If this value is omitted, the tenant configured logout URL will be used. See the Logout URL under the Tenant -> Your Tenant -> OAuth tab.
Usually this is the starting location of the application.
Debug enabled
Many service providers are not compliant with the SAML and XML signing specifications. This makes it challenging to get them working with FusionAuth.
If you are running into integration issues, toggle this setting on and FusionAuth will output debugging information into the Event Log during a SAML login. You can find the event log in System -> Event Log.
Authentication Request
Settings in this section configure SAML request handling.
Form Fields
Require signature
Enable to require the SAML v2 Service Provider to sign the SAML v2 authentication request. When this is enabled, if a signature is omitted the request will be rejected.
Default verification key
requiredThe default key used to verify the signature if the public key cannot be determined by the KeyInfo element when using POST bindings, or the key used to verify the signature when using HTTP Redirect bindings.
If a Require signature is not enabled, this field is optional.
Authentication Response
Settings in this section configure how FusionAuth processes the SAML response.
Form Fields
Signing key
requiredIn order to properly sign the SAML responses, FusionAuth requires a key pair from Key Master. You can either select an existing key here or select the first option to have FusionAuth generate a key pair to use. If no choice is selected, a new key will be automatically created and assigned.
To add, manage or import your key, navigate to Settings -> Key Master.
Signature canonicalization method
This sets the XML signature canonicalization method that FusionAuth will use when signing the SAML response. This method is also used when FusionAuth creates a message digest in the SAML response.
This option is usually the first thing to change if a service provider is rejecting the SAML response from FusionAuth. Many service providers are not compliant with the full XML signature specification and require a fixed canonicalization method. Your best bet is to try all four values until a login succeeds.
Signature location
Some service providers may require the signature in a specific location. When Assertion
is selected the signature element will be a child of the assertion. When Response
is selected the signature will be placed at the top level of the response.
Response populate lambda
This specifies a lambda that FusionAuth will invoke prior to sending the SAML response to the service provider. This allows you to write a lambda to populate additional information into the SAML response. In most cases, your lambda will add an Attribute
, or more than one,
to the response.
The complete documentation for this lambda can be found on the SAML v2 response populate lambda documentation page.
Logout Request
Settings in this section configure SAML Logout handling. They define how FusionAuth will handle incoming logout requests from a service provider. When Single Logout is enabled, additional settings are available that will be used sign the Logout Request sent to session participants.
Form Fields
Require signature
Enable to require the SAML v2 Service Provider to sign the SAML v2 Logout request. When this is enabled, if a signature is omitted the request will be rejected.
Default verification key
requiredThe default key used to verify the signature if the public key cannot be determined by the KeyInfo element when using POST bindings, or the key used to verify the signature when using HTTP Redirect bindings.
If a Require signature is not enabled, this field is optional.
Logout behavior
When set to All session participants
, each session participant that has Enable single logout set to true will be sent a Logout Request.
When set to Only Originator
, no other session participants will be notified when a logout request is sent for this application.
This configuration is functionally equivalent to the Logout Behavior found in the OAuth2 configuration.
Enable single logout
Enable Single Logout behavior. When enabled, this application will receive LogoutRequests from any other application in this tenant receives one.
Logout URL
requiredThe URL which you want to receive the LogoutRequest from FusionAuth.
If Enable single logout is not enabled, this field is optional.
Signing key
requiredIn order to properly sign the SAML Single Logout responses, FusionAuth requires a key pair from Key Master. You can either select an existing key here or select the first option to have FusionAuth use the authentication response signing key.
To add, manage or import your key, navigate to Settings -> Key Master.
Signature canonicalization method
This sets the XML signature canonicalization method that FusionAuth will use when signing the SAML Single Logout response.
This option is usually the first thing to change if a service provider is rejecting the SAML Single Logout response from FusionAuth. Many service providers are not compliant with the full XML signature specification and require a fixed canonicalization method. Your best bet is to try all four values until a logout succeeds.
Logout Response
Settings in this section configure how FusionAuth processes the SAML Logout response.
Form Fields
Signing key
requiredIn order to properly sign the SAML Logout responses, FusionAuth requires a key pair from Key Master. You can either select an existing key here or select the first option to have FusionAuth use the authentication response signing key.
To add, manage or import your key, navigate to Settings -> Key Master.
Signature canonicalization method
This sets the XML signature canonicalization method that FusionAuth will use when signing the SAML Logout response.
This option is usually the first thing to change if a service provider is rejecting the SAML Logout response from FusionAuth. Many service providers are not compliant with the full XML signature specification and require a fixed canonicalization method. Your best bet is to try all four values until a logout succeeds.
Assertion Encryption
Settings in this section configure how FusionAuth encrypts the SAML Assertion response.
Form Fields
Enabled
When enabled, assertions in SAML responses will be encrypted.
Encryption algorithm
The symmetric key encryption algorithm used to encrypt the SAML assertion.
Key location
The location that the encrypted symmetric key information will be placed in the SAML response in relation to the EncryptedData
element containing the encrypted assertion value.
Key transport algorithm
The encryption algorithm used to encrypt the symmetric key for transport in the SAML response.
Digest algorithm
The message digest algorithm to use when encrypting the symmetric key for transport.
Mask generation function
The mask generation function and hash function to use for the Optimal Asymmetric Encryption Padding when encrypting a symmetric key for transport. This configuration is only available when Key transport algorithm is set to RSA OAEP with MGF1
.
Key transport encryption certificate
The RSA certificate from Key Master that will be used to encrypt the SAML assertion encryption symmetric key for transport.
This field is required when SAML assertion encryption is enabled.
Endpoints
Once you have configured the SAML identity provider for an application, you will need to copy and paste a number of URLs to the service provider or send the metadata XML file to the service provider. The URLs for all of these items can be found by clicking on the view icon from the application list page.
Once you click the view icon, the dialog will pop up. Under the heading SAML v2 Integration details, you will see all of the SAML endpoint URLs that the service provider will need. These include the login URL, logout URL and metadata URL. If the service provider needs a metadata XML file, you can copy and paste the metadata URL from this dialog into a new browser tab and then save the contents of that webpage into a new file named metadata.xml
. Some browsers will force the name of the file to be metadata.xhtml
and you will have to rename it before sending it to the service provider.
Here is what the view dialog looks like and the SAML information you will need:
Attributes
FusionAuth provides a number of attributes as part of its SAML response. These attributes include standard ones from specifications and others that are more industry de facto standards because many service providers require them. Here’s the list of the attributes FusionAuth returns and the property of the user object they are pulled from:
id
pulled fromuser.id
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth
pulled fromuser.birthDate
birth_date
pulled fromuser.birthDate
date_of_birth
pulled fromuser.birthDate
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
pulled fromuser.email
email
pulled fromuser.email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
pulled fromuser.firstName
first_name
pulled fromuser.firstName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
pulled fromuser.fullName
name
pulled fromuser.fullName
full_name
pulled fromuser.fullName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
pulled fromuser.lastName
last_name
pulled fromuser.lastName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone
pulled fromuser.mobilePhone
mobile_phone
pulled fromuser.mobilePhone
Of course, you can modify, delete, or add any attributes you want by configuring a SAML v2 response populate lambda for the application.
Limitations
IdP Limitations
FusionAuth supports SAML both as a SAML Identity Provider (IdP) and as a Service Provider (SP). The IdP implementation has certain limitations.
Version 2.0
is supported; other SAML versions are unsupported.
FusionAuth supports only the following NameIDPolicy
values:
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
To determine the correct value for NameIDPolicy
, please examine the supported values of the software package for which you are configuring FusionAuth as the IdP.
FusionAuth won’t fail validation on any NameIDPolicy
value. If the requested NameIDPolicy
is persistent
, FusionAuth will use that and return the User’s unique id (user.id
). In all other cases, the User’s email address (user.email
) will be used for the name Id.
Prior to version 1.28.0
, FusionAuth supported two NameIDPolicy
values, both of which result in user.email
being used for the name Id:
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
FusionAuth supports the following SAMLv2 bindings:
- HTTP Redirect
- HTTP POST
Other bindings are not supported.
As of version 1.30.2, if the NameIdFormat
is omitted by an SP, urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
will be used.
SP Limitations
FusionAuth supports SAML both as a SAML Identity Provider (IdP) and as a Service Provider (SP). The SP implementation has certain limitations.
Version 2.0
is supported; other SAML versions are unsupported.
FusionAuth supports the following NameID format values by default:
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
You may also provide your own format name. To determine the correct value, please examine the supported values of the software package for which you are configuring FusionAuth as the SP.
Map between SAML claims and user claims using a reconcile lambda or FusionAuth SAMLv2 Identity Provider configuration.
Prior to version 1.28.0
, FusionAuth only supported using the name Id for the user’s email address.
FusionAuth supports the following SAMLv2 bindings:
- HTTP Redirect
- HTTP POST
Other bindings are not supported.