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. .. table:: 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" .. image:: ../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 "/login/callback" .. image:: ../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 | 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 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//callback`` .. image:: ../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:///authorize`` Access Token URL ``https:///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: .. sourcecode:: json { "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`_ =========================== =============================================== .. image:: ../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 .. _Auth0: https://auth0.com .. _Azure portal: https://portal.azure.com/#home .. _Azure Active Directory registered apps: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps .. _Azure Active Directory dashboard: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview .. _Connect your app to Microsoft Azure Active Directory: https://auth0.com/docs/connections/enterprise/azure-active-directory/v2 .. _Planviewer Api Applications: https://www.planviewer.nl/my_api/applications