Test SAML SSO with Auth0 as Service Provider and Identity Provider

Test SAML SSO with Auth0 as Service Provider and Identity Provider

You can configure Auth0 as both the service provider (SP) and the identity provider (IdP) to test your Auth0 SAML SP tenant configuration using Auth0 as the IdP so you don't have to learn and set up another identity provider.

Protocols Auth0 as SAML SP and IdP Diagram

Auth0 only supports using Auth0 as the service provider in SAML configurations with SAML 1.1 or SAML 2.0 and using Auth0 as the identity provider in SAML configurations with SAML 2.0.

The steps below show you how to set up a simple example application that uses Auth0 to do SAML single sign-on (SSO) using one Auth0 tenant as the SAML SP and authenticating users against a second Auth0 tenant serving as the SAML IdP. You will test SAML using two Auth0 tenants, where one tenant acts as the SP and the other acts as the IdP. You will configure two federations for one tenant.

Create identity provider tenant

If you do not already have two Auth0 tenants, you will need to create a second one. If you already have two tenants, you can skip this step.

  1. Go to the Auth0 Dashboard, select your tenant name and select Create Tenant.

    Dashboard Tenant Drop-Down Menu Create Tenant

  2. Enter your desired Tenant Domain, select a Region, and click Create.

    Dashboard Tenant Drop Down Menu Create Tenant

Configure identity provider tenant

Configure the second tenant as an IdP. Register an application that is a representation of your first tenant, which will be the SAML SP.

  1. Switch to your second tenant by selecting your tenant name, choosing Switch Tenant, and then selecting your new tenant name.

  2. Navigate to Dashboard > Applications > Applications and select Create Application.

  3. Enter a name for the application, such as My-Auth0-IdP, select an application type, and select Create.

  4. Scroll to the bottom of the Settings page, select Show Advanced Settings.

  5. Select the Certificates view, and select Download Certificate, then choose PEM. The certificate will download. You will use this certificate when you configure the other tenant.

  6. Select the Endpoints view, locate SAML Protocol URL, and copy its contents. You will use this URL when you configure the other tenant.

Create user to test SAML sequence

  1. Go to Dashboard > User Management > Users and select Create User.

  2. Enter an email address for your test user. The domain name should match the service provider tenant email domain that you will configure next. For example, if your user is john.doe@exampleco.com, you should enter exampleco.com for the email domain.

  3. Enter a password for the test user.

  4. Use the default value for Connection.

  5. Select Create.

Configure service provider tenant

Configure the first tenant to communicate with the second tenant for SSO using the SAML protocol.

  1. Switch to your first tenant by selecting your tenant name, choosing Switch Tenant, and then selecting your old tenant name.

  2. Go to Dashboard > Authentication > Enterprise and select SAML.

  3. Select Create Connection.

  4. Enter the following information, and select Create:

    Setting Description
    Connection Name Enter any name, such as SAML-Auth0-IDP.
    Sign In URL Enter the SAML Protocol URL value that you copied in above.
    Sign Out URL Enter the same URL as for the Sign In URL above.
    X509 Signing Certificate Click on the red UPLOAD CERTIFICATE... button and select the .pem file you downloaded above.

  5. Select the Setup view to see the metadata associated with the tenant, and copy and save the URL.

  6. Open a new browser tab, and navigate to the URL you saved to get the connection settings you will need to complete the configuration. (If you are logged in to the first tenant on the Auth0 Docs site, the settings should be pre-populated with correct values.)

    1. Locate Entity ID, and copy and save its contents. It will look like: urn:auth0:YOUR_TENANT:YOUR_CONNECTION_NAME. Replace your connection name with the name of the connection you created for your IdP tenant.

    2. Locate Metadata, and copy and save the provided URL. It will look like: https://YOUR_DOMAIN/samlp/metadata?connection=YOUR_CONNECTION_NAME.

    3. Navigate to the Metadata URL you just copied to display the metadata for this connection in the SP tenant. (Alternatively, the URL may prompt you to save the metadata file.)

    4. Locate the row that starts with AssertionConsumerService, and copy and save the value of the Location field. It will be a URL of the form: https://YOUR_DOMAIN/login/callback?connection=YOUR_CONNECTION_NAME. This is the URL on your first tenant that receives the SAML assertion from the IdP. In the next section, you will provide this URL to the IdP so it knows where to send the SAML assertion.

Add service provider metadata to identity provider

