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.

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

As a concrete example, you might have an app called Payroll Zen that manages your companies payroll. This app requires that employees who have access to use it login in using your companies Active Directory. In this case, Payroll Zen is the service provider and Active Directory is the identity provider.

This document covers the configuration for FusionAuth’s SAML v2 identity provider. If you are looking for instructions to setup 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 documentation under SAML v2 Identity Provider.

It should also be noted that 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 its own OAuth UI. This is an important concept if you are interested in using FusionAuth’s OAuth theme support to customize the look and feel of your SAML identity provider.

Configure SAML identity provider

In order to configure FusionAuth to act as a SAML identity provider, you need to specify the SAML configure for an Application. This will allow FusionAuth to present a SAML login page that will allow users to login for that application. In this case, FusionAuth will consume SAML requests from the application and return SAML responses to the application after the user logs in.

The SAML configuration is under the SAML tab on the Application form. In the screenshot below, you can see that we are configuring SAML for the Pied Piper application:

Application SAML v2 Configuration

SAML v2 Form Fields

Issuer Required

This is the issuer string that the service provider will send inside the SAML request to FusionAuth. FusionAuth uses this issuer to lookup the correct application in order to start the SAML login process.

Audience Optional

Some service providers require a different audience in the SAML response than the issuer set above. If you are configuring a service provider that has a different audience requirement, enter the audience name here. If this isn’t specified, FusionAuth will set the audience to the same string as the issuer.

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 globally configured logout URL will be used. See the Logout URL under the OAuth tab of the System Settings.

Signing key Required

In order to properly sign the SAML responses, FusionAuth requires a key pair from KeyMaster. You can either select an existing key here or select the top option to have FusionAuth generate a key pair to use.

XML signature canonicalization method Required

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 the login works.

Response populate lambda Optional

This optionally specifies a lambda that FusionAuth will invoke prior to sending the SAML response to the service provider. This allows you to write a lambda that can populate additional information into the SAML response. In most cases, your lambda will add additional `Attribute`s to the response.

The complete documentation for this lambda can be found on the SAML v2 response populate lambda documentation page.

Debug enabled Optional

Many service providers are not compliant with the SAML and XML signing specifications. This makes it very challenging to get them working with FusionAuth. If you are running into issues, you can toggle this setting to instruct FusionAuth to log debugging information the the Event Log (which is accessible via the System > Event Log menu).

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 browser 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 using SAML v2 populate lambda configuration of the application.