Configure Your Application as a SAML Service Provider

In this lab, you will learn how to configure your application to act as a SAML Service Provider and allow users to authenticate with an external Identity Provider. In particular, you will learn how to:

• Configure your application as a SAML Service Provider with Auth0.
• Configure Auth0 as an Identity Provider to test your SAML-based Service Provider configuration.
• Test your SAML Service Provider configuration.

Why Configure an Application as a SAML Service Provider?

When you build your application for your company or your business customers (e.g., in a B2B scenario), chances are that you will need to allow external users, such as a partner company's users, to access your application sooner or later.

In an enterprise context, the partner company is very likely to use a SAML-based Identity Provider. In this scenario, it is much more convenient to configure your application as a SAML Service Provider and allow access to users authenticated by your partner company's Identity Provider.

Lab Setup

To follow this lab, you need:

• An Auth0 account to access your Auth0 dashboard. If you don't have an Auth0 account, sign up now to have one for free.
• An application to test the SAML integration.

Configure Auth0 as the Identity Provider

You will use Auth0 to simulate an external SAML Identity Provider and test the SAML Service Provider configuration you will create later. For this purpose, you will create a new tenant where Auth0 will play the role of the Identity Provider.

Go to your Auth0 dashboard, select your tenant name in the upper left corner, and click Create tenant:

Then, enter a domain name, select a region, and click Create.

In the IdP tenant, navigate to Applications > Applications and click Create Application. Enter a friendly name for your application (such as My IdP), and click the Create button:

Now, go to the Settings tab and expand the Advanced Settings section on the page. Then, switch to the Certificates view, click Download Certificate, and select PEM as the certificate format:

You will get the certificate in a file named as your tenant. You will use the downloaded certificate when configuring your application as a Service Provider.

Now go to the Endpoints tab, locate the SAML section, and take note of the SAML Protocol URL shown there.

Create a SAML Connection

Switch to your SP tenant. In this tenant, you will configure your application as a SAML Service Provider. The first step is to create a SAML connection to enable your application to act as a Service Provider.

Go to Authentication > Enterprise, select SAML, and then click the Create Connection button:

You will get a form where you'll enter the configuration data for your SAML connection:

Assign a name to your SAML connection, such as saml-connection. Make sure you don't use spaces or other special characters for your SAML connection name.

Enter the SAML Protocol URL you copied earlier from your IdP tenant into both the Sign in URL and Sign Out URL fields. Upload the PEM file with your IdP tenant's SAML certificate. Finally, click the Create button.

In the resulting SAML configuration page, go to the Login Experience tab. Here you can choose how your external users will be requested to authenticate using SAML-based SSO. For our purposes, let's show them a button to log in. Locate the Connection button section in the Login Experience tab and check Display connection as a button. Then, assign the text you want to display on the button as the authentication method to the Button display name field. In our example, you will assign SSO, so the login button will display “Continue with SSO”. The following picture shows the Login Experience configuration:

Don't forget to click Save to confirm your settings.

Now, switch to the Setup tab of the SAML configuration page:

On this screen, you will see a URL that will bring you to a documentation page with all the details of the Service Provider you may need to provide your SAML-based Identity Provider. For our simple use case, you will need to take note of the following data:

• The Entity ID, which is a string in the URN format identifying your SAML connection. Its structure will be as follows:

  urn:auth0:{YOUR-TENANT-NAME}:{YOUR-SAML-CONNECTION-NAME}

  If your SP tenant name is foo and your SAML connection name is saml-connection, your Entity ID will be urn:auth0:foo:saml-connection.

• The Assertion Consumer Service URL, which is the URL on the Service Provider that receives the SAML assertion from the Identity Provider. It has the form

  https://{YOUR-SP-DOMAIN}/login/callback?connection={YOUR-SAML-CONNECTION-NAME}

  If the domain of the tenant for the Service Provider you are configuring is foo.auth0.com and your SAML connection name is saml-connection, your Assertion Consumer Service URL will be https://foo.auth0.com/login/callback?connection=saml-connection.

Now you have all the data to complete the configuration of your IdP tenant.

Complete the IdP Configuration

Go back to your IdP tenant and navigate to Applications > Applications. Here, select the application you created earlier, My IdP, if you used the name suggested in the previous section.

Once you're on the application configuration page, select the Addons tab and click the SAML2 Web App item:

Enter the value of the Assertion Consumer Service URL field you get from your Service Provider tenant in the Application Callback URL field.

In the Settings code block, uncomment the audience key and replace its assigned value with the Entity ID of your Service Provider (don't forget to remove the trailing comma!).

Scroll down and click Enable to confirm your changes.

You configured Auth0 as the SAML-based Identity Provider for your Service Provider.

Configure Your Application as a Service Provider

At this point, you have configured Auth0 as the Identity Provider in your IdP tenant and created a SAML connection in your SP tenant. You are just missing one final step: registering your application with Auth0 in the SP tenant and configuring it as a Service Provider.

Go back to your SP tenant, navigate to Applications > Applications, and click Create Application.

Enter a friendly name, e.g., My Service Provider, select Regular Web Applications as the application type, and click the Create button.

In the application configuration page, go to the Settings tab and take note of the values of the Domain and Client ID fields.

Scroll down to the Application URIs section and enter the value for the Allowed Callback URLs field. This is the URL where your application will receive the token that confirms that the user was authenticated. Its value depends on how your application is built. Since we will use a sample application for this lab, set its value to http://localhost:3000/callback.

Click the Save Changes button to confirm your changes.

Then, switch to the Connections tab and enable the SAML connection you created earlier.

Test Your SAML Service Provider Configuration

To test your configuration, you need to configure your application using the settings you got from the previous step. Basically, you need to provide your application with the domain and client ID and enable it to call Auth0 for user authentication. How to implement this depends on the specific technology stack you used to build your application. Take a look at the Quickstarts to find the right instructions for your application.

For testing purposes, you can download a configured sample application from the Quickstart tab of the application configuration page:

Choose your preferred technology and follow the instructions to download and get the application ready to run.

For this guide, we will download the Node.js web application. Once you get the sample application, go to its folder and run the following commands:

npm install
npm start

Then, point your browser to http://localhost:3000/, and you should see the following page:

Once you click the Login link, you are redirected to the SP tenant, which shows you the login button you configured for the SAML connection:

By clicking "Continue with SSO", you will access the application if you have already been authenticated. Otherwise, you will need to provide your credentials to access the application. The Profile page in the application will display the details about the authenticated user:

Congratulations — you have successfully configured your application as a SAML Service Provider!

Recap

In this lab, you learned how to configure your application as a SAML Service Provider in Auth0.

You created a SAML connection in your SP tenant, then registered your application in the same tenant using that SAML connection.

For testing purposes, you configured Auth0 as the SAML Identity Provider in a separate tenant — the IdP tenant — and downloaded a pre-configured application from the Auth0 dashboard. You then ran the application and verified that it behaved as a SAML Service Provider.