Document SCIM user provisioning under administration/managing_users

[dangrondahl]

Rescoped twice, and now unblocked. The SCIM page landed in #392 (feat: add SSO, SCIM and Magic Link documentation), which superseded #382 — #382 was closed, not merged. #392 covers most of what this issue originally asked for, and closed one of the four residual gaps outright. What remains is listed below. See the comment thread for the original scope and the two rescopings.

What #392 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 their organization membership, and a <Note> on the "Assigning roles" section of roles_in_kosli.md.

It also went beyond the original scope, so none of this needs re-auditing:

• A prerequisites section (SSO first, SCIM enabled per-org on request, wizard link, IdP admin access).
• The Okta caveat — Okta's SCIM integration only works over SAML, so an Okta OIDC connection has to be recreated. Also cross-referenced from single_sign_on.md.
• First-sync planning: a full or forced sync provisions every assigned user at once, so groups and role mappings must be right before triggering one.
• A user assigned to no Kosli group is neither provisioned nor deprovisioned, and their existing access is untouched.

Nothing below duplicates any of that.

Residual gap

1. The user-management toggle in the admin area

Not mentioned in #392, and absent from the repo entirely — grep -i "toggle\|opt.in" across administration/ returns nothing.

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 — partially covered

Status: mostly closed by #392. Its closing <Note> now reads "neither their roles nor their membership of your Kosli organizations can be changed in Kosli", and the roles_in_kosli.md "Assigning roles" <Note> says the same. Membership covers removal and re-invitation implicitly, which is a real improvement over #382's role-only wording.

Two things are still missing:

• The explicit enumeration — IdP-owned members can no longer be invited, re-invited, role-changed, or removed — and the fact that the UI now blocks these rather than accepting them and letting the next sync silently overwrite them.
• The Benefits section still frames invitation purely as a convenience: "you no longer need to explicitly invite people one-by-one". For IdP-owned members it is a removed capability. A reader who takes the Benefits framing at face value will still be surprised by the UI, so Benefits needs a pointer to the restriction.

3. Service accounts are out of scope of SCIM

Not mentioned in #392. 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

Status: fully open. #392's only edit to that file was the 4-line <Note> on the "Assigning roles" procedure. These three remain unconditional, 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.

Neither has since been published: the August 31, 2026 Platform entry now in changelog/index.mdx contains only the attestations-filter bug fix.

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; #392 answered none of these. It did answer 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? feat: add SSO, SCIM and Magic Link documentation #392 says access is "revoked automatically", which is ambiguous.

Gaps 2 and 4 need no product input and can proceed now.

Definition of done

• The SCIM page exists on main (feat: add SSO, SCIM and Magic Link documentation #392; docs: add blank authentication and user provisioning pages #382 closed unmerged)
• The admin-area toggle, the explicit invite/remove restriction, and the service-account exemption are documented on automated_user_provisioning.md, with Benefits pointing at the restriction
• 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.

[dangrondahl]

Re-checked against main now that #392 has merged, and updated the body accordingly.

Bookkeeping first: #382 was closed, not merged. #392 (feat: add SSO, SCIM and Magic Link documentation) superseded it and merged on 8 September. Every #382 reference in the body was stale, so I have swapped them for #392 and reworded the first DoD checkbox — the blocker is cleared either way.

What changed in the assessment

Gap 2 (invitation and removal) is mostly closed. #392's page ends with:

Once a user has been provisioned through SCIM, your IdP is authoritative for that user: neither their roles nor their membership of your Kosli organizations can be changed in Kosli […]

and the roles_in_kosli.md "Assigning roles" <Note> says the same. "Membership of your Kosli organizations" covers removal and re-invitation implicitly, which is a genuine improvement on #382's role-only wording. I have downgraded this gap rather than deleting it, because two things are still missing: the explicit "invited, re-invited, role-changed, or removed" enumeration plus the fact that the UI now blocks these (rather than accepting them and letting the next sync overwrite them), and a pointer from the Benefits section, which still frames invitation as pure convenience.

Gaps 1, 3 and 4 are untouched.

• 1 — the admin-area toggle: absent from the whole repo. grep -i "toggle\|opt.in" across administration/ returns nothing.
• 3 — service accounts out of SCIM scope: still absent, and still actively contradicted by the opening <Note> on roles_in_kosli.md telling the reader to read "user" as "user or service account" unless told otherwise.
• 4 — the three assertions in roles_in_kosli.md: feat: add SSO, SCIM and Magic Link documentation #392's only edit to that file was the 4-line <Note> on the "Assigning roles" procedure. The opening <Note>, the Invite and remove users / Change user roles matrix rows (both ✅ Admin), and the Admin accordion's "User Management: Invite, remove, and change roles" bullet all still read as unconditional.

The changelog item is also still open, and I have said so explicitly in the Source text section so the next person does not have to check: the August 31, 2026 Platform entry now on main contains only the attestations-filter bug fix. Neither SCIM entry has been published, and nothing in the changelog announces the SSO/SCIM/Magic Link pages at all.

Credited, so nobody re-audits it

#392 went beyond the original scope, and I have listed these in the body as covered: a prerequisites section, the Okta OIDC→SAML caveat (cross-referenced from single_sign_on.md), the first-sync planning warning, and the clarification that a user assigned to no Kosli group is neither provisioned nor deprovisioned.

Why not close and refile

The residual scope is coherent — two pages and a changelog entry — and the body is already self-contained and greppable after two rounds of rescoping. Closing would drop that history for no gain.

The four open questions still need product input; #392 answered none of them. Gaps 2 and 4 need no product input and can be picked up now.