User directory: Microsoft Graph

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

1. Configuration in Microsoft Azure
2. Configuration in Haiilo Home

Configuration in Microsoft Azure

An app must be registered via the Microsoft Azure portal.

The app must then have the API permissions "Group.Read.All" and "User.Read.All" (type application). To learn how to set permissions for apps in Azure, see this article.

Note:

These permissions can only be assigned by an administrator. Therefore, the consent of the administrator is required in this configuration.

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

Configuration in Haiilo Home

Within Haiilo Home, the configuration is initially very similar to the standard configuration. You can find it explained here.

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

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

For user filters you can use the Microsoft Graph Filters. To write and test your own filters, Microsoft Graph Explorer is recommended.

Note:

Some filter parameters do not work with the Graph API as you would expect. For example, the query function endsWith(mail,'@coyo4.com') does not work with the /users endpoint.

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

Simple expression

$.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.

Nested properties

$.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.

Predicates

$.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.

Test expressions

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.