Overview
Synchronisation between your portal and your companies Azure Active Directory is performed by polling the Azure AD periodically for changes. Communication between Cyber Risk Aware 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. Cyber Risk Aware 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 Cyber Risk Aware 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: Cyber Risk Aware
- Supported Account Types: Default option
- Redirect URI: https://{your domain name}.cyberriskaware.com (example https://mycompany.cyberriskaware.com) – This will be your Cyber Risk Aware 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 Cyber Risk Aware 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 Cyber Risk Aware 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 Cyber Risk Aware 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 Cyber Risk Aware portal.
- Select the menu item User Manager -> AD Sync Configuration.
- In the next screen, select the tab Azure AD 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.
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.
- At the bottom of the page click the button Trigger sync now
- This will manually kick of the AD synchronisation.
- To view progress of the synchronisation, you can select the menu item User Manager -> User Import / Sync progress from the main navigation.
