Okta SAML 2.0 + SCIM Setup Guide

This guide walks through the complete integration of Okta with Arbitex. When finished, your users will authenticate to Arbitex via Okta SSO, user and group accounts will be automatically provisioned and deprovisioned via SCIM, and Okta group membership will drive Arbitex governance policy conditions.

sequenceDiagram
    participant User
    participant Okta
    participant Arbitex as Arbitex Gateway

    User->>Okta: Authenticate (SAML 2.0)
    Okta-->>User: SAML assertion
    User->>Arbitex: POST /saml/acs (assertion)
    Arbitex-->>User: Session established

    Note over Okta,Arbitex: Background: SCIM incremental sync (every ~4 min)
    Okta->>Arbitex: PATCH /scim/v2/Users (group changes)
    Arbitex-->>Okta: 200 OK

Prerequisites

Before you begin:

Okta organization with Super Administrator or Application Administrator privileges
Arbitex Org Admin role — you need access to Admin → SSO
Your Arbitex organization’s SAML ACS URL (retrieved in Step 3)

Part 1: SAML 2.0 SSO Setup

Step 1: Create a new app integration in Okta

Sign in to the Okta Admin Console.
Navigate to Applications → Applications.
Click Create App Integration.
Select SAML 2.0 and click Next.
Set App name to Arbitex (or your preferred label).
Upload a logo if desired, then click Next.

Step 2: Configure SAML settings

On the Configure SAML tab, fill in the following:

Field	Value
Single sign-on URL	`https://api.arbitex.ai/saml/acs`
Audience URI (SP Entity ID)	`https://api.arbitex.ai/saml/metadata`
Name ID format	`EmailAddress`
Application username	`Email`
Response	`Signed`
Assertion Signature	`Signed`
Signature Algorithm	`RSA-SHA256`
Digest Algorithm	`SHA256`
Authentication context class	`PasswordProtectedTransport`

Step 3: Configure attribute statements

Still on the Configure SAML tab, scroll to Attribute Statements and add:

Name	Name format	Value
`email`	Basic	`user.email`
`firstName`	Basic	`user.firstName`
`lastName`	Basic	`user.lastName`

These attributes are mapped to the Arbitex user profile on first login. The email attribute is required — it is used as the primary identifier.

Click Next.

Step 4: Complete app creation

On the Feedback tab:

Select I’m an Okta customer adding an internal app.
Click Finish.

The app is created. You are now on the app’s Sign On tab.

Step 5: Retrieve the Okta SAML metadata

On the Sign On tab, click View SAML setup instructions or find the Metadata URL link in the Sign On settings panel.

Copy the Identity Provider metadata URL — it looks like:

https://your-org.okta.com/app/arbitex/exk.../sso/saml/metadata

Alternatively, download the metadata XML file.

You will need either the metadata URL or the individual fields (Entity ID, SSO URL, X.509 certificate) in the next step.

Step 6: Register the Okta IdP in Arbitex

Sign in to the Arbitex admin portal.
Navigate to Admin → SSO → SAML IdPs.
Click Add Identity Provider.
Fill in:

Field	Where to find it in Okta
Name	e.g., `Okta`
Entity ID	`entityID` attribute in Okta metadata XML, e.g. `http://www.okta.com/exk...`
SSO URL	`Location` in the `<SingleSignOnService>` element in Okta metadata
X.509 Certificate	`<X509Certificate>` value in Okta metadata (base64, no headers)
Active	Enabled

Click Save.

Step 7: Test the SAML connection

Navigate to Admin → SSO → SSO Test.
Select the Okta IdP from the dropdown.
Click Run Test.

A successful test shows green checkmarks for: metadata reachable, certificate valid, SSO URL reachable, and entity ID matches.

If the test fails, the most common causes are:

