SSO setup — Okta

Connect Okta to Pact for SAML 2.0 single sign-on and (optionally) SCIM 2.0 user provisioning. Set-up is about 10 minutes. You configure a SAML app in Okta, paste two URLs, map four attributes, and test — Pact is IdP-agnostic, so nothing here is Okta-specific beyond the screen names.

Before you start

• You need the owner or admin role in Pact and Super Admin in Okta.
• Decide your sign-in domain (e.g. acme.com). You will verify it before enforcing SSO.
• Open Pact at Admin → Single Sign-On (/admin/sso) in one tab and the Okta admin console in another.

Pact's Service Provider values

Pact's SAML endpoints carry your workspace ID, so each workspace's sign-ins land in that workspace and nowhere else. You need these values:

Field	Value
ACS URL (Single Sign-On URL / Recipient / Destination)	https://<your-pact-api-host>/v1/sso/saml/acs/<workspace-id>
SP Entity ID (Audience URI)	https://<your-pact-api-host>/v1/sso/saml
Single Logout URL (optional, HTTP-Redirect)	https://<your-pact-api-host>/v1/sso/saml/slo/<workspace-id>
Name ID format	EmailAddress
Application username	Email

Copy these from Pact, not from this page. Admin → Single Sign-On shows the exact values for your workspace, and GET /v1/admin/saml/sp-metadata.xml downloads them as SP metadata. Two details decide whether sign-in works: the ACS URL ends in your workspace ID (the bare /v1/sso/saml/acs only serves a deployment's default workspace), and the Entity ID is /v1/sso/saml itself — not the metadata URL. An IdP that uses the metadata URL as its audience issues assertions Pact refuses (auth.saml.acs.failure, reason validation_failed).

1. Create the Okta SAML app

1. In Okta: Applications → Applications → Create App Integration.
2. Choose SAML 2.0, click Next.
3. Name it "Pact", click Next.
4. Under SAML Settings:
   • Single sign-on URL → Pact's ACS URL above.
   • Audience URI (SP Entity ID) → Pact's SP Entity ID above.
   • Name ID format → EmailAddress.
   • Application username → Email.

2. Map attributes

In the Okta SAML app's Attribute Statements, add:

Name (Okta sends)	Value
email	user.email
firstName	user.firstName
lastName	user.lastName

For group-to-role mapping, add a Group Attribute Statement:

Name	Filter
groups	Matches regex .* (or a prefix like pact-)

In Pact's Add IdP form these map to:

Pact field	Okta value
Email attribute	email
First-name attribute	firstName
Last-name attribute	lastName
Groups attribute	groups

3. Register Okta in Pact

The fastest path is metadata:

1. In Okta: Applications → Pact → Sign On → SAML Setup Instructions (or View IdP metadata) and copy the metadata URL (or download the XML).
2. In Pact: Admin → SSO (SAML) → Add IdP.
3. Paste the Metadata URL and click Fetch (or paste the XML and click Auto-fill). This fills the IdP entity ID, SSO URL, and signing certificate.
4. Set a Display name ("Okta — Production") and the Email domain (acme.com).
5. Confirm the attribute mappings from step 2.
6. Save.

Storing the metadata URL lets you click Refresh later to rotate Okta's signing certificate without re-pasting anything.

4. Map groups to roles (optional)

In the Add/Edit IdP form, Group → role mapping lets an Okta group confer a Pact role at login:

IdP group (as sent in groups)	Pact role
pact-admins	admin
pact-managers	manager
pact-everyone	member

On each login the user is elevated to the highest-precedence matched role. Groups never demote — to lower a role, change it on the user directly. (If you use SCIM, group membership is synced there too and composes the same way.)

5. Test before enforcing

1. In Pact: Admin → SSO (SAML), click Test on the Okta row. Pact opens an SP-initiated login in a new tab.
2. Complete the Okta login. On success you land back in Pact and the event appears in the audit log (auth.saml.acs.success).
3. A failure is logged as auth.saml.acs.failure with the exact reason (cert mismatch, missing email, audience, etc.).
4. Admin → Single Sign-On now shows the IdP as verified, with the time and email of the last sign-in — and, if one was refused, when and why.

The Test button never disrupts other users — it's just a normal SP-initiated login from your browser.

6. (Optional) Signed AuthnRequests

If your Okta policy requires the SP to sign requests:

1. Admin → SSO (SAML) → SP signing key → Generate signing key. Pact mints a per-tenant keypair; the private key is encrypted at rest.
2. Re-download SP metadata (it now advertises the signing cert) and upload it to Okta, or enable request-signature validation in Okta.
3. In the Pact IdP form, tick Sign AuthnRequests.

7. Verify your domain, then enforce SSO

1. Admin → SSO → Domains → Add domain (acme.com). Pact gives you a DNS TXT record.
2. Add the TXT record at your DNS provider, then click Verify.
3. Designate a break-glass admin (see below) — do this before the next step.
4. Toggle Require SSO for all users. Password and passkey login are now closed for everyone except break-glass admins.

Break-glass / emergency access

If Okta is ever unavailable, a tenant with SSO enforced would otherwise be locked out. Pact's escape hatch: under Admin → SSO → Enforcement → Break-glass emergency admins, designate one or more owners/admins. They keep password login even with SSO required, and every break-glass login is recorded in the audit log (auth.break_glass.used). This mirrors the super-admin exclusion Okta itself recommends.

SCIM provisioning (optional)

To push user creates / updates / deactivations and group memberships automatically, see SCIM provisioning. Mint a token under Admin → Identity (SCIM), then in Okta enable Provisioning → SCIM with the base URL https://<your-pact-host>/scim/v2 and an HTTP Header bearer token.

Related

• SSO & SCIM overview
• SCIM provisioning
• Microsoft Entra ID setup