Test SAML SSO with Auth0 as Service and Identity Provider

You can conduct a test for SAML SSO with Auth0 as both the service and identity providers (IdP) using two Auth0 tenants. This will allow you to test user authentication against an Auth0 tenant that serves as the SAML IdP so you don't have to set up another IdP.

Here are steps needed to configure the two tenants:

Establish a second Auth0 tenant
Set up the Auth0 Identity Provider (IDP) (tenant 2)
Set up the Auth0 Service Provider (SP) (tenant 1)
Add your Service Provider metadata to the Identity Provider
Test the Identity Provider
Register a simple HTML application with which to test the end-to-end connection
Test the connection from Service Provider to Identity Provider
Create the HTML page for the application
Test your sample application

If you do not already have two Auth0 tenants, you will need to create them. If you already have two tenants, you can skip to the next section.

In the upper right corner, click on the name of your tenant and in the popup menu which appears, select Create Tenant.
In the window that appears, enter a name for your second tenant in the Your Auth0 domain field and click SAVE.

You can go between the tenants by going to the upper right corner of the Dashboard, clicking on the name of the current tenant, and using the popup menu which appears to switch between your tenants.

In this section you will configure one Auth0 tenant to serve as an Identity Provider. You will do this by registering an application, but in this case, the 'application' you register is really a representation of tenant 1, the SAML Service Provider.

Log into Tenant 2.
In the Dashboard, click Applications.
Click CREATE APPLICATION.
In the Name field, enter a name like My-Auth0-IdP and click SAVE.
Click on the Settings tab.
Scroll down and click on the Show Advanced Settings.
In the expanded window, scroll down to the Certificates section and click on the DOWNLOAD CERTIFICATE and select PEM from the dropdown to download a PEM-formatted certificate. The certificate will be downloaded to a file called YOUR_TENANT.pem. Save this file to upload when configuring the other Auth0 tenant.
On the Endpoints tab, go to the SAML section.
Copy the entire contents of the SAML Protocol URL field and save it because in the next step you will need to paste it into the other Auth0 tenant.

Next, create a user to test the SAML SSO sequence.

In the Dashboard, click on CREATE YOUR FIRST USER.
In the Email field, enter an email for your test user. The domain name for the email should match what you enter in section 3 below. For example, if your user is john.doe@abc-example.com, you would enter that here, and then enter abc-example.com in step 3 below for the Email domain.
Enter a password for the user.
For the Connection, leave it at the default value. (Username-Password-Authentication).
Click SAVE.

In this section you will configure another Auth0 tenant (tenant 1) so it knows how to communicate with the second Auth0 tenant (tenant 2) for SSO via the SAML protocol.

Switch to Tenant 1. You can do this using the Switch tenant option in the upper-right menu.
Go to Connections > Enterprise.
Click SAML.

Click Create Connection, then enter the following information:

Setting	Description
Connection Name	Enter any name, such as `SAML-Auth0-IDP`.
Email Domains	For this example, we will use the Lock widget. Enter the email domain name for the users that will log in via this connection.
Make sure the test user you created in section 2 has an email address with email domain that matches what you enter here.
Sign In URL	Enter the SAML Protocol URL value that you copied in section 2 above (from tenant 2, go to: Dashboard > Applications > Settings > Advanced Settings > ENDPOINTS section > SAML tab > SAML Protocol URL field).
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 from tenant 2 in section 2 above.

You can ignore the rest of the fields for now.

Click Save. A window will appear with a red Continue button. (You might have to scroll up to see it.)
Copy and save the URL below the Continue button, and then click Continue. In the window that appears, metadata about this SAML connection (tenant 1) should be displayed. If you are not logged into the Auth0 documentation site, generic SAML provider configuration data will be displayed. Click Login in the top-right corner of the page, log in with your Auth0 Dashboard credentials, and then go to the URL you saved in the previous step.