Add information about the service provider to the identity provider so the tenant knows how to receive and respond to SAML authentication requests.

  1. Switch to your second tenant by selecting your tenant name, choosing Switch Tenant, and then selecting your new tenant name.

  2. Go to Dashboard > Applications > Applications and select the name of the IdP application you created above.

  3. Select the Addons view.

  4. Select SAML2 Web App to view its options, and locate the Application Callback URL. Paste the AssertionConsumerService URL that you copied above.

  5. In the Settings code block, locate the audience key, and uncomment it, then remove the comma from the end of the line and replace the original value (urn:foo) with the Entity ID value you saved above (including your connection name). The new line should look like: "audience":"urn:auth0:YOUR_TENANT:YOUR_CONNECTION_NAME".

  6. Select Enable.

Test identity provider

  1. In the same window, scroll up, and select Debug. A login screen will appear.

  2. Log in with the credentials of the test user you created above. If your configuration is correct, you will see It works!. The encoded and decoded SAML response that would be sent to the IdP appears.

  3. Check the decoded SAML response, locate (half-way down) "<saml:Audience>", and make sure it matches the Entity ID you entered on the previous screen.

  4. Click Close this window.

Create application to test SAML connection

Create a simple HTML application to test the SAML connection you created.

  1. Switch to your first tenant by selecting your tenant name, choosing Switch Tenant, and then selecting your old tenant name.

  2. Go to Dashboard > Applications > Applications and select Create Application.

  3. Enter an application name, select Regular Web App, and select Create.

  4. Locate the Domain and Client ID values, and copy and save them.

  5. Locate the Allowed Callback URLs field, and enter http://jwt.io. This is the list of allowed callback URLs to which users will be redirected after authentication. The URL(s) entered here must match the callback URL in the HTML code created in the next step. Normally you would enter a URL for your application, but to keep this example simple, the test user will be sent to the Auth0 JWT online tool, which provides some information about the JSON Web Token (JWT) returned at the end of the authentication sequence.

  6. Select Save Changes.

  7. Select the Connections view, locate the Enterprise section, and find the SAML connection you created, then enable its switch.

Test connection between service and identity provider

Test to ensure the SAML configuration between your SP tenant and IdP tenant works.

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

  2. Locate the SAML connection you created, and select its Try arrow icon. Because you already logged in while testing this connection above, you should be sent directly to the It works! screen. If you see the login screen, log in using your test user's credentials.

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

Create HTML page for test application

Create a simple HTML page that invokes the Lock widget triggering the SAML login sequence.

  1. Create an HTML page, and insert the following HTML and JavaScript code. Replace YOUR_CLIENT_ID and YOUR_DOMAIN with the actual values of the application you registered above. (If you did not note those values, you can find them in the Application Settings on your first tenant.)

    <!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">
    <HTML>
    <BODY>
    <p> Click on the button to log in </p>
    
    <script src="https://cdn.auth0.com/js/lock/11.14/lock.min.js"></script>
    <script type="text/javascript">
      var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_DOMAIN',{
            auth: {
              redirectUrl: 'http://jwt.io',
              audience: 'https://your-audience.com',
              responseType: 'token',
              params: {scope: 'openid'}
            }
        });
    
      function signin() {
        lock.show();
      }
    </script>
    <button onclick="signin()">Login</button>
    </BODY>
    </HTML>
    
    
    

    Was this helpful?

    /

  2. You can also replace audience with the appropriate value for your application; however, for the purposes of this test, a placeholder works. When specifying the audience parameter, be sure that it matches an identifier of an existing API you have configured in Auth0.

  3. Save the HTML file where you can access it from a browser.

Test sample application

Test the sample HTML application that uses the Auth0 SAML connection you created in your first tenant to perform SSO authentication against the IdP you created in your second tenant.

  1. Open the HTML file you created above with a browser. You should see a login button.

  2. Click Login. You should see the Lock widget with one option. If you have other connections turned on for your application, the screen may look different. If you are prompted for an email address, make sure the email address you enter has the same domain name as the domain you entered in the Settings view for the application in the first tenant.

  3. Click the blue button, which may say saml or ACCESS. Whether you are prompted for credentials or immediately redirected to the callback URL depends on whether you still have an active session.

Troubleshoot test scenario

  • 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, go to Dashboard > Applications > Applications and select the name of your application, then locate Allowed Callback URLs.

  • Use the http://samltool.io tool to decode a SAML assertion.

Learn more