Single sign-on (OIDC): Entra ID, Google Workspace, Okta

Staff sign in with the account their organisation already gives them; the portal never sees a password. One connection per organisation, managed under Settings → Security → Single sign-on, which also shows the exact redirect URI to register with the identity provider:

https://app.cardoffice.nz/api/auth/sso/callback

(Substitute your own host on a self-hosted deployment — it must match APP_URL exactly, scheme and all.)

Every connection needs the same three things from the IdP: a discovery URL, a client ID, and a client secret. The walkthroughs below get you those. SAML is not supported; all three providers speak OIDC.

What signing in looks like

The login page gains a Use single sign-on option: the person enters their work email, the domain routes them to their organisation’s IdP, and they come back signed in. First sign-in creates their account automatically (unless auto-provisioning is off), as a staff user or whatever the role mapping says.

Portal passwords and portal 2FA do not apply to SSO sessions — credentials and MFA are the IdP’s job. The Enforce single sign-on toggle under Security refuses password sign-in for anyone whose email domain has an active connection (super admins stay exempt, so a broken IdP cannot lock the bureau out). Turn enforcement on only after a real sign-in has worked.

Microsoft Entra ID

1. Register an application: entra.microsoft.com → Identity → Applications → App registrations → New registration. Single tenant. Platform Web, redirect URI as above.

2. Client secret: Certificates & secrets → New client secret. Copy the Value immediately (it is shown once). Note the expiry — Entra secrets live 6–24 months and a calendar entry now beats an outage later.

3. Collect the IDs: the Overview page shows the Application (client) ID and the Directory (tenant) ID. The discovery URL is:

   https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

   It must contain your tenant ID. The portal rejects common, organizations and consumers endpoints outright — a multi-tenant endpoint would accept sign-ins from any Microsoft directory in the world.

4. Email claim: Entra only sends email when the account has one. For accounts without a mail attribute, add the optional claim: Token configuration → Add optional claim → ID → email.

5. Role mapping (optional): App roles → create roles (e.g. card-office), assign users/groups to them, and map the same strings under Role mapping in the portal. They arrive in the roles claim.

Google Workspace

1. OAuth client: console.cloud.google.com → APIs & Services → Credentials → Create credentials → OAuth client ID → Web application. Authorised redirect URI as above.

2. Consent screen: set User type Internal — the portal is for your organisation’s staff, and Internal skips Google’s app verification process entirely.

3. Discovery URL (the same for every Workspace):

   https://accounts.google.com/.well-known/openid-configuration

4. Domain enforcement: the portal requires Google’s hd claim to match one of the connection’s email domains. Consumer @gmail.com accounts are refused even if invited — only Workspace members of your domain get in.

5. Google has no role/group claim in the ID token; leave role mapping empty and set roles in the portal after first sign-in.

Okta

1. App integration: Admin console → Applications → Create App Integration → OIDC – Web Application. Sign-in redirect URI as above. Assign the people or groups who should have access.

2. Discovery URL (org authorization server):

   https://<your-org>.okta.com/.well-known/openid-configuration

   If you use a custom authorization server, use its discovery URL instead — what matters is that the issuer in the document is the one that will sign the tokens.

3. Role mapping (optional): add a groups claim to the ID token (Sign On → OpenID Connect ID Token → Groups claim filter), then map group names under Role mapping in the portal.

Role mapping rules

• Applies to newly provisioned accounts only. SSO never changes the role of an existing account — roles are managed in the portal.
• Mappable roles: administrator, staff user, print operator. A mapping can never grant super admin, and card holders cannot sign in at all.
• Anyone whose claims match nothing becomes a staff user.

Troubleshooting

• “Single sign-on didn’t complete.” The audit log (Settings → area admin) records the reason for every refused SSO sign-in: domain mismatch, unverified email, token exchange failure. The login page stays vague on purpose.
• Test button: each connection’s Test runs discovery and reports the issuer the IdP claims. It validates the URL, not the secret — the secret is only exercised by a real sign-in.
• Clock or nonce errors usually mean the flow took longer than ten minutes (the transaction cookie’s life) — try again.
• Entra: no email in token — see the optional claim in step 4 above; the portal refuses tokens without a usable email rather than guessing from preferred_username.
• Kill switch: FEATURE_SSO=false in the deployment env hides the login panel, the settings page, and disables both SSO routes.