OpenAssistantAPI
→

Setting up Okta (SAML + SCIM)

Step-by-step Okta configuration for single sign-on and automatic user provisioning.

This is a click-by-click walkthrough for Okta specifically. See the SSO guide and SCIM guide for what each feature does and why you'd want it.

Okta login and Okta provisioning are two separate app integrations in Okta. You need both if you want users to both log in via Okta and be automatically created/removed as your directory changes — but each is independently useful on its own.

Before you start, make sure your company email domain is verified under Organization → Settings → Domains — users are routed to Okta based on their email domain.

Part 1 — SAML app (login)

  1. In the Okta Admin Console, go to Applications → Create App Integration and choose SAML 2.0.
  2. Give it a name, e.g. "OpenAssistant SSO".
  3. On the Configure SAML step, set:
    • Single sign-on URL (ACS URL): https://app.openassistant.us/api/sso/saml/acs
    • Audience URI (SP Entity ID): https://app.openassistant.us/api/sso/saml/metadata
    • Name ID format: EmailAddress
    • Application username: Email
  4. Under Attribute Statements, map:
    • email → user.email
    • firstName → user.firstName
    • lastName → user.lastName
  5. Finish, then open the app's Sign On tab and click View SAML setup instructions (or copy the Identity Provider SSO URL, Issuer, and X.509 certificate directly from that page).
  6. In OpenAssistant, go to Organization → SSO, choose SAML 2.0 (Generic), and paste those three values into Entry Point URL, IdP Entity ID (Issuer), and X.509 Certificate. Under Member Sync, choose SCIM 2.0, then click Configure SSO. (The same screen shows the ACS URL and Entity ID from step 3, if you need to copy them.)
  7. Open the app's Assignments tab in Okta and assign the people or groups who should have access. Creating the app does not grant anyone access — this is a separate, required step.
  8. Back in OpenAssistant's SSO settings, turn on Enable SSO. Leave Enforce SSO off for now.
  9. Sign in as an assigned Okta user (an incognito window works well) to confirm the full round trip. Once it works, you can turn on Enforce SSO if you want to require it.

Part 2 — SCIM app (provisioning)

  1. In Okta, create a second app integration. Search the catalog for "SCIM 2.0 Test App (OAuth Bearer Token)".

    Use the OAuth Bearer Token variant specifically. The similarly-named "Header Auth" variant doesn't produce a standard Authorization: Bearer <token> header, and OpenAssistant's SCIM endpoint will reject it with an "Authorization header with Bearer token is required" error.

  2. In OpenAssistant, go to Organization → SSO. In the SCIM Provisioning section (shown when the sync method is SCIM 2.0), click Regenerate Token. The token is displayed when you generate it, so copy it somewhere safe — later visits show only that a token exists. Generating a new token invalidates the previous one.

  3. In the Okta app, go to Provisioning → Integration, check Enable API integration, and enter:

    • SCIM 2.0 Base URL: https://app.openassistant.us/api/scim/v2
    • OAuth Bearer Token: the token from step 2

  4. Click Test API Credentials to confirm before saving.

  5. Under Provisioning → To App, enable Create Users, Update User Attributes, and Deactivate Users.

  6. Assign users or groups under the app's Assignments tab to trigger provisioning. Just like the SAML app, this is a separate step from creating the integration — nothing syncs until someone is assigned.

Troubleshooting

"User is not assigned to this application" at Okta's login screen Add the user to the SAML app's Assignments tab (Part 1, step 7). Being assigned to the SCIM app doesn't count — they're independent assignments.

A freshly-created Okta user can't sign in at all New Okta users default to "Pending user action" until they complete account activation via the emailed link. Either wait for them to activate, or use an already-active account to test the login flow itself.

The SCIM integration stopped working after nothing changed on your end If your Okta admin session timed out and you had to log back in (Okta sessions time out fairly aggressively and require MFA re-entry), check Provisioning → Integration on the SCIM app again — the "Enable API integration" checkbox can silently reset to unchecked even though the Base URL and token are still saved underneath. Re-check the box and re-run Test API Credentials.

Provisioning ran but the user never showed up Confirm the user (or their group) is actually assigned to the SCIM app — see Part 2, step 6.