Preamble

This is the setup process for Microsoft Azure AD and Azure AD Automatic Account Provisioning to work with Maintenance Connection products and Maintenance Connection LoginHub.

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.

SCIM Setup Process

As of April 2019 Microsoft has the setup process documented at: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups

Data/Details Required During Setup

Tenant URL: https://one.loginhub.app/scim/v2/

Secret Token will be provided by your MC Support representative. This CANNOT be left blank. This is your secret token to be used in your setup, you cannot use someone else's. Very rarely this will change in particular due to changes Microsoft makes and we will in that event provide you with a new Secret Token.

Syncing of groups is required. Users that do not have a group are currently unsupported in Maintenance Connection.

Notes

• As of April 2019 there are bugs in Microsoft's code, acknowledged by Microsoft, setting up the Provisioning features of Azure. It may be required to re-enter the URL and Token a few times with saving before it actually properly saves and allows you to activate provisioning. We have opened some bugs with Microsoft support related to these problems, if they cause you issues, you may want to contact Microsoft support as well¹.
• As above, if you see failure messages in the Audit Log it is usually Azure deleting the secret token and breaking the sync. You will need to re-enter the secret token again to fix the sync.
• Most (over 50%) of the document by Microsoft details the HOW of building your own SCIM service. Since this has already been completed by Maintenance Connection Canada's LoginHub you don't need to dwell on the details unless you want to. Everything from "Understanding the Azure AD SCIM implementation" to the end of the document is technical implementation details that are not required.
• The initial sync can take a long time.
• The Azure logs appear to be delayed by at least 5 minutes. Don't rely on them for determining if something is actually happening *now* due to the delay.

Setting Up For Login

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

The SCIM setup process will have automatically registered an Application in the Azure Portal. To see what the manual registration process is: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app

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/)

Automatically registered applications will require the following changes made:

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:

1. Assign the user in Enterprise Applications  <the application>  Users and groups
2. Disable user assignment required in Enterprise Applications  <the application>  Properties. Set "User assignment required?" to No.

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.