> ## Documentation Index
> Fetch the complete documentation index at: https://docs.envzero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM provisioning with Okta

> Configure the Okta SCIM connector for env zero, push Okta groups to env zero teams, and recover a group push mapping that Okta has moved into Error state.

## Prerequisites

* A SAML app integration for env zero in Okta. See [Okta integration](/guides/sso-integrations/okta-integration).
* A SCIM endpoint URL and bearer token from env zero. See [Set up SCIM](/guides/sso-integrations/scim-provisioning#set-up-scim).
* Okta administrator access to the app integration.

## Configure the SCIM connector

<Steps>
  <Step title="Enable SCIM on the app">
    In the Okta Admin Console, open the env zero app integration. On the **General** tab, under **App Settings**, click **Edit**, set **Provisioning** to **SCIM**, and save.
  </Step>

  <Step title="Enter the connector settings">
    Open the **Provisioning** tab. Under **Settings** > **Integration**, click **Edit** and set:

    * **SCIM connector base URL**: the SCIM Endpoint URL from env zero
    * **Unique identifier field for users**: `userName`
    * **Supported provisioning actions**: **Push New Users**, **Push Profile Updates**, and **Push Groups**
    * **Authentication Mode**: **HTTP Header**, with the env zero bearer token as the authorization value

    Click **Test Connector Configuration**, then save.
  </Step>

  <Step title="Enable provisioning to env zero">
    Still on the **Provisioning** tab, select **To App** and click **Edit**. Enable **Create Users**, **Update User Attributes**, and **Deactivate Users**.
  </Step>

  <Step title="Check the user attribute mappings">
    In the **To App** attribute mappings, confirm that **Username** resolves to the user's email address. env zero uses `userName` to match IdP users to organization members and rejects a create without it. Okta sends its own user identifier as `externalId`, which env zero also requires.

    Attributes env zero does not store are ignored rather than rejected, so a stock Okta mapping needs no trimming. See [User attributes](/guides/sso-integrations/scim-provisioning#user-attributes) for what is stored.
  </Step>

  <Step title="Assign users">
    Assign users or groups to the app integration. Okta pushes each assigned user to env zero, and env zero adds them to the organization and any sub-organizations mapped to it.
  </Step>
</Steps>

## Push groups to env zero teams

Group push creates an env zero team for each pushed Okta group and keeps its membership in sync. See [Group to team mapping](/guides/sso-integrations/scim-provisioning#group-to-team-mapping) for the env zero side of the behavior.

<Steps>
  <Step title="Open Push Groups">
    In the app integration, open the **Push Groups** tab and click **Push Groups**.
  </Step>

  <Step title="Select groups">
    Choose **Find groups by name** or **Find groups by rule**, select the groups to push, and save. Each pushed group appears with a push status of **Active**.
  </Step>

  <Step title="Verify in env zero">
    Each pushed group appears as a team under **Organization Settings** > **Teams**, with the group's members.
  </Step>
</Steps>

### How Okta pushes groups

* Okta sends group updates as `PUT /scim/v2/Groups/{id}` with the full group state, not `PATCH`.
* Okta does not send `externalId` on group push, so env zero matches Okta groups by display name. Two Okta groups cannot map to one env zero team, and renaming a group in Okta renames the env zero team.
* Members must already be provisioned in env zero. A push that carries an unassigned user fails on that member, so assign the user to the app integration before adding them to a pushed group.

## Recover a group push mapping in Error state

Any non-2xx response from env zero puts the Okta push mapping into **Error** state, including the expected HTTP 409 when a pushed group's name collides with an existing env zero team.

<Warning>
  While a push mapping is in **Error** state, Okta stops pushing both profile and membership changes for that group. Reactivating the mapping does not replay the renames or membership changes made while it was errored, and Okta's System Log reports the reactivation push as a success anyway. Replay the changes explicitly using the steps below.
</Warning>

<Steps>
  <Step title="Fix the underlying rejection">
    Read the error on the **Push Groups** tab. A name collision reads `Conflict. Errors reported by remote server: A group named <name> already exists`. Resolve it by renaming the Okta group, or by renaming or deleting the env zero team that holds the name.
  </Step>

  <Step title="Reactivate the mapping">
    On the **Push Groups** tab, activate the group again, either on its own row or through **Bulk Edit**. Okta reports success, but nothing that changed during the error window has been sent yet.
  </Step>

  <Step title="Replay membership changes">
    On the errored group's row, use **Push Now**. This sends the group's current membership, which brings adds and removes made during the error window into env zero.
  </Step>

  <Step title="Replay renames">
    **Push Now** does not replay a rename. If the group was renamed while the mapping was errored, rename it again in Okta, or rename it away and back, to trigger a fresh profile push.
  </Step>

  <Step title="Confirm in env zero">
    Check the team's name and membership under **Organization Settings** > **Teams**. On the Enterprise plan, the [audit log](/guides/admin-guide/audit-logs) records every SCIM write with `SCIM` as the actor, so a missing entry means the push never reached env zero.
  </Step>
</Steps>

## Troubleshooting

| Symptom in Okta                                                                   | Cause                                                                                       | Fix                                                                                                                                    |
| :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------- |
| `Conflict. Errors reported by remote server: A group named <name> already exists` | An env zero team already uses that name. env zero matches pushed groups by display name.    | Rename the Okta group, or rename or delete the env zero team, then reactivate the push mapping.                                        |
| Push status **Error**, and later changes to the group never arrive                | Okta blocks all pushes for a group whose mapping is errored.                                | Fix the rejection, reactivate, then replay changes as described above.                                                                 |
| Reactivation logs success, but env zero shows no change                           | Reactivation does not replay changes made during the error window.                          | Use **Push Now** for memberships, and re-rename the group for renames.                                                                 |
| `SCIM provisioning is not enabled for this organization` (HTTP 403)               | The env zero organization is in **JIT** mode, which rejects SCIM writes.                    | Switch the [provisioning mode](/guides/sso-integrations/scim-provisioning#provisioning-modes) to **Full SCIM** or **Hybrid (legacy)**. |
| A member fails with `Member <id> is not part of this organization` (HTTP 400)     | The user is not provisioned into the env zero organization or one of its sub-organizations. | Assign the user to the app integration, confirm the user push succeeded, then push the group again.                                    |
| Provisioning stops after a token rotation with HTTP 401                           | The grace period on the previous token expired.                                             | Rotate the token in env zero and paste the new one into **Provisioning** > **Integration**.                                            |

## Next steps

* [SCIM provisioning](/guides/sso-integrations/scim-provisioning) - Provisioning modes, token rotation, and reconcile.
* [Okta integration](/guides/sso-integrations/okta-integration) - The SAML side of the Okta setup.
* [Manage teams](/guides/admin-guide/user-role-and-team-management/teams) - Assign project roles to pushed teams.