You can synchronize your users using Microsoft Graph as a user directory.

Configuration in Microsoft Azure

First, an app must be registered via the Microsoft Azure portal.

The following permissions must be configured for Microsoft Graph within the API Permissions settings in Azure:

To learn how to set permissions for apps in Azure, see this article.

Note:

The permissions in Azure can only be assigned by an administrator. Therefore, you need the consent and help of an Azure administrator for this configuration.

Please refer to this Part 1 tutorial video on how to set up the required app for a Microsoft Graph user directory (including OpenId authentication for Microsoft 365). Part 2 can be found below.

Configuration in Haiilo

1. Connection
2. User
3. Groups
4. Synchronization
5. Scheduling

Connection

Please refer to this Part 2 tutorial video on how to set up the Microsoft Graph user directory (including OpenId authentication for Microsoft 365) inside Haiilo. Part 1 can be found above.

To connect to Azure, you need to enter the client ID, client secret, and tenant from the Azure app.

User

Then you need to enter the attribute for username in the "User" tab. We recommend using "mail" or "userPrincipalName" here.

For user filters, you can use the standard Microsoft Graph filters. For example, a filter on all users whose name starts with "Dennis" in MS Graph looks like this:

startswith(displayName,'Dennis')

Note:

It is recommended to leave the user filter empty and to use the group filter in the tab "Groups", because this way a more precise filtering is possible. You will learn how to do this below.

If you also want to synchronize superiors, you have to check the option "Sync managers". You can find more information here.

The profile field mapping of a user can be somewhat complex because the MS Graph API responds with JSON objects that can contain nested data. This requires the use of a more complex field address syntax. We chose JSONPath, which allows access to nested or indexed properties and also the use of predicates, which are useful for extension selection.

Note:

MS Graph also requires that you specify in the query which properties the call should return. This is done by passing a list of fields in the $select or $expand parameters. A simple field name is automatically inserted verbatim into the $select clause of the MS Graph API query. The new syntax accepts the select/expand clause as an optional second part of the expression.

The previous simple field syntax is still valid and can also be used.

For the additional field mapping the syntax is as follows:

<jsonpath>[:select/expand- clause]

Please pay attention to the following syntax:

1. The JSONPath must start with $. to be recognized as new JSONPath syntax
2. If the JSONPath contains a colon, the colon must be masked with a backslash
3. If the JSONPath selects more than one entry, only the first one is returned
4. The selected value is converted to a string
5. A missing value leads to an empty profile field

The path may optionally be followed by a colon (the colon must not be masked with a backslash here) and the select/expand clause corresponding to an entry of the $select or $expand parameter above. Only if the value is extensions, the query parameter $expand=extensions is added. Any other value is interpreted as an entry for the $select field list. It is recommended to configure the select/expand clause to ensure that the API response contains the required field.

Examples of syntax for profile fields assignment

$.aboutMe:aboutMe

This expression adds the $select=aboutMe parameter to the query. The JSONPath part will select the aboutMe property from the query result. This expression is equivalent to the aboutMe simple field expression.

$.employeeOrgData.division:employeeOrgData

This expression adds the $select=employeeOrgData parameter to the query. The JSONPath part selects the nested property division of the root employeeOrgData property. This expression has no equivalent in a simple field expression because it is not possible to select nested properties in this way.

$.extensions[?(@.id=='com.haiilo')].nested.prop1:extensions

This expression adds the $expand=extensions parameter to the query. The JSONPath part selects the first extension inside the root object, which has a property id with value com.haiilo. From this extension, the nested property nested.prop1 is selected.

The API response is not known until the synchronization job (sync job) is executed, so it is not known what a valid JSONPath expression actually selects.

We currently recommend administrators to query the Microsoft Graph API manually with a tool like Postman, copy the JSON response into a JSONPath evaluation tool and find out there what the expression returns.

The rest of the configuration works exactly as you know it from the configuration of a user directory.

Groups

To activate the synchronization of groups in general, you must first check the "Synchronize Groups" option.

Then the options for group filter and "Users from groups only" are enabled.

For group filters you can use the standard Microsoft Graph filters. For example, a filter on all groups that start with "Haiilo" in MS Graph looks like this:

startswith(displayName, 'Haiilo')

The "Users from groups only" option also ensures that users are only synchronized if they are part of a synchronized group.

Synchronization

In this tab you can make settings for synchronization. 

The value in Page Size defines how many elements should be synchronized per query. The LDAP protocol limit is 1000, so you should not select a higher value.

The Activation option allows new and recovered users to be activated during synchronization. Otherwise, you would have to manually set the status of the users to "Active" in the user management.

Note:

If you have enabled terms of use in administration, the new and restored users will remain on "Hidden" until they accept it.

Orphaned users are users that currently exist as active users, but no longer exist in the LDAP directory. There is an option to ignore, disable or delete users in Haiilo during sync.

The restore users option allows deactivated or deleted users from Haiilo to be reactivated if they exist again in the user directory at sync.

Note:

It is not possible to restore anonymized users. The previously anonymized user can then only be created as a new user. Anonymization is disabled by default and can be enabled in the "General settings" of the administration.

Scheduling

Here you can configure the regularity of synchronization. You have the options once a day (at night), several times a day (every four hours) and once an hour.