Skip to content

Microsoft Entra ID sign-in

Lets staff sign in with their Microsoft 365 / Entra ID work account. You need an owner account in Crow HR, rights to register applications in your Entra tenant, and PUBLIC_URL set to its final address.

What Crow HR does

Section titled “What Crow HR does”
  • OpenID Connect against https://login.microsoftonline.com/<tenant id>/v2.0 with scopes openid email profile, authorisation code flow with PKCE.
  • Single tenant only. The tenant ID is required, multi-tenant values (common, organizations, consumers) are refused, and any token whose tid differs from your tenant is rejected (tid_mismatch).
  • A matching tenant does not verify the email claim. Automatic email linking requires xms_edov: true, the optional domain-verification claim (Microsoft reference). Without it, use the invitation link for the first sign-in; later sign-ins match the already-linked issuer and subject. Configure the optional email and xms_edov ID-token claims if you want automatic linking.

Set it up

Section titled “Set it up”

  1. Microsoft Entra admin centre: open App registrations → New registration. Name it (for example “Crow HR”) and choose Accounts in this organizational directory only (single tenant). Leave the redirect URI empty for now and register.

  2. On the app’s Overview page copy the Directory (tenant) ID and the Application (client) ID.

  3. Under Certificates & secrets → Client secrets, create a secret and copy its Value (not the Secret ID). Note its expiry date: sign-in stops working when it expires, and you then paste a new secret into Crow HR.

  4. Crow HR: in Settings → Security choose Add a method → Microsoft Entra ID. Paste the tenant ID, client ID and secret. Optionally add allowed email domains (used only to limit JIT accounts). Save.

  5. Copy the Redirect URI shown after saving (https://hr.example.sg/api/v1/auth/oidc/<provider id>/callback).

  6. Entra: in the app registration open Authentication → Add a platform → Web and paste the redirect URI. Save.

  7. Crow HR: use Test sign-in, then switch the method on.

Check

Section titled “Check”
  • A member whose email matches and whose token has xms_edov: true can link automatically; otherwise start from their invitation.
  • A personal Microsoft account or another tenant’s account is refused (tid_mismatch in the audit log).
  • Enforce MFA with Entra (security defaults or Conditional Access). Crow HR also enforces its MFA policy unless the validated ID token explicitly asserts MFA.

Common errors

Section titled “Common errors”
Symptom Cause
Microsoft error AADSTS50011 (redirect URI mismatch) The Web platform redirect URI does not exactly match the one Crow HR showed.
Sign-in worked, then stopped months later The client secret expired. Create a new one and paste it in Edit.
“Your account has not been set up” No member with that email, or the token lacks a verified email (xms_edov: true). Use the invitation link.

Tested against an in-process mock identity provider in Crow HR’s test suite, not against a live Entra tenant in CI.