OAuth with Auth0 and Azure AD as identity provider

To be able to use Azure Active Directory as an Identity Provider, we use Auth0 as middleware to connect to Azure Active Directory.
Your Planviewer API Application uses Auth0 as authorization server, wich in turn connects to Azure Active Directory to authenticate and authorize your users.
In this howto:
  • We configure an Auth0 “Microsoft Azure AD” connection and register that as “registered app” in your Azure Active Directory.
  • We create an Auth0 Application and configure that to use the “Microsoft Azure AD” connection as Identity Provider
  • We configure a Planviewer Application to use Auth0 as authorization server.

Note

In this walkthrough we use Auth0 as an example. other authentication services may use a different setup.
Please consult their documentation for implementation.

The “registered app” for the Auth0 “Microsoft Azure AD” connection, needs the following “Delegated permissions” for the “Microsoft Graph” API, to operate correctly.

Required API Permissions
Microsoft API Delegated Permissions  
Microsoft Graph User.Read Sign in and read user profile
Azure Active Directory Graph Directory.AccessAsUser.All Access directory as the signed in user
Azure Active Directory Graph Directory.Read.All Read directory data

You need a (free) Auth0 account and an Azure portal administrative account to continue. You need an Auth0 Tenant and it’s Domain.

Note

When you create an Auth0 account, you will also get a default Tenant,

Prepare an app registration in Azure Active Directory

Create a new Azure AD app registration
go to Azure Active Directory registered apps
create a new registration.
leave Redirect URI for now, we’ll create one later.
Create a Client secret to authenticate your Auth0 connection with
go to Azure Active Directory registered apps
select the app
go to “Certificates & secrets”
create a new Client Secret

Warning

Copy the secret value, it is only shown once

Note

If you are unsure what to choose for expire, choose never
Grant the registered app API Permissions to access data in your directory
go to Azure Active Directory registered apps
select the app
go to “API permissions”
../../_images/azure-api-permissions.png

Note

You need to have administrative permissions for this action, or have an admistrator
grant the permissions.
Even as administrator you need to grant the permissions.
Microsoft API Delegated Permissions  
Microsoft Graph User.Read Sign in and read user profile
Azure Active Directory Graph Directory.AccessAsUser.All Access directory as the signed in user
Azure Active Directory Graph Directory.Read.All Read directory data
Configure the registered app to accept Auth0 callback URL
Go to Azure Active Directory registered apps
Select the app
Go to Authentication
Create a new “Redirect URI”, type: Web, with value “<auth0-tenant-domain>/login/callback”
../../_images/azure-authentication.png

Note

The tenant can be found in Auth0.
Your default tenant domain looks like your-tenant-name.eu.auth0.com
If you have a custom domain, use that as <auth0-tenant-domain>
You can find your current domain under Tenant Settings - Custom Domains.

Connect your Planviewer Application

Create an Auth0 Application
Choose: Regular Web Application
Enable your Auth0 Application to use “Microsoft Azure AD” connection
Go to Connections, enable your “Microsoft Azure AD” connection configured earlier.
Configure Allowed Callback URL
Go to Planviewer Api Applications - “Algemeen en Beveiliging”
Make a note of your <application-id> it is the last number in the URL https://planviewer.nl/my_api/applications/37
Go to your Auth0 Application - Settings
In the field “Allowed Callback URL” add the following URL with your application-id https://www.planviewer.nl/maps_api/v2/oauth/<application-id>/callback
../../_images/auth0-callback.png
Configure your Planviewer Application to use Auth0
Open your Auth0 application - Settings
Go to Planviewer Api Applications
Select “Algemeen en Beveiliging”
Choose “Beveiliging en toegang”
Select “Bewerk OAuth gegevens”
Fill in the settings with the following values
OAuth instelling value from Auth0 Application
Client Id Client ID
Client Secret Client Secret
Authorisatie URL https://<auth0-tenant-domain>/authorize
Access Token URL https://<auth0-tenant-domain>/oauth/token
Resource URL https://example.com/resourse.json

Note

You need to use the Client Id and the Client secret from Auth0

Note

The resource URL is a file which must be accessible on the internet, with the following structure:
{
    "id": "1",
    "username": "planviewer",
    "email": "info@planviewer.nl"
}

And should be accessible like https://example.com/resourse.json. The values should be changed to your own values.

Configure an Auth0 “Microsoft Azure AD” Connection

Create an Auth0 “Microsoft Azure AD” Connection
in Auth0.com
Go to Connections
Select Enterprise
Choose Microsoft Azure AD
Select Add

Note

Can’t find “Microsoft Azure AD” connection?
It’s on the bottom of the list, sometimes it takes a few seconds to appear.

Fill in the settings with the following values

Connection setting value from Azure AD
Client ID “Application (client) ID” from Azure Active Directory registered apps
Client Secret Client secret value you copied
Azure AD Domain shown on Azure Active Directory dashboard
../../_images/auth0-connection.png
Test the “Microsoft Azure AD” Connection
go to Connections -> Enterprise -> Microsoft Azure AD - Manage
Click “Try” next to your new Connection
Login with your Azure administrative account
review and authorize the requested permissions
You should see a page with a succes result

Note

An administrator must allow a connection between Azure and Auth0.
If you get an error message from azure, about not having administrative rights,
it means that the connection works and can be used with a planviewer application.

Note

For a complete guide from Auth0, see: Connect your app to Microsoft Azure Active Directory

Go to your Planviewer Application and open a Viewer, you should see a login box