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

    Issuer Required

    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 Optional

    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 Required

    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 Optional

    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 Optional

    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

    Application SAML v2 Authentication Configuration

    Settings in this section configure SAML request handling.

    Form Fields

    Require signature Optional

    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 Required

    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.

    Authentication Response

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

    Form Fields

    Signing key Required

    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 Optional

    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 Optional

    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 Optional

    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.

    Application SAML v2 Logout Configuration

    Form Fields

    Require signature Optional

    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 Required

    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 Optional

    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 Optional

    Enable Single Logout behavior. When enabled, this application will receive LogoutRequests from any other application in this tenant recieves one.

    Logout URL Required

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

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

    Signing key Required

    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 Optional

    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 Required

    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 Optional

    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.

    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

    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

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

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo