To configure Auth0 as the service provider (SP) in a federation, you will need to create an Enterprise connection in Auth0 and then update your SAML (IdP) with the connection’s metadata. Auth0 supports using Auth0 as the SP in configurations that conform to the SAML 1.1 or SAML 2.0 protocol.

​
Get metadata and certificate from the IdP

You’ll need to collect some configuration metadata from the IdP to create a connection in Auth0:
FieldDescription
Sign In URLThe URL where SAML authentication requests are sent. This is also called the single sign-on (SSO) endpoint.
Sign Out URLThe URL where SAML logout requests are sent. This is also called the single logout (SLO) endpoint.
X509 Signing CertificateThe public-key certificate required by the SP to validate the signature of the authentication assertions that have been digitally signed by the IdP. Auth0 accepts the .pem and .cer formats.

​
Create SAML Enterprise connection in Auth0

You can create a SAML Enterprise connection in the or with the Auth0 :
  1. Go to Dashboard > Authentication > Enterprise and select SAML.
  2. Select Create Connection.
  3. Configure the following settings:
SettingDescription
Connection NameEnter a connection name such as SAML-SP.
Sign In URLEnter the Sign In URL that you obtained from the IdP.
X509 Signing CertificateUpload the X509 Signing Certificate file (in .pem or .cer format) that you obtained from the IdP.
Enable Sign OutEnable the Sign Out URL field.
Sign Out URLEnter the Sign Out URL obtained from the IdP.
User ID AttributeEnter the attribute in the SAML token that will be mapped to the user_id property in Auth0. If not set, then the user_id will be retrieved from the following (in listed order):
Debug ModeEnable Debug Mode for more verbose logging.
Sign RequestEnable signed SAML authentication requests.
Sign Request AlgorithmFrom the dropdown menu, select the hash algorithm to use.
Sign Request Algorithm DigestFrom the dropdown menu, select the algorithm to use to check the validity of the assertion.
Protocol BindingFrom the dropdown menu, select one of the following options:
  • HTTP-Redirect: Enables messages to be transmitted within URL parameters.
  • HTTP-POST: Enables messages to be transmitted within an HTML form.
Sync user profile attributes at each loginEnable syncing user profile attributes during each login.
  1. Select Create.

​
Configure SAML connection for proxy gateways

If you have Auth0 behind a proxy gateway, you’ll need to configure the SAML connection’s destinationUrl and recipientUrl fields accordingly.
  1. Get your SAML connection’s current configuration with the Management API Get a connection endpoint.
  2. Copy the value of the options object from the returned response.
  3. Add the following fields to the options object:
FieldTypeValue
destinationUrlStringURL of the proxy gateway.
recipientUrlStringURL of the proxy gateway.
  1. Call the Management API Update a connection endpoint with the entire updated options object in the request body.

​
Customize the request template

When Auth0 sends the authentication request to the IdP, the request body contains an AuthnRequest object. You can customize the template used for this object:
  1. Go to Dashboard > Authentication > Enterprise > SAML, and select your connection.
  2. Switch to the Settings view, and locate the Request Template field.
  3. Modify the template.
  4. Select Save Changes.

​
Template variables

Variables can be placed into the AuthnRequest template using the @@VariableName@@ syntax. The following variables are available:
NameDescription
AssertionConsumerServiceURLThe URL where the IdP sends the response after the user signs in. Include the ProtocolBinding attribute in the request template if you use this.
Connection.<options-key>Use dot notation on the Connection key to access any of the connection’s options values as returned from the Auth0 Management API’s Get a Connection endpoint. For example, if the connection has options.some_property: “value”, then you can use @@Connection.some_property@@ in the template.
DestinationThe URL where Auth0 sends the request. This should be the Sign In URL configured for the connection.
IDThe transaction ID.
IssueInstantThe transaction date timestamp.
IssuerThe entity ID of the SP in urn format.

For example, urn:auth0:<YOUR_AUTH0_TENANT_NAME>:<YOUR_AUTH0_CONNECTION_NAME>.
LoginHintThe username or email of the user logging in. If you are using Identifier First Authentication, Auth0 can send this value to the IdP to pre-populate it in the IdP’s login form.
ProtocolBindingThe protocol binding type.
ProviderNameThe name of the application that initiated the request. This always returns the Auth0 tenant name.
AssertServiceURLAndDestinationDeprecated. For new configurations, use AssertionConsumerServiceURL and Destination instead.

​
Configure the IdP

Go to SAML Identity Provider Configuration Settings to find the metadata you’ll need to provide to the IdP. Auth0 supports all SAML IdPs that conform to the SAML 1.1 or SAML 2.0 protocol. We have detailed instructions for configuring specific providers:

​
Test connection

To test your connection in the Dashboard:
  1. Go to Dashboard > Authentication > Enterprise > SAML.
  2. Locate the connection you created, select the … (three dots) menu icon, and select Try.
  3. A Universal Login Page will appear and prompt you to enter credentials.
  4. Enter the email address of a user who exists in the IdP. If you configured Home Realm Discovery, make sure you enter an email address that uses one of the specified domains.
  5. After you are redirected to the login screen for the IdP, log in as you normally would.
  6. You will be redirected to a page on Auth0 that displays the contents of the authentication assertion sent to Auth0 from the IdP.

​
Troubleshoot connection

If your connection is not working as expected, try the following steps:
  • Clear your browser history, cookies, and cache before each test. If you do not, the browser may not pick up the latest configuration information, or it may have stale cookies that affect execution.
  • Ensure that your browser allows cookies and has JavaScript enabled.
  • Capture a HAR file of the transaction, and then use the Auth0 SAML Tool to decode the SAML assertion and inspect its contents.

​
Learn more