Microsoft configuration
An app must be registered via the Azure Portal > app registrations. The app needs to have the application (type application) API permissions "Group.Read.All" and "User.Read.All". In addition, application permissions can only be consented by an administrator. Thus, the administrator approval in the permission configuration is required. You can check this article on how to do give permissions for Haiilo.
The following permissions must be configured for MS Graph within the Azure AD - API permissions settings:
| API / Permissions Name | Type |
| Group.Read.All | Application |
| User.Read.All | Application |
| User.Read | Delegated |
Haiilo configuration
Within Haiilo, the configuration is very similar to the LDAP protocol. Under the administration, you choose the tab "User directories" and select "Microsoft Graph" for type.
The following fields need to be configured to establish the connection. The tenant identifier can be found in Azure portal > Properties:
In the tab "User", it can be decided to use "mail" or "userPrincipalName" as the users' identifier:
To filter users and groups you can use Microsoft Graph filters.
Example:
Filter all groups starting with 'COYO_'.
startsWith(displayName, 'COYO_')
To write and test your own filters, Microsoft Graph Explorer is recommended.
Hint:
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.
This is an issue on Microsoft side, which we unfortunately can't fix.
The rest of the config works exactly as you know it from configuring your user sync e.g. via LDAP-protocol.
MS Graph user profile field mapping syntax
A user’s profile field mapping is usually configured by specifying a plain field name.
The MS Graph API however 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 accessing nested or indexed properties and also the use of predicates, which are useful for selecting extensions.
MS Graph also requires to state in the query which properties the call should return. This is done by passing a field list in either the $select or $expand parameters. A plain field name is automatically added verbatim to the $select clause of the MS Graph API query. The new syntax will accept the select/expand clause as an optional second part of the expression.
Syntax
The usual field syntax is still valid and the syntax for the additional field mapping looks like this:
<jsonpath>[:select/expand- clause]Please be aware of the following infos:
- The JSONPath must start with
$.to be recognized as the new JSONPath syntax - If the JSONPath contains a colon the colon must be escaped with a backslash
- If the JSONPath selects more than one entry, only the first will be returned
- The selected value will be converted to a string
- A missing value will result in an empty profile field
The path can optionally be followed by a colon (do not escape this colon) and the select/expand clause which corresponds to an entry of the above mentioned $select or $expand parameter. Only If the value is extensions, the query parameter $expand=extensions will be added. Every other value will be interpreted as an entry for the $select field list. It is recommended to configure the select/expand clause to ensure that the API response will contain the required field.
Examples
Simple expression
$.aboutMe:aboutMeThis expression will add the parameter $select=aboutMe to the query. The JSONPath part will select the property aboutMe from the query result. This expression is equivalent to the plain field expression aboutMe.
Nested properties
$.employeeOrgData.division:employeeOrgDataThis expression will add the parameter $select=employeeOrgData to the query. The JSONPath part will select the nested property division of the root property employeeOrgData. This expression does not have a plain field expression equivalent since it is not possible to select nested properties that way.
Predicates
$.extensions[?(@.id=='com.haiilo')].nested.prop1:extensionsThis expression will add the parameter $expand=extensions to the query. The JSONPath part will select the first extension object inside the root object that has a property id having the value com.haiilo. From this extension the nested property nested.prop1 is selected.
Testing expressions
The API response is unknown until the synchronisation job is running, so it is unknown what a valid JSONPath expression will actually select. We currently advise administrators to query the MS Graph API manually with a tool like Postman, copy the response JSON to a JSONPath evaluation tool like JSONPath Online Evaluator and find out there what the expression returns.
Hint:
Take precautions to not violate data protection laws by copying sensitive user data to public online tools!