SAML — Okta

SAML 2.0 is the enterprise SSO protocol. Your partner organisation's IT team manages an Okta tenant; their employees sign into many products through Okta; they want to add yours to that list. The right shape is a SAML connection where IntelliAuth is the Service Provider (SP) and Okta is the Identity Provider (IdP).

This guide walks the full handshake. The flow has more moving pieces than OIDC — XML, certificates, metadata documents — but each piece serves a purpose.

The mental model

IdP-initiated SSO — Okta is the entry point. SP-initiated (user starts at your app) is also supported with the same setup.

This is IdP-initiated SSO — Okta is the entry point. SP-initiated (user starts at your app, gets sent to Okta) is also supported and uses the same setup.

Before you start

The customer's IT admin needs:

• Admin access to their Okta tenant.
• Permission to create SAML applications.

You need:

• Your IntelliAuth tenant URL ready to share.

This is a two-side setup; you and the IdP-owning organisation's IT will each configure half.

Step 1 — start the connection on the IntelliAuth side

Tenant admin console → Authentication → SAML connections → New connection.

Fill in:

• Connection name — your label, e.g. "Cymmetri Okta".
• Slug — URL-safe identifier, e.g. cymmetri-okta. Becomes part of the ACS URL. Pick carefully — the slug is locked once the connection saves; renames mean recreating the connection.

Save. IntelliAuth gives you back two values you will share with the customer:

• ACS URL (Assertion Consumer Service URL) — https://<your-tenant-url>/auth/saml/cymmetri-okta/acs. This is where Okta will POST the SAML response.
• SP Entity ID — https://<your-tenant-url>/saml/cymmetri-okta. This is how IntelliAuth identifies itself to Okta.
• Service Provider metadata URL — a downloadable XML document describing the SP. Many IdPs accept this URL directly instead of asking for ACS + Entity ID manually.

Step 2 — configure the application in Okta

The customer's IT admin in Okta:

1. Applications → Create App Integration → SAML 2.0 → Next.

2. General settings:

   • App name: whatever they want users to see ("Cymmetri Banking").
   • Logo: optional.

3. SAML settings:

   • Single sign-on URL: paste the ACS URL you provided.
   • Audience URI (SP Entity ID): paste the SP Entity ID.
   • Name ID format: EmailAddress. (Unspecified works but is less interoperable.)
   • Application username: Email typically. This is what Okta sends as the SAML NameID.

4. Attribute statements — map Okta user attributes to SAML attributes. Common mapping:

   Name	Value
   email	user.email
   firstName	user.firstName
   lastName	user.lastName
   displayName	user.displayName
   groups	(group filter: Matches regex .* for all, or limit to specific groups)

5. Save.

Step 3 — give IntelliAuth the IdP metadata

In Okta's app: Sign On tab → "View SAML setup instructions" or "Identity Provider metadata" → copy the XML or the URL.

Back in IntelliAuth's SAML connection editor:

• IdP metadata — paste the XML, or paste the URL (IntelliAuth fetches it). The fields IntelliAuth fills from this:
  • IdP Entity ID.
  • IdP SSO URL.
  • X.509 signing certificate.

Save.

Step 4 — attribute mapping on the IntelliAuth side

For each SAML attribute Okta sends, decide what to do with it on the IntelliAuth user record. Defaults are sensible:

• email → user's email.
• firstName → given name.
• lastName → family name.
• groups → group memberships (auto-create groups in IntelliAuth if they don't exist, or only attach to existing).

Custom claims (department, region, employee id) map to user attributes on the IntelliAuth side. The full attribute mapping screen is in the connection's Advanced tab.

Step 5 — JIT provisioning

For SSO to feel seamless, new users should be created automatically the first time they sign in via Okta — no pre-provisioning required. Enable the Just-in-time provisioning toggle in the SAML connection.

When JIT is on:

• First sign-in: a new IntelliAuth user record is created from the SAML attributes.
• Subsequent sign-ins: the user is matched by NameID (the SAML subject) and the record is updated with fresh attributes.

When JIT is off, signing in via SAML requires the user to exist in IntelliAuth already — useful for pre-allocated B2B tenant seats.

Step 6 — test

In Okta, assign the new application to a test user. Have that user sign into Okta and click the Cymmetri tile. They should land in your app, signed in. Check the audit log on the IntelliAuth side — every SAML sign-in attempt is recorded, success or failure.

Common failures

• InResponseTo mismatch on SP-initiated flows — Okta sometimes strips the InResponseTo value, causing strict validators to refuse. The connection has a "Tolerate missing InResponseTo" toggle; turn it on for Okta unless you have a security reason not to.
• Certificate expired — Okta's signing certificate rotates. IntelliAuth fetches the metadata URL on each sign-in, so this is invisible if you used the metadata URL. If you pasted the XML by hand, watch for expiry warnings in the audit log and refresh.
• Clock skew — SAML assertions have tight validity windows (5 minutes by default). If Okta and IntelliAuth disagree on time by more than the window, sign-ins fail. The SP allows 30 seconds of clock skew by default; widen if needed.

The audit log surfaces the specific SAML error code for each failure. That code, plus Okta's documentation, will point you at the exact configuration field.

See also

• SAML — Microsoft Entra ID
• Federation — OIDC and SAML
• Custom OIDC provider