Logo / Docs

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:

Application SAML v2 Configuration

Form Fields

Issuerrequired

This 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 URLsrequired

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

Application SAML v2 Authentication Configuration

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 keyrequired

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

Enable login hintAvailable since 1.47.0

When enabled, FusionAuth will accept a username or email address as a login hint on a custom HTTP request parameter.

Login hint parameter nameDefaults to login_hintAvailable since 1.47.0

The name of the login hint parameter provided by the service provider on an AuthnRequest. If this parameter is present, its value will be used to pre-populate the username field on the FusionAuth login form.

For example, suppose Enable login hint is enabled and Login hint parameter name has the value login_name. When FusionAuth is set up as an IdP, the SP can send a request which includes the parameter login_name=richard@example.com, and FusionAuth will pre-populate richard@example.com into the login form the end user sees.

Note that this setting names an HTTP query parameter, not an element in the SAML AuthnRequest XML.

Authentication Response

Settings in this section configure how FusionAuth processes the SAML response.

Form Fields

Signing keyrequired

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

Enable IdP initiated loginDefaults to falseAvailable since 1.41.0

When enabled, FusionAuth will be able to initiate a login request to a SAML v2 Service Provider.

Once enabled, open the View dialog or this application to view the integration URI. You will find this value in the view dialog in the SAML v2 Integration details, and the value will be named Initiate login URL: .

NameID formatDefaults to PersistentAvailable since 1.41.0

The NameId format to send in the AuthN response to the SAML v2 Service Provider. There are two valid values:

  • Persistent - The urn:oasis:names:tc:SAML:2.0:nameid-format:persistent NameID format will be used.
  • Email - The urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress NameID format will be used.

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.

Application SAML v2 Logout Configuration

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 keyrequired

The 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 URLrequired

The URL which you want to receive the LogoutRequest from FusionAuth.

If Enable single logout is not enabled, this field is optional.

Signing keyrequired

In 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 keyrequired

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

Application SAML v2 Assertion Encryption Configuration

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.

View icon on the Application listing 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:

View dialog on the Application listing page

SAML v2 IdP Initiated RelayState

Since version 1.55.1, FusionAuth supports an opaque value in the RelayState parameter on a request to begin an IdP-initiated SAML v2 login workflow. An opaque RelayState value will be passed unmodified to the SAML v2 Service Provider on the request to the Assertion Consumer Service (ACS) URL. The RelayState parameter and ACS URL resolution function as follows:

  • If the RelayState value matches a configured Authorized redirect URLs value, that value is used as the ACS URL for the current workflow. The RelayState parameter will not be included on the request to the ACS URL.
  • If the RelayState value does not match a configured Authorized redirect URLs value, the RelayState parameter will be treated as an opaque value and included unmodified on the request to the ACS URL. ACS URL resolution continues as follows:
    • If a redirect_uri parameter was provided on the IdP-initiated login request, it must match a configured Authorized redirect URLs value, or the request will result in an error. Otherwise, the matched value will be used as the ACS URL for the workflow.
    • If no redirect_uri parameter was provided on the request, the first configured Authorized redirect URLs value will be used as the ACS URL for the workflow.

In FusionAuth versions before 1.55.1 the RelayState parameter is only used for ACS URL resolution. If provided on the request, it must match a configured Authorized redirect URLs value, or the request will result in an error. No RelayState value is passed to the ACS URL.

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 from user.id
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth pulled from user.birthDate
  • birth_date pulled from user.birthDate
  • date_of_birth pulled from user.birthDate
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress pulled from user.email
  • email pulled from user.email
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname pulled from user.firstName
  • first_name pulled from user.firstName
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name pulled from user.fullName
  • name pulled from user.fullName
  • full_name pulled from user.fullName
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname pulled from user.lastName
  • last_name pulled from user.lastName
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone pulled from user.mobilePhone
  • mobile_phone pulled from user.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.