Microsoft Entra ID (SSO)

Engineers sign in to the AVA dashboard with their existing Microsoft 365
accounts — no separate passwords to manage, and sign-in is restricted to a
single Entra security group you control. This page walks through the app
registration, the groups-claim token configuration, and how engineers map to
AutoTask Resources.

The client chat page has no login at all (it is protected by reCAPTCHA and
rate limiting instead — see recaptcha-email.md);
Entra ID applies only to the engineer dashboard.

How the flow works

The OAuth flow is entirely server-side (@azure/msal-node) using the
authorization-code flow with PKCE. The browser never holds Azure tokens —
after Microsoft sign-in completes, AVA issues its own signed, HTTP-only
session cookie (HS256 JWT, 24-hour expiry, signed with NEXTAUTH_SECRET).
The requested scopes are openid, profile, email, User.Read — standard
sign-in scopes, no directory-wide permissions.

Authorization is a two-gate check on every sign-in:

1. Authentication — Microsoft confirms the user's identity.
2. Group membership — AVA reads the groups claim from the Entra ID token
   and requires it to contain your engineering group's object ID. This check
   is fail-closed (details below).

Step 1 — Create the app registration

In the Entra admin center: App registrations → New registration. Collect:

Redirect URI precision matters. The value on the app registration and the
AZURE_AD_REDIRECT_URI env var must match character-for-character — scheme,
host, and path. A mismatch produces a Microsoft-side error before AVA is ever
reached. For local development, http://localhost:3000/api/auth/callback can
be added as an additional redirect URI.

Step 2 — Create the engineer security group

Create (or choose) an Entra security group and add every engineer who
should be able to use the dashboard. Note its object ID:

ENGINEERING_GROUP_ID=<group-object-id-guid>

Membership in this group is the only thing that authorizes dashboard access.
Adding an engineer to the group grants access on their next sign-in; removing
them blocks new sign-ins immediately (their existing session cookie expires
within 24 hours).

Step 3 — Emit the groups claim in the ID token

By default, Entra ID tokens do not include group membership. Configure the
app registration to emit it:

App registration → Token configuration → Add groups claim → select
Security groups, for the ID token.

Without this, every sign-in — including valid group members — is denied with
access_denied. That is fail-closed behavior working as designed, and it is
the single most common Entra setup miss.

Large-directory note (groups overage). If an engineer belongs to very
many groups, Entra stops emitting the full groups array inline and
substitutes an overage reference instead. AVA treats a missing/malformed
groups claim as a denial (fail-closed), so those engineers would be locked
out. If this applies to your directory, configure the app registration to
emit groups assigned to the application only (and assign your
engineering group to the app), which keeps the claim inline regardless of
total membership count.

The fail-closed authorization contract

AVA's group check accepts a sign-in only when the ID token's groups
claim is a string array that includes ENGINEERING_GROUP_ID. Every other
condition denies, each with a distinct reason in the server logs:

There is no configuration that weakens this: a misconfigured deployment locks
engineers out rather than letting anyone in.

Engineer → AutoTask Resource mapping

On an engineer's first sign-in, AVA auto-creates their engineer record and
looks up an AutoTask Resource whose email matches their O365 sign-in
email, storing the mapping. This is how time entries and ticket assignments
attribute to the right person in AutoTask.

Practical implications:

• Make each engineer's O365 sign-in email match their AutoTask resource
  email before their first login. The comparison is by email address.
• If no matching resource is found, the engineer still signs in — chats
  work normally; time entries just fall back to the default role
  (AUTOTASK_DEFAULT_ROLE_ID, see autotask-setup.md)
  without per-resource attribution.
• The lookup runs at first sign-in. If you create the AutoTask resource
  after an engineer's first login, the stored mapping stays unmapped — plan
  to have resources in place before onboarding engineers.
• There is no separate admin onboarding flow: being in the Entra group is
  the onboarding. Repeat sign-in for each engineer and you're done.

The Resources entity read that powers this lookup is part of the AutoTask
security-level grants in autotask-setup.md Step 2.

Environment variable summary

Troubleshooting

Next steps

• autotask-setup.md — the AutoTask side of resource
  mapping and everything else PSA.
• configuration.md — the full environment variable
  reference.
• quickstart.md — first engineer login is Step 9 of the
  bring-up.