Document SCIM user provisioning under administration/managing_users

[dangrondahl]

Rescoped. #382 adds administration/managing_users/automated_user_provisioning.md and covers most of what this issue originally asked for. What remains is the residual gap listed below, and this issue now depends on #382 merging first. See the comment thread for the original scope.

What #382 already covers

Setup via the wizard, IdP group → Kosli role mapping (kosli-<org-name>-<role>), sync timeliness, deprovisioning, what happens to people who already had SSO access, the IdP being authoritative for a provisioned user's roles, and a <Note> on the "Assigning roles" section of roles_in_kosli.md. Nothing below duplicates that.

Residual gap

1. The user-management toggle in the admin area

Not mentioned anywhere in #382. An admin in a SCIM-managed org can opt back in to managing the remaining non-IdP users, via a toggle on the user management page. With the opt-in off, the UI permits no invitations or role changes at all.

This is the control an admin actually reaches for when they discover they can't invite someone, so it needs to be documented on the provisioning page.

2. Invitation and removal, not just role changes

#382 states the restriction for roles only — "their roles can no longer be changed in Kosli". The actual restriction is broader: IdP-owned members can no longer be invited, re-invited, role-changed, or removed through Kosli.

The only place #382 touches invitation is in Benefits: "you no longer need to explicitly invite people one-by-one". That reads as convenience, when the reality for IdP-owned members is a removed capability. A reader who takes the Benefits framing at face value will be surprised by the UI.

3. Service accounts are out of scope of SCIM

Not mentioned in #382. Service accounts are unaffected and stay editable in Kosli throughout.

Worth stating explicitly because roles_in_kosli.md opens by establishing the opposite default: "Roles apply to service accounts the same way they apply to users. Wherever this page mentions a 'user', read it as 'user or service account' unless explicitly stated otherwise." Under that instruction, a reader carries the SCIM restrictions onto service accounts unless told not to.

4. Three assertions in roles_in_kosli.md are still unqualified

#382 adds its <Note> to the "Assigning roles" procedure only. These remain, and are wrong for a SCIM-managed org — quoted rather than line-numbered, since line numbers drift:

• The opening <Note>: "The only role-related capability that is user-only is being invited to or removed from the organization." In a SCIM org, invitation and removal of IdP-owned members is not a Kosli capability at all.
• The permissions matrix: the Invite and remove users and Change user roles rows, both ✅ for Admin.
• The Admin accordion: "User Management: Invite, remove, and change roles of organization members (Admin only)".

The permissions matrix is the most-read part of that page and the most likely to be trusted verbatim.

Source text

Reproduced from two changelog entries (dated August 31, 2026, tagged Platform) that were written and then dropped, because at the time there was no page to link them to. They are the only written description of this behavior. Treat as a starting point, not as verified reference copy.

SCIM orgs: user management moves to your IdP — in an organization whose user lifecycle is managed by SCIM, members owned by the IdP can no longer be invited, re-invited, role-changed, or removed through Kosli. Such edits used to appear to succeed, only to be silently overwritten by the next sync, leaving Audit Log entries attributing the change to the wrong actor. Service accounts are unaffected and stay editable throughout.

Opt back in to managing non-SCIM users — an admin in a SCIM-managed organization can manage the remaining (non-IdP) users via a toggle on the user management page. With the opt-in off, the UI permits no invitations or role changes.

Open questions

Product input needed. #382 answered the rest of the original list — SCIM is enabled per-org on request, and people with existing SSO access keep it and become SCIM-managed once provisioned.

• Is the user-management toggle visible to admins in every org, or only in SCIM-managed ones?
• With the opt-in off, are invitations blocked for non-IdP users too, or only for IdP-owned ones?
• Are service accounts genuinely untouched by SCIM, including role changes?
• Does deprovisioning in the IdP archive or delete the Kosli member? docs: add blank authentication and user provisioning pages #382 says "automatically revoked", which is ambiguous.

Definition of done

• docs: add blank authentication and user provisioning pages #382 merged
• The admin-area toggle, the invite/remove restriction, and the service-account exemption are documented on automated_user_provisioning.md
• The three assertions above in roles_in_kosli.md are qualified for SCIM orgs
• mint broken-links clean
• The two changelog entries quoted above are added to changelog/index.mdx, linking /administration/managing_users/automated_user_provisioning

[dangrondahl]

Rewrote the description to be self-contained and anchored to main rather than to the #376 branch. Three things were at risk of dying with that PR:

1. A file-and-line reference into changelog/index.mdx — the number was valid only on the chore: update changelog CLI v2.39.0/v2.39.1 and Platform updates #376 branch, and changelog line numbers shift every time an entry is added at the top. Removed; no line number now.
2. The dropped changelog entries existed only in the chore: update changelog CLI v2.39.0/v2.39.1 and Platform updates #376 branch. Once that PR merges, the text is recoverable only from git history, so anyone picking this issue up would have had nothing to work from. Both entries are now quoted verbatim in a "Behavior to document" section, and the definition of done refers to those quotes instead of to the PR.
3. roles_in_kosli.md line numbers (L8, L24-25, L71) — accurate on main today, but they drift with any future edit to that page. Replaced with the quoted sentences and row names, which stay greppable.

Also corrected two errors of my own: an inaccurate description of where the string already occurs in the repo, and a link to mapping users to roles that was missing its managing_users/ path segment.

[dangrondahl]

Rescoped against #382, which I had missed when filing this.

#382 adds administration/managing_users/automated_user_provisioning.md and covers most of the original scope: setup via the wizard, IdP group to Kosli role mapping, sync timeliness, deprovisioning, what happens to people who already had SSO access, and the IdP being authoritative for a provisioned user's roles. It also answered two of my open questions — SCIM is enabled per-org on request, and existing SSO users keep access and become SCIM-managed once provisioned. I have removed all of that from this issue rather than have two issues claiming the same page.

Four things are genuinely not covered by #382, and this issue is now just those, blocked on it merging:

1. The admin-area user-management toggle — absent entirely. It is the control an admin reaches for the moment they find they cannot invite someone.
2. Invitation and removal — docs: add blank authentication and user provisioning pages #382 states the restriction for roles only ("their roles can no longer be changed in Kosli"). The real restriction also covers invite, re-invite, and remove. Its only mention of invitation is in Benefits, "you no longer need to explicitly invite people one-by-one", which frames a removed capability as a convenience.
3. Service accounts being out of scope of SCIM — absent, and it matters more than it looks: roles_in_kosli.md opens by instructing the reader to read "user" as "user or service account" unless told otherwise, so the SCIM restrictions get carried onto service accounts by default.
4. Three assertions in roles_in_kosli.md — docs: add blank authentication and user provisioning pages #382 adds its <Note> to the "Assigning roles" procedure only. The opening <Note>, the permissions-matrix rows, and the Admin accordion bullet are still unqualified and wrong for a SCIM org. The matrix is the most-read part of that page.

Two notes on #382 itself, which I have not touched:

• Its description says "Adds three placeholder pages for content to be written manually" and "Each page contains only its title". That is no longer true — all three pages have substantial written content. Worth correcting the description before merge so reviewers know to actually read them.
• It is BLOCKED / REVIEW_REQUIRED; all checks pass but it needs a human review.