[objectstack-fleet]

Requested by Steve · project thread

Fixes #31658

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么：SSO 文档页新增一节「Grant permission sets from IdP groups」，讲清 SSO 登录时 IdP 组如何按映射授予普通权限集；SCIM 凭据一节加一行回链（同一映射模型，两个来源）。
• 为什么改：feat(plugin-auth): an SSO sign-in grants the permission set its IdP group is mapped to #31657 已上线 SSO 一半的组映射行为，运维文档还没写，管理员找不到怎么配。
• 风险与回滚：纯文档，不发布任何包；回滚即 revert 本 PR。
• 先看：content/docs/permissions/sso.mdx（新节，逐条对照 feat(plugin-auth): an SSO sign-in grants the permission set its IdP group is mapped to #31657 的代码与 changeset）、content/docs/permissions/authentication.mdx（一行回链）。
• 两分钟验证：pnpm check:doc-anchors，预期两处新锚点链接都能解析、全绿。
• 需要你做的：无，席位落地。

What changes

content/docs/permissions/sso.mdx gains one section, Grant permission sets from IdP groups, describing the SSO half of IdP group mapping that PR #31657 landed. Every statement was read from the merged code (sso-group-projection.ts, idp-group-mapping-admin.ts, the route-ledger notes) and #31657's changeset, not written from memory:

• the groups claim is configured in the provider's own mapping.extraFields.groups (on oidcConfig.mapping / samlConfig.mapping at POST /api/v1/auth/sso/register); a string or a list; a provider whose mapping fills no groups signs in as before;
• a mapping is saved through POST /api/v1/auth/admin/scim/set-group-mapping with providerId (exactly one of connectionId / providerId; exactly one of groupExternalId / groupDisplayName), removed through delete-group-mapping;
• only an ordinary permission set inside the provider's organization is granted; the save refusals (400 VALIDATION_FAILED on providerId / permissionSet, 503 with SSO off or no security service);
• grants follow the IdP at every sign-in, a sign-in with no groups claim removes that provider's own earlier grants, and a grant made by hand or through SCIM is never touched;
• a failure is logged at error and never fails the sign-in.

The section links the SCIM credentials section of content/docs/permissions/authentication.mdx, and that section gains one back-link line (one mapping model, two sources). Rules only; no bypass narrative.

Tests

Docs only: no test, no ablation (os-dev: docs are not ablated). The derived doc gates below are the verification.

Acceptance notes

• No SCIM group-mapping section exists to link. The delta asked to link "the SCIM page's group-mapping section"; on origin/main no page under content/docs/ describes the SCIM group mapping that PR feat(plugin-auth): a SCIM group push grants the ordinary permission set its group mapping names #31443 landed (zero hits for set-group-mapping, sys_idp_group_mapping, groupDisplayName outside this diff). The link and back-link therefore use the existing SCIM Connection Credentials section, and the new SSO section carries the shared door's rules for both sources. Documenting the SCIM half's push-time behaviour is left out of this card's file surface.
• ADR-0152 is not linked: it is not on origin/main (PR docs(adr): ADR-0152 a SCIM group grants only an ordinary permission set, through a per-connection mapping row #31636 still open).
• The no-code Setup form cannot set the groups claim. register-sso-provider.ts writes oidcConfig.mapping as { email, name } only and no SAML mapping, so the page sends operators to the vendor's /sso/register for extraFields. Noted, not filed.
• Changeset: skip-changeset. No package's files[] ships content/docs/ (grep of every package.json under packages/ and apps/), so the diff publishes nothing.

Verification

Head: a7bcac5c (origin/main 8c9260f7, which carries PR #31657, merged in; no rebase).

Derived gates on the head

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on a7bcac5c derived 45 commands (the same 45 as on the pre-merge head af648c0e); all 45 ran with exit 0 after the spec, lint and client-react closure was rebuilt for the merged tree, and --ran reconciled: 45 derived, 45 run, 0 NOT-MEASURED, 0 UNRUN. Among them check:doc-anchors (956 internal fragment links resolve, the two new ones included), check:doc-authoring, check:doc-frontmatter, check:docs-single-h1, check:doc-route-spelling (advisory, population clean) and check:doc-security-posture.

On the pre-merge head, check:skill-examples first exited 3 (PREREQUISITE NOT MET: client-react had no .d.ts); it ran green after that package was built, and green again on this head.

Lint

No package is touched (two .mdx pages only), so no package-scoped pnpm lint applies.

Merged behaviour read

sso-group-projection.ts, idp-group-mapping-admin.ts, scim-group-projection.ts, auth-manager-plugin-list.ts and #31657's changeset are byte-identical between #31657's last head 70db6d06 and origin/main 8c9260f7 (git diff --stat empty), so the page describes what landed.

---

Generated by Claude Code

[objectstack-fleet]

domain:server#2 · os-steve · session_01ADHkmQKZzp4DLtqiCkZZRM

维护者速读

• 改了什么：SSO 文档页新增"从 IdP 组授予权限集"一节；SCIM 部分加一行指过去。
• 为什么改：plugin-auth SSO: expose the operator knobs Enterprise SSO needs — IdP-initiated sign-in, IdP group to role / permission set, and refusing unknown users instead of JIT #30967 第 3 项（PR feat(plugin-auth): an SSO sign-in grants the permission set its IdP group is mapped to #31657）已上线 SSO 组映射，文档还没写。
• 风险与回滚：只有文档，无代码、无变更集。回滚即还原本 PR。
• 先看：content/docs/permissions/sso.mdx 新的一节。
• 两分钟验证：读那一节，对照 PR feat(plugin-auth): an SSO sign-in grants the permission set its IdP group is mapped to #31657 的变更说明。
• 需要你做的：无，席位落地。
• 席位意见：ACCEPT。只写规则，不写绕过方式；Setup 表单不能配组声明的缺口另开 setup: the SSO Providers form cannot set the groups claim mapping, so IdP group mapping needs the vendor register door #31666。

席位核对 — ACCEPT · domain:server#2 · Head-sha a7bcac5cbfc1d8d45755c34f3aaea947771099a9 · 2026-11-08T21:20Z

1. Shape: draft to main, Fixes #31658; Clause-②: no, Metadata-protocol: none; skip-changeset (no package ships content/docs). Two files: sso.mdx (+58), authentication.mdx (+4, back-link).
2. Premise: read on main after PR feat(plugin-auth): an SSO sign-in grants the permission set its IdP group is mapped to #31657 merged: the SSO page named no group mapping. The section states the merged behaviour: the claim in mapping.extraFields.groups, the save and delete doors with providerId, ordinary sets inside the provider's organization only, grants follow the IdP at each sign-in, an absent claim removes the provider's own grants, a failure never fails the sign-in.
3. Gates (check-runs on this head): Lint & Repo Gates, Check Documentation Links and Check Changeset success; 33 success, 19 skipped, 0 failed. Dev: 45/45 derived gates exit 0, 0 NOT-MEASURED.
4. Accepted deviations: links point at the SCIM Connection Credentials section (no SCIM group-mapping section exists) and ADR-0152 is not linked (not on main), both as the seat ruled.
5. Out of scope: the Setup → SSO Providers form cannot set the groups claim: filed setup: the SSO Providers form cannot set the groups claim mapping, so IdP group mapping needs the vendor register door #31666. No separate SCIM group-mapping page: dropped — covered, this section documents the one shared model with both connectionId and providerId, and the SCIM section links to it.
6. Landing: docs only, no contract review face. Ordinary queue landing: pr_ready + automerge_enable.