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

1. Sign in to the Okta Admin Console.
2. Navigate to Applications → Applications.
3. Click Create App Integration.
4. Select SAML 2.0 and click Next.
5. Set App name to Arbitex (or your preferred label).
6. 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

Note

The ACS URL and Entity ID above are for Arbitex Cloud. If you are using a self-hosted Arbitex deployment, replace api.arbitex.ai with your deployment’s domain.

---

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.

Note

Group membership in Arbitex is populated via SCIM, not SAML assertion attributes. You do not need to add a groups attribute statement — it is not consumed by the SAML flow.

Click Next.

---

Step 4: Complete app creation

On the Feedback tab:

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

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

---

Step 5: Retrieve the Okta SAML metadata

1. On the Sign On tab, click View SAML setup instructions or find the Metadata URL link in the Sign On settings panel.
2. Copy the Identity Provider metadata URL — it looks like:

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

3. 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

1. Sign in to the Arbitex admin portal.
2. Navigate to Admin → SSO → SAML IdPs.
3. Click Add Identity Provider.
4. 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

5. Click Save.

---

Step 7: Test the SAML connection

1. Navigate to Admin → SSO → SSO Test.
2. Select the Okta IdP from the dropdown.
3. 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.

1. Navigate to Applications → Arbitex → Assignments.
2. Click Assign and choose Assign to People or Assign to Groups.
3. 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

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

A Provisioning tab now appears in the app.

---

Step 10: Generate the SCIM bearer token in Arbitex

1. In the Arbitex admin portal, navigate to Admin → SSO → SCIM Sync.
2. Click Rotate Token for your organization.
3. Acknowledge the warning — the existing token (if any) will be immediately invalidated.
4. Click Confirm Rotate.
5. 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

1. In the Okta app, click the Provisioning tab.
2. Click Edit in the SCIM Connection section.
3. 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

4. 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.
5. 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.

1. On the Push Groups tab, click Push Groups.
2. Choose Find groups by name or Find groups by rule.
3. Select the Okta groups you want to sync to Arbitex.
4. 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.

Caution

Group names are case-sensitive in Arbitex policy rules. If your Okta group is named Finance_Team, your policy user_groups condition must use "Finance_Team" exactly. Establish a naming convention before configuring policy rules.

---

Step 15: Run an initial provisioning test

Before enabling full provisioning, test with a single user:

1. On the Assignments tab, assign one test user to the app.
2. On the Provisioning tab, find the user and click Provision User (or wait for the next scheduled sync).
3. Check the Okta System Log (Reports → System Log) for provisioning events. A successful event shows user.provision.profile_push.success.
4. In the Arbitex admin portal, navigate to Admin → Users and confirm the test user appears with the correct userName and group memberships.
5. 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: alice@example.com
              ↓ SCIM sync
Arbitex Group: "finance-restricted"
  └── Member: alice@example.com
        ↓ 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/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/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

SAML login fails: “No matching IdP found”

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.

---

See also

• SSO Configuration (admin) — managing SAML IdPs and SCIM tokens from the Arbitex admin panel
• Entra ID SCIM Setup — reference patterns for SCIM provisioning (Entra-specific but the SCIM API is identical)
• Policy Rule Reference — user_groups condition and all other condition types
• Groups and RBAC — group management, IdP-managed vs. local groups
• User and Group Management — admin panel group operations