> For the complete documentation index, see [llms.txt](https://docs.onepub.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onepub.dev/guides/scim-provisioning.md).

# SCIM provisioning

Use your identity provider to manage OnePub members, roles and teams through SCIM.

**Release availability:** The organisation-owner and team-leader protections described below belong to the upcoming release being validated for beta. They are not yet confirmed available in production. Transfer ownership and leadership before offboarding; do not rely on these new rejection safeguards until your OnePub version includes them.

SCIM lets your identity provider add members to OnePub, update their details and remove their access when they leave. Provider groups can assign OnePub's built-in roles, team memberships and team leadership.

SCIM can manage existing members without SSO. To let new provisioned members join, configure [SSO](https://docs.onepub.dev/guides/okta-single-sign-on.md) so they can complete their first sign-in.

## Before you start

You need an Enterprise plan and administrator access to OnePub and your identity provider. Open **My OnePub > Account > SCIM** to see the available providers. If yours is not listed, contact support to arrange the connection.

For a privately configured Okta application, complete the [private application prerequisites](https://docs.onepub.dev/guides/okta-single-sign-on/okta-private-application.md#before-adding-scim) first. They cover production registration, exact callbacks and the OAuth capabilities your Okta tenant must provide. A beta test application is not a production connection.

For SSO sign-in, your provider must send the same stable user ID in SCIM `externalId` and SAML NameID. OnePub checks this automatically. Keep a record of current roles and team assignments before handing their management to SCIM.

## 1. Connect provisioning

1. In **My OnePub > Account > SCIM**, click **Connect provisioning**.
2. In your provider, open the OnePub application's provisioning settings and select **Authenticate with OnePub**, or its equivalent.
3. In the OnePub window, sign in as an administrator, choose your organisation and approve access.
4. Return to OnePub and click **Finish connecting**.
5. In your provider, enable user creation, profile updates and deactivation as needed. Assign a few test members and send their groups. In Okta, application assignment and **Push Groups** are separate settings.
6. In OnePub, click **Refresh groups** to show the users and groups received. This does not start a provider sync.

Do not use a member's OnePub CLI token for provisioning. See [Okta's provisioning setup guide](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SCIM.htm) for the provider settings.

During setup, OnePub receives users and groups without granting new access. Deactivation of an already linked member still removes access, provided the member is not the organisation owner or a current team leader.

## 2. Map groups to roles and teams

In **Account > SCIM**, choose whether SCIM manages roles, teams, or both. SCIM-managed assignments cannot also be edited locally.

You control when to transfer this management. For an initial pilot, leave **Manage roles through SCIM** and **Manage teams through SCIM** off if you want existing members to retain locally managed assignments. Review member matching and removal decisions separately: leaving these two controls off does not approve a sync or prevent a deactivation. Enable either category only when its mappings and preview are ready.

1. Use the group mapping editor to select a provider group.
2. Choose the built-in roles, team memberships and team leadership it should grant, and save the mapping. Repeat for each group.

Select existing teams in each mapping. Before transferring team management to SCIM, create any missing teams under **My OnePub > Teams**. Matching group and team names do not link them automatically.

Provider groups can grant **Collaborator**, **Team Leader** and **Uploader**, but cannot create or delete OnePub roles. Administrator access remains managed in OnePub. A team leader also needs the **Team Leader** role. See [Roles](https://docs.onepub.dev/fundamentals/roles.md) for their normal permissions.

**Members of this group lead these teams** selects teams, not people. Every member of the mapped provider group becomes a leader of those teams; a team can have several leaders.

When SCIM manages teams, it controls their members and leaders. The **Everyone** team is protected: every organisation member belongs to it, and provider groups cannot change that relationship. CI/CD members retain their locally managed access.

## 3. Review and approve

Under **Existing members**, OnePub suggests matches by email and checks any existing SSO user ID. Matched members are hidden by default; select **Show matched members** to check them. Review unmatched members and correct any wrong selections.

Click **Preview sync**, then review the proposed links and access changes:

* **Match existing members** defaults to removing access for OnePub members not supplied by your provider. Choose **Keep** for anyone who should retain locally managed access.
* **Add members from provider** defaults to keeping those OnePub members. Your explicit choices are retained when switching modes.
* For provider users without a match, choose **Add**, **Exclude**, or **Link existing member**. Resolve identity conflicts in your provider, or exclude those users before approving. A manual link cannot bypass a conflicting SSO user ID.

Review all role, team membership and leadership removals, including people absent from the provider's list. Approval covers every page, even hidden or filtered members. Check the seat summary too.

Confirm the review and click **Approve sync**. If users, groups or permissions change before approval, preview again. Links and access changes apply only after approval; disconnecting later does not undo them.

New members are created at their first SSO sign-in after approval. They need an active provider account and approved access. They accept OnePub's terms without creating a separate personal organisation. If a new member has no usable roles, sign-in shows **pending access** rather than granting package access. An administrator must assign access locally or approve the appropriate SCIM mappings; application assignment alone does not grant OnePub roles.

## 4. Test provisioning

Use a few members to check these actions before adding everyone:

| Action in your provider   | Expected result in OnePub                                                                                                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Assign an existing member | Review and approve their identity association; retain their existing membership and packages.                                                                                                 |
| Assign a new member       | They receive the roles and teams you configured.                                                                                                                                              |
| Change a name or email    | The provisioning profile is updated; an established identity link remains attached to the same member.                                                                                        |
| Change group membership   | The corresponding roles and team access change.                                                                                                                                               |
| Deactivate a member       | Access stops, including existing sessions and CLI tokens, once organisation ownership and actual team leadership have been transferred. Protected members are rejected without losing access. |
| Reactivate a member       | Access can resume, but they must sign in again and get new CLI tokens.                                                                                                                        |

Check failed provisioning jobs before adding more members. Changes take effect only after OnePub receives them successfully.

## Names, email addresses and identity links

SCIM updates the provisioning profile, not the member's global OnePub name or ordinary sign-in email. Once linked, the stable provider ID identifies the member even if their email changes. Keep SCIM and SAML IDs unchanged and never reuse a former employee's ID. Reassigning their email does not transfer their linked account.

## Removing access

With deactivation enabled, a successful SCIM deactivation removes access to the connected OnePub organisation. The person's account is retained, and access to other organisations is unchanged. Provider actions differ: confirm that the action sends a SCIM deactivation.

### Transfer protected responsibilities first

The organisation owner and anyone currently leading a team cannot be deactivated through SCIM or placed on a local security hold. This applies during initial setup as well as after sync approval. Adding a replacement leader alone is not enough: the departing member must no longer lead any team in this organisation.

1. Transfer organisation ownership to another Administrator, if needed.
2. Transfer the member's team responsibilities, then remove their leadership assignments locally. If SCIM manages those assignments, return the affected management to OnePub or exclude the member from SCIM management and approve that change first. Save the leadership changes before offboarding.
3. Keep the member included in SCIM when retrying provider deactivation. An excluded member retains locally managed access; alternatively use the local removal/security-hold action after the transfer.
4. Retry the failed provisioning job and check that it succeeds.

Group membership changes, group deletion and sync approval are also blocked if they would silently remove existing leadership or its required Team Leader role. A rejected request leaves status, roles, credentials and sessions unchanged and records a rejected audit result. It is not a successful offboarding.

The restriction follows actual responsibility, not every role label. A member who is not the owner and does not lead a team is not blocked merely for holding Administrator or Team Leader, or receiving billing email. Tenant provisioning never closes the member's global account.

**Suspending a user in Okta does not send a deactivation to OnePub.** It prevents new Okta sign-ins but leaves existing OnePub sessions and CLI tokens working. See [Okta's SCIM reference](https://developer.okta.com/docs/api/openapi/okta-scim/guides/scim-20/).

Deleting a provisioned group removes the access supplied by that group unless it would remove protected leadership. It does not delete the OnePub team or its packages. A deletion can still succeed when another approved group preserves the same leadership assignments.

## Disconnecting SCIM

Open **Account > SCIM** and click **Disconnect provisioning**.

This stops provisioning updates and returns role and team management to OnePub. Existing assignments and the separate SSO policy remain unchanged. Deactivated members stay inactive. Reconnect by approving provisioning again in your provider, then preview and approve a new sync before transferring role or team management back to SCIM.

Disconnecting does not undo an earlier approved sync.

## Troubleshooting

| Problem                                      | Check                                                                                                                                                             |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A member has no access                       | Check that their identity association is approved, they are active, and their group mappings have been approved.                                                  |
| A role or team cannot be edited in OnePub    | Check whether SCIM manages that category.                                                                                                                         |
| Mappings cannot be activated                 | Resolve the problems shown, refresh the users and groups, and review the changes again.                                                                           |
| Deactivation has not taken effect            | Check failed provisioning jobs and whether your provider sent a SCIM deactivation.                                                                                |
| Ownership or leadership transfer is required | Transfer ownership and remove the member's actual leadership assignments locally before retrying. Another leader's presence alone does not remove the protection. |
| The connection stops working                 | Contact support to check the provisioning connection.                                                                                                             |

OnePub does not support password synchronisation, SCIM bulk operations or deleting users through SCIM. Users are deactivated instead.

For help, contact [OnePub support](https://docs.onepub.dev/faq/how-do-i-get-support.md) with the step that failed and any error reference.
