Microsoft

Firstly, we need to obtain credentials such as

• Tenant ID

• Client ID

• Client secret

If you already have them, please skip to Configuring Microsoft as external OIDC in Defguard

Obtaining basic credentials

1. Go to https://portal.azure.com/

2. Navigate to Microsoft Entra ID

3. In the Microsoft Entra ID, click Manage and select App registrations from the menu on the left.

   
4. Click "Make new registration"

5. Fill out the form, like in the example:

   

Make sure the Redirect URL you insert here is correct. The full list of redirect URLs that should be configured in order to use all features is available here.

1. You should be now on the registered application's management screen. You can copy the client's ID and the tenant ID from here, as you need to provide them on the Defguard settings' page.

   
2. Now back in Microsoft Entra ID, still in your newly created application, go to Certificates & Secrets

   
3. Go to Certificates & secrets and create a new client secret. Copy its value.

1. Go to Token configuration (in the menu on the left) and add a new optional token claim.

2. Make sure to select the ID token type and the following claims:

   
3. Accept the popup or configure the API permissions manually.

1. Now you should be good to go.

Obtaining Directory Synchronization credentials

This feature is currently technically limited to 10000 members or groups. High user or group counts may still trigger your provider API limits even below this threshold. If you have many users (200+), we recommend you test this feature first before you decide to turn on automatic user deletion.

Defguard supports synchronizing groups' and users' states based on your Microsoft directory.

Make sure to check the general guide to directory synchronization to learn more about the available configuration options.

Setup

1. Go back to your app registrations in Microsoft Entra ID and select the app you registered during the provider setup.

2. Navigate to API permissions

   
3. Click "Add a permission", then select "Microsoft Graph"

   
4. Select "Application permissions", as Defguard will perform the synchronization in the background.

   
5. Assign the following permissions:

   • GroupMember.Read.All

   • Group.Read.All

   • User.Read.All

6. Now grant admin consent for the permissions using the "Grant admin consent for" button\

   
7. You should be good to go now. Navigate to the directory sync settings in Defguard and try to test your setup using the test connection button.

Configuring Microsoft as external OIDC in Defguard

1. Go to Settings → External identity providers.

1. Click "Connect" in row with Microsoft.

1. Fill out Tenant ID, Client ID, Client secret (Check Obtaining basic credentials)

1. Click "Continue"

2. If you decide to use Directory Synchronization, enable it. (If you don't need Directory Synchronization, go to step 6).

In order for Entra users to be created in Defguard they must have the following attributes set:

• email (or otherMails)

• first name

• last name

By default, directory sync guaranteed only that the state and group membership of Defguard users also present in the directory is up-to-date. It does not create Defguard users until they log in using an External OpenID provider.

To create Defguard users during directory sync, enable the Import users from your Microsoft directory to Defguard option:

Limiting sync to specific groups

• Sync only matching memberships - decides which group memberships get synced.

  • Empty field means that Defguard will sync every group.

  • A comma-separated list of groups: keeps the groups and ignores the rest. It doesn't change who gets an account, just how memberships are mapped.

• Synchronize users only from specified groups - decides who gets an account.

  • Empty field means that anyone from the directory will be imported and will be able to sign in.

  • A comma-separated list of groups: imports members of the specified groups, while people outside won't be able to enroll via external SSO, and accounts won't be created on the first sign-in (if enabled).

If a group is not listed in the Synchronize users only from specified groups field, only the first sign-in is blocked. Existing Defguard accounts, created earlier or kept because User behaviour is set to Keep, can still sign in. If such an account is deleted, the user will not be able to sign in again until adding the desired group to Synchronize users only from specified groups field.

Sync only matching memberships	Synchronize users only from specified groups	Who will be imported (if enabled)	Who can enroll via external SSO? (on Edge site)	Who will have account created on first sign-in (if enabled)
Empty	Empty	Everyone	Everyone	Everyone
Group 1,Group 2	Empty	Everyone	Everyone	Everyone
Empty	Group 1	Only users in Group 1	Only users in Group 1	Only users in Group 1
Group 1,Group 2	Group 1	Only users in Group 1	Only users in Group 1	Only users in Group 1
Group 1	Group 2	No one	No one	No one

If you use both fields, the second one depends on the first. Any group in "Synchronize users only from specified groups" also has to be in "Sync only matching memberships", otherwise nobody will be recognized as its member, and no one will be imported.

1. Click "Continue"

If no errors occurred during configuration, you will see a message indicating that your OIDC provider has been successfully added.

1. Click "Finish"