Overview

Synchronisation between your portal and your company's Azure Active Directory is performed by polling the Azure AD periodically for changes. Communication between SafeTitan and Azure AD is handled via the Microsoft Graph API.

Microsoft Graph API acts as a gateway to data held in Microsoft 365. Applications can communicate using the Graph API either on behalf of a user or alternatively on behalf of an application. SafeTitan communicates with the application level permissions to avoid storing sensitive information on a user (such as password).

The 5 basic steps needed to configure an application to communicate via the Graph API without the need for user credentials are listed below and discussed in more detail in the configuration section:

Register your app with Azure AD.
Configure permissions for Microsoft Graph on your app.
Get administrator consent for the permissions.
Get an access token.
Use the access token to call Microsoft Graph

Before you run the sync, if you require additional domains to be added to your portal, please contact support and we will add those for you.

NOTE: The Same Application Registration can be used for both Azure AD SSO and Azure AD Synchronization.

Configuration

Before configuring the AD Synchronisation in the portal, you must first register the application within Microsoft’s App Registration portal and assign the relevant permissions.

Register the SafeTitan portal within Microsoft App Registration portal

To register the application in the Microsoft App Registration portal, navigate to your Azure portal : https://portal.azure.com/
In the left-hand navigation pane, click on Azure Active Directory.

Click on App Registrations and click on New application registration.

Set the following values in the form:
- Name: SafeTitan
- Supported Account Types: Default option
- Redirect URI: https://{your domain name}.safetitan.com (example https://mycompany.safetitan.com) – This will be your SafeTitan portal URL

Once you've completed registration, Azure AD will assign your application a unique client identifier, the Application ID. You need this value in the next sections, so copy it from the application page. The Application ID can be found on the Overview screen of your App registration. Take note of this value.

Generate Application Secret

The next step is to generate an application secret. Your SafeTitan instance will use this value to prove its identity when connecting to Azure.

Select the Certificates & Secrets tab.

In the next screen, click New client secret. Provide a description and select an expiration date.

Once you've created the Client Secret, please take note of the Client Secret Value - and not the Client Secret ID, as this field will be needed when configuring the Azure AD Sync Configuration on the SafeTitan portal.

Many of the issues we see where users see errors when they go to perform a sync are down their having copied the Client Secret ID rather than the Client Secret value into the portal configuration.

Configure permissions for Microsoft Graph on your app.

Now we need to configure the permissions granted to the SafeTitan App. We need Directory.ReadAll access.

Click API Permissions.

Click Add a Permission
In the dialog that appears, select Microsoft APIs and Microsoft Graph

Next, select Application Permissions

Search for the permission Directory.Read.All and add the permission.

In the API permissions screen, click the button Grant admin consent for ...

This will effectively approve the permission request for the application.

Portal Configuration

The final step is to configure your Azure AD setup in your portal.

Log in to your SafeTitan portal.
Select the menu item Settings -> AD Sync Configuration.

In the next screen, select the tab Azure Sync.

To enable Azure AD synchronisation with the portal, select the checkbox Enable Azure AD Sync

This will result in the form appearing to provide your Azure AD app registration and attribute mapping details. All fields are explained below:

Field	Description	Mandatory
Application Id	This is the application id you will have generated when creating your app registration above.	Yes
Application Secret	This is the password/secret value generated when creating your app registration above.	Yes
Tenant Name / Id	This can be the name of your Azure tenant (typically your organisations domain e.g. Your-company.com). It can also be the id of your tenant is Azure.	Yes
First Name attribute mapping	This will be the attribute in your Azure AD that contains the users First Name. This will be the unique identifier in the portal.	Yes
Last Name attribute mapping	This will be the attribute in your Azure AD that contains the users Last Name. This will be the unique identifier in the portal.	Yes
Email attribute mapping	This will be the attribute in your Azure AD that contains the users Email address. This will be the unique identifier in the portal.	Yes
Department attribute mapping	If applicable, this will be the attribute in your Azure AD that contains the users Department.	No
Country attribute mapping	If applicable, this will be the attribute in your Azure AD that contains the users Country.	No
Locale attribute mapping	If applicable, this will be the attribute in your Azure AD that contains the users locale (defaults to en-US).	No
Office attribute mapping	If applicable, this will be the attribute in your Azure AD that contains the users Office location.	No
Mobile / Cellular phone attribute mapping	If applicable, this will be the attribute in your Azure AD that contains the users mobile phone number.	No
External Id attribute mapping	If applicable, this will be the attribute in your Azure AD that contains the users External Id (such as HR ID).	No
Business unit attribute mapping	If applicable, this will be the attribute in your Azure AD that contains the users Business unit.	No
Users to exclude	This is a list of user emails (separated by a semicolon) that you wish to exclude from synchronisation.	No
Restrict to groups	When this is checked, only the groups or directory roles included in the Group restrictions field will be considered in the synchronisation.	No
Group restrictions	This is a list of group names or directory roles (separated by a semicolon) that you wish to include in synchronisation.	No

Populate these fields, or at least those that are mandatory and click Save at the top of the screen.
Select Test Synchronization Configuration to confirm that the settings you have saved are correct before you trigger synchronization.
Once you are satisfied that your settings are correct and you have saved them, select Trigger Synchronization Now. Note that the length of the synchronization process will vary depending on the traffic in the system as well as the size of the organization; that is, the number of users who are being processed by the system.
You can select View Sync History to see the progress of the synchronization and also to see a list of previously triggered user synchronizations.

Custom Fields

Azure AD Sync allows for users to make use of up to 5 custom fields. These fields can be mapped to a user in the same way as the core filed mappings above. They can be configured on the UI, just below the core field set up.

Synchronised Deletions

The Azure AD Syncronisation process also allows customers to keep user deletions synchronised. If the checkbox 'Sync Deletion' is checked, then any users that exist on a customers portal, that are not returned during the next synctionisation run, will be removed from the customers portal.

Re-Enabling Deleted users

It can happen on occasion that a user can enable synchronised deletions by mistake and have the unexpected behavior where users are removed from their portal. It should be noted however that when a user is deleted from their portal, their historical record still exists - therefore the delete can be reversed. The setting Re-enable deleted users serves this purpose.

When the setting Re-enable deleted users is checked, users that had been marked as deleted on the portal but are returned as part of the next sync run will be re-enabled on their portal.

Triggering Synchronisation

By default, Azure AD synchronisation will run every Saturday evening to limit disruption. You can however also trigger the process manually.

To trigger the process manually, open the page above where you set the configuration with the AD Synchronisation.
Ensure that all data is correct and saved.
Select Test Synchronization Configuration to confirm that the settings you have saved are correct before you trigger synchronization.
Once you are satisfied that your settings are correct and you have saved them, select Trigger Synchronization Now. Note that the length of the synchronization process will vary depending on the traffic in the system as well as the size of the organization; that is, the number of users who are being processed by the system.
You can select View Sync History to see the progress of the synchronization and also to see a list of previously triggered user synchronizations.

Azure Active Directory Synchronisation Print