> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SCIM with Okta
> Automatically provision users and groups from Okta into TrueFoundry using SCIM 2.0.
This guide explains how to push users and groups from Okta into TrueFoundry automatically using SCIM 2.0. With SCIM enabled, assigning a user (or one of their groups) to your Okta application creates them in TrueFoundry; removing the assignment deactivates them. Okta group push syncs group memberships as TrueFoundry teams.
## Prerequisites
* Single sign-on between TrueFoundry and Okta is already configured. Follow [SAML with Okta](/docs/platform/sso/okta/saml) first — SCIM is configured inside the **same Okta application**.
* You have **Admin** access in both TrueFoundry and Okta (Super Admin or App Admin in Okta).
* You're on TrueFoundry **v0.143** or higher. (On earlier versions, SCIM is configured directly inside the SSO form.)
Okta does not send a SCIM `DELETE` operation when a user is unassigned or deactivated. Instead it sends a PATCH with `active=false`. TrueFoundry handles this as a soft deactivation — see the [Troubleshooting](#troubleshooting) section.
## Configuration overview
Enable SCIM provisioning and grab the SCIM URL and bearer token.
Choose **SCIM** for provisioning under the **General** tab of your Okta app.
Paste TrueFoundry's SCIM URL and token into Okta, set the unique identifier field, and pick the provisioning actions.
Turn on **Create / Update / Deactivate Users** in Okta, then assign people or push groups.
## Step 1 — Generate the SCIM credentials in TrueFoundry
In TrueFoundry, go to **Settings → Security & Access → Provisioning** and turn on the **SCIM** toggle.
On the **Provisioning** page, click **View Config** on the **SCIM** row.
In the **SCIM configuration** dialog, copy both values using the copy icons next to each field:
* **SCIM URL** — this is the value Okta calls the **SCIM connector base URL**.
* **Token** — this is the bearer token Okta calls the **SCIM 2.0 authentication token**.
Store the token somewhere safe and treat it like a password. If you lose it, open **View Config** again to generate a new token — which invalidates the previous one.
## Step 2 — Enable SCIM on your Okta app
SCIM lives inside the **same** Okta application you set up for SSO.
Sign in to the Okta admin console and go to **Applications → Applications**. Click the TrueFoundry app you created in the SSO guide.
On the **General** tab, click **Edit** on the **App Settings** card.
Under **App Settings**, choose **SCIM** for provisioning and click **Save**. A new **Provisioning** tab appears on the application.
## Step 3 — Configure the SCIM integration
Click the **Provisioning** tab. By default Okta lands on the **Integration** view. Click **Edit** on the top right of the card.
Enter the following values:
| Okta field | Value |
| ------------------------------------- | ----------------------------------------- |
| **SCIM connector base URL** | The **SCIM URL** from TrueFoundry |
| **Unique identifier field for users** | `email` |
| **Authentication Mode** | **HTTP Header** |
| **HTTP Header → Authorization** | `Bearer` + the **Token** from TrueFoundry |
The **Unique identifier field for users** must be `email` exactly. TrueFoundry matches incoming SCIM users to TrueFoundry accounts by email address.
Set the **Supported provisioning actions** checkboxes as follows:
| Action | Setting |
| ------------------------------------ | ------------- |
| Import New Users and Profile Updates | **Unchecked** |
| Push New Users | Checked |
| Push Profile Updates | Checked |
| Push Groups | Checked |
| Import Groups | **Unchecked** |
Leave **Import Groups** **unchecked**. The SCIM connection will fail to save otherwise.
Click **Test Connector Configuration**. Okta probes the SCIM endpoint; on success you'll see **Connector configured successfully** and a list of detected provisioning features. Click **Close**, then click **Save**.
If the test fails with a 401 response, your token is wrong or has been rotated. Generate a new SCIM token in TrueFoundry and re-paste it into the **Authorization** field.
## Step 4 — Turn on provisioning to the app
In the left sub-navigation of the **Provisioning** tab, click **To App**, then click **Edit**.
Check the following:
* **Create Users**
* **Update User Attributes**
* **Deactivate Users**
Leave **Sync Password** unchecked — TrueFoundry never receives or stores Okta passwords.
Click **Save**.
## Step 5 — Assign people and push groups
Open the **Assignments** tab. From the **Assign** dropdown choose either **Assign to People** or **Assign to Groups**, pick the users/groups you want to provision, and click **Assign** for each. Click **Done** when finished.
Prefer assigning **groups**. Group memberships become TrueFoundry teams, and managing membership at the IdP level scales better than user-by-user assignment.
Open the **Push Groups** tab. From the **Push Groups** dropdown choose **Find groups by name** (or **Find groups by rule** for prefix matches). Search for the group(s) you want to send to TrueFoundry and click **Save**.
Okta will create matching groups in TrueFoundry and continuously sync membership.
## Step 6 — Verify in TrueFoundry
Go to **Access → Users** in TrueFoundry. Assigned Okta users should appear within a few minutes with their email, first/last name, and group memberships populated. Pushed groups appear under **Access → Teams**.
If you assigned users to the application *before* enabling SCIM, Okta won't replay those events automatically. Use **Provisioning → To App → Force Sync** (or unassign and re-assign the user) to trigger an initial sync.
## How SCIM behaves with Okta
* **Sync cadence** — Okta pushes changes in near-real time when users are assigned, unassigned, or their profile changes.
* **Deactivation** — Unassigning a user (or deactivating them in Okta) sends a PATCH with `active=false`. TrueFoundry deactivates the user instead of deleting them.
* **Group naming** — Pushed Okta group display names become TrueFoundry team names. See [Provision teams via SCIM](/docs/platform/team-management#provision-teams-via-scim) for naming rules.
## Optional next steps
* **Review your SSO setup** — see [SAML with Okta](/docs/platform/sso/okta/saml) or [OIDC with Okta](/docs/platform/sso/okta/oidc) if you haven't completed the SSO side yet.
## Troubleshooting
The bearer token is incorrect or has been rotated. Generate a new SCIM token in TrueFoundry, paste it into Okta's **Authorization** field, and click **Test Connector Configuration** again.
Okta tries to verify the import-side capabilities even when you only push. Open **Provisioning → Integration → Edit** and make sure **Import Groups** is **unchecked**, then save and test again.
1. In Okta, go to **Reports → System Log** and filter for `target.displayName eq ""` — you'll see the SCIM call Okta made (or didn't make).
2. Confirm the user is **active** in Okta and is **assigned** to the application (directly or via an assigned group).
3. Use **Provisioning → To App → Force Sync** to retry. If the user was assigned *before* SCIM was enabled, Force Sync is the only way to backfill them.
This is expected. Okta does not issue SCIM `DELETE` operations. Instead, when a user is unassigned, suspended, or deactivated, Okta sends a PATCH that sets `active=false`. TrueFoundry interprets this as a deactivation — the user is disabled in TrueFoundry but their history (audit log, runs, etc.) is preserved.
Okta only dispatches a SCIM event for users who are explicitly **unassigned from the application**. Suspending or deactivating a user in Okta without unassigning them is a [known Okta limitation](https://help.okta.com/) and will not trigger a SCIM PATCH. As a workaround, remove the user from the assigned groups or unassign them directly from the application.
Confirm that you pushed the group itself on the **Push Groups** tab (not just the underlying users on **Assignments**), and that **Push Groups** is checked under **Provisioning → Integration → Supported provisioning actions**. Nested groups are not supported — only direct members of a pushed group are synced.