PPact
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 in one call — including your workspace's SP values (sp.acs_url, sp.entity_id, sp.slo_url), and, per IdP, whether a real sign-in has completed (verified, last_login_at) and the last refusal and its reason. scim reports active tokens, the last time your IdP called (last_sync_at) and how many users it provisioned. A read that failed is listed in gaps; it never shows as "never". 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; your workspace's SP metadata is GET /v1/admin/saml/sp-metadata.xml (or the public GET /v1/sso/saml/metadata.xml?tenant=<workspace-id>).

  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?tenant=<workspace-id>, GET /v1/sso/saml/login (SP-initiated start), POST /v1/sso/saml/acs/<workspace-id> (assertion consumer service), GET|POST /v1/sso/saml/slo/<workspace-id> (single logout, HTTP-Redirect or HTTP-POST binding), plus /logout and an email-domain IdP /discover endpoint. An IdP-initiated LogoutRequest must be signed; it ends the user's Pact session. The tenant-less /acs and /slo remain for configurations made before the workspace-scoped URLs and serve only the deployment's default workspace.

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.*.