PPact
Security & Privacy

SSO & SCIM setup

Configure SAML 2.0 single sign-on and SCIM 2.0 user provisioning for Okta, Microsoft Entra ID (Azure AD), Google Workspace, and OneLogin.

Pact federates with any SAML 2.0 IdP and supports SCIM 2.0 for automatic user lifecycle management. SAML carries the login. SCIM carries provisioning, deprovisioning, and group membership.

This page is the operator setup guide for the four most common IdPs. Pact is IdP-agnostic — anything that speaks SAML 2.0 (HTTP-POST binding on the ACS, HTTP-Redirect on the AuthnRequest) will work, including AD FS, Ping, JumpCloud, and Authentik.

What you get

  • Single sign-on — SAML 2.0 with assertion-signature verification, replay protection, audience restriction, and clock-skew tolerance per SAML Core §4.1.4.
  • JIT user provisioning — first login from your IdP creates the Pact user record. No manual seat onboarding.
  • SCIM 2.0 user lifecycle — push user creates, updates, deactivations, and group memberships from your IdP. Standard /scim/v2/Users and /scim/v2/Groups endpoints.
  • Per-domain SSO routing — users entering their work email at /login are auto-redirected to the right IdP via a discovery probe.
  • SP-initiated and IdP-initiated logins — both bindings work; the ACS handler validates InResponseTo correctly in both cases.
  • Single Logout — SP- and IdP-initiated SLO with embedded XML-DSig signature verification (closes the XML signature wrapping attack).
  • Full audit log — every SAML and SCIM event lands in the tenant audit log under the auth.saml.* and auth.scim.* action namespaces.

Where to set it up

Configure SSO in the admin UI — never through environment variables or platform secrets.

  • Wizard — /admin/sso walks through provider cards for Google Workspace, Microsoft Entra ID, and Okta. Domain claims, the SSO-required toggle, and the auto-join-by-domain switch all live here.
  • Direct SAML CRUD — /admin/sso-saml lists every IdP the tenant has registered, lets you paste IdP metadata XML or fill in entityID / SSO URL / certificate by hand, and offers a "Test connection" button that opens an SP-initiated login in a new tab.
  • SCIM token + groups — /admin/scim-groups generates the SCIM bearer token your IdP pushes into the Authorization: Bearer … header and shows the inbound provisioning audit feed.

Quick provider setup

Okta (SAML)

  1. In Pact, open /admin/sso-saml → Add IdP → copy the SP metadata URL shown in the dialog.
  2. In Okta admin → Applications → Create App Integration → SAML 2.0.
  3. App name: "Pact". Logo: download from the Pact brand kit (or skip).
  4. Single sign on URL: paste the ACS URL from Pact — it ends in your workspace ID (…/v1/sso/saml/acs/<workspace-id>).
  5. Audience URI (SP Entity ID): paste the SP entity ID from Pact (…/v1/sso/saml, not the metadata URL).
  6. Name ID format: EmailAddress. Application username: Email.
  7. Attribute statements — add these four:
    • email → user.email
    • firstName → user.firstName
    • lastName → user.lastName
    • groups (Group Attribute Statement, filter "Matches regex: .*") → user.groups
  8. In Okta → Sign-On tab → View SAML Setup Instructions → copy the Identity Provider metadata URL.
  9. Back in Pact → paste it into the IdP metadata URL field, save, then click Test connection.

Microsoft Entra ID / Azure AD (SAML)

  1. In Pact, open /admin/sso-saml and copy the SP metadata URL.
  2. In the Entra portal → Enterprise applications → New application → Create your own application → Integrate any other application you don't find in the gallery.
  3. Select Single sign-on → SAML.
  4. Basic SAML Configuration — paste the SP Identifier (entity ID), Reply URL (ACS), and Sign on URL from Pact.
  5. Attributes & Claims:
    • email → user.mail
    • firstName → user.givenname
    • lastName → user.surname
    • groups → group claim with "All groups" or "Groups assigned to the application"
  6. Download the Federation Metadata XML and paste it into Pact's IdP metadata field, save, then Test connection.
  7. Assign the app to the users / groups that should be able to sign in.

Google Workspace (OIDC via wizard)

