The Azure Active Directory connector supports delta synchronization to speed up Azure Active Directory synchronization. The method is based on the delta query function from Microsoft Graph. It supports the schema types User (user account), Group (group), and DirectoryRole (administrator role). Delta synchronization is not enabled by default. It is a custom setup.
Implementing delta synchronization
-
Set up a regular Azure Active Directory synchronization project.
-
Run initial synchronization.
-
Modify the TargetSystem | AzureAD | DeltaTokenDirectory configuration parameter.
The configuration parameter contains the directory where the delta token files are stored. In the Designer, modify the value of the configuration parameter. Ensure that the One Identity Manager Service user account has write access to the directory.
-
(Optional) Modify the AAD_Organization_DeltaSync process.
The process is made up of three process steps. Each process step handles on of the three supported schema types. Each process step is configured such that it synchronizes all supported delta properties of the schema types. Furthermore, each of these process step adds its own delta token file. The order of process steps is as follows:
-
Synchronize user accounts (Synchronize User process step)
-
Synchronize groups (Synchronize Group process step)
-
Synchronize administration roles (Synchronize DirectoryRole process step)
If customized, ensure that the process is only generated if there is no other similar process is in the Job queue. In the same way, the process may not start during a regular synchronization.
-
-
(Optional) Customize processing scripts for supporting schema types.
-
Process user accounts (AAD_ProcessDeltaQueryUser script)
-
Process groups (AAD_ProcessDeltaQueryGroup script)
-
PRocess administration roles (AAD_ProcessDeltaQueryDirectoryRole script)
The AAD_ProcessDeltaQueryGroup script has had comments added to it to simplify editing and custom development.
-
-
Adjust and enable the Azure Active Directory delta synchronization schedule
The schedule ensures regular delta synchronization of the Azure Active Directory tenants. The schedule is run by default at 15 minute intervals. You can change this interval in the Designer if necessary. Enable the schedule.
The delta synchronization sequence
-
An initial query is run for a schema type (user account, group, administrator role). The initial query returns a complete list for the schema type, such as all user accounts, including the queried properties. This also returns a state token. This token represents the state of the data at the time of the query in Azure Active Directory.
The state token and the queried properties are written to a delta token file. By default, there is no initial processing of the data.
Delta token file storage structure
<Directory in TargetSystem | AzureAD | DeltaTokenDirectory configuration parameter>\<UID_AADOrganization>_<SchemaTyp>Query.token
Example:
C:\Temp\OneIM\DeltaToken\2da43fd4-ce7b-48af-9a00-686e5e3fb8a5_UserQuery.token
-
The rest of the queries use the state token of the previous query. Apart from the new state token, they only return the objects that have changed since the last query.
-
Tries to add new objects if all mandatory properties have been queried.
-
Objects deleted in the target system are generally marked as Outstanding.
Objects that fail during processing are logged in the process step's messages.
The new state token is written in the delta token file.
-
Restrictions
With respect to the stability of repetitions, the difference query method has certain limitations. If a state token has been used once, it is generally invalid and the query cannot be run again. If an error occurs processing the return date, the respective change cannot be loaded until the next time synchronization is scheduled to run. For example, this happens to new group memberships if the member themselves has not been loaded yet.
Another disadvantage is the runtime of the initial query and initial data processing. This process is not recommended. However, because initial processing is meant to be carried out during scheduled synchronization, it is recommended to set the DoNotProcessOffset parameter in the process steps to True (default).
You should also take into account that not all properties can be queried using the Microsoft Graph API delta query.
If the data in the delta token file does not match the calling parameters of a query, the existing file is renamed to <alterName>.backup in order not to lose the state token and a new file is created. In this case, a new initial query is run. This also happens if the file does not exist or is empty.
Supported schema types
The following tables contain the supported schema types and their supported properties. As long as new objects are imported into the database, the mandatory properties in the delta synchronization must be queried.
Property |
Mandatory |
Remark |
---|---|---|
AccountEnabled |
|
|
AgeGroup |
|
|
BusinessPhones |
|
|
City |
|
|
CompanyName |
|
|
ConsentProvidedForMinor |
|
|
Country |
|
|
Department |
|
|
DisplayName |
X |
|
ExternalUserState |
|
|
ExternalUserStateChangeDateTime |
|
|
GivenName |
|
|
ID |
X |
|
JobTitle |
|
|
LastPasswordChangeDateTime |
|
|
LegalAgeGroupClassification |
|
|
Licenses |
|
When this property is queried, another query runs about the user account's assignment status (LicenseAssignmentStates). This increases the runtime massively. Contains a list of objects with the DisabledPlans, SkuId, AssignedByGroup, State, and Error properties. |
|
|
|
MailNickname |
|
|
Manager |
|
|
MobilePhone |
|
|
OfficeLocation |
|
|
OnPremisesDistinguishedName |
|
|
OnPremisesDomainName |
|
|
OnPremisesImmutableId |
|
|
OnPremisesLastSyncDateTime |
|
|
OnPremisesSamAccountName |
|
|
OnPremisesSecurityIdentifier |
|
|
OnPremisesSyncEnabled |
|
|
OnPremisesUserPrincipalName |
|
|
PostalCode |
|
|
PreferredLanguage |
|
|
ProxyAddresses |
|
|
State |
|
|
StreetAddress |
|
|
Surname |
|
|
UsageLocation |
|
|
UserDomain |
x |
|
UserPrincipalName |
x |
|
UserType |
x |
|
Property |
Mandatory |
Remark |
---|---|---|
Description |
|
|
DisplayName |
x |
|
GroupTypes |
x |
|
ID |
x |
|
Licenses |
|
Contains a list of objects with the DisabledPlans and SkuId properties. |
|
|
|
MailEnabled |
x |
|
MailNickName |
x |
|
Members |
|
The property is not available in an initial query. The result contains the schema type and the ID. |
OnPremisesSecurityIdentifier |
|
|
OnPremisesSyncEnabled |
|
|
Owners |
|
The property is not available in an initial query. The result contains the schema type and the ID. |
ProxyAddresses |
|
|
SecurityEnabled |
x |
|
Property |
Mandatory |
Remark |
---|---|---|
Description |
|
|
DisplayName |
x |
|
ID |
x |
|
Members |
|
The property is not available in an initial query. The result contains the schema type and the ID. |