Entra ID single sign-on

DTM supports Microsoft Entra ID single sign-on over OIDC. With it configured, users click Sign in with Microsoft in the web UI and authenticate against your tenant. DTM validates the sign-in and derives the user’s role from an app role you assign in Entra.

The sign-in uses the authorization-code flow with PKCE and validates the identity token against your tenant’s published signing keys. The API example below sends an admin bearer token as $DTM_TOKEN; the API overview shows how to capture one.

Role mapping

DTM reads the roles claim from the identity token:

• Users assigned the Admin app role get the admin role in DTM.
• Everyone else who can sign in gets read-only.

Manage fine-grained editor access with local accounts, or assign the Admin app role to those who need full control.

If you set an SSO user’s role manually (over the API or UI), later sign-ins keep that manual role with one exception: when Entra proposes a lower role, the downgrade is honored and the manual role clears, so revoking someone’s Entra app role reliably demotes them. An Entra-proposed higher role never silently escalates a manually set one.

How SSO and local accounts coexist

Local accounts and Entra identities are separate, disjoint namespaces. Enabling SSO changes nothing about existing local accounts, in either direction:

• Mixed sign-in is the model. With SSO configured, the sign-in page offers both the Microsoft button and the local username/password form. Local accounts keep working, and there is deliberately no switch to turn local sign-in off: an Entra outage or misconfiguration must never lock every admin out.
• An Entra user is its own account. The first Microsoft sign-in creates a DTM account keyed to the Entra user’s immutable subject, named with an entra: prefix (for example entra:[email protected]) and holding no local password. It shows up in the user list like any other account and can be disabled or deleted there; a disabled Entra user is refused at the Microsoft sign-in too.
• Same name, no collision. A local alice and an Entra entra:[email protected] are unrelated accounts: neither inherits the other’s role or sessions, and the local password only ever signs in to the local account. Local usernames cannot contain :, so a local account can never occupy the entra: namespace. And because the Entra account is keyed to the immutable subject rather than the name, a UPN your tenant later reassigns to a different person maps to a new DTM account instead of inheriting the old one.
• Order does not matter. Creating a local account that happens to match an Entra UPN, before or after enabling SSO, is allowed and has no effect on the Entra identity.
• Turning SSO off later. Entra-created accounts hold no password, so they can no longer sign in; the accounts and their audit history remain, and the same people map back to the same accounts if you re-enable SSO. Local accounts are unaffected throughout.
• Sessions. Enabling or disabling SSO does not revoke tokens that are already issued; they run out their 24-hour lifetime. Disabling or deleting any account, local or Entra, cuts its tokens off immediately, because every request re-checks the account.

Register the application in Entra

1. In the Azure portal, go to Microsoft Entra ID → App registrations → New registration.
2. Give it a name (for example Hayami DTM).
3. Add a redirect URI of type Web pointing at DTM’s callback endpoint, for example https://dtm.example.com/api/v1/auth/entra/callback.
4. Note the Application (client) ID and Directory (tenant) ID.
5. Under Certificates & secrets, create a client secret and copy its value.
6. Under App roles, create an app role named Admin (allowed member type: Users/Groups).
7. Under Enterprise applications → your app → Users and groups, assign the Admin app role to the users or groups who should administer DTM.

Configure DTM

Provide the tenant ID, client ID, client secret, and redirect URI to DTM. You can do this from the Settings area of the UI, with the dtm_sso_config Terraform resource (the client secret is a write-only argument that never enters state; see users and SSO as code), or over the API (admin role):

curl -sk -X PUT https://dtm.internal:8443/api/v1/auth/entra/config \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "<tenant-id>",
    "client_id": "<client-id>",
    "client_secret": "<client-secret>",
    "redirect_uri": "https://dtm.example.com/api/v1/auth/entra/callback"
  }'

The stored client secret is redacted when you read the config back (GET /api/v1/auth/entra/config).

Verify

• Check that SSO is enabled:

  curl -sk https://dtm.internal:8443/api/v1/auth/entra/status
  # {"configured": true}

• Open the UI sign-in page: a Sign in with Microsoft button appears. Sign in as a user with the Admin app role and confirm you have admin access; sign in as a user without it and confirm read-only access.

Note

Rotate the Entra client secret on your normal schedule at the app registration, then update DTM’s config with the new value. Local accounts continue to work alongside SSO, so keep at least one local admin account as a break-glass path. If an SSO misconfiguration ever locks every admin out, the local admin password can be reset offline.