Skip to content

docs(enterprise): Add IdP delegation documentation [PLAT-4827]#1416

Open
justinegeffen wants to merge 7 commits into
enterprise-26.1-documentationfrom
justine-idp-enterprise
Open

docs(enterprise): Add IdP delegation documentation [PLAT-4827]#1416
justinegeffen wants to merge 7 commits into
enterprise-26.1-documentationfrom
justine-idp-enterprise

Conversation

@justinegeffen
Copy link
Copy Markdown
Contributor

@justinegeffen justinegeffen commented May 12, 2026

Summary

Customer-facing documentation for PLAT-4827 — IdP delegation & claims mapping on Seqera Platform Enterprise, shipping with the v26.1 release. Targets the `enterprise-26.1-documentation` branch so this content flows into the 26.1 versioned docs.

This PR adds the documentation layer that explains how organization owners can map a Seqera Team to an IdP group, populate the group catalog (SCIM or manual), configure the IdP to emit the `groups` claim, and understand multi-organization routing.

Pages added

Under platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/:

  • `overview.md` — concept hub: three components, login evaluation, multi-org routing, audit trail
  • `group-catalog/overview.md` — SCIM vs manual entry, promotion, orphan behavior
  • `group-catalog/scim-okta.md` — full Okta SCIM setup procedure
  • `group-catalog/scim-entra-id.md` — full Entra ID SCIM setup procedure
  • `group-catalog/manual-google-workspace.md` — manual catalog entries for Google Workspace
  • `group-catalog/manual-keycloak.md` — manual catalog entries for Keycloak
  • `claim-mapping.md` — per-IdP OIDC and SAML `groups` claim configuration
  • `multi-org-routing.md` — topology decision table, FR-039 uniqueness invariant, conflict resolution

Plus a new Teams page (created from scratch — Enterprise didn't have one):

  • `platform-enterprise_docs/orgs-and-teams/teams.md` — Team creation, editing, and full IdP delegation procedure with the `#delegate-a-team-to-an-idp-group` anchor used by cross-references

Pages updated

  • `platform-enterprise_docs/enterprise-sidebar.json` — adds IdP delegation category under Authentication, adds the new Teams page under Organizations & teams
  • `platform-enterprise_docs/enterprise/configuration/authentication/overview.md` — OIDC group-claim note + new IdP delegation and group claims section

AC coverage (PLAT-4827)

User story Covered in
US1 / PLAT-5164 — Connect IdP groups `group-catalog/*`
US2 / PLAT-5165 — Delegate a Team `teams.md` — "Delegate a Team to an IdP group"
US3 / PLAT-5166 — Login JIT evaluation `overview.md`, `teams.md`
US3 AC 7 — Multi-org routing `multi-org-routing.md`
US4 / PLAT-5167 — Immutability `teams.md`
US5 / PLAT-5168 — Audit trail (delegation/SCIM) `overview.md` — "Audit trail"
USV / PLAT-5172 — Per-IdP setup sufficient `group-catalog/*`, `claim-mapping.md`

Out of scope

  • US8 / PLAT-5171 — workspace assignment usability content is blocked on Figma. Will follow in a separate PR once UX assets land.
  • Audit log page update — Enterprise has `platform-enterprise_docs/monitoring/audit-logs.md` but the SCIM/delegation audit content lives in `idp-delegation/overview.md` instead. If you'd prefer the SCIM/delegation entries to also appear in `audit-logs.md`, flag and I'll lift a short section across.
  • Changelog entries — landing separately.

Open questions for product/engineering

  1. Auth0 mapping for Enterprise-on-Auth0 customers — a subset of Enterprise deployments run their instance behind their own Auth0 tenant. Should the Enterprise docs cross-link to the Cloud Auth0 connection mapping page, or get a sibling Enterprise version? Currently silent (assumes Enterprise reads IdP tokens directly).
  2. Screenshots — PLAT-5172 AC 1 implies the SCIM and claim mapping guides should be sufficient for setup without backend assistance. Would screenshots of the Okta, Entra, and Keycloak admin consoles raise the bar enough to commission them? Currently none.
  3. Multi-organization naming conventions — `multi-org-routing.md` includes operator guidance with three example conventions (prefix, reverse-DNS, project-coded). Confirm this aligns with how Seqera SAs guide multi-org deployments, or flag a different recommended pattern.

Reviewers

CODEOWNERS will auto-request docs reviewers. Please also add:

  • A PLAT-4827 SME (Andrew Dawson reported the epic; Rob Newman commented on it)

Test plan

  • Local Docusaurus build (`npm start` or `npm run build` from repo root)
  • All internal markdown links resolve, including the deep anchor `teams#delegate-a-team-to-an-idp-group`
  • New sidebar entries render in correct order under Authentication → IdP delegation and the new `teams` entry appears under Organizations & teams
  • Cross-links from `authentication/overview.md` to the new sub-folder navigate correctly
  • The 26.1 versioned snapshot picks up these files when the release process runs

Companion Cloud PR: #1415 against `master`.

🤖 Generated with Claude Code

justinegeffen and others added 4 commits May 12, 2026 22:40
…[PLAT-4827]

Add the conceptual hub page for IdP-delegated Teams and the group catalog
documentation set: SCIM provisioning guides for Okta and Entra ID, manual
entry guides for Google Workspace and Keycloak, and a catalog overview that
covers SCIM push, manual entry, manual-to-SCIM promotion, orphaned-team
behavior on group removal, and multi-organization deployment notes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…PLAT-4827]

Add per-IdP OIDC and SAML claim configuration guidance for Okta, Entra ID,
Keycloak, and Google Workspace. Add the multi-organization routing page
covering the topology decision table, the cross-organization group-name
uniqueness invariant, and conflict resolution.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…4827]

Add a standalone Enterprise Teams page covering Team creation, editing, and
the IdP delegation procedure. The delegation section includes prerequisites,
the assignment flow, immutability behavior, login-time evaluation, and the
conversion path back to manual management. Anchored as
#delegate-a-team-to-an-idp-group for cross-references from the authentication
docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… overview [PLAT-4827]

Register the new IdP delegation pages and the new orgs-and-teams Teams page
in the Enterprise sidebar. Update the authentication overview with a one-line
OIDC group-claim note and an "IdP delegation and group claims" section that
links to the new sub-folder.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@justinegeffen justinegeffen added 1. Dev/PM/SME Needs a review by a Dev/PM/SME claude-code-assisted Vibe-coded but with human oversight and guidance. Must be validated by another human and co-pilot. enterprise-26.1 labels May 12, 2026
@justinegeffen justinegeffen marked this pull request as ready for review May 12, 2026 21:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

1. Dev/PM/SME Needs a review by a Dev/PM/SME claude-code-assisted Vibe-coded but with human oversight and guidance. Must be validated by another human and co-pilot. enterprise-26.1

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant