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

1. Set up a regular Azure Active Directory synchronization project.

2. Run initial synchronization.

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

4. (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.

5. (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.

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

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

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

Table 6: Supported properties for user accounts (schema type: User)

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

Table 7: Supported properties for groups (schema type: Group)

Property	Mandatory	Remark
Description
DisplayName	x
GroupTypes	x
ID	x
Licenses		Contains a list of objects with the DisabledPlans and SkuId properties.
Mail
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

Table 8: Support properties for administration role (schema type: DirectoryRole)

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.