# Okta provisioning (/platform/enterprise/scim/okta)





Connect an Okta SCIM 2.0 integration to create, update, and deactivate Sim organization members. Configure [single sign-on](/platform/enterprise/sso) separately for authentication.

## Before you start [#before-you-start]

* Use an Enterprise organization in Sim and an organization owner or admin account.
* [Verify each provisioned email domain](/platform/enterprise/verified-domains).
* Use an Okta administrator with access to application provisioning.
* Make the Sim deployment reachable by Okta over HTTPS. Self-hosted deployments must meet the [SCIM rollout requirements](/platform/enterprise/scim#deployment-and-upgrades).

Start with a test account and a dedicated group. Provisioned members use a seat and receive workspace access through mappings or existing grants.

## Choose an integration [#choose-an-integration]

SCIM support depends on how the Okta app was created:

| Integration | SCIM setup |
| - | - |
| OIDC app created with the newer **Okta Integration Wizard** | Can support SCIM; follow the instructions for that creation experience |
| OIDC app created with **Classic experience** | Does not support adding SCIM; use a separate provisioning integration |
| Custom SAML or SWA app created with **Classic experience** | Enable SCIM under **General → App Settings → Provisioning**, then configure its SCIM fields |

See [Okta's custom-app SCIM instructions](https://help.okta.com/en-us/Content/Topics/apps/apps_app_integration_wizard_scim.htm). If the provisioning option is missing, confirm that the feature is enabled for your Okta organization.

<Callout type="warn">
  The Header Auth Test App walkthrough below is for evaluation. [Okta support limits SCIM Test Apps to development and testing](https://support.okta.com/help/s/article/What-are-SCIM-20-Test-Apps?language=en_US), although its developer guide also describes private template integrations. For production, confirm a supported integration route for your Okta organization using the corresponding official instructions. This guide does not establish a published or certified Sim OIN integration.
</Callout>

### Connect a supported custom app [#connect-a-supported-custom-app]

1. In Sim, open **Settings → Organization → Single sign-on → Provisioning** and enable **Enable directory provisioning**. Copy **Connection → Base URL**, choose a token expiry under **Tokens**, and select **Issue token**. Copy it before closing the dialog; it is shown once.
2. In the supported Okta app, enable SCIM. For a Classic SAML or SWA app, open **General → App Settings → Edit**, set **Provisioning** to **SCIM**, and save.
3. Open **Provisioning → Integration** and configure **SCIM connector base URL** with Sim's Base URL. Set **Unique identifier field for users** to `userName`.
4. Enable the supported push actions needed for your deployment: **Push New Users**, **Push Profile Updates**, and **Push Groups** for group-based access.
5. Configure **HTTP Header** authentication to send `Authorization: Bearer <your-sim-token>`. Use the chosen integration's documented credential fields; they differ from the Test App's **API Token** field below.
6. Test and save the connection. Under **Provisioning → To App**, enable user creation, attribute updates, and deactivation. Leave password synchronization disabled.

Use an application username and primary email in a domain verified by Sim. If Okta usernames differ from email addresses, review the attribute mappings before assigning members. Then complete the lifecycle and group checks below.

## Evaluate with the Header Auth Test App [#evaluate-with-the-header-auth-test-app]

These steps use Okta's [private SCIM template guide](https://developer.okta.com/docs/guides/scim-provisioning-integration-connect/main/). The screenshots show the Test App configuration.

<Steps>
  <Step>
    ### Enable provisioning in Sim [#enable-provisioning-in-sim]

    Open **Settings → Organization → Single sign-on → Provisioning** and enable **Enable directory provisioning**. Copy **Connection → Base URL**. Under **Tokens**, choose an expiry and select **Issue token**. Copy the token before closing its dialog.
  </Step>

  <Step>
    ### Add the evaluation app [#add-the-evaluation-app]

    In Okta, open **Applications and Resources → Applications → Browse App Catalog**. Search for &#x2A;*SCIM 2.0 Test App (Header Auth)**, select **Add Integration**, and name it, for example **Sim provisioning evaluation**.

    For a provisioning-only app, hide its icon from members and turn off automatic sign-in from the landing page. Under **Sign-On Options**, choose **Secure Web Authentication**, use your Sim HTTPS login URL, and set **Application username format** to **Email**. Complete setup. These template options do not configure Sim SSO.
  </Step>

  <Step>
    ### Configure API integration [#configure-api-integration]

    Open **Provisioning → Integration → Configure API Integration** and select **Enable API integration**.

    | Field | Value |
    | - | - |
    | **Base URL** | Sim's HTTPS URL ending in `/api/scim/v2` |
    | **API Token** | `Bearer <your-sim-token>` — include the prefix and a space |

    Select **Test API Credentials**, then save. The Header Auth template sends **API Token** as the complete `Authorization` header. Entering the token alone produces **A bearer token is required**.

    <Image src="/static/enterprise/okta/api-integration.png" alt="Header Auth Test App API integration showing a successful credential test, a redacted Base URL, and a masked token" width="1001" height="678" className="mx-auto h-auto w-full max-w-xl" />

    A successful credential test confirms connectivity and authentication. Assign a test account to verify provisioning itself.
  </Step>

  <Step>
    ### Enable provisioning actions [#enable-provisioning-actions]

    Under **Provisioning → To App → Edit**, enable **Create Users**, **Update User Attributes**, and **Deactivate Users**, then save. Leave **Sync Password** disabled; Sim does not synchronize passwords through SCIM.

    Use a verified-domain email for both the application username and primary email. Review mappings if Okta usernames differ from email addresses.

    <Image src="/static/enterprise/okta/provisioning-actions.png" alt="Header Auth Test App actions with user creation, attribute updates, and deactivation enabled, and password synchronization disabled" width="1001" height="832" className="mx-auto h-auto w-full max-w-xl" />
  </Step>
</Steps>

## Verify the user lifecycle [#verify-the-user-lifecycle]

1. Assign a test account from **Assignments**. Confirm it appears in Sim's organization and **Provisioning → Activity** shows successful requests.
2. Update **Display name** in Okta and confirm the change in Sim. Sim uses mapped `displayName`, falling back to the structured name when omitted.
3. If the account belongs to a pushed group, remove it from that group and confirm the downstream removal before unassigning the app.
4. Unassign the account and confirm Sim marks it deactivated.
5. Reassign it and confirm the existing member becomes active again.

Okta sends deactivation, not SCIM user `DELETE`. Sim suspends access while retaining organization membership, ownership, and the seat. Removing organization membership is a separate offboarding action. See [Sim deactivation behavior](/platform/enterprise/scim#what-it-does) and [Okta's offboarding order](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/app-assignments-group-push.htm).

## Push groups and verify access [#push-groups-and-verify-access]

Use separate groups for app assignment and Group Push; Okta does not support using the same group for both. Assign accounts to the app first.

1. Under **Push Groups → Find groups by name**, select the group.
2. Leave **Push group memberships immediately** enabled. For a new downstream group, save with **Create Group** selected.
3. In Sim, open **Single sign-on → Provisioning → Group mappings** and map the synced group to a workspace, permission group, or organization admin role. Workspace access requires a workspace mapping. Name matching can map existing permission groups automatically.
4. Confirm a test member gains workspace access. Remove it from the pushed group while keeping its app assignment, and confirm the directory grant is withdrawn. Add it back and verify access returns without another account being created.

<Image src="/static/enterprise/okta/group-push.png" alt="Header Auth Test App Group Push selecting an engineering group and Create Group for the downstream group" width="1001" height="927" className="mx-auto h-auto w-full max-w-xl" />

With **Lock managed membership** enabled, Sim blocks manual invitations and grants for provisioned members. Read [How access is withdrawn](/platform/enterprise/scim#how-access-is-withdrawn) before mapping groups that overlap existing manual access.

## Rotate a token [#rotate-a-token]

Issue a replacement token in Sim while the current one remains active. Update the chosen integration's credential field. For the Header Auth template, replace **Provisioning → Integration → API Token** with `Bearer <new-token>`.

Test credentials, save, and confirm a successful provisioning request before revoking the old token. Sim allows two active tokens for overlapping rotation.

## Troubleshooting [#troubleshooting]

| Symptom | Check |
| - | - |
| Credential test fails | For Header Auth, include `Bearer `. Check the complete HTTPS URL, token expiry, provisioning switch, and network reachability. |
| User creation fails | Verify the email domain, available seats, and whether the account belongs to another Sim organization. |
| Member has no workspace access | Push the group and add a workspace mapping. App assignment creates organization membership. |
| Name or membership updates do not arrive | Check app assignment, provisioning actions, attribute mappings, and Group Push status. |
| A pushed group is missing members | Confirm those accounts are active and successfully assigned to the app. After activation, repush the group; see [Okta Group Push troubleshooting](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-group-push-troubleshoot.htm). |
| A deactivated member still uses a seat | Deactivation suspends access; remove organization membership to complete that offboarding step. |

Use **View Logs** in the Okta app and **Provisioning → Activity** in Sim. Invalid or revoked tokens appear only in Okta because Sim cannot associate them with a connection.

## Related docs [#related-docs]

* [Directory provisioning](/platform/enterprise/scim)
* [Single sign-on](/platform/enterprise/sso)
* [Verified domains](/platform/enterprise/verified-domains)