Configure Auth0 as SAML Service Provider

Configure Auth0 as SAML Service Provider

Configure Auth0 to serve as a service provider (SP) in a SAML federation. Auth0 only supports using Auth0 as the service provider in SAML configurations with SAML 1.1 or SAML 2.0.

Obtain metadata and certificate from identity provider

These instructions are generic. You will have to locate this information in your specific identity provider (IdP).

  • SSO URL: URL at the IdP to which SAML authentication requests should be sent. This is often called an SSO URL.

  • Logout URL: URL at the IdP to which SAML logout requests should be sent. This is often called a logout URL, a global logout URL, or a single logout URL.

  • Signing certificate: Certificate needed by the service provider to validate the signature of the authentication assertions that have been digitally signed by the IdP. There should be a place to download the signing certificate from the IdP. If the certificate is not in .pem or .cer format, you should convert it to one of these formats.

Configure Auth0 as service provider

  1. Go to Dashboard > Authentication > Enterprise, and select SAML.

  2. Select Create Connection.

    Dashboard Authentication Enterprise SAML Connection Settings

  3. Enter the following information and select Create:

    Setting Description
    Connection Name Enter a connection name such as SAML-SP.
    Sign In URL Enter the SAML SSO URL that you obtained from the IdP.
    X509 Signin Certificate Click on the CHOOSE FILE button and select the .pem file you obtained from the IdP.
    Sign Out URL Click the toggle to enable Sign out. Enter the SAML Logout URL obtained from the IdP.
    User ID Attribute 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 Mode Toggle to enable Debug Mode for more verbose logging.
    Sign Request Toggle to enable signed SAML authentication request .
    Sign Request Algorithm Click the drop-down menu to choose which secure hash algorithm to use.
    Sign Request Algorithm Digest Choose which algorithm to cross check the validity of the assertion.
    Protocol Binding Choose HTTP-redirect to enable messages to be transmitted within URL parameters. Choose HTTP-POST to enable messages to be transmitted within an HTML form.
    Advanced Choose if you want to sync user profile attributes during each login.

  4. Under Login Experience, add the IdP domain(s) and select Save.

  5. In the Setup tab, select Continue. In the window that appears, metadata about this SAML service provider is displayed. You will need to use the information from this screen to configure the IdP.

    1. The first bullet is the post-back URL or Assertion Consumer Service (ACS) URL. This is the URL to which the Identity Provider will send Authentication Assertions after authenticating a user. Enter this value where the IdP asks for Assertion Consumer Service URL. It may just call this a Service Provider URL.

    2. The second bullet tells you the Entity ID. It will be in the form urn:auth0:YOUR_TENANT:YOUR_CONNECTION_NAME. Copy and save this entire Entity ID field from "urn" all the way to the end of the connection name. Use this value if the Identity Provider asks for Entity ID or SAML Audience.

    3. The third bullet indicates the binding that will be used to send the SAML Request from Auth0 to the Identity Provider. If the Identity Provider provides a choice, select HTTP-Redirect as shown on your metadata screen.

    4. The fourth bullet indicates that Auth0 expects the Identity Provider to respond with an HTTP POST, such as the Authentication Assertion from the Identity Provider will be sent using the HTTP POST binding. If the Identity Provider provides a choice, indicate that HTTP-POST binding should be used for Authentication Assertions. The nameid format is the format for the attribute that will be used to identify users.

  6. In the same window, near the bottom, locate Metadata, and copy and save the provided URL. It will look like: https://YOUR_DOMAIN/samlp/metadata?connection=YOUR_CONNECTION_NAME. Note that if you have custom domains set up, you should use the custom domain based URL rather than your Auth0 domain. So, it should be in the format of https://<YOUR CUSTOM DOMAIN>/samlp/metadata?connection=YOUR_CONNECTION_NAME. Make a note of this metadata URL as you may be able to use it to configure the IdP in the next section.

Add service provider metadata to IdP