Certificate mismatch: Verify you copied the full X.509 certificate value from Okta metadata without truncation.
Entity ID mismatch: Confirm the Entity ID value in Arbitex exactly matches entityID in the Okta metadata XML.
Clock skew: If tests pass intermittently, check that both servers are synced to NTP.

Step 8: Assign users to the Okta app

SAML authentication only works for users assigned to the Okta app.

Navigate to Applications → Arbitex → Assignments.
Click Assign and choose Assign to People or Assign to Groups.
Assign the users or groups who should have access.

Users not assigned to the app will not be able to authenticate to Arbitex via Okta SSO.

Part 2: SCIM Provisioning

SCIM automatically creates, updates, and deactivates Arbitex users and groups as they change in Okta. Group membership synced via SCIM is used by the Arbitex Policy Engine in user_groups conditions.

Step 9: Enable SCIM provisioning in Okta

On the Arbitex app in Okta Admin Console, go to the General tab.
Click Edit.
Under Provisioning, select SCIM.
Click Save.

A Provisioning tab now appears in the app.

Step 10: Generate the SCIM bearer token in Arbitex

In the Arbitex admin portal, navigate to Admin → SSO → SCIM Sync.
Click Rotate Token for your organization.
Acknowledge the warning — the existing token (if any) will be immediately invalidated.
Click Confirm Rotate.
Copy the displayed token. It is shown only once. Store it in a secrets manager (e.g., 1Password, Vault) before closing the dialog.

Step 11: Configure SCIM in Okta

In the Okta app, click the Provisioning tab.
Click Edit in the SCIM Connection section.
Fill in:

Field	Value
SCIM connector base URL	`https://api.arbitex.ai/scim/v2`
Unique identifier field for users	`userName`
Supported provisioning actions	Check: Import New Users and Profile Updates, Push New Users, Push Profile Updates, Push Groups, Deactivate Users
Authentication Mode	HTTP Header
Authorization	Paste the bearer token from Step 10

Click Test Connector Configuration. Okta will make a test request to the Arbitex SCIM endpoint. A green success message confirms the token and URL are correct.
Click Save.

Step 12: Configure provisioning actions

On the Provisioning → To App tab, enable:

Action	Setting
Create Users	Enabled
Update User Attributes	Enabled
Deactivate Users	Enabled

Leave Sync Password disabled — Arbitex uses SAML for authentication, not password sync.

Step 13: Configure user attribute mappings

On the Provisioning → To App → Attribute Mappings tab, verify the following mappings are present:

Okta attribute	SCIM attribute	Required
`user.login`	`userName`	Yes
`user.email`	`emails[primary eq true].value`	Yes
`user.firstName`	`name.givenName`	No
`user.lastName`	`name.familyName`	No
`user.displayName`	`displayName`	No

The userName mapping is the primary key — Arbitex uses it to match incoming SCIM updates to existing user accounts.

Step 14: Enable group push

Group push syncs Okta group objects and their membership to Arbitex. Arbitex group names are what the Policy Engine uses in user_groups conditions.

On the Push Groups tab, click Push Groups.
Choose Find groups by name or Find groups by rule.
Select the Okta groups you want to sync to Arbitex.
Click Save.

Each pushed group creates (or updates) a group in Arbitex. The Okta group’s display name becomes the group name in Arbitex. Group names are used verbatim in policy conditions.

Step 15: Run an initial provisioning test

Before enabling full provisioning, test with a single user:

On the Assignments tab, assign one test user to the app.
On the Provisioning tab, find the user and click Provision User (or wait for the next scheduled sync).
Check the Okta System Log (Reports → System Log) for provisioning events. A successful event shows user.provision.profile_push.success.
In the Arbitex admin portal, navigate to Admin → Users and confirm the test user appears with the correct userName and group memberships.
Deactivate the test user in Okta and confirm their active status becomes false in Arbitex within one sync cycle.

Part 3: Group-Based Policy Conditions

Okta groups synced via SCIM map directly to Arbitex policy rule conditions. This is how you enforce different AI governance rules for different parts of your organization.

