> ## 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](https://docs.envzero.com/guides/sso-integrations/okta-integration.md). * A SCIM endpoint URL and bearer token from env zero. See [Set up SCIM](https://docs.envzero.com/guides/sso-integrations/scim-provisioning.md#set-up-scim). * Okta administrator access to the app integration. ## Configure the SCIM connector **1. 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. **2. 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. **3. 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**. **4. 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](https://docs.envzero.com/guides/sso-integrations/scim-provisioning.md#user-attributes) for what is stored. **5. 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. ## 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](https://docs.envzero.com/guides/sso-integrations/scim-provisioning.md#group-to-team-mapping) for the env zero side of the behavior. **1. Open Push Groups** In the app integration, open the **Push Groups** tab and click **Push Groups**. **2. 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**. **3. Verify in env zero** Each pushed group appears as a team under **Organization Settings** > **Teams**, with the group's members. ### 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. **1. 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 already exists`. Resolve it by renaming the Okta group, or by renaming or deleting the env zero team that holds the name. **2. 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. **3. 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. **4. 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. **5. Confirm in env zero** Check the team's name and membership under **Organization Settings** > **Teams**. The [audit log](https://docs.envzero.com/guides/admin-guide/audit-logs.md) records each change SCIM makes, such as **Group member added**, with **Unknown user (SCIM)** under **Performed By**. If the team didn't change and no event appears, the push didn't reach env zero or was rejected. ## Troubleshooting | Symptom in Okta | Cause | Fix | | :- | :- | :- | | `Conflict. Errors reported by remote server: A group named 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](https://docs.envzero.com/guides/sso-integrations/scim-provisioning.md#provisioning-modes) to **Full SCIM** or **Hybrid (legacy)**. | | A member fails with `Member 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 Permissions stay in env zero, so once a group is pushed, [give the new team a project role](https://docs.envzero.com/guides/admin-guide/user-role-and-team-management/teams.md#managing-team-access-to-a-project). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.