PPactDocs
Administration

SSO

Configure single sign-on for Pact via SAML or OIDC, verify email domains, enforce SSO, provision users with SCIM, and set break-glass emergency accounts.

SSO

Pact supports enterprise single sign-on through SAML 2.0 and OIDC, with SCIM 2.0 for user and group provisioning. A guided setup wizard at /admin/sso walks you through Google Workspace (OIDC), Microsoft Entra ID (SAML or OIDC), and Okta (SAML). The wizard surface is api/routes/admin_sso.py; the provider runtimes are api/routes/auth_saml.py (SAML) and api/routes/auth_sso_oauth.py + core/sso.py (OIDC).

Setup wizard

GET /v1/admin/sso/status returns everything the wizard needs to render its three provider cards in one call. All wizard endpoints are owner/admin-only, and every mutation is audit-logged under the auth.sso.* action prefix.

  1. 1

    Configure a provider

    For OIDC, upsert config at PUT /v1/admin/sso/oidc-config (issuer, audience, client ID, JWKS URI, authorize/token URLs, redirect URI, allowed domains, default role, auto-provision flag). For SAML, use the SAML admin endpoints under /v1/admin/saml and expose your SP metadata at GET /v1/sso/saml/metadata.xml.

  2. 2

    Claim your email domain

    POST /v1/admin/sso/domains starts a DNS TXT verification flow. POST /v1/admin/sso/domains/{id}/verify re-checks the record. A verified domain is what lets Pact route users at that domain into your SSO configuration.

  3. 3

    Enforce SSO

    PATCH /v1/admin/sso/mode sets two opt-in flags: sso_required (block password login for the tenant) and sso_domain_auto_join (users authenticating from a claimed, verified domain join automatically).

SAML endpoints

The SAML runtime provides the standard SP surface: GET /v1/sso/saml/metadata.xml, GET /v1/sso/saml/login (SP-initiated start), POST /v1/sso/saml/acs (assertion consumer service), plus logout (/logout) and an email-domain IdP /discover endpoint. Single logout (POST /v1/sso/saml/slo) is routed but currently returns 501 — front-channel SLO is not yet wired.

OIDC endpoints

GET /v1/auth/sso/oauth/providers lists configured providers; GET /v1/auth/sso/{provider}/start begins the flow and GET /v1/auth/sso/{provider}/callback completes it. New users are provisioned with the default_role from your OIDC config when auto_provision is on.

SCIM provisioning

User and group lifecycle can be driven by your IdP over SCIM 2.0 at /scim/v2/Users and /scim/v2/Groups, authenticated with a per-tenant bearer token stored in tenant_scim_tokens (Pact does not reuse the login session for SCIM). See Groups for how provisioned groups map to roles and personas.

Break-glass emergency access

Don't lock yourself out

When SSO is enforced, designate one or more break-glass accounts that retain a working password login in case your IdP is unavailable. Manage them at GET /v1/admin/sso/break-glass and PUT /v1/admin/sso/break-glass/{user_id}. Break-glass can only be granted to an account that already holds owner or admin; every grant/revoke is audited under auth.sso.break_glass.*.

GroupsMap SCIM groups to roles and personas.Security settingsSession timeouts, MFA, and network policy.SessionsReview and revoke active sessions.Audit logEvery SSO change lands here under auth.sso.*.