Integrate with Microsoft

In case your company uses Office 365, your corporate address book resides in Azure AD.
Which is great, because you can integrate Azure AD with Federated Directory.

Integration is possible in two ways and it works best when you enable both.


Authentication

The login chapter describes how users can log in with their Microsoft account. Enabling this, is a two step process.

1 Select Microsoft accounts as the authentication method on a directory.

Set authentication to Microsoft

2 In your Azure AD portal, add the Federated Directory application from the gallery. Go to: https://aad.portal.azure.com → Enterprise applications → New application. And search for Federated Directory

We only allow access to those that have been created in this directory. During the authentication process we map the users Azure AD user principle name (upn) with the userName of this user in our directory. The upn of a user is usually the email address, used during the login process.

Azure AD Federated Directory
Attribute mapping upn userName ️️

So make sure these are filled in correctly. The best and easiest way to do that, is to let Azure AD do this and enable automatic user management


Automatic user management

Azure Active Directory (Azure AD) allows you to automate the creation, maintenance, and removal of user identities in your Federated Directory. Microsoft calls it: automatic provisioning and you can read all about it here: https://docs.microsoft.com/en-us/azure/active-directory/active-directory-saas-app-provisioning

Please note, you need an Azure AD Premium license for this. (free trial available)

The setup consists out of 4 steps: Setup automatic user management with Azure AD in 4 steps Step one and two (blue) are performed in Federated Directory and steps three and four (orange) in Azure AD.


1. Create a directory

Create a new directory or select an existing directory that will be integrated with your Azure AD. Set automatic user management to Azure AD.

More details about creating a directory can be found in the directory introduction.


2. Create a directory key

A directory key can be seen as a user with the admin role, however limited to the directory it was created in. So a directory key can only manage users in that specific directory. A directory key is made for integrations on a directory level.

To generate a directory key, open the directory you just created and go to the keys tab.
Select the orange '+' plus button at the bottom right.

Create a new directory key button

A dialog opens in which you can configure your new directory key. It might be good to know that you can always change these settings later on.

Input Description
Name Give your new directory key a name, to make it easily recognizable. Max 100 characters.
Description Optionally, give your new directory key a description. Max 250 characters.

After creation, copy your access token and store it somewhere safe, you will need it in the final step. For security reasons, we only show you this access token directly after the creation of the new key.


3. Add a new enterprise application

Login to your Azure AD portalEnterprise applicationsNew application.

Select the option to create a Non-gallery application and give it a name ('Federated Directory' for example).


4. Configure automatic user provisioning

When the application is created, go to provisioning. Switch the provisioning mode to Automatic.

Press Save and Microsoft will verify the settings, before you can continue to the next steps.

Disable the synchronization of Groups.
We don't use any groups data so make sure it is disabled in your Azure AD provisioning settings. You can do this below the Mappings settings.

Last but not least you will have to enable the Provisioning Status and set the Scope to "Sync all users and groups".

Azure AD provisioning configuration

Save the settings again and your integration is done!


Configure which user data will be synced

You can limit the data that you sync to us (optional). This can be done on two levels:

  1. Only provision a subset of your Azure AD users to Federated Directory
  2. Decide which user attributes to sync

1. Change the user scope In step 4 we set the scope to 'Sync all users and groups", which provisions all users in your Azure AD to us. But if you want to have a bit more control of which users gets synced, switch the scope to: "Sync only assigned users and groups". This way, you first have to assign a user to Federated Directory in Azure AD, in order to trigger the provisioning.

2. Decide which user attributes to sync Open the attribute mapping settings of the users. You will see all the attributes that are being pushed to your Federated Directory. Every attribute you remove from this list, will not be synced to us. There are only 2 SCIM attributes mandatory on a user:

  1. userName
  2. displayName

Troubleshooting

It can take up to 15 minutes, before Azure AD pushes a user to your Federated Directory. If a user or an update on a user still isn't synced after 30 minutes, perform the next steps.

Check the 'Synchronization Details' at the bottom of the provisioning page in Azure AD. It shows you the date and the time of the last synchronization and if there were any errors. Also follow the link to the Azure Audit logs.

Check your configuration:

  • Is provisioning enabled?
  • Is the attribute mapping correct? (Reset to default if needed)
  • Is provisioning of groups disabled?
  • Do the values within the user attributes comply with our requirements?

You can always trigger a new, complete synchronization from Azure to Federated Directory. Check the option: "Clear current state and restart synchronization". This could take a while. Especially if you have a lot of users in your Azure AD.

Still need help? Get in touch!
Last updated on 24th Mar 2019