You will need to collect two pieces of information about this Auth0 tenant (the service provider) that you will then paste into the other Auth0 tenant you set up (the identity provider).

First, look for the second bullet in the list of information that tells you the Entity ID. It will be of 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. You will need to replace YOUR_CONNECTION_NAME with the name of the connection you created previously (SAML-Auth0-IDP in the example above).
In that same window, near the bottom, there is a line that says, "You can access the metadata for your connection in Auth0 here:".
Copy the URL below that line into your browser address bar. Again, you will need to replace YOUR_CONNECTION_NAME with the name of the connection you created previously (SAML-Auth0-IDP in the example above). You can access the metadata for a given SAML connection in Auth0 here: https://YOUR_DOMAIN/samlp/metadata?connection=YOUR_CONNECTION_NAME
Once you go to that metadata URL, it will display the metadata (or prompt you to save the metadata file) for this connection in tenant 1 (service provider side of the federation). It will look something like the following with your tenant name in place of the xxxxx:
You need to locate the row that starts with AssertionConsumerService and copy the value of the Location field. It will be a URL of the form: https://YOUR_DOMAIN/login/callback?connection=YOUR_CONNECTION_NAME.
Copy and save this URL. This is the URL on Tenant 1 that will receive the SAML assertion from the IdP. In the next section you will give this URL to the IdP so it knows where to send the SAML assertion.

In this section you will go back and add some information about the Service Provider (Tenant 1) to the Identity Provider (tenant 2) so the Identity Provider Auth0 tenant knows how to receive and respond to SAML-based authentication requests from the Service Provider Auth0 tenant.

On the Dashboard, switch back to Tenant 2 and click Applications.
Find the row for the application you created earlier, and click Addons to the right of the application name. (the angle bracket and slash icon)
Locate the box named SAML2 WEB APP and click on the toggle to turn it green.
In the Addon: SAML2 Web App window, go to the Settings tab.
Paste the Assertion Consumer Service URL that you copied previously in the Application Callback URL field.
In the Settings field, go to line 2 that has the audience attribute.
1. Remove the "//" at the beginning of the line to uncomment it, and remove the comma (,) from the end of the line.
2. Replace the original value (urn:foo) with the Entity ID value you saved and copied above (including your connection name). The new line 2 should look something like: "audience":"urn:auth0:YOUR_TENANT:YOUR_CONNECTION_NAME"
Click SAVE.

In the same screen, click Debug. That will trigger a login screen from tenant 2, the identity provider tenant.
Log in with the credentials for the user you created above. If your configuration is correct, you will see a screen titled It works! This screen will show you the encoded and decoded SAML response that would be sent by the identity provider.
Check the decoded SAML response and locate (about half-way down) the <saml:Audience> tag and make sure it matches the Entity ID you entered in the previous screen.
Click Close this window.

To test the end-to-end connection, you need to register an application in Auth0 that will use the SAML connection you set up.

Switch to Tenant 1 In the Dashboard and click Applications.
Click Create.
1. In the Name field, enter a name like My-HTML-SAML-App.
2. Select Regular Web App and click Save.
Select the Settings tab.
1. Save the Domain and Client ID values for use below.
2. In the Allowed Callback URLs field, enter http://jwt.io. The list of allowed callback URLs are the 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, we will send test users to the Auth0 JWT online tool which will provide some information about the JWT returned at the end of the authentication sequence.
3. Click Save Changes.
In the same screen, go to the Connections tab. Scroll down to the section near the bottom where it says Enterprise. Find the row for the SAML connection you created above and toggle it on. That enables the SAML connection for this application.

You will now test the SAML configuration between tenant 1 (service provider) and tenant 2 (identity provider).

