feat: add SSO, SCIM and Magic Link documentation

[gsavage]

Add documentation for setting up SSO, setting up SCIM and using Magic Link

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
kosli	🟢 Ready	View Preview	Sep 7, 2026, 3:07 PM

[claude]

Claude finished @FayeSGW's task in 3m 38s —— View job

---

Doc review — PR #392

• Read all changed files at branch HEAD (446acc3)
• Checked config/navigation.json entries + IA placement
• Cross-file sweep: SSO ↔ SCIM ↔ roles_in_kosli ↔ mapping_users_to_roles ↔ authenticating_to_kosli ↔ faq/faq.md ↔ changelog
• Verified every internal link target and anchor by hand, and checked the prose against the eight new screenshots
• Posted findings

Two findings are inline on administration/managing_users/automated_user_provisioning.md (step order vs. the first-sync warning; the step-1 screenshot showing the already-configured state). Two more are below because they anchor to lines outside the diff.

---

administration/managing_users/roles_in_kosli.md

Suggestion — the new <Note> at line 191 is the only place the SCIM carve-out appears, and it sits ~165 lines below the two statements it contradicts:

• line 25, permissions matrix: Invite and remove users | ✅ | ❌ | ❌ | ❌
• line 8: "The only role-related capability that is user-only is being invited to or removed from the organization."
• line 71: "User Management: Invite, remove, and change roles of organization members (Admin only)"

The Note now says a SCIM-provisioned user's "roles, and their membership of the organization, cannot be changed in Kosli" — so the matrix, which is the part of this page people actually scan, overstates what an Admin can do once SCIM is on. A short parenthetical on the matrix row (or a pointer under the matrix) would close it without duplicating the Note.

Fix this →

config/navigation.json

Suggestion (placement question) — all three new pages are listed, so core rule 2 is satisfied, and putting Single sign-on and Magic Link ahead of the machine-credential pages reads well. Worth a second thought on the third page though: automated_user_provisioning is in Administration ▸ Users & roles, while SSO is in Administration ▸ Authentication & access — yet the two document halves of the same setup wizard, the SCIM page's first prerequisite is the SSO page, and its group-mapping steps send the reader back into SSO Configuration. An admin doing the SSO → SCIM sequence the page prescribes has to cross groups to do it. Either group is defensible; if it stays under Users & roles, a cross-link from single_sign_on.md would carry the reader across.

Not re-reported

• The SSO-wizard group-mapping pointer — you deferred it pending Descope's in-flight changes to that part of the wizard.
• Screenshot claims I could confirm: Continue with SSO and Continue with GitHub both appear on the sign-in page, so the getting-started sentence and magic_link.md:17 are accurate; the IdP-selection screen does surface the OIDC/SAML choice as a badge on the vendor card, matching single_sign_on.md:28.
• Links: every internal target in the new pages resolves to an existing file, and both in-page anchors (#roles-for-new-and-existing-users, #map-your-idp-groups-to-kosli-roles) match real headings. I could not run mint broken-links or gh pr checks in this environment (mint isn't installed here and the commands weren't permitted), so this was verified by hand rather than by the link-rot check.

0 Critical, 1 Improvement, 3 Suggestions. Nothing here blocks the merge; the ordering trap in the SCIM setup steps is the one worth fixing before it ships.
· branch docs/new-auth-pages

[claude]

Improvement — the procedure's step order and the page's own warning disagree about when to sync.

The <Steps> block ends at "Trigger a provisioning cycle", but group → role mapping is documented after this block, in Map your IdP groups to Kosli roles (line 90). Line 78-80 then says the opposite of what the steps imply:

A full or forced sync in your IdP … provisions every assigned user at once, not only the ones you have just changed, so make sure your groups and role mappings are correct before you trigger one.

An admin following the numbered steps top-to-bottom triggers the first sync at step 4 — before they have mapped any IdP group to a Kosli role, and before they have read the warning. Given the same page says the IdP becomes authoritative for every provisioned user (line 109-112), getting that order wrong is expensive to unwind.

Making the mapping an explicit step before the sync would remove the trap, e.g. insert a step after "Create your IdP groups and add your users":

Map your groups to Kosli roles — follow Map your IdP groups to Kosli roles before you sync. The first sync provisions every assigned user at once.

Fix this →

[claude]

Suggestion — the screenshot shows the state after this step, not the state the reader is in.

images/administration/scim-setup-wizard.png shows both cards already reading ✓ Configured (SSO Configuration (OIDC) and SCIM Configuration, both for Azure Entra ID). A reader arriving to set SCIM up for the first time sees the SCIM card with a + Add action instead — the same shape as add-sso.png on the SSO page, which correctly shows the pre-setup state.

Either capture the screen before SCIM is configured, or add a line saying the card shows + Add until the connection exists (and Configured afterwards), so nobody concludes they are looking at the wrong wizard.