This lab will guide you in creating a custom SSO integration that allows a SaaS application to use Auth0 as its SAML Identity Provider. Specifically, you will learn how to:
- Define a custom SAML SSO integration.
- Configure the SaaS application (Service Provider).
- Test the configured integration.
Why Create a Custom SSO Integration?
Auth0 provides several off-the-shelf integrations that enable Single Sign-On for a SaaS application using the SAML protocol, also known as Service Provider. If you want to use Auth0 as the Identity Provider for Google Workspace or Office 365, Dropbox, OneDesk, and other well-known SaaS applications, you have a ready-to-use integration for it. But what do you do when a built-in SSO integration is not available?
In this case, you need to set up a custom SSO integration to allow a SAML-enabled SaaS application to use Auth0 as its Identity Provider.
Lab Setup
To follow this lab, you need:
- An Asana super admin account.
- An Auth0 account to access the Auth0 dashboard. If you don't have an Auth0 account, sign up now to have one for free.
Create and Configure an Auth0 Application
As the first step, go to your Auth0 dashboard and click the Applications > Applications menu. Here, create a new application by giving it a friendly name, such as Asana in our case:
Then, go to the Settings tab, scroll down to the Advanced Settings section, and click on it. You will see the following screen:
Go to the Certificates tab and click the Download Certificate button at the bottom of the section:
You will get the certificate in a file named as your tenant. For example, if you choose PEM as the certificate format for your tenant named foo, you will get a file named foo.pem. You will use this file to configure your Asana instance as a Service Provider.
Go to the Endpoints tab of the Advanced Settings section and locate the SAML section. You should see two URLs similar to the ones shown below:
Take note of these URLs — you will need them to configure your Asana instance.
Now go to the top of the page and select the Addons tab of the Asana application configuration page. Select the SAML2 Web App toggle:
In the popup window that appears, select the Settings tab:
Enter the Assertion Consumer Service (ACS) URL in the Application Callback URL field. This is the Service Provider endpoint where SAML assertions will be sent after Auth0 has authenticated the user. At the time of writing, the URL for Asana is https://app.asana.com/-/saml/consume.
Check out Asana documentation to learn more about the configuration parameters on Asana's side.
Scroll down to the bottom of the tab and click the Enable button to save your settings.
Now switch to the Usage tab of the SAML Addon to get the information you need to configure Asana as your Service Provider:
At the end of this step, your custom SAML SSO integration is set up. You have a certificate and configuration data to use to set up Asana to use Auth0 as an Identity Provider.
Configure Your Service Provider
Once you create and configure your custom SAML SSO integration, configure your Service Provider to use Auth0 as its Identity Provider.
Here are the steps to configure your Asana instance to use Auth0 as an Identity Provider. Remember to follow Asana's official documentation to configure SSO on your Asana instance.
Go to your Asana Admin console and navigate to the Security tab. Locate the Global authentication settings section and click SAML authentication.
In the window that opens, select the Required for all members, except guest accounts option. Then, paste the Identity Provider Login URL from the SAML2 Web App addon configuration data to the Sign-in page URL field. Finally, paste the content of your certificate file to the X.509 certificate field and click the Save changes button.
Your Asana instance is now ready to use Auth0 as an Identity Provider.
Test the SAML SSO Integration
Now that you have configured Auth0 as your SAML Identity Provider and Asana as your SAML Service Provider, let's make sure everything works as expected.
First, ensure you have at least one user created in your current Auth0 tenant. These users will be enabled to access Asana through Auth0. If you don't have any, create one following these steps.
Then, clear your browser history and cookies — this ensures that you are not using an existing authenticated session.
Now, access your Asana instance. You should be redirected to the Auth0 login page. After you enter your user's credentials, you should go back to Asana.
Awesome! Now Auth0 is the Identity Provider for your Asana application.
Recap
In this lab, you learned how to create a custom SSO integration to allow users authenticated with Auth0 to access SaaS applications without ready-to-use SSO integrations. This enables Single Sign-On in your organization since, with a single Auth0 account, your users can access multiple SaaS applications.
Picking Asana as a SaaS application example, you learned how to create and configure a custom SSO integration on the Auth0 dashboard and how to configure the SaaS application by providing the data shown on the SAML2 Web App addon configuration page.