Preamble

This is the setup process for Microsoft Azure AD to work with Maintenance Connection products and Maintenance Connection LoginHub. If you want to use SCIM or Azure AD Automatic Account Provisioning there is a different document you should be using.

Please note that authentication & authorization is a complex process that includes lots of double checks and encryption, attention must be carefully paid to each part of the process since seemingly minor things can cause decryption failures or cause a security double check to not pass. These failures often require billable support time since they end up needing to tie up some of the most technically knowledgeable in order to diagnose very tiny settings differences that are hard to identify.

Setting Up For Login

As of April 2019 this process is using the App Registrations UI that is currently listed as (Preview).

You will need to setup an Application in the Azure Portal. Microsoft has documented this process at: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app

The Redirect URI you will need to enter when registering the application is: https://one.loginhub.app/signin-oidc

The following data must be provided/collected in order for proper login to be successful:

Domain
Tenant ID
Client ID
Client Secret
Client Secret expiration date
URL that LoginHub is installed at (eg. https://example.com/mc_web/)

Registered applications will require the following changes made or confirmed:

Redirect URLs

Go to Manage -> Authentication and Add a Web redirect URL. The value must be: https://one.loginhub.app/signin-oidc

Implicit Grant

Implicit Grant must be turned on for both "Access tokens" and "ID tokens".

Client Secrets

Go to Manage -> Certificates & Secrets. Add a new Client Secret. Microsoft will generate a new Client Secrete for you. Ensure you copy/paste the secret displayed, Azure will never display it to you again and a new secret will need to be generated. Also capture the expiry date Microsoft gives you since it will be required to generate a new secret before it expires or LoginHub will stop logging users in.

Azure Graph

(optional, recommended¹) To enhance a user with details from Azure Graph that are not provided by via a normal user login token. Go to Manage -> API Permissions. Add a Microsoft Graph permission.

The following permissions should be granted:

email
profile
penid

Grant Consent

(optional, recommended²) If you don't want to bother users while logging in with a consent permissions screen (at least once per user logging in), you can grant consent for ALL users.

Go to Manager -> API Permissions. Select "Grant admin consent for <your directory name>"

Troubleshooting

User is not assigned a role for the application

This means you are not allowed to login to the application. There are 2 solutions:

Setup Azure Graph so that the users roles can be queried during login
Add role information to the data that is sent to LoginHub automatically during login. This must be done carefully because it may overload the cookie and throw errors for users with too many groups.

Users are always asked for consent (Permissions requested)

Follow the instructions above to "Grant Consent" by an administrator for all users.

New API Permissions granted but existing users aren't working

When API Permissions change Azure requires you revoke the consent for existing users and re-do the consent. It won't do this automatically for you.

1: If you are unsure – try it one way, then try it the other way, then come back and decide. ↩
2: If you are unsure – try it one way, then try it the other way, then come back and decide. ↩