Microsoft Entra ID setup

Configure sign-in with Microsoft Entra ID.

This is the operator guide for wiring the BARRY UI against Microsoft Entra ID (formerly Azure AD) — the configurable alternative to the default Keycloak provider. For the concepts behind login and roles, read Authentication & Roles first.

Like Keycloak, Entra uses the Backend-for-Frontend pattern: the SPA never sees tokens; the server runs the authorization-code flow and issues a session cookie. Users and roles live entirely in Entra.

Prerequisites

• An Entra tenant where you have Application Administrator (or Global Administrator) rights.
• The public origin the UI is reachable at (e.g. https://<frontend-host>, and the local-dev origin for development).

Setup steps

1. Create the app registration

In the Entra portal, create an App registration:

• Name: e.g. BARRY.
• Supported account types: single tenant — multi-tenant is not needed for a self-hosted tool.
• Leave the redirect URI empty at this step.

From the overview page, copy the Application (client) ID and the Directory (tenant) ID into the runtime configuration.

2. Add platform redirects

Under Authentication → Add a platform → Web, add one redirect URI per environment, always with the path /signin-oidc (e.g. https://<frontend-host>/signin-oidc). Add the matching front-channel logout URL …/signout-callback-oidc. Leave the implicit grant checkboxes unchecked — the runtime uses the code flow only.

3. Add a credential

A confidential client needs a credential to exchange the authorization code for tokens:

• Client secret — acceptable for development. Copy the secret Value (not the Secret ID) immediately; it is shown only once.
• Certificate — strongly preferred for production; upload the public certificate and mount the private key into the server (or use a Key Vault reference).

The basic sign-in and role-mapping flow needs no Microsoft Graph permissions — everything is read from the ID token. Granting tenant-wide admin consent once is recommended so users are not prompted on first sign-in.

4. Define App Roles

Under App roles, create three roles. The value of each must match exactly:

• Admin — full control.
• Operator — operate clients and trigger transports; no settings.
• Viewer — read-only.

Roles are hierarchical in the backend (Admin satisfies Operator and Viewer; Operator satisfies Viewer).

5. Assign users and groups

App-role values appear in a user's token only if the user is assigned to the application:

• Go to Enterprise applications → BARRY → Properties and set Assignment required? to Yes.
• Under Users and groups → Add user/group, select users (or a security group) and assign the role.

A common pattern is to create three security groups (Admins, Operators, Viewers) and assign the groups to the roles, so membership is managed in the group. Group claims are not required — Entra emits the role claim for app-role assignments either way.

A user without an assignment signs in successfully but the application shows Access denied (the token carries no role claim).

Configuring the runtime

The minimum configuration the server needs:

BARRY_AUTH_PROVIDER=Entra
BARRY_ENTRA_TENANT_ID=<directory (tenant) id>
BARRY_ENTRA_CLIENT_ID=<application (client) id>
BARRY_ENTRA_CLIENT_SECRET=<secret value from step 3>

For production on Azure, prefer a federated identity credential plus a managed identity over a stored client secret, which removes secret rotation from the operational burden entirely.

Troubleshooting

• AADSTS50011: redirect URI does not match — the exact origin you accessed the UI under is missing from the app's redirect URIs.
• AADSTS7000215: invalid client secret — you copied the secret's ID instead of its value, or it expired.
• AADSTS65001: not consented — grant admin consent under API permissions.
• /api/me returns 403 with empty roles — the user has no app-role assignment; assign them under Enterprise applications → Users and groups.