OAuth 2.0 Authorization Framework
SAML SSO with Auth0 as Service Provider and as an Identity Provider
This tutorial will create a simple example application that uses Auth0 to do Access TokenSAML JSON Web Token (JWT)Single Sign-on (SSO), using one Auth0 tenant (tenant 1) as a SAML Service Provider(SP), and authenticating users against a second Auth0 tenant (tenant 2) serving as SAML Identity Provider(IDP). This gives you a way to test your Auth0 SAML tenant (tenant 1) configuration, using Auth0 as an IDP so you don't have to learn and set up another IDP.
There are 9 steps to this sample and the tenth is a troubleshooting section to help resolve any problems that might arise.
- Establish two Auth0 tenants
- 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
1. Establish two Auth0 Tenants
If you do not already have two Auth0 tenants, you will need to create them. If you do already have two tenants, you can skip to step #2.
In the Auth0 Dashboard
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 which appears, enter a name for your second tenant in the "Your Auth0 domain" field and press the "SAVE" button.
You can switch back and forth 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.
2. Set up the Auth0 IDP (tenant 2)
In this section you will configure one Auth0 tenant (tenant 2) 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 Auth0 dashboard:
Click on "Applications" link at left.
Click on the red "+ CREATE APPLICATION" button on the right.
In the Name field, enter a name like "My-Auth0-IDP".
Press the blue "SAVE" button.
Click on the "Settings" tab.
Scroll down and click on the "Show Advanced Settings" link.
In the expanded window, scroll down to the "Certificates" section and click on the "DOWNLOAD CERTIFICATE" link 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 as you will need to upload this file when configuring the other Auth0 tenant, tenant 1.
- Click on the "Endpoints" tab and go to the "SAML" section. Copy the entire contents of the "SAML Protocol URL" field and save it as in the next step you will need to paste it into the other Auth0 tenant, tenant 1.
Next, create a user to use in testing the SAML SSO sequence. In the Auth0 dashboard:
- Click on the "+ CREATE YOUR FIRST USER" button.
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
email@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)
Press the blue "SAVE" button.
3. Set up the Auth0 service provider (tenant 1)
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.
In the Auth0 dashboard:
- Click on "Connections" link at left.
- In the list of options below "Connections", click on "Enterprise"
- In the middle of the screen, click on "SAMLP Identity Provider"
- Click on the blue "Create New Connection" button
In the "Create SAMLP Identity Provider" connection window, enter the following information into the "Configuration" tab.
Connection Name: You can enter any name, such as "SAML-Auth0-IDP"
Email Domains: In this example, we will use the audienceLock widget, so in the Email Domains field enter the email domain name for the users that will log in via this connection. For example, if your users have an email domain of 'abc-example.com', you would enter that into this field. You can enter multiple email domains if needed. 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 field 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.
Save: Click on the blue "SAVE" button at the bottom.
After pressing the "SAVE" button, 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 on the "CONTINUE" button.
In the window that appears, metadata about this SAML provider (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 management 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).
In general, you can access the metadata for a given SAML connection in Auth0 here:
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
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.
4. Add your Service Provider metadata to the Identity Provider
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.
- Switch back to Tenant 2.
In the Auth0 dashboard: for Tenant 2
Click on "Applications" link at left.
Find the row for the application you created earlier, and click on the "Add Ons" icon to the right of the application name. (the angle bracket and slash icon)
Locate the box with the "SAML2 WEB APP" label and click on the circle toggle to turn it green.
- Next, a configuration window will pop up for the "Addon: SAML2 Web App". Make sure you are in the Settings" tab.
- In the "Application Callback URL" field, paste in the Assertion Consumer Service URL that you copied and saved in section 3 above (the last step).
- In the Settings field below, go to line 2 that has the "audience" attribute.
First remove the "//" at the beginning of the line to uncomment it, and remove the comma (',') from the end of the line.
Next, replace the original value (urn:foo) with the Entity ID value you saved and copied in step 3 above (including your actual connection name). The new line 2 should look something like:
- Click on the blue "SAVE" button at the bottom of the screen
How response type works
5. Test Identity Provider
In the same screen, click on the red "DEBUG" button.
That will trigger a login screen from tenant 2, the Identity Provider.
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 (obtained during step 3).
Click on "Close this window" at the bottom of the screen.
How response mode works
6. Register a simple HTML application with which to test the end-to-end connection.
In this section, you will register an application in Auth0 that will use the SAML connection you set up in the above steps.
Make sure you are logged into the Tenant 1 Auth0 dashboard.
In the Auth0 dashboard, click on the "Applications" link at left.
Click on the red "+ CREATE APP" button on the right.
In the Name field, enter a name like "My-HTML-SAML-App".
Select "Regular Web App"
Press the blue "SAVE" button.
Click on the "Settings" tab.
Save the "Domain" and "Client ID" values for use below in step 8.
In the "Allowed Callback URLs" field, enter http://jwt.io.
The list of allowed callback URLs is a list of URL(s) 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, users will simply be sent to the Auth0 JWT online tool which will provide some information about the scopesJSON Web Token (JWT) returned at the end of the authentication sequence.
Press the blue "SAVE CHANGES" button at the bottom of the screen.
In the same screen, click on the blue "Connections" tab (In the row that says Quick Start, Settings and so on.
Scroll down to the section near the bottom where it says "ENTERPRISE".
Find the row for the SAML connection you created above and click on the on/off toggle at right so that it is green, for "on". That enables the SAML connection for this application.
7. Test the connection from Service Provider to Identity Provider
In this section, you will test to make sure the SAML configuration between Auth0 tenant 1 (Service Provider) and Auth0 tenant 2 (Identity Provider) is working.
- On the Dashboard, navigate to: Connections -> Enterprise -> SAMLP Identity Provider.
- Click on the triangular "Try" button for the SAML connection you created earlier. This button is to the right of the name of the connection. You can hover your mouse over the button to have the text label appear.
- Because you already logged in while testing this connection above, you will likely be sent directly to the "It Works!" page shown previously. If you are presented with the Lock login screen, login using the credentials for the user you created above. On some older tenants, you may see the "Last time you signed in using" dialog as shown below, in which case you can just click on your email address to continue.
If the SAML configuration works, your browser will be redirected back to an Auth0 page that says "It works!". This page will display 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.
If it didn't work, double check the above steps and then consult the troubleshooting section at the end of this document.
8. Create the HTML page for a test application
In this section you will create a very simple HTML page that invokes the Auth0 Lock Widget which will trigger the SAML login sequence. This will enable an end-to-end test of the SAML SSO.
Make sure you replace YOUR_CLIENT_ID and YOUR_DOMAIN with the actual values of the app you registered in step 6 above. If you did not record these values in step 6, they can be found in the Auth0 dashboard for Tenant 1 by going to "Applications" link and clicking on the "Settings" (gear) icon to the right of your application's name.
You can also replace OpenID Connect (OIDC)audience with the value appropriate for your Application -- however, 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".
9. Test your sample application
In this step, you will 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.
If you have other connections turned on for your application, your Auth0 Lock Widget may look slightly different. 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 Auth0 dashboard (Applications > Settings).
After entering your email address, the blue button on the Lock widget may have a new label. Click on the button which may be labeled "saml" or ACCESS or with 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.
From the "try me" 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. (Remember that this callback URL must also be in the Allowed Callback URLs in the application's Settings tab in the Auth0 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.
This section has a few ideas for things to check if your sample doesn't work.
Note that if your application doesn't work the first time, you should clear your browser history and ideally cookies each time before you test again. Otherwise, the browser may not be picking up the latest version of your html page or it may have stale cookies that impact execution.
When troubleshooting SSO, it is often helpful to capture an HTTP trace of the interaction. There are many tools that will capture the HTTP traffic from your browser for analysis. Search for "HTTP Trace" to find some. 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 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 Auth0 Dashboard. (In dashboard, Click on Applications link, then on the "Settings" icon to the right of the application's name.)
The http://samltool.io tool can decode a SAML assertion and is a useful debugging tool.