openwork/packages/docs/cloud/scim-okta.mdx

---
title: "Okta SCIM provisioning"
description: "Provision OpenWork members and teams from Okta"
---

Use Okta Lifecycle Management to create, update, deactivate, and reactivate
OpenWork members. Okta groups can also become SCIM-managed OpenWork teams.

## Before you start

You need:

- A working and domain-verified [Okta SAML SSO](/cloud/sso-okta) connection.
- An OpenWork owner, or a member who can manage security configuration.
- An Okta administrator who can configure provisioning for the SAML app.
- An Okta plan that supports the provisioning and group-push features you
  intend to use.

Keep OpenWork SSO enforcement off until both SAML and a narrowly scoped SCIM
test pass. Make sure at least one OpenWork owner can sign in through Okta.

## 1. Create the OpenWork SCIM connector

In OpenWork, select the organization, then open **Settings → SCIM**. Confirm
the page reports that SAML/SSO is active, then:

1. Select **Create connector**.
2. Copy the **SCIM base URL**.
3. Copy the bearer token immediately. OpenWork displays the full token only
   after creating or rotating the connector.
4. Leave **Create teams from SCIM groups** off until user provisioning works.

Treat the bearer token like a password. Do not put it in tickets, screenshots,
logs, or documentation. Rotating it invalidates the previous token, so update
Okta during the same maintenance window.

<Note>
Use the base URL OpenWork displays. In a split-host Helm deployment it may use
the web auth origin even when a separate Den API origin also exists. Do not
rewrite the hostname.
</Note>

## 2. Enable SCIM on the Okta application

Use the same Okta application as SAML SSO:

1. Open **Applications → Applications → OpenWork**.
2. Open **General** and edit **App Settings**.
3. Enable **SCIM** under **Provisioning**, then save.
4. Open the new **Provisioning** tab.
5. Select **Configure API Integration**.
6. Enable **API Integration**.

Enter:

| Okta field | Value |
| --- | --- |
| SCIM connector base URL | OpenWork **SCIM base URL** |
| Unique identifier field for users | `userName` |
| Supported provisioning actions | Push new users and push profile updates. Add push groups after user provisioning works |
| Authentication mode | HTTP Header |
| Authorization | OpenWork SCIM bearer token |

Select **Test API Credentials** or **Test Connector Configuration**, depending
on your Okta interface. Save only after Okta reports **Connector configured
successfully**. For the initial user-only setup, Okta should detect **Create
Users** and **Update User Attributes**. It is expected for import and group
features to remain undetected when you have not selected them.

## 3. Configure provisioning to OpenWork

Open **Provisioning → To App**, then enable:

- **Create Users**
- **Update User Attributes**
- **Deactivate Users**

Do not enable password synchronization. SCIM creates federated membership; it
does not create an OpenWork password credential.

Review the attribute mappings. At minimum, keep these identity values aligned:

| Okta value | SCIM attribute |
| --- | --- |
| Stable work email or Okta username | `userName` |
| Primary work email | `emails[type eq "work"].value` |
| First name | `name.givenName` |
| Last name | `name.familyName` |
| Display name | `displayName` |

The SAML NameID and SCIM `userName` must identify the same person. A mismatch
can create a duplicate OpenWork member instead of linking SSO and SCIM.

## 4. Provision one test user

For the cleanest first test, use a user who has never been assigned or
provisioned to this Okta application:

1. Open the Okta application's **Assignments** tab.
2. Assign one test user and confirm their application username is the same
   email used for SAML NameID and SCIM `userName`.
3. Wait for Okta's automatic provisioning job to finish. Do not repeatedly
   edit the assignment or trigger provisioning while the job is running.
4. Open Okta **Reports → System Log** and confirm a single **Push new user to
   external application** event succeeds.
5. In OpenWork, open **Members** and verify the same member appears without a
   second password-backed account.

If the user was already assigned for the earlier SAML test, Okta may show a
**Provision User** action after you enable provisioning. Select it once, then
wait and inspect the System Log before taking another action. A second request
can race the first successful create and return `409 User already exists`.

Do not broaden assignments until the test user's create, update, deactivate,
and reactivate lifecycle works.

## 5. Verify the user lifecycle

For the assigned test user, verify:

1. Changing the profile name in Okta updates the OpenWork member.
2. Unassigning or deactivating the user removes active organization access.
3. The user cannot regain access through password sign-up while SCIM marks the
   identity inactive.
4. Reactivating and reassigning the user restores the same OpenWork identity.
5. An unrelated OpenWork member remains unchanged throughout the test.

OpenWork retains a disconnected member record for organization history. The
global user is deleted only after their final active organization membership
is removed.

## 6. Push Okta groups as OpenWork teams

After user provisioning works:

1. In OpenWork **Settings → SCIM**, enable
   **Create teams from SCIM groups**.
2. In Okta, open the application's **Push Groups** tab.
3. Select **Push Groups** and choose a small test group by name or rule.
4. Confirm Okta creates the group and pushes its current membership.
5. In OpenWork, open **Members → Teams** and verify a team labeled
   **Managed by SCIM** appears with the expected members.
6. Add and remove one member in Okta and verify the OpenWork team follows.

Manage pushed groups in Okta, not in OpenWork. Manually created OpenWork teams
remain independent.

## 7. Expand scope and enforce SSO

After the lifecycle and group tests pass:

1. Assign the intended Okta users and groups to the application.
2. Review Okta provisioning events for failures.
3. Review OpenWork's SCIM health and unresolved-failure count.
4. Confirm at least one owner has working Okta SAML access.
5. Only then consider enabling **Require SSO for this organization**.

## When to run reconciliation

Use **Settings → SCIM → Run reconciliation** to check OpenWork's local
SCIM-managed identities for inconsistent organization membership or missing
provider-account state. OpenWork records unresolved drift for retry or manual
review.

Reconciliation does not import users from Okta, force Okta to provision an
assigned user, or clear an Okta application-assignment error. Use the Okta
Assignments page and System Log for outbound provisioning. When OpenWork has no
local drift to process, reconciliation may complete without a visible member
change.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| **Create connector** is disabled | OpenWork does not see an enabled SSO provider | Complete and test Okta SAML first; if SAML returns `invalid_saml_configuration`, upgrade and save the connection again |
| **Test API Credentials** fails | Incorrect base URL, stale token, whitespace, or a rewritten hostname | Copy both values again from OpenWork and use the advertised base URL unchanged |
| Okta reports `409 User already exists` | The user existed before SCIM, or more than one create job ran for the same assignment | Inspect the System Log first. If a successful create immediately precedes the conflict and the exact member exists in OpenWork, stop triggering **Provision User**. Use a never-before-provisioned user for the clean lifecycle test |
| Okta creates a duplicate member | SAML NameID and SCIM `userName` differ | Map both to the same stable work email |
| Assignment succeeds but no member appears | To App provisioning is disabled or the user is outside assignment scope | Enable **Create Users** and confirm the person is assigned to the application |
| **Run reconciliation** does not provision an assigned user | Reconciliation only checks OpenWork's local SCIM identity state | Trigger and inspect outbound provisioning in Okta instead |
| Deactivation does not remove access | **Deactivate Users** is disabled or Okta has not sent the event | Enable it and inspect the Okta System Log and OpenWork SCIM health |
| A pushed group does not create a team | OpenWork team synchronization is off | Enable **Create teams from SCIM groups**, then retry the Okta group push |
| A group is pushed without members | Its members are not assigned or provisioned to the application | Assign and provision the users before validating group membership |

For member and team behavior after provisioning, see
[Members and RBAC](/cloud/members-and-rbac).