# Microsoft

{% embed url="<https://youtu.be/KxwJ9E3d3Lk>" %}

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](#configuring-microsoft-as-external-oidc-in-defguard "mention")

## Obtaining basic credentials

1. Go to [https://portal.azure.com/](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.

   <figure><img src="/files/UkcIGM4uCHWXZsZMOSkr" alt=""><figcaption></figcaption></figure>
4. Click "Make new registration"
5. Fill out the form, like in the example:

   <figure><img src="/files/AEI5kG4vMjFohMd9I9RQ" alt=""><figcaption></figcaption></figure>

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](/features/external-openid-providers.md#redirect-uri).

6. 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.

   <figure><img src="/files/263Fp2omSohIubuvV6q2" alt=""><figcaption></figcaption></figure>
7. Now back in Microsoft Entra ID, still in your newly created application, go to **Certificates & Secrets**

   <figure><img src="/files/SL84PrfFumQOTi9yzBVo" alt=""><figcaption></figcaption></figure>
8. Go to `Certificates & secrets` and create a new client secret. Copy its **value.**

<figure><img src="/files/LYzNuLlNgoU8CiyHKcmN" alt=""><figcaption></figcaption></figure>

9. Go to Token configuration (in the menu on the left) and add a new optional token claim.
10. Make sure to select the ID token type and the following claims:

    <figure><img src="/files/Srua6oTjqgAfP0TGBA1g" alt=""><figcaption></figcaption></figure>
11. Accept the popup or configure the API permissions manually.

<figure><img src="/files/L5EIqsAEDsRB0MLH5tfz" alt=""><figcaption></figcaption></figure>

12. Now you should be good to go.

## Obtaining Directory Synchronization credentials

{% hint style="info" %}
This feature is available only in Defguard 1.2.1 and above
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

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

Make sure to check the [general guide to directory synchronization](/features/external-openid-providers.md#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

   <figure><img src="/files/Udo2VebMe3vNGfGOpnJO" alt=""><figcaption></figcaption></figure>
3. Click "Add a permission", then select "Microsoft Graph"

   <figure><img src="/files/Spg6f8U8JlshvbTeh83W" alt=""><figcaption></figcaption></figure>
4. Select "Application permissions", as Defguard will perform the synchronization in the background.

   <figure><img src="/files/zPNWWo6AiPfWMl12VAtz" alt=""><figcaption></figcaption></figure>
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\\

   <figure><img src="/files/JUdZY5BzeQEgvtTigtqd" alt=""><figcaption></figcaption></figure>
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.**

<figure><img src="/files/6b7ImsaJoEZtichzWvel" alt=""><figcaption></figcaption></figure>

2. Click "**Connect"** in row with **Microsoft**.

<figure><img src="/files/VMJlYtGzik83ROQ0r00W" alt=""><figcaption></figcaption></figure>

3. Fill out **Tenant ID**, **Client ID**, **Client secret** (Check [#obtaining-basic-credentials](#obtaining-basic-credentials "mention"))

<figure><img src="/files/DNrP4Pft4q9q2lUnQtaE" alt=""><figcaption></figcaption></figure>

4. Click "**Continue**"
5. If you decide to use **Directory Synchronization**, enable it. (If you don't need **Directory Synchronization**, go to step 6).

<figure><img src="/files/7Mfuel7jbd6lPdXF3ctD" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
In order for Entra users to be created in Defguard they must have the following attributes set:

* email (or otherMails)
* first name
* last name
  {% endhint %}

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 `Prefetch users` option:

<figure><img src="/files/Y2tiYXxT1BfZUVhkV0ll" alt=""><figcaption></figcaption></figure>

6. Click "**Continue**"

<figure><img src="/files/QH3loPJ5zoAKPNYHzYVs" alt=""><figcaption></figcaption></figure>

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

7. Click "**Finish**"


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.defguard.net/features/external-openid-providers/microsoft.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.