Skip to content
Menu

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#

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#

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

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.

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.