Add information about the service provider to the identity provider so the tenant knows how to receive and respond to SAML authentication requests. The instructions provided here are generic. You will need to find the appropriate screens and fields on the Identity Provider.

  1. Locate the screens in the Identity Provider that allow you to configure SAML. If the IdP supports uploading a metadata file, you can simply provide the metadata URL obtained in the step above. If the IdP does not support uploading a metadata file, you can configure it manually as follows.

  2. The IdP will need to know where to send the SAML assertions after it has authenticated a user. This is the Assertion Consumer Service URL in Auth0. The IdP may call this Assertion Consumer Service URL or Application Callback URL. https://YOUR_DOMAIN/login/callback?connection=YOUR_CONNECTION_NAME

  3. The connection URL parameter is required for identity provider-initiated flows. Note that if you have custom domains set up, you should use the custom domain based URL rather than your Auth0 domain. So, it should be in the format of https://YOUR_CUSTOM_DOMAIN/login/callback?connection=YOUR_CONNECTION_NAME.

  4. If the IdP has a field called Audience or Entity ID, enter into that field the Entity ID from Auth0: "audience":"urn:auth0:YOUR_TENANT:YOUR_CONNECTION_NAME" You can also configure the connection to expect a custom Entity ID.

  5. If the IdP provides a choice for bindings, you should select HTTP-Redirect for Authentication Requests.

  6. The Single Logout Service URL, where SAML logout requests and/or responses from the Identity Provider must be sent, should be configured as: https://YOUR_DOMAIN/logout

    Note that if you have custom domains set up, you should use the custom domain based URL rather than your Auth0 domain. So, it should be in the format of https://YOUR_CUSTOM_DOMAIN/logout.

  7. Signing Logout Requests: When configuring the IdP, make sure that SAML Logout Requests sent to the service provider are signed.

Customize the request template

When Auth0 initializes the request to the SAML identity provider with a redirect that includes an XML AuthnRequest object. The object template can be configured from the Management API's update a connection endpoint or on the dashboard from the connection's configuration settings page.

Template Variables

Variables can be placed into the AuthnRequest template using the @@VariableName@@ syntax.  The following variables are available:

  • ID: Transaction id

  • IssueInstant: Transaction date timestamp

  • Issuer: SAML Service Provider (connection name) in urn format

  • ProtocolBinding: The protocol binding type.

  • AssertionConsumerServiceURL: The URL the SAML response should be sent to after the user signs in (URL on the service provider). ProtocolBinding should also be set if this is used.

  • Destination: The URL the SAML request is being sent to; the URL for the identity provider and the same as “Sign in URL” in the Auth0 SAML connection configuration.

  • LoginHint: Useful when the Identifier First prompts are used, so after redirecting to the SAML identity provider, the username/email is pre-populated.

  • ProviderName: The name of the application that initiated the request

  • Connection.<options-key> - Using dot notation on the Connection key provides access to any of the connection's options values as returned from the /api/v2/connections endpoint. For example, if the connection has options.some_property: "value" then you can use @@Connection.some_property@@ in the template.

  • AssertServiceURLAndDestination: Deprecated variable. For new configurations, use AssertionConsumerServiceUrl and Destination instead.

Test connection

Test to ensure the SAML connection works:

  1. Go to Dashboard > Authentication > Enterprise > SAML.

  2. Locate the SAML connection you created, and select its Try arrow icon.

  3. You will first see a Lock login widget appear, which is triggered by the Auth0 Service Provider. Enter a username. If you entered an email domain in the SAMLP connection configuration, the username should belong to that email domain.

  4. You will then be redirected to the login screen for the Identity Provider. Log in with credentials for a user that exists in the Identity Provider.

If the configuration is set up correctly, you will see It works!, and the page will display the contents of the SAML authentication assertion sent by the Identity Provider to the Auth0 Service Provider.

If it is not configured correctly, double-check your steps. If you are still having trouble, consult the troubleshooting section at the end of this document.

Troubleshoot connection

  • If your application doesn't work the first time, clear your browser history and (ideally) cookies each time before you test. Otherwise, the browser may not pick up the latest version of your HTML page, or it may have stale cookies that impact execution.

  • To help troubleshoot SSO, capture an HTTP trace of the interaction. Many tools will capture the HTTP traffic from your browser for analysis.

    • Search the internet for "HTTP Trace" to find and install a tool.

    • Capture the login sequence from start to finish and analyze the trace. Track the sequence of GETs to see how far in the expected sequence you get. You should see a redirect from your original site to the SP and then to the IdP, a post of credentials if you had to log in, then a redirect back to the callback URL or the SP, and then a redirect to the callback URL specified in your application.

  • Make sure that cookies and JavaScript are enabled for your browser.

  • Make sure that the callback URL specified in the HTML file is also listed in the Allowed Callback URLs field for your application. To do so, navigate to Dashboard > Applications > Applications and select the name of your application, then locate Allowed Callback URLs.

  • Use the tool to decode a SAML assertion.

Configure identity provider

When Auth0 serves as the SAML service provider, you need to use an Auth0 connection to configure the identity provider side of each SAML federation. See steps to configure the following providers:

Supported algorithms for signatures

We currently support the following algorithms for processing XML Digital Signatures:

Learn more