Configure Single Sign-on with Heroku

Connect your app to Microsoft Azure Active Directory


There are different scenarios in which you might want to integrate with Microsoft Azure AD:

  • You want to let users into your application from an Azure AD you or your organization controls (such as employees in your company).

  • You want to let users coming from other companies' Azure ADs into your application. You may want to set up those external directories as different connections.

If you plan on allowing users to log in using a Microsoft Azure Active Directory account, either from your company or from external directories, you must register your application through the Microsoft Azure portal. If you don't have a Microsoft Azure account, you can signup for free.

You can access the Azure management portal from your Microsoft service, or visit and sign in to Azure using the global administrator account used to create the Office 365 organization.

There is no way to create an application that integrates with Microsoft Azure AD without having your own Microsoft Azure AD instance.

If you have an Office 365 account, you can use the account's Azure AD instance instead of creating a new one. To find your Office 365 account's Azure AD instance:

  1. Sign in to Office 365.
  2. Navigate to the Office 365 Admin Center.
  3. Open the Admin centers menu drawer located in the left menu.
  4. Click on Azure AD.

This will bring you to the admin center of the Azure AD instance backing your Office 365 account.

1. Obtain Your Heroku Identifiers

Step-by-step guide

2. Register Heroku with Auth0

1. Create a new application

Login to Microsoft Azure and choose Azure Active Directory from the sidebar.

Select Active Directory

Then under MANAGE, select App registrations.

Select App registrations

Then click on the + ADD button to add a new application.

Enter a name for the application, select Web app/API as the Application Type, and for Sign-on URL enter your application URL.

Create application form

3. Provide Auth0 Metadata to Heroku

2. Configure the permissions

Once the application has been created, you will have to configure the permissions. Click on the name of the application to open the Settings section.

Created application list

Click Required permissions.

Choose Required Permissions

Then click on Windows Azure Active Directory to change the access levels.

Required Permissions

The next step is to modify permissions so your app can read the directory. Under DELEGATED PERMISSIONS check next to Sign in and read user profile and Read directory data.

Check access levels

If you want to enable extended attributes (like Extended Profile or Security Groups) you will also need to enable the following permissions: Application Permissions: Read directory data, Delegated Permissions: Access the directory as the signed-in user.

Click the SAVE button at the top to save these changes.

3. Allowing access from external organizations (optional)

If you want to allow users from external organizations (such as other Azure directories) to log in, you will need to enable the Multi-Tenant flag for this application. In the Settings section, click Properties. Locate the Multi-tenanted toggle at the bottom and select Yes. Finally click the SAVE button at the top to save these changes.

Enable Multi-tenanted

4. Create the key

Next you will need to create a key which will be used as the Client Secret in the Auth0 connection. Click on Keys from the Settings menu.

Select Keys

Enter a name for the key and choose the desired duration.

If you choose an expiring key, make sure to record the expiration date in your calendar, as you will need to renew the key (get a new one) before that day in order to ensure users don't experience a service interruption.

Creating a Key

Click on Save and the key will be displayed. Make sure to copy the value of this key before leaving this screen, otherwise you may need to create a new key. This value is used as the Client Secret in the next step.

Creating a Key

5. Configure Reply URLs

Next you need to ensure that your Auth0 Single Sign-on (SSO)callback URL is listed in allowed reply URLs for the created application. Navigate to Azure Active Directory -> Apps registrations and select your app. Then click Settings -> Reply URLs and add:


Add Reply URL

It has the following format https://<domain>.<region> (region is omitted if the Auth0 tenant was created in the US).

If you are using the custom domains feature, your Reply URL will instead be in the following format: https://<YOUR CUSTOM DOMAIN>/login/callback.

Without this step the App consent page will return a "Bad request" error. The fine print in the footer of this error page can be used to identify the exact tenant name and missing callback url.

6. Create Connections

Login to your Auth0 Dashboard, and select the Connections > Enterprise menu option.

Add connection

Select Microsoft Azure AD. You will be asked to provide the appropriate settings, including data about the app registration you just created in Auth0.

Dashboard Config

For the Client ID, this value is stored as the Application ID in Azure AD.

Application ID

For the Client Secret use the value that was shown for the key when you created it in the previous step.

Set the name of the Microsoft Azure AD Domain and under Domain Aliases put any email domain that corresponds to the connection.

Connection settings

Multi-tenant applications: if you are creating multi-tenant applications where you want to dynamically accept users from new directories, you will setup only one connection and enable the Use Common Endpoint toggle. By enabling this flag, Auth0 will redirect users to Azure's common login endpoint, and Azure itself will be doing Home Realm Discovery based on the domain of the email address.

Then choose the protocol. OpenID Connect is the default, and should be selected in the majority of cases. This is independent of the protocol that your application will use to connect to Auth0.

Next complete the App ID Uri field if you intend to use active authentication, as explained in Native Azure AD applications with Auth0.

Click the SAVE button. Auth0 will provide you with a URL that you will need to give to the Azure AD administrator. This URL will allow the administrator to give consent to the application so that users can log in.

Congratulations! You are now ready to accept Microsoft Azure AD users.

Video tutorial

This video tutorial will show you how to integrate Azure Active Directory with Auth0.


  • Make sure you are in the desired directory to add you application. If you do not have an existing directory you will need to create one.

  • When granting access, make sure to use an Incognito/InPrivate window and a Global Administrator user.

  • If you get Access cannot be granted to this service because the service listing is not properly configured by the publisher, try enabling Multi Tenanted in the Windows Azure AD application under Settings -> Properties.

  • If you get an "Failed to obtain access token" error when users try to log in, the most likely reason is an invalid or expired App Key (Client Secret). Application keys in Azure AD can expire so if user suddenly can't log in using an Azure AD connection you should generate a new application key and update the client secret value in the connection configuration.

Signing Key Rollover in Azure Active Directory

Signing keys are used by the identity provider to sign the authentication token it issues, and by the consumer application (Auth0 in this case) to validate the authenticity of the generated token.

For security purposes, Azure AD’s signing key rolls on a periodic basis. If this happens, you do not need to take any action. Auth0 will use the new key automatically.

Using Microsoft Identity Platform (v2.0) endpoints

Microsoft provides two ways to interact with Azure AD endpoints:

  • Azure Active Directory (v1.0)
  • Microsoft identity platform (v2.0)

You can learn about the differences in behavior here.

To change which endpoint Auth0 uses, you can set the 'identity-api' connection option using the Management API. The possible values are azure-active-directory-v1.0 and microsoft-identity-platform-v2.0.

The example below sets it to Identity Platform v2.0, requesting the 'email' scope: