This document will describe how to set up user and group syncing between Azure AD and Zinc.
- Create the Zinc enterprise application in Azure - this provides connectivity to Zinc.
- Configure the user attributes - this configures mappings to work with Zinc.
- Configure the user scoping filters - this allows the customer to define which users are synchronized with Zinc.
- Configure the group attributes and configure the group scoping filters
- Start provisioning and monitor progress.
- Any existing Zinc enterprise application must be removed. Prior to removing this application, please note any scoping filters (users and/or groups) used by the application as these will need to be transferred to the new application created below.
Create the Zinc enterprise application
Open the Azure portal at https://portal.azure.com/, and you should see something like this:
Select the 'Azure Active Directory' from the main navigation on the left. If the link is not visible in the menu, select 'more services' and search for 'Azure Active Directory'.
In your directory default view, select 'Enterprise Applications' and then 'All Applications' to view your current application list.
Create a new application by clicking '+ New Application' link in the top menu.
If you already have an application connected to Zinc, you can skip this step and just configure the existing application.
In the 'Add an Application' view, select 'Non-Gallery Application'.
Enter the name for your application and click 'Add'. Wait for a notification telling you your new application is ready to be configured. You should be redirected to the application settings page, but if that doesn't happen you can always find your new application from your 'All Applications' list.
Configuring the application
Navigate to your new application's settings - the view looks like this:
- Select 'Provisioning' from the left side menu
- Change the 'Provisioning Mode' to 'automatic'. This will reveal all configuration fields for automatic user and group provisioning.
Configuring Admin credentials
- Fill up tenant URL and Secret Token fields and test the connection by clicking 'Test Connection' button.
- After you get notified that the supplied credentials are authorized, save your credentials by clicking 'save' button.
After the credentials are saved successfully, you're able to edit application attribute mappings and other provisioning settings.
User and Group attribute mappings
Its necessary to map User and Group object attributes correctly so correct names will get synced to Zinc. You can edit the attribute mappings and enable/disable user or group sync in the 'Mappings' section of the settings.
In the mappings section, click 'Synchronize Azure Active Directory Users to customappsso' to open User attribute mapping view.
- Make sure user sync is 'Enabled'
Zinc API currently consumes following fields and they must be mapped correctly:
- externalId - User's email address (required)
- userName - User's full name
- name.giveName - User's first name
- name.familyName - User's last name
The value of 'externalId' must be the user's email address - 'mailNickName' seems to work with default Azure AD mappings but depending on your setup, you might need to map the source attribute to 'mail' or some other field which has the user's email.
When you click any attribute in the attribute mapping list, you'll be able to edit the attribute and select a source attribute and its target attribute.
In the mappings section, click 'Synchronize Azure Active Directory Groups to customappsso' to open Group attribute mapping view.
- Enable group sync if groups should be synced.
- 'externalId' must be mapped to Azure 'objectId'
- 'displayName' should be mapped to 'displayName'
Filtering Users and Groups
You're able to control which users and groups will get synced to Zinc with filters. You might not need to create them at all, but you might want to apply some filtering first and test the AD sync features with a small subset of users and groups first - This way you'll ensure that your attribute mappings are correct and the user provisioning works correctly.
You can define the scope for User and Group syncing In the application Settings section.
- If you select 'Sync only assigned users and groups', only users and groups assigned to this application will get synced.
- If you select 'Sync all Users and Groups' your whole AD directory will get synced to Zinc.
Refining the sync scope with filters
If the default syncing scope is not detailed enough, it is possible to filter the Users and Groups which will get synced to Zinc using filters.
Select 'Source Object Scope' from Group or User attribute mapping view:
To add a new filter for users or groups, Click 'Add scoping filter'
Every attribute on a User or Group object can be matched with a logical operator - for example 'isPublic = IS TRUE' means that only groups with 'isPublic' field set to true will get synced to Zinc.
After you've added new Scoping Clauses give the scoping filter a title and save it by clicking 'OK'.
Add Users and Groups
You can add and edit the users and groups assigned to your application by selecting 'Users and Groups' from you application's settings:
Remember that your User / Group scope filtering settings will have an effect how the Users / Groups will get synced to Zinc.
- If you've selected 'Sync all Users and Groups' in your application settings, you don't even need to assign Users or Groups for your application.
- If you've selected 'Sync only assigned users and groups' or more detailed filters, you must assign groups and users to your application and make sure the filters allow your groups and users to get synced.
After the attribute mappings and sync scopes have been set correctly you can start provisioning. Turn provisioning 'On' in the application 'Settings' section and 'save' the changes - this will start the synchronization process.
Provisioning should start immediately, but it might take some time before you start seeing users and groups in Zinc
You should see a notification that synchronization is in progress and you should come
back later to see the results. The first initial sync might take a while, depending on your directory size.
It is possible to restart full synchronization by checking the box 'Clear current state and restart synchronization' and confirm the action by pressing 'Save' again. You shouldn't need to restart full synchronization but sometimes its helpful and speeds things up for example if the first synchronization run into trouble and you want to start over after resolving possible errors.
You can check the 'Synchronization Details' section for progress details and full details after the provisioning is done - You should see a full summary of what was synced and when.
After successful synchronization you should see all of your users and groups in Zinc admin console:
If you experience any issues with provisioning - a user or group not showing up in Zinc, its important to check the 'Synchronization Details' section for errors. If the sync process encounters an error it will stop and the user/group provisioning will not be successful. You can find the full error details from the audit log. Errors are not common, but might happen for example if changes to attribute mappings weren't saved before provisioning was started.
After the possible errors have been addressed, the provision should happen automatically in the next few hours, or you can choose a sledgehammer approach and restart the full synchronization.