SAML v2 Identity Provider
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. In this example FusionAuth is the SAML service provider and we are configuring a connection to the SAML Identity Provider.
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 and click Add provider and select SAML v2 from the dialog.
This will take you to the Add SAML v2 panel. 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 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 the Pied Piper application using this identity provider, if their user does not exist in FusionAuth it will be created dynamically. Additionally, if the Create registration toggle has been enabled, the user will also be registered for the Pied Piper application in FusionAuth 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 this identity provider, leave Create registration off and you will need to manually register a user for this application before they may complete login with this provider.
That’s it, now the Login with PiedPiper button will show up on the login page.
Form Fields
- Id Optional
-
An optional UUID. When this value is omitted a unique Id will be generated automatically.
- Name Required
-
A unique name to identity the identity provider. This name is for display purposes only and it can be modified later if desired.
- IdP endpoint Required
-
The URL of the SAML identity providers login page.
- Callback URL (ACS) Read-only
-
This is the callback URI you will need to provide to your identity provider.
- Issuer Required
-
The name of your FusionAuth deployment that is configured in the SAML identity provider.
- Use NameId for email Optional
-
If this is enabled, FusionAuth will assume that the
NameIDin the SAML response contains the email address of the user. - Email claim required Required
-
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.
- Verification key Required
-
The 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 Required
-
The text to be displayed in the button on the login form. This value is defaulted to
Login with SAMLbut it may be modified to your preference. - Button image Optional
-
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.
- Reconcile lambda Optional
-
A lambda may be utilized to map custom claims returned from the SAML response.
To configure a lambda, navigate to .
- Managed domains Optional
-
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.comto 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.
CORS Configuration
In order 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 add the SAML IdP origin to 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 wil be shown the following warning prompting you to complete the CORS configuration. See CORS Filter for additional details on modifying the CORS configuration.
