Auth Governance
This guide is for the Warden side of identity: not how your end users sign in (that's authored in Studio → Auth Flows), but how you govern it — wiring up the identity providers your application trusts, and reaching for the forensic surfaces when you need to understand who signed in, from where, and whether anything looks wrong.
Everything here lives in Admin mode: provider configuration under Manage, the investigative surfaces under Monitor.
1. Connecting an identity provider
End-user identity providers are configured in Admin → Manage → End User Providers. Whether you're connecting Google, an enterprise OIDC provider, SAML to Okta or Entra, or AD/LDAP, the wizard walks the same three steps:
- Connection — the provider's endpoints and credentials: the issuer URL, client ID, and client secret for OIDC; the metadata URL or certificate for SAML; the bind credentials for LDAP. This is where the trust relationship is established.
- Attribute mapping — how the provider's claims map onto the identity fields your application reads. The provider calls it
email; your app expectsemailAddress; the mapping step reconciles them. Get this right and downstream policies that branch on user attributes work without surprises. - Test and save — the wizard runs a live round-trip against the provider before it saves, so a typo in the issuer URL or a mispasted secret surfaces here rather than in your users' faces at sign-in.
Rotate the client secret through Vault, not inline. The provider's client secret is a credential like any other — store it as a Vault secret and reference it, so that rotating it is a Vault operation with a ledger entry, not an untracked edit buried in provider config. When the provider forces a secret rotation, you rotate it in one place and the connection picks up the new value.
Provider configuration is per-project. You can — and usually should — run a stricter posture in production than in staging: tighter MFA requirements, a narrower set of allowed providers, shorter session lifetimes.
2. Investigating sessions during an incident
When something looks wrong — a credential-stuffing pattern, an account you think is compromised, a sign-in from a place that doesn't make sense — the session inventory at Admin → Monitor → Sessions is where you start. It lists active sessions with the signals you triage on: the user, MFA freshness, IP and geo, device, and last activity.
Two surfaces do two different jobs, and reaching for the right one saves time:
- The single-session view answers "what is this session doing?" Open it when you've already identified a suspect session and you want its full detail — its origin, its activity, the auth flow that created it — and, if it's hostile, to revoke it on the spot.
- Cross-session correlation answers "what else is connected to this?" Open it when one session is a thread you want to pull — correlate by user, by IP, by device fingerprint to surface the other sessions that share a signal. This is how you turn "one suspicious login" into "here are the eleven sessions from the same IP block in the last hour."
A practical triage order: start from a risk signal (a flagged session, a spike in failures), open the single-session view to confirm it's worth pursuing, then pivot to correlation to find the blast radius. Revoke from whichever surface you're on.
3. Querying the auth-flow audit trail
Session inventory tells you about sessions that exist now. To reconstruct what happened — every sign-in, magic-link redemption, MFA challenge, and OAuth callback, succeeded or failed — you query the auth-flow audit trail at Admin → Monitor → Auth Flows audit.
The trail is backed by the data.write.auth.* audit-event family (Security API reference), written to the project's signed ledger on every auth-flow transition. Each event carries the actor identity, the provider, the outcome, the session reference, and the originating IP, so queries can be precise. The audit-log query API exposes the same predicate surface the console uses — saved queries you build here can also be driven programmatically.
Common event types and the incident shapes they answer:
| Event | When it fires | Incident shape |
|---|---|---|
data.write.auth.session.created | Successful sign-in; session issued | Every new session for a user in a window |
data.write.auth.session.failed | Failed credential check, blocked sign-in | Failed sign-ins for a user or from an IP block |
data.write.auth.mfa.challenged | MFA challenge issued | Challenges issued but not paired with mfa.verified |
data.write.auth.mfa.verified | MFA step completed | Correlate with mfa.challenged to find abandoned challenges |
data.write.auth.oauth.callback | OAuth provider callback received | Callbacks from a specific provider that carried an error |
data.write.auth.magic_link.redeemed | Magic link consumed | Magic-link redemptions outside expected geo or device |
The surface takes a query expression so you can ask precise questions rather than scrolling. Common incident-response shapes:
- "Every failed sign-in for this user in the last 24 hours" — filter on
data.write.auth.session.failed, scope to the actor and the time window; this is your starting point when a user reports they're locked out or you suspect a targeted attack. - "All OAuth callbacks from this provider that errored" — filter on
data.write.auth.oauth.callbackwhere the outcome is an error, scope to the provider; this is how you tell "the provider is down" apart from "our config is wrong." - "MFA challenges that were issued but never completed, by IP" — filter on
data.write.auth.mfa.challengedwith no paireddata.write.auth.mfa.verified, grouped by originating IP; abandoned MFA at volume from one place is a credential-stuffing tell.
Save the queries you run often. An incident at 3am is not the time to reconstruct the query that finds dormant-account sign-ins — write it once, save it, and reach for it by name.
The handoff loop. Sessions and the audit trail are two ends of the same investigation, and you'll move between them: spot a suspicious live session in the inventory → pivot to the audit trail to see the flow that created it and whether the same actor has prior failed attempts → come back to the inventory to revoke the session and any correlated siblings. Neither surface is complete on its own; the investigation lives in the handoff.
See also
- Studio → Auth Flows — authoring the end-user sign-in experience (the other half of identity).
- Admin mode — where Manage (providers) and Monitor (sessions, audit) live.
- Vault mode — where provider client secrets should be stored and rotated.
- API → Auth — the identity substrate behind providers and sessions.
- API → Security — the audit-event contract behind the auth-flow trail.