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

• 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 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:

      1. User sign-in callback: https:///api/external-provider-response.
      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.

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.

1. Enter a description and set an expiry date. Click Add.
2. 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.
3. Select the app registration you just created.
4. In the API permissions section, click + Add a permission.
5. Select Microsoft Graph.
6. 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.

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.

1. Click Add permissions.
2. 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

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

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.

1. Paste the Application (client) ID in the Client ID field (see step #18 of the App registration in Azure portal section).
2. Paste the Value in the Secret value field.
3. 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.
4. For Delegated permissions mode only:

   • Enter the UPN of the user account Devolutions Server will impersonate for Microsoft Graph calls (e.g., [e-mail]).
   • 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.

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.

1. Click Save.

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

After activating Microsoft authentication, it may take a while for the cache to load before being able to import users and user groups.

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.

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.

Delegated mode limitations

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