SSO setup — Okta
Step-by-step SAML 2.0 single sign-on and SCIM 2.0 provisioning setup for Okta, with exact field values, group-to-role mapping, and break-glass access.
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 exposes one Service Provider for the whole deployment; multi-tenant routing happens from the SAML Issuer. You need these two values (also shown in the wizard, and downloadable as SP metadata XML):
| Field | Value |
|---|---|
| ACS URL (Single Sign-On URL / Recipient / Destination) | https://<your-pact-host>/v1/sso/saml/acs |
| SP Entity ID (Audience URI) | https://<your-pact-host>/v1/sso/saml/metadata.xml |
| Name ID format | EmailAddress |
| Application username | Email |
Get the exact values for your deployment from Admin → SSO (SAML) → Show SP metadata, or
GET /v1/admin/saml/sp-metadata.xml.
1. Create the Okta SAML app
- In Okta: Applications → Applications → Create App Integration.
- Choose SAML 2.0, click Next.
- Name it "Pact", click Next.
- 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:
- In Okta: Applications → Pact → Sign On → SAML Setup Instructions (or View IdP metadata) and copy the metadata URL (or download the XML).
- In Pact: Admin → SSO (SAML) → Add IdP.
- 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.
- Set a Display name ("Okta — Production") and the Email domain (
acme.com). - Confirm the attribute mappings from step 2.
- 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
- In Pact: Admin → SSO (SAML), click Test on the Okta row. Pact opens an SP-initiated login in a new tab.
- Complete the Okta login. On success you land back in Pact and the event appears in the audit log (
auth.saml.acs.success). - A failure is logged as
auth.saml.acs.failurewith the exact reason (cert mismatch, missing email, audience, etc.).
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:
- Admin → SSO (SAML) → SP signing key → Generate signing key. Pact mints a per-tenant keypair; the private key is encrypted at rest.
- Re-download SP metadata (it now advertises the signing cert) and upload it to Okta, or enable request-signature validation in Okta.
- In the Pact IdP form, tick Sign AuthnRequests.
7. Verify your domain, then enforce SSO
- Admin → SSO → Domains → Add domain (
acme.com). Pact gives you a DNS TXT record. - Add the TXT record at your DNS provider, then click Verify.
- Designate a break-glass admin (see below) — do this before the next step.
- 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.