Turn on Microsoft Entra ID

Sign in through Microsoft Entra ID instead of the factory's own account list, with the role decided by security-group membership rather than a row somebody edited.

Before you start

• Rights to create an app registration in the tenant, or the identity team's help with the steps below.
• The GUIDs of the security groups that should map to each role.
• SECRET_KEY, to sign the session cookie, and DPF_PREFIX if the factory is mounted under a path on the host.

Steps

1. Register the application

In Microsoft Entra admin centre → App registrations → New registration:

1. Supported account types: Accounts in this organizational directory only — single tenant.
2. Redirect URI: platform Web, https://<host>/auth/callback — or https://<host><DPF_PREFIX>/auth/callback when mounted under a path. It must equal DPF_ENTRA_REDIRECT_URI exactly, scheme included.
3. Certificates & secrets → New client secret. Copy the Value, not the Secret ID, and note its expiry: Entra caps it at 24 months and sign-in stops that day with no other warning.
4. API permissions: openid, profile, email — Microsoft Graph, delegated — and nothing else. No GroupMember.Read.All, no User.Read.All: the factory reads the groups already on the token and never calls Graph.
5. Token configuration → Add groups claim: choose Security groups (or Groups assigned to the application — see group overage, below), and tick Group ID under ID.
6. Enterprise applications → this app → Users and groups: assign the groups you map in the next step. Set Assignment required to Yes, so Entra is the first refusal rather than the factory's own.

2. Set the environment

export DPF_IDENTITY=entra
export DPF_ENTRA_TENANT_ID=…        # the directory (tenant) id
export DPF_ENTRA_CLIENT_ID=…        # the application (client) id
export DPF_ENTRA_CLIENT_SECRET=…    # the secret's Value, not its id
export DPF_ENTRA_REDIRECT_URI=https://<host>/auth/callback
export DPF_ENTRA_ROLE_MAP=use_case=<guid>,data_hub=<guid>,admin=<guid>,source_system:<system>=<guid>
export SECRET_KEY=…

Besides DPF_IDENTITY, all six are required; the factory refuses to start without any one of them. DPF_ENTRA_ROLE_MAP is comma-separated role=group pairs — a group id, or a name where the tenant is set to emit names, matched case-insensitively. A source owner's rule also names the system it answers for, using that system's own key from the Users page: source_system:<system>=<guid>. A role may appear more than once. DPF_ENTRA_SESSION_HOURS (default 8) and DPF_ENTRA_AUTHORITY (default the public cloud) are optional.

3. Restart, then sign in

Restart the service. Signing in for the first time creates the person's row from their token — there is no "add somebody" form in this mode.

Check that it worked

Sign in as somebody in a mapped group and confirm the role shown is the one that group grants. On the Users page, Act as is refused with a 403 naming the group that would grant the requested role — that refusal is this mode working, not a fault.

Group overage

Entra puts at most about 200 groups in an id_token; above that it replaces the claim with a link to Microsoft Graph, which this application deliberately does not read. Sign-in is refused with "group overage" rather than being read as no groups. The fix is step 1.5 above: set the groups claim to Groups assigned to the application, which emits only the ones that matter.

If it does not work

Symptom	Fix
"Entra sign-in is not configured" (503)	A required variable is missing or was unset after start-up — check it against the list in step 2.
Signed in, then refused with no row created	Nobody is in a mapped group. There is no default role: check DPF_ENTRA_ROLE_MAP and the group assignment in Entra, not the application.
"group overage"	See above.
"Act as" refused, naming a group	Expected — Entra decides the role here. Ask the identity team to add the person to the named group instead.

What to tell the identity team

One single-tenant app registration, one redirect URI, one secret. Delegated openid profile email only — no Graph read, no application permissions, no directory access. Authorization code flow with PKCE; the id_token's signature, issuer, audience, tenant, expiry and nonce are all validated. Authorisation is by group, and the mapping lives in this application's environment, not in Entra — joiners-movers-leavers stays entirely theirs. Sessions last DPF_ENTRA_SESSION_HOURS (default 8 hours); sign-out is local only, not federated.

Related

• Identity — why the narrowest matching role wins, and why no mapped group means no access at all.
• Configuration — every DPF_ENTRA_* variable.
• Roles and permissions — the roles the groups map to.