On the Dashboard, navigate to Connections > Enterprise > SAML Connection.
Click Try on the SAML connection you created earlier. (The Try button only works for users logged in to the Dashboard. You cannot send this to an anonymous user to have them try it.)
Because you already logged in while testing this connection above, you will likely be sent directly to the It Works! page.
1. If you are presented with the Lock Login screen, login using the credentials for the user you created above.
2. If the SAML configuration works, your browser will be redirected back to an Auth0 page that says It works!. This page displays the contents of the SAML authentication assertion sent by the Auth0 identity provider to Auth0 service provider. This means the SAML connection from Auth0 service provider to Auth0 identity provider is working.
3. If it didn't work, double check the above steps and then consult the troubleshooting section at the end of this document.

You can create a simple HTML page that invokes the Auth0 Lock Widget to trigger the SAML login sequence. This will enable an end-to-end test of the SAML SSO.

Create an HTML page and insert the following HTML and javascript code:

    <!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?/

Make sure you replace YOUR_CLIENT_ID and YOUR_DOMAIN with the actual values of the app you registered above. If you did not record these values, find them in the Dashboard for Tenant 1 by going to Applications link and Settings (gear).
Replace audience with the value appropriate for your app. For the purposes of this test, a placeholder will work. When specifying the audience parameter, be sure that it matches an identifier of an existing API that has been configured in Auth0.
Save this file in a place where you can access it via a browser. For this example, we'll call it hello-saml.html.

You can now test your sample HTML application that uses the Auth0 SAML connection you set up in Tenant 1 to perform SSO via SAML against Tenant 2, serving as the SAML identity provider.

Open the HTML file created above with a browser. You should first see a white page with a login button on it.
Click on the login button. The Auth0 Lock widget should appear with one login option.
1. If you have other connections turned on for your application, your Auth0 Lock Widget may look slightly different.
2. If you are prompted to enter an email address, make sure the email address you enter has the same domain name as the domain(s) you entered in the Settings tab for the application in the Tenant 1 Dashboard (Applications > Settings).
3. After entering your email address, the blue button on the Lock widget may have a new label. Click saml or ACCESS or the email domain of the email address you are logging in with to initiate the SAML SSO sequence with the Auth0 identity provider. As above, whether you are prompted for credentials or immediately redirected to the callback URL depends on whether you still have an active session at the Identity Provider.
4. From the test you did earlier, you may still have an active session at the Identity Provider. If this is the case, you will not be prompted to log in again and will simply be redirected to the callback URL specified in the HTML file. (This callback URL must also be in the Allowed Callback URLs in the application's Settings tab in the Dashboard.)
If sufficient time has passed, or if you delete your browser cookies before initiating the test, then you will be prompted to login when redirected to the Identity Provider. Log in to the Identity Provider using the credentials for the test user you created in Auth0 Tenant 2.

If your application doesn't work the first time, try the following:

Clear your browser history and cookies and run the test again. If that doesn't work, the browser may not be picking up the latest version of your HTML page or it may have stale cookies that impact execution.
Capture an HTTP trace of the interaction.
- There are many tools that will capture the HTTP traffic from your browser for analysis. Once you have an HTTP trace tool, capture the login sequence from start to finish and analyze the trace to see 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 service provider, and then to the identity provider, a post of credentials if you had to log in, and then a redirect back to the callback URL or the service provider and then finally a redirect to the callback URL specified in your application.
Check to make sure cookies and javascript are enabled for your browser.
Check to make sure that the callback URL specified in the HTML file is also listed in the Allowed Callback URLs field in the Settings tab of the application registered in the Dashboard.
Use the http://samltool.io tool to decode a SAML assertion .

Docs

Test SAML SSO with Auth0 as Service and Identity Provider

Test SAML SSO with Auth0 as Service and Identity Provider

Establish a second Auth0 tenant

Set up Auth0 as the IdP (tenant 2)

Set up the Auth0 service provider (tenant 1)

Add service provider metadata to identity provider

Test identity provider

Register app to test connection

Test connection from service provider to identity provider

Create HTML page for test application

Test sample application

Troubleshoot test configuration

Was this article helpful?