Microsoft Entra ID Synchronization

If you use Microsoft Entra ID to manage your users, here is how to do to set-up a seamless user synchronisation with Ziik.

Topics in this article

How the User synchronisation works

Requirements in Ziik

Requirements in your Microsoft Entra ID

Setting up the integration in Microsoft Entra ID

Setting-up the integration in Ziik

Synchronized data

Integration inner workings

---

How the User synchronisation works

The purpose of the integration is to automate the synchronization of users from Microsoft Entra ID to Ziik. The integration automatically creates, updates, and deletes users in Ziik in accordance with the users present within Microsoft Entra ID. The integration can also be configured to synchronize memberships for the imported users.

The integration is scheduled to run hourly. This means that users will be synchronized with a maximum delay of 60 minutes from when the change was made in Microsoft Entra.

---

Requirements in Ziik

You need to be a platform administrator to set-up integrations in Ziik. Go to the Integrations via the admin cogwheel and select Microsoft Entra ID User Sync. 

---

Requirements in your Microsoft Entra

You will need permissions to create a new App Registration with the ability to grant admin consent.

---

Setting-up the integration in Microsoft Entra

 

1. Create App Registration in Microsoft Entra

The App Registration is used by Ziik to communicate with Microsoft Entra.

1. 1. Navigate to “App registrations” in the left sidebar under “Applications”
   2. Click on “New registration”
   3. Fill in a name for the application. We recommend that you name it something like “Ziik Microsoft Entra User Sync” so it’s easy to know what the purpose of the application is at a later point.
   4. Choose “Accounts in this organizational directory only (Single tenant)” for the account type
   5. Register the application

2. Assign permissions
This step is about assigning the required permissions to the application. The permissions needed depend on which users you want to import.

a. To add the permissions, navigate to “API permissions” within the created applicationb. Click on “Add a permissions”

c. Click on “Microsoft Graph”

d. Select “Application permissions”

e. Find and select the permissions needed (based on table below)

f. Click on “Grant admin consent for X”

Permissions - We want to import all users

User.Read.All - Used to read all users

Permissions - We want to limit import to users in certain groups

User.Read.All - Used to read all users

Group.Read.All - Used to read all groups

 

3. Configure API credentials

a. Navigate to “Certificates & secrets” within the created application

b. Click on “Client secrets”

c. Click on “New client secret”

d. Fill in a description for the client secret. We recommend something like “Ziik client secret”

e. Select an option for when the client secret should expire. (Preferably before this date gets hit, you'll want to create another secret, then switch your Ziik integration to using the new one.)

f. Make sure to save the client secrets “value”, as Microsoft Entra will never show the value again and you’ll need to supply it to Ziik

We're ready to set up the integration in Ziik.

---

Setting-up the integration in Ziik
 

1. Fill out the form:

Name - Name your Microsoft Entra User Synchronisation. The name will appear in the integration list in Ziik.

Application ID - Insert the Application (client) ID belonging to the App registration in Entra.

Tenant ID - Insert the Directory (tenant) ID for your Microsoft Entra.

Secret - The "value" part of the "Client Secret" which we created for the App Registration in Entra earlier, which contains the secret used to access MS Graph.

Unit - Users' permissions in Ziik are determined by their “unit” and “role” relationship. Users without an assigned “unit” and “role” will not see anything in Ziik. It is therefore essential to match these fields in Ziik.

A user’s “unit” in Ziik can be matched from one of the following fields on the user in Microsoft Entra:

• JobTitle
• CompanyName
• Department
• Street Address
• State
• Country
• Office Location
• City
• Postal Code
• Employee type

Role - Users' permissions in Ziik are determined by their “unit” and “role” relationship. Users without an assigned “unit” and “role” will not see anything in Ziik. It is therefore essential to match these fields in Ziik.

A user’s “roles” in Ziik can be matched from one of the following fields on the user in Microsoft Entra:

• JobTitle
• CompanyName
• Department
• Street Address
• State
• Country
• Office Location
• City
• Postal Code
• Employee type

It is possible to assign more than one role to a user I Ziik. This can be done in Microsoft Entra with a comma separated list of roles. The user will then get all roles with a match in Ziik, in the unit given.

 

Import mode - This setting is used to specify which users to import. There are two different modes; all and groups. The group option is only available if the required permissions have been granted for the App registration in Microsoft Entra.

If you only want to import users from certain groups in Microsoft Entra, you can select the group option and then proceed to select the groups you want to synchronize users from.

Exclude unassignable - This setting is used to ignore importing users from Microsoft Entra if we weren't able to assign a membership to the user. If the setting is disabled, users without memberships will still be imported but placed under “Unassigned” in the user administration.

Finally, you’re ready to create the integration. You can click “Synchronize” on the newly created integration to enforce synchronisation. You can also enable automatic synchronisation by enabling the integration. When enabled, synchronisation will happen hourly as previously explained.

---

Synchronized data

The following data is synchronized for all users created, updated, and deleted through the integration:

• User’s first name
• User’s last name
• User’s email address
• User’s status
• User’s reference
• User’s memberships

---

Integration inner workings

Importing users from Microsoft Entra ID

New users created in Microsoft Entra ID will be synchronised to Ziik if they:

• Have a first name
• Have a last name
• Have an email

If “Ignore unassignable” is enabled for the integration, a valid membership is required to import a user. If we weren’t able to assign a complete membership to the user based on their properties in Microsoft Entra, the user will be ignored and only imported once all requirements have been met. If the integration is configured to only import users from certain groups, then the user must also be part of at least one of the selected groups.

• If a user’s email already exists in Ziik, the user will be ignored and not imported
• If multiple users have the same email address within Microsoft Entra, only the first one will be imported and the second one will be ignored
• New users will be assigned the default platform language set in Ziik

Synchronization of memberships:

• All memberships created by the integration, will be linked
• If you add a role to a membership that was created through the integration, the integration will not overwrite the change.
• If you remove a role in a membership that was created through the integration, the role will not be restored/replaced by the integration

Updating users from Microsoft Entra

When a user is updated in Microsoft Entra, the user is also updated in Ziik. However, there are a few pitfalls to consider.

• Users not considered valid, will be deleted. Users are considered invalid when they’re missing first name, last name, or email.
• If the integration only imports users from certain groups, the user will also be deleted if the user has been removed from all of the selected groups.

Synchronization of memberships:

• If a membership created through the integration is updated in Microsoft Entra, placing a user in a different unit, the new unit membership will replace the old one in Ziik
• If a membership created through the integration is updated in Microsoft Entra, placing a user in a unit that they already have been assigned to manually in Ziik, the membership will be linked and any additional roles will be added to the existing membership
• If a membership created through the integration has been updated in Microsoft Entra, changing a user's set of roles, only the roles previously created by the integration are subject to removal. Any roles assigned manually in Ziik need to be deleted manually.
• If a linked membership is manually deleted in Ziik, the membership will automatically be recreated the next time the integration runs.
• If a linked user, with only manually created memberships, is updated such that the user should be placed in another unit, an additional membership will be created with the assigned roles.
• If roles in a membership that was created through the integration are changed manually in Ziik, the integration will not overwrite the changes

Delete users in Microsoft Entra

When users are deleted in Microsoft Entra, the user is deactivated in Ziik and marked to be deleted in 90 dayhaha12s. These users can be viewed in the user administration panel.