Okta SSO + SCIM

This guide assumes:

• You are an Okta admin with access to the Admin console
• You have completed Mode A/B/C provisioning up to portal Step 4 (the “Configure SSO” step)

Total time: 10–15 minutes.

Part 1 — SAML SSO

1. In Claresia Onboarding Portal, click Configure SSO (Step 4). Choose the Okta tab. Copy the two values displayed:

   • Single sign-on URL (also called ACS URL): https://api.workos.com/sso/saml/acs/conn_<id>
   • Audience URI (also called SP Entity ID): https://api.workos.com/sso/saml/<conn-id>

2. In the Okta Admin console, go to Applications → Browse App Catalog, search for “Claresia”. If listed, click Add Integration. (If not yet listed, choose Create App Integration → SAML 2.0 → Next.)

3. General Settings:

   • App name: Claresia
   • App logo: upload from docs.claresia.com/brand/claresia-mark.svg
   • App visibility: visible to users (recommended)

4. Configure SAML:

   • Single sign-on URL: paste the ACS URL from Step 1
   • Audience URI (SP Entity ID): paste the Audience URI from Step 1
   • Default RelayState: leave blank
   • Name ID format: EmailAddress
   • Application username: Email
   • Update application username on: Create and update

5. Attribute Statements — add the following:

   Name	Name format	Value
   email	Unspecified	user.email
   firstName	Unspecified	user.firstName
   lastName	Unspecified	user.lastName
   groups	Unspecified	array.flatten(arrayContains(user.groups, 'claresia-'))

6. Group Attribute Statement:

   • Name: groups
   • Filter: Starts with → claresia-

7. Click Next → Finish. On the Sign On tab, click View SAML setup instructions, copy the Identity Provider Single Sign-On URL and the X.509 Certificate.

8. Back in Claresia Onboarding Portal, paste the IdP SSO URL + X.509 Certificate into the form. Click Test login — Claresia opens a popup, completes a real auth round-trip, and shows a green check.

Tip

If Test login fails with invalid_audience, double-check the Audience URI in the Okta app config matches exactly what the portal showed (no trailing slash, no https / http mix-up).

Part 2 — SCIM provisioning

1. In Claresia Onboarding Portal, click Configure SCIM (Step 5). Display the auto-generated SCIM endpoint URL + bearer token. Keep this tab open.

2. In Okta, open your Claresia app → Provisioning tab → Configure API Integration → check Enable API Integration.

3. Paste:

   • Base URL: the SCIM endpoint URL from Step 1 (looks like https://api.workos.com/scim/v2/<directory_id>)
   • API Token: the bearer token from Step 1

4. Click Test API Credentials. Should show “Claresia was verified successfully!”

5. Click Save.

6. Under Provisioning → To App, enable:

   • Create Users
   • Update User Attributes
   • Deactivate Users
   • Sync Password — leave disabled (Claresia doesn’t store passwords)

7. Under Provisioning → To App → Attribute Mappings, ensure these are mapped:

   • userName → user.email
   • givenName → user.firstName
   • familyName → user.lastName
   • email → user.email (Primary)

8. Under Push Groups, click Push Groups → Find groups by name, search for claresia-, push all matches.

9. Back in Claresia Onboarding Portal, click Sync now. You should see a count of users + groups imported within ~30 seconds.

Part 3 — Group → role mapping

In the portal, under RBAC → Group mappings, map your Okta groups to Claresia roles:

Okta group	Claresia role
claresia-admins	tenant_admin
claresia-auditors	auditor
claresia-users	member
claresia-eng-pilot	member (with archetype-eng grant)

De-provisioning behavior

When a user is removed from Okta (or all claresia-* groups), Okta sends a SCIM PATCH /Users/{id} with active: false. Claresia:

• Revokes their JWT immediately (subsequent API calls return 401)
• Removes them from the per-archetype skill entitlement
• Triggers a publish refresh to the LLM platform — within 60s the user cannot invoke any Claresia skill

The governance_event Hub record user_deactivated is written with the actor set to okta:scim.

Common gotchas

Symptom	Cause	Fix
Test login fails invalid_signature	Wrong X.509 cert (Okta has rotated)	Re-fetch from Okta → Sign On tab
SCIM sync returns 0 users	Users not assigned to the Claresia Okta app	In Okta: Assignments → Assign → People or Groups
Groups don’t appear in Claresia	Group filter regex mismatch	In SAML attribute statement: ensure Filter: Starts with claresia-
User removed in Okta but still has Claresia access	SCIM hasn’t fired yet	Wait 60s, then re-check; or trigger manual sync from portal

Reference

• Okta — SCIM 2.0 SDK
• WorkOS — Okta integration guide