How group membership flows to policy enforcement

Okta Directory
  └── Group: "finance-restricted"
        └── Member: [email protected]
              ↓ SCIM sync
Arbitex Group: "finance-restricted"
  └── Member: [email protected]
        ↓ Policy evaluation
Policy Rule: user_groups contains "finance-restricted"
  └── Action: BLOCK (entity_type: credit_card)

When Alice sends a message, the Policy Engine checks her group memberships (populated by SCIM) against the user_groups condition in each rule. If she is in finance-restricted, the credit card BLOCK rule applies to her.

Configuring a group-based policy rule

In the Arbitex admin portal, navigate to Admin → Policy Engine → Policy Rules and create or edit a rule:

{
  "name": "finance-credit-card-block",
  "conditions": {
    "user_groups": ["finance-restricted"],
    "entity_types": ["credit_card", "bank_account"],
    "entity_confidence_min": 0.80
  },
  "action": {
    "type": "BLOCK"
  }
}

Or via the Policy Engine API:

POST /api/v1/admin/policy/rules
Authorization: Bearer arb_live_your-api-key-here
Content-Type: application/json

{
  "name": "finance-credit-card-block",
  "conditions": {
    "user_groups": ["finance-restricted"],
    "entity_types": ["credit_card", "bank_account"],
    "entity_confidence_min": 0.80
  },
  "action": { "type": "BLOCK" }
}

Common group policy patterns

Okta group	Arbitex policy intent	Suggested action
`ai-unrestricted`	Power users with full access	`ALLOW` (high priority, first in chain)
`finance-team`	Finance users — block financial PII	`BLOCK` on `credit_card`, `bank_account`
`healthcare-users`	Clinical staff — block PHI	`BLOCK` on HIPAA entity types
`contractors`	External contractors — restrict models	`ROUTE_TO` only approved models
`ai-blocked`	Users barred from AI access	`BLOCK` all (no conditions)

Verifying group sync

After SCIM runs, you can confirm group membership in Arbitex:

GET /api/v1/admin/groups
Authorization: Bearer arb_live_your-api-key-here

Look for groups with "idp_managed": true — these were created by SCIM and should not be modified manually. Manual membership changes are overwritten on the next sync cycle.

Troubleshooting

The Audience URI in your Okta SAML configuration does not match the Entity ID registered in Arbitex. Verify both are set to https://api.arbitex.ai/saml/metadata.

SAML assertion rejected: timestamp error

Clock skew between Okta and Arbitex servers. SAML assertions include NotBefore and NotOnOrAfter timestamps. Ensure both systems sync to NTP. Okta allows a configurable clock skew tolerance — check your Okta SAML app settings.

SCIM connection test fails

Confirm the bearer token was copied completely — tokens are long and truncation is the most common cause.
Confirm the SCIM base URL is https://api.arbitex.ai/scim/v2 with no trailing slash.
Confirm SCIM provisioning is enabled in Admin → SSO → SCIM Sync.

Users not appearing in Arbitex after SCIM sync

The user must be assigned to the Okta app (not just in a pushed group). Assignments and group push are separate in Okta.
Check the Okta System Log for provisioning errors on the specific user.
Run an on-demand sync from the Provisioning tab: find the user, click the kebab menu, select Sync Now.

Group memberships not reflecting in policy enforcement

Confirm the group was added to Push Groups (group push is separate from user provisioning).
Check that the Okta group displayName matches the user_groups string in the policy rule exactly (case-sensitive).
Navigate to Admin → SSO → SCIM Sync in Arbitex and verify the group shows IdP-managed status.
Allow one sync cycle (Okta runs SCIM incrementally approximately every 4 minutes).

Users deprovisioned unexpectedly

A user loses access when their Okta account is deactivated or when they are unassigned from the Arbitex app. Check the Okta System Log for the provisioning event that triggered the deactivation and confirm it was intentional.