SAML v2
Overview
Adding a Login button for a third-party SAML v2 Identity Provider to FusionAuth is simple. This guide will walk you through the steps necessary to enable a SAML v2 Identity Provider.
This document covers the configuration for FusionAuth’s SAML v2 Identity Provider, where FusionAuth is a relying party. This is useful if you want to allow users to log into either FusionAuth’s UI or your applications via a third party SAML v2 identity provider.
If you are looking for instructions to set up FusionAuth as a SAML v2 IdP (i.e. you want FusionAuth to be the system of record for your users, and other applications authenticate against FusionAuth), consult the SAML v2 IdP documentation.
In this example FusionAuth is the SAML service provider and we are configuring a connection to a SAML Identity Provider which will be the system of record for user data.
We also provide specific examples for configuring SAML with some providers whose implementation requires unique configuration. If you’d like us to provide additional examples, please open a request on GitHub.
Once you have completed this configuration you will be able to enable the SAML v2 login button for one or more FusionAuth Applications. Below is an example login page with a SAML v2 Identity Provider enabled for PiedPiper.
Create a SAML v2 Identity Provider
To create an Identity Provider navigate to Settings -> Identity Providers and click Add provider
and select SAML v2
from the dialog.
This will take you to the Add SAML v2
screen. Here you will need to fill out the required fields. If you do not know the IdP endpoint of your SAML v2 provider, you will need to contact the identity provider owner to get the URL.
To enable this identity provider for an application, find your application name in the Applications
configuration section at the bottom of this panel. You will always see the FusionAuth
application, this application represents the FusionAuth administrative user interface. If you wish to be able to log into FusionAuth with this provider, you may enable this application.
In the following screenshot you will see that we have enabled this login provider for the Pied Piper
application and enabled Create registration
. Enabling create registration means that a user does not need to be manually registered for the application prior to using this login provider.
For example, when a new user attempts to log into Pied Piper
using SAMLv2, if their user does not exist in FusionAuth it will be created dynamically, and if the Create registration
toggle has been enabled, the user will also be registered for Pied Piper
and assigned any default roles assigned by the application.
If you do not wish to automatically provision a user for this application when logging in with SAMLv2, leave Create registration
off. You will need to manually register a user for this application before they may Sign in with SAMLv2
.
That's it, now the 'Login with PiedPiper' button will show up on the login page.
Form Fields
Enabled
Whether this SAMLv2 Identity Provider is enabled.
Id
An optional UUID. When this value is omitted a unique Id will be generated automatically.
Name
requiredA unique name to identify the identity provider. This name is for display purposes only and it can be modified later if desired.
IdP endpoint
requiredThe URL of the SAML identity providers login page.
NameID format
Available since 1.28.0The NameID format to send to the SAML v2 identity provider in the AuthN request.
Verification key
requiredThe public key or certificate that you must import into FusionAuth’s KeyMaster. This is the public key provided to you by the identity provider.
Button text
requiredThe text to be displayed in the button on the login form. This value defaults to Login with SAML
but it may be modified to your preference.
Button image
The image to be displayed in the button on the login form. When this value is omitted a default SAML icon will be displayed on the login button.
Enable IdP initiated login
Available since 1.43.0Allows IdP initiated login requests for this configuration. You must have a valid license to use this feature.
In general FusionAuth does not recommend you utilize this type of login due to the inherent risks of accepting an unsolicited authentication response from a third-party identity provider.
In a service provider initiated login, the SAML Authentication Response is returned to the service provider (FusionAuth) in response to an authentication request. This means FusionAuth can validate certain parameters and only accept a response for a request that FusionAuth initiated. In contrast, during an identity provider initiated login, the third-party identity provider sends FusionAuth a SAML Authentication Response indicating a user has been authenticated without any context. The problem is that FusionAuth did not initiate this so it is unexpected, and this limits what can be verified and requires FusionAuth to allow a cross site request from this third party.
If you must enable this feature to support a legacy integration or because the user experience is of the highest concern, then you may proceed.
Issuer
Available since 1.43.0The EntityId (unique identifier) of the SAML v2 identity provider. Required when Enable IdP initiated login is enabled. This value should be provided to you.
Linking strategy
Available since 1.28.0The linking strategy for the SAMLv2 provider. See Linking Strategies for more.
Reconcile lambda
A lambda maps custom claims returned from the SAML Response to the FusionAuth User or Registration.
To create or configure a lambda, navigate to Settings -> Lambdas. See the lambda documentation for more.
Debug enabled
Defaults to falseSome identity 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.
Options
Form Fields
Unique Id claim
The name of the claim that is returned in the SAML response that contains the unique Id of the user.
Use NameId for email
If this is enabled, FusionAuth will assume that the NameID
in the SAML response contains the email address of the user.
Email claim
The name of the email claim returned in the SAML response.
When Use NameId for email is enabled this field will not be displayed and will not be required.
Use POST method
When enabled the authentication request will use the HTTP POST binding with the identity provider instead of the default Redirect binding which uses the HTTP GET method.
Sign requests
When enabled authentication requests sent to the Identity Provider will be signed.
Request signing key
The key used to sign the SAML request. Required when Sign request is enabled. To create, manage or import a key, navigate to Settings -> Key Master.
Canonicalization method
The XML signature canonicalization method used when digesting and signing the SAML request. Required when Use POST method and Sign request are enabled.
Enable login hint
Available since 1.43.0When enabled FusionAuth will provide the username or email address when available to the IdP as a login hint when HTTP redirect bindings are used to initiate the AuthN request.
Login hint parameter name
Available since 1.43.0The name of the parameter used to pass the username or email as login hint to the IDP when HTTP redirect bindings are used to initiate the AuthN request. Required when Enable login hint is enabled.
Destination assertion policy
Available since 1.43.0The policy to use when performing a destination assertion on the SAML login request.
The possible values are:
Enabled
- Verifies the Destination attribute in the SAML response is equal to the expected Destination which is the FusionAuth ACS (Assertion Consumer Service) URL. This is the default and the recommended setting.Disabled
- Do not validate the Destination attribute. This is not recommended, please use with caution.Allow alternates
- Verifies the Destination attribute is either the expected FusionAuth ACS, or one of the configured alternate values. This option is intended to assist with migrations from third-party IdPs and should be used with caution.
Alternate destinations
Available since 1.43.0The array of URLs that FusionAuth will accept as SAML login destinations if the Destination Assertion Policy is Allow alternates
.
Managed domains
Form Fields
Managed domains
You may optionally scope this identity provider to one or more managed domains. For example, if you were to use a SAML v2 identity provider for your employees, you may add your company domain piedpiper.com
to this field.
Adding one or more managed domains for this configuration will cause this provider not to be displayed as a button on your login page. Instead of a button the login form will first ask the user for their email address. If the user’s email address matches one of the configured domains the user will then be redirected to this login provider to complete authentication. If the user’s email address does not match one of the configured domains, the user will be prompted for a password and they will be authenticated using FusionAuth.
These configured domains will be used by the Lookup API.
Integration Details
After configuring the Identity Provider, FusionAuth will display values likely required by your SAML v2 Identity Provider to trust FusionAuth as a relying party. Do so by navigating to Settings -> Identity Providers and click the green magnifying glass on your SAML provider.
When viewing the details, scroll to the SAML v2 Integration details section. There you will find the necessary values to configure an integration with a SAMLv2 IdP.
SAML v2 Integration Details
Fields
IdP Initiated Callback URLs (ACS)
An Assertion Consumer Service (or ACS) is the location at a service provider that accepts messages to establish a session based on the assertion.
By default the redirect URI will be the first Authorized redirect URI found in the FusionAuth Application OAuth configuration. To specify a redirect URI send the authorized URI in the RelayState
parameter. Support for using the RelayState
in this manner is supported in FusionAuth version greater than or equal to 1.41.0
. In prior versions, append a query parameter named redirect_uri
to the ACS in the IdP configuration.
This field will only be present if you have Enable IdP initiated login
toggled on for this identity provider.
Note: IdP initiated logins go through a separate endpoint from SP initiated logins. For IdP initiated logins in order to receive a refresh token the query parameter ?scope=offline_access
will need to be appended to the url. When logging into the FusionAuth Admin application this parameter is included by default and does not need to be supplied.
Callback URL (ACS)
This is the Assertion Consumer Service (ACS) endpoint for SP initiated logins and otherwise follows the same rules as IdP Initiated Callback URLs (ACS)
.
Issuer
The service provider EntityId. This is a URL.
Metadata URL
The URL where the service provider metadata resides.
CORS Configuration
To complete the login request, the SAML v2 Identity Provider will make an HTTP POST
request to the callback URL in FusionAuth. In order for this request to be allowed through the CORS filter you will need to navigate to Settings -> System -> CORS and add the SAML IdP origin as an Allowed Origin the CORS configuration.
Once you complete your SAML v2 Identity Provider configuration, if your CORS configuration is not yet configured to allow the login request to complete you will be shown the following warning prompting you to complete the CORS configuration. See CORS Filter reference for additional details on modifying the CORS configuration.
Redirects
After a user has logged into their SAML IdP and then sent back to FusionAuth, they can be redirected to another URL. To do so, follow these steps:
- Determine the URL you want the user to arrive at after logging in. Suppose that URL is
https://example.com/welcome
. - Make sure that
https://example.com/welcome
is added to the Authorized Redirect URLs field in the Application configuration. - URL encode the URL.
https://example.com/welcome
becomeshttps%3A%2F%2Fexample.com%2Fwelcome
. - Append the URL encoded value to the ACS you are putting in the IdP. It might look something like this:
https://local.fusionauth.io/samlv2/acs?RelayState=https%3A%2F%2Fexample.com%2Fwelcome
.
If you do not provide a RelayState
parameter, the user will be redirected to the first Authorized redirect URI found in the FusionAuth Application OAuth configuration.
See SAML v2 Integration Details for additional details.
Redirects And Lambdas
While you can configure a lambda to be executed when a user logs in to FusionAuth using SAML, they cannot affect the end destination of a user. Instead, they allow you to examine a read-only SAML response and add, modify, or remove attributes from the user or registration objects.
Troubleshooting
A common pattern is to set up SAML as the login method for the FusionAuth application. This lets you keep all your users in the SAML system, and have FusionAuth delegate auth decisions to it. However, if your Identity Provider isn’t configured correctly, you can end up in a dead end, unable to log in. This might happen if the following occurs:
- You set up SAML as the authentication method for your FusionAuth admin application.
- You set the Managed domains to your domain. For example,
example.com
. - All added users have the same
example.com
domain. - You accidentally misconfigure SAML and break authentication.
- Then you log out of the FusionAuth administrative user interface.
You won’t be able to log in to the FusionAuth admin application to correct the misconfiguration. You’ve locked down the FusionAuth admin application so that only users with example.com
email domains can access it, but because of the misconfiguration, there is no account with a valid SAML login.
This is a problem, but not an insurmountable one. Your options depend on when you discover the issue. If you are beginning your SAML configuration, you can avoid this scenario. Follow these steps:
- Don’t set any value of Managed domains before you have tested the SAML configuration.
- Test authentication in a different or incognito browser window, ensuring that an admin user account is always accessible to modify configuration.
- Add an admin user account with a domain not in the Managed domains setting. Ensure this user is registered with the FusionAuth admin application and has the
admin
role. - Set up an API key. Navigate to Settings -> API Keys to do so and make sure it has privileges to create users and registrations. This will open up options in the future to reset settings without using the administrative user interface.
If you are currently locked out of your FusionAuth application, you have fewer options:
- If you have a known username and password that are not delegated to SAML (perhaps the initial account created when you set up FusionAuth) proceed to the FusionAuth admin login page. Append
&showPasswordField=true
to the end of the login URL. This will force the UI to show the password field. - If you have an API key with appropriate privileges, you can modify the configuration without using the administrative user interface. Add an admin user with a different email domain and sign into the admin interface to correct your SAML configuration. Here’s how you might do so (
3c219e58-ed0e-4b18-ad48-f4f92793ae32
is the FusionAuth application Id):
Adding a New Admin User With a Different Domain
curl -XPOST -H "Authorization: $API_KEY" -H "Content-Type: application/json" \
-d '{
"user": {
"email": "user@differentdomain.com",
"password": "password"
},
"registration": {
"applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
"roles": ["admin"]
}
}' \
https://login.piedpiper.com/api/user/registration
If you have neither an API key nor a known user, you can restore from a database backup, modify the database directly if you have access, or re-install FusionAuth.
Troubleshooting SAML Flows
To troubleshoot, turn on the Debug option and then navigate to System -> Event Log.
Proceed through the SAML flow and review the Event log entries to see if there are any configuration issues.
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.