---
title: "Register Drawbridge in Entra ID | DRAWBRIDGE docs"
description: "How to register Drawbridge as one app registration in Entra ID, covering redirect URIs, the client secret, token claims and authentication contexts."
url: https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html
llms: https://drawbridge.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# Register Drawbridge in Entra ID [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#register-drawbridge-in-entra-id)

Register one app registration in Entra ID that covers every app host, so the gateway has one OpenID Connect client for all of them.

## Before you start [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#before-you-start)

You need:

- A **test app registration** in a tenant that is safe for a first test (single tenant, platform Web). Not the production registration.
- A **test host** where the gateway image can run with TLS terminated in front of it: the issuer must be https, and the session cookie is Secure.
- **Two throwaway users** in that tenant: one for the run sheet, and one to confirm that sessions are separate per user and that signing one out touches nothing of the other.
- The deployment's secret store, ready to hold `DRAWBRIDGE_OIDC_CLIENT_SECRET` and `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE`, and a fresh assertion signing key made with `keys:generate`.

## In the Entra admin center [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#in-the-entra-admin-center)

One app registration covers every app host. In the Entra admin center, under App registrations:

1. **New registration.** Single tenant. Platform **Web**.
2. **Redirect URIs.** One per app host: `https://<app host>/_drawbridge/oidc/callback` (for example `https://app1.apps.wayne.edu/_drawbridge/oidc/callback`). Each host gets its own session, so each needs its own redirect URI; add one whenever an app is added to the config. Leave the implicit grant boxes unticked: the gateway uses the authorization code flow with PKCE.
3. **Certificates & secrets.** Make a client secret and put it in the deployment's secret store as `DRAWBRIDGE_OIDC_CLIENT_SECRET`. Put its expiry date in `DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES` (`YYYY-MM-DD`): Entra secrets expire, the gateway cannot sign anyone in once it has, and with the date set `config:validate`, `/metrics` and the container log count down to it ([the expiry date](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html#client-secret-expiry)).
4. **Token configuration.** Add the optional ID token claims the config reads: `accessid` (the AccessID, transformed from the user principal name with `ExtractMailPrefix`; this is what the example config uses for `oidc.user_claim`), `email`, `auth_time`, and `acrs` if any path uses an authentication context. Add `wsu_roles` as a mapped claim (the source attribute is `user.wsuRoles`, an on-premises AD attribute; the emitted claim is `wsu_roles`) and set `acceptMappedClaims: true` in the app manifest, so no custom signing key is needed and the metadata URL stays plain; list it in `oidc.extra_claims`. A tenant that does not send `accessid` leaves `oidc.user_claim` at `preferred_username`.
5. **Overview.** Copy the Directory (tenant) ID into `oidc.issuer` (`https://login.microsoftonline.com/<tenant-id>/v2.0`) and the Application (client) ID into `oidc.client_id`. Neither is a secret, but neither belongs in this repository either. The issuer is in Playbook as `SESAME_OAUTH2_ISSUER`.
6. **Authentication contexts** (only if a path uses `auth_context`): in Conditional Access, create the context (`c1` ...), and a policy that targets it with whatever it should demand.

Warning

The client secret never goes in this repository: put the value in the deployment's secret store as `DRAWBRIDGE_OIDC_CLIENT_SECRET`, and only the name of the variable goes in the config. Entra secrets expire, and the gateway cannot sign anyone in once it has, so note the expiry date. To rotate without signing anyone out: add a new secret in Entra, update `DRAWBRIDGE_OIDC_CLIENT_SECRET`, restart the gateway, check a sign-in, then delete the old secret.

## What to check [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#what-to-check)

Before the first real sign-in, walk the first real Entra test: every setting by name, and what to check for each open question E-1 to E-8. Start the gateway the way the quick start shows: mount `drawbridge.yaml` and the signing key read-only, put the two secrets in the environment, and run the image. Then sign in as the first throwaway user and work through the rows. Inspect the claims in the ID token and in the assertion (for example through the app or a token inspector); never paste a token into a ticket.

| Row | What to look at | What it answers |
| --- | --- | --- |
| E-1 | the `amr` values in the ID token after a normal sign-in and after an MFA sign-in | which real values the default `amr_map` passes through, and that an unknown value gives no `amr` |
| E-2 | whether `auth_time` is present in the ID token | whether the tenant releases it as an optional claim |
| E-3 | the `sub` claim in the assertion | that `accessid` (the UPN mail prefix) is the user identifier every app stores |
| E-4 | the `wsu_roles` claim in the ID token | that the mapped claim arrives under that exact name, as a list of role strings |
| E-5 | request a path with `auth_context: c1` and look at `acrs` in the ID token | that Entra honors the `claims` request parameter and returns the context, and what the context demands |
| E-6 | the client secret's expiry date and who receives the notice | the rotation procedure and its owner |
| E-7 | the redirect URI list after the test host is added | that one URI per app host works as apps join |
| E-8 | sign out through `/_drawbridge/oidc/callback?logout=<URL-encoded address on the same host>` and see where the browser lands | that Entra accepts the post-logout address on the app host, and that another host is refused |

For E-5, sign in without the context first, then request the step-up path: the visitor should be sent back to Entra and come back with the context listed in `acrs`. For E-8, also try a logout address on another host and confirm the gateway refuses it.

Danger

Never commit values: keys, secrets, the passphrase, a real tenant ID or client ID stay out of git. This page carries names and placeholders only. Never use a production tenant for the first test. Never reuse the rig secrets: the values in `rig/compose.yaml` are throwaway and exist only for the mock provider. Never paste an ID token or an assertion into a ticket; describe the claims instead. Never write a tenant ID by hand; copy the issuer from the app registration Overview.

## Report back [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#report-back)

Update the rows you checked in `OPEN_QUESTIONS.md`, in the table "The identity provider: Microsoft Entra ID (E-1 to E-8)": mark each answered row with the date and a short answer, in the style the file already uses (`**Answered YYYY-MM-DD:** ...`). If a claim arrives under a different name than expected (for example a long directory extension name instead of `wsu_roles`), say so on E-4: the config can list the exact name, or rename it to `wsu_roles` with a `{from, as}` entry in `oidc.extra_claims`. Leave a row open when the check could not be done, and note what is missing.

## Related [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#related)

- [Try it without Entra](https://drawbridge.apps.wayne.edu/docs/guides/try-without-entra.html)
- [WSU values (Playbook)](https://drawbridge.apps.wayne.edu/docs/guides/wsu-values.html)
- [Configuration](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html)
- [Quick start](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html)
