Provision Users into Rolter from Okta, Entra ID, or Any SCIM 2.0 Identity Provider

Rolter speaks SCIM 2.0, so your identity provider can create, update, and deactivate Rolter accounts — and push its groups — without anyone touching the dashboard. You issue a provisioning token for the org, paste it into the IdP’s SCIM connector, and the IdP does the rest on its own schedule.

The direction of control matters: the identity provider drives provisioning, Rolter receives it. The dashboard never calls the SCIM endpoints. What you manage in Governance → User Provisioning is the credential the IdP authenticates with — issuing one, seeing when it last synced, and revoking it — and the address it connects to, which the screen shows so you never assemble it by hand.

What a provisioning token is#

A provisioning token is an opaque bearer credential scoped to exactly one org.

Issuing, listing, and revoking tokens all require the admin role on the org (see RBAC). A member or viewer sees an explanation instead of the token list.

Wire up an identity provider#

What provisioning does and does not grant#

A provisioned account is deliberately minimal:

• It joins the org with the viewer role, merely for existing. SCIM decides who exists; anything beyond a read comes from a group mapping you wrote (see Map groups to teams).

• It has no local password. A password attribute sent by the IdP is ignored rather than stored — provisioned accounts are SSO-shaped by construction.

• Deactivating a user through SCIM also drops their live sessions, so a leaver disabled in the IdP is logged out of Rolter rather than merely blocked from signing in again.

• A SCIM DELETE deactivates the account and removes the org’s identity mapping, but keeps the underlying user row: its memberships and audit trail have to outlive any one IdP. Re-provisioning the same person adopts the existing account instead of creating a duplicate. When that create carries active: false and the deactivation is refused (see below), nothing is linked, so the IdP’s retry gets the same 409 rather than a userName conflict.

• Deactivating or deprovisioning the deployment’s last active superadmin is refused with 409, the same as from the dashboard, so an IdP sync cannot leave nobody able to administer the deployment. Make another account superadmin first.

• Deactivating or deprovisioning an account that holds an organization’s last active admin grant is refused with a SCIM 409 too, for every organization the account administers, not only the one the token belongs to. The provisioning token cannot repair an organization afterwards the way a superadmin can, so the IdP is told and retries. Grant admin to another person first.

• Its display name comes from the IdP. SCIM displayName is copied onto the account on every create and replace, and the account cannot change it from the dashboard or PATCH /api/v1/me/profile (the API answers 409); GET /api/v1/auth/me reports display_name_managed: true. An IdP that sends no displayName leaves the stored name as it was. The account’s bio stays its own. A PUT with active: false that is refused because the account is the last active superadmin (409) applies none of its other changes, so the account keeps its userName, externalId and display name. The account stores the name with surrounding whitespace and control characters removed and cut to 80 characters, while the SCIM resource returns displayName exactly as your IdP sent it, so the IdP’s reconciliation sees its own value and does not push it again on every sync.

• A PATCH carrying displayName renames the account the same way, and if two organizations provision the same account the most recent sync from either decides the name.

Every provisioning action is written to the audit log with the token id as the actor, since the change was made by a machine and not by a person. Issuing and revoking a token are operator actions and name the operator instead: the token’s created by field and the scim_token.create entry carry the account that issued it, including a superadmin who holds no role in the org. A token issued with the admin token, or in open mode, names nobody. See who an entry names as the actor.

Supported operations#

Map groups to teams#

A group arriving from your identity provider grants nothing on its own. You decide what it is worth, by writing a mapping — the identity provider never gets to name a role.

Governance → User Provisioning carries a Group mappings panel under the token list. Type the group’s display name, pick where the role applies — the whole organization, a team, or a project — pick the role, and press Map group. The scope list covers the whole organization: every team, and every project in any of those teams grouped under the team it belongs to, so a mapping onto a project outside the team the scope switcher currently shows needs no detour through the switcher. An organization with no teams yet says so, and offers only itself. Role to grant starts on viewer, the least powerful role, and the scope starts on the whole organization. A mapping that grants admin, or grants at the whole organization, is confirmed before it is written: the dialog names the group, the role and the scope, says that everyone in that group at your identity provider gets the role straight away, and lists what raised it (the role, the scope, or both). A member or viewer mapping on one team or one project saves without asking. Once a mapping is written, the form goes back to viewer on the whole organization. The panel lists every mapping the org has with its scope and role, and removing one asks first, because it withdraws that role from everyone in the group. A mapping whose team or project cannot be named — the row was deleted, or the account reading the page cannot see it, or the list failed to load — is marked Unresolved scope rather than shown as a bare id, and hovering it gives the stored id to quote in a support request. Until a mapping exists the panel says so plainly: the groups your IdP pushes grant nothing, and every provisioned account stays a viewer.

The same thing over the API:

curl -X POST https://your-rolter-host/api/v1/orgs/$ORG_ID/scim-group-mappings \  -H "Authorization: Bearer $ADMIN_TOKEN" \  -H "Content-Type: application/json" \  -d '{"group_name": "platform", "role": "member", "team_id": "'$TEAM_ID'"}'

• group_name is the group’s display name as your IdP shows it.
• role is one of admin, member, viewer — the same three roles RBAC defines. Nothing else is mappable.
• Name a team_id or a project_id to grant at that scope; omit both to grant at the org.
• The scope must belong to the same org. A mapping cannot reach another tenant’s team, whatever the IdP sends.

This is the same model single sign-on uses for its group mappings, so you only learn it once.

You can write a mapping before the group has ever been pushed. Creating or deleting one takes effect immediately for whoever is already in that group, rather than waiting for the next sync.

What a sync does to roles#

Every group change recomputes the affected people’s provisioning-granted roles from scratch:

• Running the same sync twice changes nothing.
• Removing someone from a group revokes exactly what that group gave them, right away.
• A role you granted by hand — in the dashboard, through the API, or through an invitation — is never touched by a sync. Manual and provisioned grants coexist.
• Deleting a group, or deprovisioning a user, withdraws the roles involved in the same request.
• The one exception is an organization’s last active admin grant: a sync that would withdraw it keeps it, still answers success, and records membership.last_admin_kept in the audit log. The next sync that touches that person withdraws it once someone else holds admin on the organization. Deleting a group mapping from the dashboard or the API follows the same rule for an org admin, but a superadmin deleting the mapping withdraws even the last admin grant, exactly as a superadmin revoking it directly would.

Rotating and revoking a token#

Revocation takes effect on the very next request — the token is resolved from the database on every call, so there is no cache to wait out.

To rotate without a gap in coverage:

1. Issue a second token and copy it.
2. Update the connector in the identity provider to use the new value.
3. Run a sync and confirm the new token’s Last sync moves from never used to a date (hover it for the exact time).
4. Revoke the old token.

If you need to cut off an identity provider immediately — a compromised connector, for example — revoke the token first and deactivate the affected accounts from Governance → Users separately. Revocation alone is not a way to lock people out.