> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/server/knowledge-base/how-to-articles/configure-microsoft-authentication-with-entra-id.md).

# Configure Microsoft authentication with Entra ID

Configure Microsoft Entra ID and Devolutions Server properly to use Microsoft authentication by following the instructions below.

Devolutions Server supports two authentication modes for Microsoft sign-in: ***Application permissions*** (recommended default) and ***Delegated permissions*** (for tenants where application permissions are blocked by policy). It is important to pick the right mode for your tenant policy before starting the procedure since the redirect URIs and Microsoft Graph permissions will differ based on your choice.

| Feature                    | Application     | Delegated                   |
| -------------------------- | --------------- | --------------------------- |
| ***Acts as***              | The application | A service account user      |
| ***Admin consent***        | Required        | Required for `*.All` scopes |
| ***Login authentication*** | Yes             | Yes                         |
| ***PAM***                  | Yes             | No, use Application         |
| ***Microsoft 365 email***  | Yes             | No ,use Application mode    |
| ***Auto-create users***    | Yes             | Yes                         |

## Requirements <a href="#requirements" id="requirements"></a>

* Devolutions Server scheduler installed and running
* A Microsoft Entra ID subscription
* An Entra ID web application for the Devolutions Server web application and the cache

## App registration in the Azure Portal

1. Log in to your [Microsoft Azure Portal](https://portal.azure.com) using administrator credentials.
2. Once logged in, select ***Microsoft Entra ID*** in the Azure services section. If you do not see it, click on ***More services*** to make other services appear or search for it in the search bar.
3. In the left navigation pane, select ***App registrations***.
4. Click ***+ New registration***.
5. Enter a name for the application. This name will not be used outside of the Azure Portal.
6. Set which ***Supported account types*** are allowed to connect. Usually, selecting ***Single tenant only*** is more than enough for your Entra ID authentication.
7. Set the ***Redirect URI*** to ***Web*** and enter the URIs for your chosen authentication mode. All URIs must point to the public URL of your Devolutions Server instance, including any virtual path (for example `https://dvls.contoso.com/dvls/api/...`):
   1. **Application permissions mode**:&#x20;
      1. User sign-in callback: `https:///api/external-provider-response`.&#x20;
      2. Go to ***Authentication (Preview)*** – ***Settings***, tick the ***ID tokens (used for implicit and hybrid flows)*** checkbox, and click ***Save***.
   2. **Delegated permission mode**:
      1. User sign-in callback: `https:///api/external-provider-response`
      2. Service-account binding, start: `https:///api/configuration/authentication/azure/connect`
      3. Service-account binding, callback: `https:///api/configuration/authentication/azure/connect-callback`
8. Select the app registration you just created. In the ***Certificates & secrets*** section, click ***+ New client secret***.

{% hint style="warning" %}
When the client secret expires, no one will be able to connect to the associated Devolutions Server instance. You will then need to create a new client secret. We recommend setting yourself a reminder before the expiration date.
{% endhint %}

9. Enter a description and set an expiry date. Click ***Add***.
10. Copy the ***Value***. Be sure to save it in a secure note before switching to another Azure Portal page, as the copy button will no longer be available.
11. Select the app registration you just created.
12. In the ***API permissions*** section, click ***+ Add a permission***.
13. Select ***Microsoft Graph***.
14. Choose the API permission type and add permissions based on your authentication mode:

    | Mode                        | API Permissions                                                                                                                                                  |
    | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Application permissions** | `User.Read.All`, `Group.Read.All` (type Application) — admin consent required.                                                                                   |
    | **Delegated permissions**   | `User.Read` (type Delegated, user-consentable) plus `User.Read.All`, `Group.Read.All` (type Delegated) for directory reads — admin consent required for `*.All`. |

{% hint style="info" %}
Although admin consent is not required by default, your organization may force consent for `openid`, `profile`, and `offline_access` upon first user login. You can add these permissions here to remove that prompt.
{% endhint %}

15. Click ***Add permissions***.
16. On the app registration ***Overview*** page, locate the ***Application (client) ID*** in the ***Essentials*** section and the ***Tenant ID*** in the ***Basic information*** section. Keep this page open or save these value in a secure note. These will be needed later for the configuration of Devolutions Server so keep the page open.

## Authentication mode configuration in Devolutions Server&#x20;

1. Log in to your Devolutions Server and navigate to ***Administration*** – ***Server settings*** – ***Authentication***.
2. Under **Authentication modes**, ensure **Authenticate with Microsoft user** is enabled.
3. Under **Configuration**, click **Microsoft authentication**.
4. In the **Authentication mode** dropdown menu, select the authentication mode that matches the registration app you just configured, i.e., ***Application permissions*** or ***Delegated permissions***.
5. Paste the application's tenant ID in the ***Tenant ID*** field of the ***Microsoft Authentication*** configuration page (see step #18 of the App registration in Azure portal section).

{% hint style="info" %}
The ***Use specific client ID*** ***for users and user groups cache*** option should only be checked when migrating from a Devolutions Server version older than 2024.1. Enabling it on a clean install can disable the user cache.
{% endhint %}

6. Paste the ***Application (client) ID*** in the ***Client ID*** field (see step #18 of the App registration in Azure portal section).
7. Paste the ***Value*** in the ***Secret value*** field.
8. In the ***Type of user interaction on login*** dropdown, set the Entra ID sign-in prompt behavior:
   * ***Select account*** (`select_account`): Always displays the account picker, even if the user already has an active session.
   * Leave at default for silent sign-in when a valid session already exists.
9. For ***Delegated permissions*** mode only:
   * Enter the UPN of the user account Devolutions Server will impersonate for Microsoft Graph calls (e.g., `svc-dvls@contoso.com`).
   * Click ***Connect to Microsoft***. An OAuth sign-in window opens. Sign in with the service account to bind it to Devolutions Server. Once the OAuth flow completes successfully, the ***Connected*** status displays the UPN of the bound service account.
   * Click ***Test connection*** to run a delegated Graph API call and verify the service account token is working correctly.

{% hint style="info" %}
To revoke the cached token and clear the service account binding at any time, click ***Disconnect***. Do this before changing the service account or rotating credentials.

Rotating the client secret or changing the tenant configuration invalidates the cached delegated token automatically. On service account password change or session revocation, an admin must reconnect from ***Administration – Server settings – Authentication – Microsoft authentication***; the rest of the configuration is preserved.
{% endhint %}

10. Click ***Save***.

You should now be able to use the ***Microsoft*** button on Devolutions Server's web interface.

{% hint style="info" %}
After activating Microsoft authentication, it may take a while for the cache to load before being able to import users and user groups.
{% endhint %}

#### Consent flow

Depending on your tenant configuration, one of the following outcomes will occur after consent is handled:

| Scenario                                                                                            | Result                                                                     |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Admin grants tenant-wide consent in the portal**                                                  | Silent — all users covered, no popup.                                      |
| **Admin doesn't consent + service account holds User Administrator and Groups Administrator roles** | First sign-in shows a consent popup; the service account can self-consent. |
| **Admin doesn't consent + service account cannot self-consent**                                     | Sign-in blocked with `AADSTS65001.`                                        |

{% hint style="info" %}
For restricted tenants: users who cannot get tenant-wide admin consent can still operate ***Delegated mode*** if they grant the service account the two Entra built-in roles above.
{% endhint %}

## Delegated mode limitations <a href="#delegated-mode-limitations" id="delegated-mode-limitations"></a>

* Login only: PAM (privileged access) and Microsoft 365 email integration require ***Application permissions***. If you use those features, keep Application mode or run a hybrid configuration with separate app registrations.
* Tenant-wide directory reads: `User.Read.All` and `Group.Read.All` are tenant-wide scopes. Entra ID has no native subset scope for OAuth. To restrict which users Devolutions Server can auto-create, use the auto-create restriction by group option in Devolutions Server itself.
* Service account dependency: Delegated mode binds Devolutions Server to a single service account's identity. If the service account is disabled, password-rotated, or has its session revoked, an admin must reconnect via ***Administration*** – ***Server settings*** – ***Authentication*** – ***Microsoft authentication***.
* Sign-in only: Privileged Access Management (PAM) and Microsoft 365 mail integration require Application permissions. If you use those features, keep Application mode or maintain a hybrid configuration with two separate app registrations.
* Single-account binding: Delegated mode ties Devolutions Server to one service account. If that account is disabled or has its password rotated, an admin must reconnect.

## Maintenance notes

#### Client secret rotation

Before the client secret expires, create a new one in the app registration's **Certificates & secrets** page, paste the new value into the **Secret value** field on the Devolutions Server *Microsoft authentication* page, and click **Save**. Delete the old secret in the app registration only after confirming that sign-in still succeeds.

#### Service-account rotation (Delegated mode)

Rotating the service account password, revoking its session, or rotating the client secret invalidates the cached delegated refresh token. An administrator must reconnect by clicking **Disconnect** then **Connect to Microsoft** on the *Microsoft authentication* page using the updated credentials. The rest of the configuration is preserved.

#### First sign-in without tenant-wide admin consent (Delegated mode)

If admin consent was not granted in step #14 of the app registration:

* If the service account holds the Entra built-in roles **User Administrator** and **Groups Administrator**, the first sign-in prompts for consent and the service account can accept it itself.
* Otherwise the first sign-in fails until an Entra admin grants consent for the `*.All` permissions.

## Troubleshooting

| Symptom                                                                                                                                                                           | Likely cause                                                                                                              | Resolution                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `AADSTS50011: The redirect URI specified in the request does not match the redirect URIs configured for the application` when clicking **Connect to Microsoft** in Delegated mode | Only the user-sign-in redirect URI was registered on the app registration.                                                | Add the `/api/configuration/authentication/azure/connect` and `/api/configuration/authentication/azure/connect-callback` URIs and save.       |
| User sign-in succeeds but directory or group lookups fail with `Insufficient privileges`                                                                                          | The required `*.All` Microsoft Graph permissions were added but not admin-consented.                                      | On the app registration's ***API permissions*** page, click ***Grant admin consent for*** `<tenant>`.                                         |
| Sign-in returns `invalid_client` or `unauthorized_client`                                                                                                                         | The client secret has expired or the value pasted into Devolutions Server does not match the one in the app registration. | Create a new client secret, paste the new value into the *Microsoft authentication* page in Devolutions Server, and save.                     |
| In Delegated mode, the ***Connected*** indicator clears unexpectedly                                                                                                              | The bound service account password was rotated, its sessions were revoked, or the client secret was changed.              | Reconnect from the *Microsoft authentication* page by clicking ***Disconnect*** then ***Connect to Microsoft*** with the updated credentials. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.devolutions.net/server/knowledge-base/how-to-articles/configure-microsoft-authentication-with-entra-id.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.