Admin Managers' Guide: Microsoft AD Integration

This article describes how you can manage your learners through integration with your company’s Microsoft Active Directory (AD) or Azure AD. Syncing your learners is a straightforward three-step process, with built-in options to sync all company contacts or only a designated AD group (for example, employees taking Security Awareness Training).

In this Article:

Step 1: Register Graph API Application

Step 2: Configure in the Security Awareness Platform

Active Directory Group Sync (Optional)

Step 3: Sync Summary & Sync Review

Troubleshooting

Before You Start

Before setting up integration, make sure you have the following in place:

• Valid Azure AD account with Global Admin rights to register and grant permissions.
• Enough licences to cover all the users you want to sync. (If you attempt to sync more users than you have licences for, the sync will fail.)
• Clean AD records: every synced user must have a valid email address (no blanks or duplicates).
• Planned AD structure: decide if you’re syncing all users or creating a designated AD Security Group for training.
• Client Secret management: note that client secrets expire — you’ll need to renew them before they do to keep the sync running.

Step 1: Register Graph API Application

First, you need to create a valid Microsoft Graph API application — you will enter these credentials into the Security Awareness Platform in Step 2.  

Follow these steps to create a valid Microsoft Graph API application:

1. Sign in to your Azure Portal.
2. If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the Azure AD tenant that you want.
3. In the left-hand navigation pane, go to Azure Active Directory > App registrations > New registration.
4. When the Register an application page appears, give your application a Security Awareness-related name (e.g., Security Awareness Integration).
5. Select Register.
6. Temporarily copy the correct Application (client) ID and Directory (tenant) ID, NOT the "Object ID". You'll be entering these values into our Platform later.

7. Select Certificates & secrets > Add a client secret, choose an expiration time > and click Add. 

8. Temporarily copy the newly created client Secret Value into the text file from step 6, NOT the "Secret ID". You'll need to input it into our Platform later.

9. Go to API Permissions > Add a permission. Choose Microsoft Graph > Application permissions.
10. Select Directory > Directory.Read.All > and click Add Permissions. *This is the only permission our Platform needs access to.
11. Finally, select API Permissions, click Grant admin consent for... to finalise the setup. *The status will then change to Granted.

Step 2: Configure in the Security Awareness Platform

Next, you need to add these credentials from Step 1 into the User Sync section on the Platform.

Follow these steps to add your copied data from Step 1 into our Platform:

1. In the Platform, navigate to the Users section, click Add Users >, and select Sync Users.

2. You will be taken to the Settings > User Sync section. Click the Setup Microsoft.

3. Select your Sync Schedule Type (when do you want syncing to take place):

• Manual: run only when you choose. ( not scheduled)
• Daily: run once per day at a set time.
• Weekly: run once per week on a set day and time.

4. Paste the Application (client) ID from the temporary text file you created into the;

• Application ID field

5. Paste the Directory (tenant) ID from the temporary text file you created into the;

• Tenant ID field

6. Paste the Client Secret from the temporary text file you created into the;

• Client Secret field

7. Click Save to progress to the Sync Summary and Review step.

Active Directory Group Sync (Optional)

You can restrict sync to a specific AD group rather than syncing your entire directory:

Follow these steps to do this using the Active Directory Groups feature:    

1. In  Azure Active Directory > Go to Groups > New group. 
2. Choose Security as the group type, and give it a name (e.g., Security Training).
3. Click on the newly created group's name, then click Members. From here, you can add any users you want to the group.
4. Copy the Group's Object ID. You can find this ID by clicking on Properties and looking for the Object ID field.
5. In the Platform’s sync configuration, paste the Group ID into the Group ID field.
6. Click Save to progress to the Sync Summary and Review step.

*Now, only users in this AD group will be synced to the Security Awareness Platform

Step 3: Sync Summary & Sync Review

1. On the Config Summary page, review your settings.

2. Click Test Connection to confirm settings are correct. A confirmation message will appear if the connection is successful.
3. Click the Preview Sync button.
4. The Preview Sync dashboard will give you a preview of what actions will take place once the User Sync is activated. Users will be allocated one of four statuses:

• New Learners: Learners that don't currently exist on the Platform but appear in your Active Directory. They will be imported into the Platform when the next sync runs.
• Deleted Learners: Learners that currently exist on the Platform but don't appear in your Active Directory. They will be removed from the Platform when the next sync runs.
• Existing Learners: Learners that currently exist on the Platform AND in your Active Directory. They will remain unchanged on the Platform when the next sync runs.
• Manager: The designated company Manager will remain unchanged by User Sync.

5. Select the Run User Sync button to manually run your first sync and activate any scheduled syncing.

Troubleshooting Common Sync Issues

If the sync fails or shows errors in Preview Sync, check the following:

Blank email addresses

• Users without valid email addresses in AD cannot be synced. Update or exclude them in AD.

Licence shortfall

• If you’re syncing more users than you have licences for, the sync will fail. Order more licences or reduce the synced group.

Expired client secret

• If the client secret has expired, generate a new one in Azure AD and update it in the Platform.

Permissions not granted

• Ensure Directory.Read.All has been consented by a Global Admin.

The Test Connection Failed

• Double-check that the Application ID, Tenant ID, and Secret Value are entered correctly.

👉 If the issue persists after checking the above, please record a short Loom video or take screenshots of your sync setup and error message, and share them with our Support team at support@goldphish.com for further help.