Google Workspace uses OIDC in the Pact wizard — no XML required.

  1. In Pact, open /admin/sso → Google Workspace card → Set up.
  2. In Google Cloud Console → APIs & Services → Credentials → OAuth client ID → Web application.
  3. Authorized redirect URI: paste the redirect URI shown in Pact (https://app.pact.place/v1/sso/oauth/callback).
  4. Copy the Client ID and Client secret into the Pact wizard.
  5. Add the email domains you want to auto-route (e.g. @yourcompany.com).
  6. Click Save then Test connection.

OneLogin (SAML)

  1. In Pact, open /admin/sso-saml and copy the SP metadata URL + ACS URL.
  2. OneLogin admin → Applications → Add App → search for SAML Custom Connector (Advanced).
  3. Configuration tab:
    • Audience (EntityID) → paste Pact SP entityID.
    • Recipient → paste Pact ACS URL.
    • ACS (Consumer) URL Validator → ^https:\/\/app\.pact\.place\/v1\/sso\/saml\/acs$.
    • ACS (Consumer) URL → paste Pact ACS URL.
    • SAML signature element → Assertion.
    • SAML nameID format → Email.
  4. Parameters tab — map email, firstName, lastName, groups to the matching OneLogin user attributes.
  5. SSO tab → copy the Issuer URL and X.509 Certificate.
  6. In Pact → fill IdP Entity ID, SSO URL, X.509 cert by hand, save, then Test connection.

SCIM provisioning

SCIM is independent of SAML — you can run SAML without SCIM, or both. SCIM means your IdP can push new hires, role changes, and offboardings into Pact without an admin doing it by hand.

  1. In Pact → /admin/scim-groups → Generate SCIM token. Copy it once — Pact never shows it again.
  2. In your IdP's app → Provisioning → Configure API integration (or equivalent).
  3. SCIM Connector base URL: https://app.pact.place/scim/v2
  4. Authorization: Bearer <token> — bearer token mode.
  5. Map the standard SCIM attributes (userName, name.givenName, name.familyName, emails[0].value, active). Pact reads them from the standard SCIM 2.0 user schema (RFC 7643).
  6. Map groups → Pact roles via the group sync section in /admin/scim-groups. Each Pact role can be claimed by one or more IdP group names.

The supported SCIM operations:

OperationEndpointWhat it does in Pact
Create userPOST /scim/v2/UsersCreates the local user, JIT-provisions tenant membership.
Update userPATCH /scim/v2/Users/:idUpdates name/email; active=false deactivates.
Soft-deletePATCH active=falseUser can no longer log in. Data is retained.
Hard-deleteDELETE /scim/v2/Users/:idRemoves the user row. SOC 2 reviewers typically prefer soft-delete.
Create groupPOST /scim/v2/GroupsCreates a SCIM group; map to a Pact role for RBAC.
Update group membershipPATCH /scim/v2/Groups/:idAdds / removes members; role mapping fires on the next member login.
List + filterGET /scim/v2/Users?filter=...Standard SCIM filter syntax (RFC 7644).

Force-SSO and per-domain auto-join

Once Test connection succeeds, flip Require SSO for all users in /admin/sso. After that:

  • Email/password login is blocked for any account in your tenant.
  • The login page detects a verified SAML domain on email blur and renders Sign in with SSO above the password field.
  • The auto-join by verified domain switch is saved but not yet applied at sign-in. New users from your IdP are provisioned just-in-time on their first SAML login either way.

Domain claims require DNS TXT verification. Publish the TXT record value Pact gives you, then click Check TXT record — Pact checks when you click; it does not poll. Until the domain is verified, typing an address at that domain on the login page does not route to your SSO, even if a SAML connection names the domain: the admin page says "Unverified — sign-in routing is off until the TXT record is found". Ownership is exclusive — one Pact workspace per domain. If another workspace has already verified it, the check says so ("Owned elsewhere"); contact Pact support to transfer it.

Your Okta or Entra app tile (IdP-initiated sign-in) and direct SSO links work without a verified domain.

What gets audited

Every SAML and SCIM event lands in the tenant audit log under auth.saml.* and auth.scim.*. Examples:

  • auth.saml.login.start — SP-initiated login was kicked off.
  • auth.saml.acs.success — assertion validated, session issued.
  • auth.saml.acs.failure — assertion rejected; the reason field carries the taxonomy (signature_invalid, replay, audience_mismatch, notbefore, notafter, subject_missing, ...).
  • auth.saml.slo.success / .failure — Single Logout.
  • auth.saml.idp.created / .updated / .deleted — admin actions on the IdP config row.
  • auth.scim.user.created / .updated / .deactivated / .deleted.
  • auth.scim.group.created / .updated / .membership_changed.

Filter the audit log by action prefix in /admin/security/audit-log.

Troubleshooting

"Test connection" opens a tab but the IdP rejects the AuthnRequest. Your SP metadata in the IdP is stale. Re-download Pact's SP metadata XML and re-paste it. The entityID changes if you change your custom domain.

Login fails with signature_invalid in the audit log. The IdP signing cert in Pact doesn't match what the IdP is using. Re-fetch the IdP metadata URL or paste the current X.509 cert.

Login fails with audience_mismatch. The IdP is sending the wrong <Audience> element. It must equal Pact's SP entityID exactly.

SCIM returns 401 on every request. The bearer token rolled or was revoked. Re-generate in /admin/scim-groups and update your IdP.

Users land in Pact but with no role. No SCIM group → Pact role mapping fired. Add a mapping in /admin/scim-groups or grant a default role in /admin/iam.

My IdP isn't listed in the wizard. Use the Add IdP dialog in /admin/sso-saml — the manual fields work for any SAML 2.0 IdP. The wizard is a convenience layer; everything is generic SAML underneath.

SSO & SCIM setup — Pact Docs · Pact