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

platform-enterprise_docs/enterprise-sidebar.json

@@ -75,7 +75,35 @@
                   "enterprise/configuration/authentication/google",
                   "enterprise/configuration/authentication/keycloak",
                   "enterprise/configuration/authentication/entra",
-                  "enterprise/configuration/authentication/okta"
+                  "enterprise/configuration/authentication/okta",
+                  {
+                    "type": "category",
+                    "label": "IdP delegation",
+                    "collapsed": true,
+                    "link": {
+                      "type": "doc",
+                      "id": "enterprise/configuration/authentication/idp-delegation/overview"
+                    },
+                    "items": [
+                      {
+                        "type": "category",
+                        "label": "Group catalog",
+                        "collapsed": true,
+                        "link": {
+                          "type": "doc",
+                          "id": "enterprise/configuration/authentication/idp-delegation/group-catalog/overview"
+                        },
+                        "items": [
+                          "enterprise/configuration/authentication/idp-delegation/group-catalog/scim-okta",
+                          "enterprise/configuration/authentication/idp-delegation/group-catalog/scim-entra-id",
+                          "enterprise/configuration/authentication/idp-delegation/group-catalog/manual-google-workspace",
+                          "enterprise/configuration/authentication/idp-delegation/group-catalog/manual-keycloak"
+                        ]
+                      },
+                      "enterprise/configuration/authentication/idp-delegation/claim-mapping",
+                      "enterprise/configuration/authentication/idp-delegation/multi-org-routing"
+                    ]
+                  }
                 ]
               },
               "enterprise/configuration/networking",
@@ -264,6 +292,7 @@
           "administration/overview",
           "orgs-and-teams/organizations",
           "orgs-and-teams/workspace-management",
+          "orgs-and-teams/teams",
           "orgs-and-teams/roles",
           "orgs-and-teams/custom-roles",
           "monitoring/dashboard",

platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/claim-mapping.md

@@ -0,0 +1,81 @@
+---
+title: "IdP claim mapping"
+description: "Configure your identity provider to include the groups claim in OIDC or SAML tokens issued to Seqera Platform Enterprise."
+date: "2026-05-12"
+tags: [sso, idp-delegation, oidc, saml, administration, enterprise]
+---
+
+For IdP-delegated Teams to evaluate correctly at login, the tokens your identity provider sends to Seqera must include a `groups` claim. This page lists the per-IdP configuration steps for the supported providers.
+
+Unlike Cloud Pro — which authenticates through Auth0 and requires a connection-level mapping in the Auth0 tenant — Enterprise reads the IdP's tokens directly. The mapping happens at the IdP, not in front of it.
+
+## OIDC providers
+
+### Okta
+
+1. In the Okta administrator console, open **Security**, then **API**, then **Authorization Servers**.
+2. Select the authorization server backing your Seqera application (typically `default`).
+3. Open **Claims**, then **Add claim**.
+4. Set:
+   - **Name** — `groups`
+   - **Include in token type** — **ID Token** (and **Access Token** if you use access tokens for downstream services)
+   - **Value type** — **Groups**
+   - **Filter** — match the groups you want exposed (`Matches regex .*` to expose all of them).
+5. Save.
+
+### Entra ID
+
+Entra ID requires an app-registration change, plus attention to the format Entra emits.
+
+1. In the Azure portal, open the app registration that backs your Seqera connection.
+2. Open **Token configuration**, then **Add groups claim**.
+3. Select the group types you want emitted (typically **Security groups**).
+4. Under **Customize token properties by type**, choose whether to emit **Group ID** (object GUIDs) or **sAMAccountName** (display names where supported).
+5. Confirm via Entra ID's **Token Preview** that a sample sign-in includes the `groups` claim.
+
+:::caution
+With **Group ID** selected, Entra ID emits group object GUIDs. You have two options:
+
+- Use the GUID values directly as the catalog identifier and the **IdP Group** field on each Team. This works but makes the catalog harder to read.
+- Configure Entra ID to emit display names instead — set **sAMAccountName** as the source where supported, or post-process via a custom claims policy.
+
+The GUID and the display name don't both flow at the same time, so pick one approach for your tenant and stick with it.
+:::
+
+### Keycloak
+
+1. In your Keycloak administrator console, open the realm containing the Seqera client.
+2. Open **Client scopes**, then **Create client scope**.
+3. Set **Name** to `groups` and **Type** to **Default**.
+4. Open the new scope's **Mappers** tab and create a **Group Membership** mapper:
+   - **Token Claim Name** — `groups`
+   - **Full group path** — **OFF** if you want simple group names; **ON** if you prefer paths like `/engineering/admins`. Match this with what you store in the Seqera catalog.
+   - **Add to ID token** — **ON**
+   - **Add to access token** — **ON** (if used)
+5. Open **Clients**, then your Seqera client, then **Client scopes**, and add the `groups` scope to the **Default Client Scopes** list.
+
+### Google Workspace
+
+Google Workspace doesn't include group memberships in OIDC tokens by default. There is no token-level configuration to enable this directly. Seqera Platform Enterprise installations on Google Workspace must use the [manual entry flow](./group-catalog/manual-google-workspace) and rely on the email-address claim chain. Contact Seqera support if you need an alternative configuration for your deployment.
+
+## SAML providers
+
+For SAML SSO connections, configure the IdP's attribute statement to include groups:
+
+| IdP | Attribute name | Notes |
+|-----|----------------|-------|
+| Okta | `groups` | Set the **Filter** to match the groups you want emitted. |
+| Entra ID | `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` | Same GUID-vs-display-name caveat as the OIDC flow. |
+| Other SAML providers | Configure the attribute name to match what your IdP emits. | — |
+
+Seqera reads the `groups` claim from the SAML response on every login.
+
+## Verify the mapping
+
+To confirm the `groups` claim is reaching Seqera:
+
+1. Have a test user sign in via SSO.
+2. In your Seqera Enterprise instance logs, look for the SSO callback log line. It records the full claim set the platform received.
+3. Confirm the `groups` claim is present and contains the expected group identifiers.
+
+If the claim is missing or empty, the user's delegated-Team memberships are revoked at login (this is by design — Seqera treats absent claims as no-membership). Fix the IdP-side mapping before delegating production Teams.

platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/manual-google-workspace.md

@@ -0,0 +1,62 @@
+---
+title: "Manual entry for Google Workspace"
+description: "Populate Seqera Platform Enterprise's IdP group catalog manually for Google Workspace organizations."
+date: "2026-05-12"
+tags: [sso, google-workspace, idp-delegation, administration, enterprise]
+---
+
+Google Workspace doesn't expose a SCIM 2.0 group provisioning API, so the Seqera group catalog is populated manually for Google Workspace organizations. This guide explains the format Seqera expects and where to find the right value in your Google Workspace administrator console.
+
+## Before you begin
+
+- Administrator access to your Google Workspace admin console.
+- Organization owner access to your Seqera organization.
+- An active SSO connection. See [Google authentication](../../google).
+
+:::note
+Google Workspace doesn't include group memberships in OIDC tokens by default. Before catalog entries match at login, configure your IdP to emit a `groups` claim and complete the [IdP claim mapping](../claim-mapping) guidance.
+:::
+
+## What value to enter
+
+Google Workspace identifies groups in OIDC tokens by the **group's primary email address**, not its display name. The value you enter in the Seqera catalog must match that email exactly — for example:
+
+```
+nextflow-admins@yourcompany.com
+```
+
+The value is case-insensitive but must include the full domain. Seqera matches the user's `groups` claim against this value at login.
+
+## Find a group's primary email
+
+1. Sign in to your Google Workspace admin console at [admin.google.com](https://admin.google.com).
+2. Open **Directory**, then **Groups**.
+3. Select the group you want to add to Seqera.
+4. Copy the **Group email** value at the top of the group's details page.
+
+## Add the group to Seqera
+
+1. In Seqera, open **Organization settings** and select **Manage single sign-on**, then **Group mapping**.
+2. Select **Add group manually**.
+3. In **Group identifier**, paste the group's email address.
+4. (Optional) In **Display name**, enter a human-friendly label for the group. This appears in the **IdP Group** dropdown on the Team form.
+5. Save.
+
+The group now appears in the catalog and in the **IdP Group** dropdown on the Team form. To delegate a Team to this group, see [Delegate a Team to an IdP group](../../../../../orgs-and-teams/teams#delegate-a-team-to-an-idp-group).
+
+## Verify the value at login
+
+If a delegated Team isn't picking up users you expect, inspect what Google Workspace is actually emitting:
+
+1. Sign in to a Seqera test account using SSO.
+2. In your Seqera Enterprise instance logs, look for the SSO callback log line. It records the full claim set the platform received.
+3. Confirm the `groups` claim is present and that its values match the catalog entries.
+
+## Limitations
+
+- Google Workspace doesn't support SCIM group sync, so renames and deletes don't propagate automatically. If you rename a group in Workspace, update the catalog entry in Seqera. If you delete a group, also delete the catalog entry to avoid stale references.
+- Nested groups are flattened by Google Workspace into the user's `groups` claim. A user is a member of any group whose membership chain reaches them.
+
+## Multi-organization deployments
+
+On Enterprise instances that host more than one organization, group display names must be unique across all organizations. The manual-add form rejects a value with `409 Conflict` if another organization already has a catalog entry with the same display name. See [Multi-organization routing](../multi-org-routing).

platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/manual-keycloak.md

@@ -0,0 +1,65 @@
+---
+title: "Manual entry for Keycloak"
+description: "Populate Seqera Platform Enterprise's IdP group catalog manually for Keycloak realms."
+date: "2026-05-12"
+tags: [sso, keycloak, idp-delegation, administration, enterprise]
+---
+
+Keycloak doesn't expose a SCIM 2.0 group provisioning API by default, so the Seqera group catalog is populated manually for Keycloak realms. This guide explains the format Seqera expects and where to find the right value in your Keycloak administrator console.
+
+## Before you begin
+
+- Administrator access to your Keycloak realm.
+- Organization owner access to your Seqera organization.
+- An active SSO connection. See [Keycloak authentication](../../keycloak).
+- A **Group Membership** mapper configured on the client scope your Seqera connection uses, so the `groups` claim is included in tokens. See [IdP claim mapping](../claim-mapping#keycloak).
+
+## What value to enter
+
+Keycloak emits group memberships as **group paths** in the `groups` claim — for example:
+
+```
+/engineering/admins
+```
+
+The leading slash and the full path are significant. If your Group Membership mapper is configured with **Full group path: OFF**, Keycloak emits just the group name (`admins`) instead. The value in the Seqera catalog must match the token format exactly.
+
+:::caution
+Check the **Full group path** setting on your Group Membership mapper before adding catalog entries. Mixing full paths and bare names within the same realm leads to login-time mismatches that are hard to diagnose. Pick one format and use it consistently.
+:::
+
+## Find a group's path
+
+1. Sign in to your Keycloak administrator console.
+2. Open the realm containing the Seqera client.
+3. Select **Groups** in the left sidebar.
+4. Navigate to the group you want to add to Seqera. The path shown in the breadcrumb is the value Keycloak emits when **Full group path** is **ON**.
+
+## Add the group to Seqera
+
+1. In Seqera, open **Organization settings** and select **Manage single sign-on**, then **Group mapping**.
+2. Select **Add group manually**.
+3. In **Group identifier**, paste the group path (with the leading slash) or the bare group name, matching your Keycloak Group Membership mapper configuration.
+4. (Optional) In **Display name**, enter a human-friendly label for the group.
+5. Save.
+
+The group now appears in the catalog and in the **IdP Group** dropdown on the Team form. To delegate a Team to this group, see [Delegate a Team to an IdP group](../../../../../orgs-and-teams/teams#delegate-a-team-to-an-idp-group).
+
+## Verify the value at login
+
+If a delegated Team isn't picking up users you expect, inspect what Keycloak is actually emitting:
+
+1. Sign in to a Seqera test account using SSO.
+2. In your Seqera Enterprise instance logs, look for the SSO callback log line. It records the full claim set the platform received.
+3. Confirm the `groups` claim is present and that its values match the catalog entries.
+
+If you see no `groups` claim in the platform logs, your Keycloak Group Membership mapper isn't attached to the client scope. See [IdP claim mapping](../claim-mapping#keycloak).
+
+## Limitations
+
+- Keycloak doesn't push group changes to Seqera automatically. If you rename a group in Keycloak, update the catalog entry in Seqera. If you delete a group, also delete the catalog entry to avoid stale references.
+- Nested groups in Keycloak each emit their own path in the `groups` claim. A user who belongs to `/engineering/admins` is emitted as a member of `/engineering/admins` only, not also of `/engineering`. Add catalog entries for every level you want to delegate.
+
+## Multi-organization deployments
+
+On Enterprise instances that host more than one organization, group display names must be unique across all organizations. The manual-add form rejects a value with `409 Conflict` if another organization already has a catalog entry with the same display name. See [Multi-organization routing](../multi-org-routing).

platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/overview.md

@@ -0,0 +1,64 @@
+---
+title: "Manage your IdP group catalog"
+description: "Populate Seqera with your IdP's groups using SCIM push or manual entry."
+date: "2026-05-12"
+tags: [sso, scim, idp-delegation, administration, enterprise]
+---
+
+Seqera maintains a per-organization catalog of identity provider (IdP) groups. The catalog populates the **IdP Group** dropdown on the Team form, so organization owners can select a group when delegating a Team. The catalog is independent of user activity — groups appear as soon as they're synced or entered, before any user has signed in.
+
+Use the table below to choose the path that fits your IdP.
+
+| IdP | Recommended path | Setup guide |
+|-----|------------------|-------------|
+| Okta | SCIM push | [SCIM provisioning with Okta](./scim-okta) |
+| Entra ID | SCIM push | [SCIM provisioning with Entra ID](./scim-entra-id) |
+| Google Workspace | Manual entry | [Manual entry for Google Workspace](./manual-google-workspace) |
+| Keycloak | Manual entry | [Manual entry for Keycloak](./manual-keycloak) |
+| Other | SCIM push if your IdP supports SCIM 2.0 group provisioning; otherwise manual entry. | — |
+
+## SCIM push
+
+If your IdP supports SCIM 2.0 group provisioning, Seqera exposes a per-organization SCIM endpoint that the IdP can push to. Group create, rename, and delete events flow through automatically, and the catalog stays in sync without administrator intervention.
+
+To set up SCIM:
+
+1. Open **Organization settings** and select **Manage single sign-on**, then **Group mapping**.
+2. Copy the **SCIM endpoint URL** and the generated **bearer token**.
+3. Configure these values in your IdP's SCIM provisioning settings.
+4. Trigger an initial sync from the IdP.
+
+After the sync completes, the catalog displays every group your IdP shared, and the **IdP Group** dropdown on the Team form is populated.
+
+:::caution
+Treat the SCIM bearer token like a password. It grants write access to your organization's group catalog. If the token is compromised, rotate it immediately using **Generate new token** in the **Group mapping** panel — the previous token is revoked atomically.
+:::
+
+## Manual entry
+
+If your IdP doesn't support SCIM group sync, populate the catalog by entering group identifiers manually. The value to enter depends on your IdP — see the per-IdP guides for the format and where to find it.
+
+To add a group manually:
+
+1. Open **Organization settings** and select **Manage single sign-on**, then **Group mapping**.
+2. Select **Add group manually**.
+3. Enter the group identifier exactly as it appears in your IdP's `groups` claim. The form links to per-IdP guidance.
+4. Save.
+
+To delete a manually-entered group, select **Delete** on its row. If any delegated Team references the group, its members are immediately purged and a warning indicates that the Team has lost its source of membership.
+
+:::info
+A manually-entered group is automatically promoted to SCIM-managed if your IdP later pushes the same group via SCIM. The promotion happens in place — the catalog row is reused, and any delegated Teams that reference it continue to work without interruption. After promotion, the row's lifecycle is fully driven by SCIM, and the manual **Delete** action is no longer available; the row is removed when your IdP issues a SCIM `DELETE`.
+:::
+
+## What happens when a catalog entry is removed
+
+When a group is removed from the catalog — by SCIM `DELETE`, manual deletion, or IdP-side rename detection — Seqera does the following synchronously:
+
+- The catalog row is removed.
+- Every delegated Team that referenced the group has its delegation-driven members purged. The Team's other settings — name, workspace assignments, role — are preserved.
+- An orphaned-team warning appears in the **Group mapping** panel, listing the affected Teams. To restore the Team's membership, set its **IdP Group** field to a different group, or clear the field to convert the Team back to manual management.
+
+## Multi-organization deployments
+
+On Enterprise instances that host more than one organization, group display names must be unique across all organizations on the instance. Adding a group that conflicts with another organization's catalog entry fails with a `409 Conflict`. See [Multi-organization routing](../multi-org-routing) for the full rules.