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

platform-cloud/cloud-sidebar.json

@@ -22,6 +22,28 @@
           "getting-started/deployment-options",
           "getting-started/workspace-setup",
           "getting-started/single-sign-on",
+          {
+            "type": "category",
+            "label": "IdP delegation",
+            "link": {"type": "doc", "id": "getting-started/idp-delegation/overview"},
+            "collapsed": true,
+            "items": [
+              {
+                "type": "category",
+                "label": "Group catalog",
+                "link": {"type": "doc", "id": "getting-started/idp-delegation/group-catalog/overview"},
+                "collapsed": true,
+                "items": [
+                  "getting-started/idp-delegation/group-catalog/scim-okta",
+                  "getting-started/idp-delegation/group-catalog/scim-entra-id",
+                  "getting-started/idp-delegation/group-catalog/manual-google-workspace",
+                  "getting-started/idp-delegation/group-catalog/manual-keycloak"
+                ]
+              },
+              "getting-started/idp-delegation/auth0-connection-mapping",
+              "getting-started/idp-delegation/delegate-a-team"
+            ]
+          },
           "getting-started/quickstart-demo/add-pipelines",
           "getting-started/quickstart-demo/add-data",
           "getting-started/quickstart-demo/launch-pipelines",

platform-cloud/docs/getting-started/idp-delegation/auth0-connection-mapping.md

@@ -0,0 +1,96 @@
+---
+title: "Auth0 connection mapping"
+description: "Map your IdP's groups claim through Auth0 so Seqera can see it at login."
+date created: "2026-05-12"
+last updated: "2026-05-12"
+tags: [sso, auth0, idp-delegation, administration, cloud-pro]
+---
+
+For IdP delegation to work on Cloud Pro, your IdP's `groups` claim must reach Seqera at login. Cloud Pro authenticates through Auth0, and Auth0 needs to be told how to extract the `groups` claim from the upstream IdP's token and surface it on the Auth0 user profile. This page provides copy-pasteable mapping snippets for the supported protocols and IdPs.
+
+:::caution
+Auth0 connection mapping is configured in **your** Auth0 tenant for Cloud Pro organizations that bring their own connection. Seqera cannot configure it on your behalf. Without this configuration, delegated Teams will never match — the `groups` claim won't be available at login evaluation time.
+:::
+
+## Before you begin
+
+- An active SSO connection. See [Single sign-on (SSO)](../single-sign-on).
+- Administrator access to the Auth0 tenant that hosts your SSO connection.
+- A populated IdP group catalog in Seqera. See [Manage your IdP group catalog](./group-catalog/overview).
+
+## Where to apply these snippets
+
+In Auth0:
+
+1. Open **Authentication**, then **Enterprise** (or the section matching your connection type).
+2. Select the connection that fronts your IdP.
+3. Open **Settings**, then **Mappings** (or the equivalent for your connection type).
+4. Paste the snippet for your protocol from one of the sections below.
+
+## OIDC connections
+
+For OIDC connections (Okta, Keycloak, Google Workspace, generic OIDC), use this `attribute_map`:
+
+```json
+{
+  "mapping_mode": "use_map",
+  "attributes": {
+    "name": "${context.tokenset.name}",
+    "given_name": "${context.tokenset.given_name}",
+    "family_name": "${context.tokenset.family_name}",
+    "nickname": "${context.tokenset.nickname}",
+    "picture": "${context.tokenset.picture}",
+    "email": "${context.tokenset.email}",
+    "email_verified": "${context.tokenset.email_verified}",
+    "groups": "${context.tokenset.groups}"
+  },
+  "userinfo_scope": "openid email profile groups",
+  "bind_all": true
+}
+```
+
+The two entries specific to delegation are:
+
+- `"groups": "${context.tokenset.groups}"` — copies the `groups` claim from the IdP's token into the Auth0 user profile.
+- `"userinfo_scope": "openid email profile groups"` — instructs Auth0 to request the `groups` scope from the IdP. Required for IdPs that gate group claims on a scope (Keycloak does; Okta does not).
+
+## SAML connections
+
+For SAML connections, use this `fieldsMap`:
+
+```json
+{
+  "groups": "<the SAML attribute name your IdP uses for groups>"
+}
+```
+
+The right-hand value differs by IdP:
+
+| IdP | SAML attribute name |
+|-----|---------------------|
+| Okta | `groups` |
+| Entra ID | `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` |
+| Other SAML providers | Check your IdP's SAML attribute statement configuration. |
+
+:::caution
+Entra ID's default group claim emits **group object GUIDs** (for example, `a8b3c0d1-...`), not display names. You have two options:
+
+- **Recommended** — configure Entra ID to emit display names. In the Entra application registration, open **Token configuration**, then **Add groups claim**, and configure the source attribute to emit display names where supported. Refer to Microsoft's documentation for the current UI flow.
+- **Alternative** — use the GUID itself as the **IdP Group** value on each Team and as the catalog identifier when adding groups manually. This works but makes the catalog harder to read.
+:::
+
+## Verify the mapping
+
+After saving the mapping in Auth0:
+
+1. Sign out of Seqera, then sign in again as a test user who's a member of at least one IdP group.
+2. In Auth0, open **Monitoring**, then **Logs**, and find the **Success Login** event for your test user.
+3. Expand the event details and look for `user.groups`. It should contain the array of group identifiers your IdP emitted.
+
+If `user.groups` is empty or missing:
+
+- Confirm the IdP itself is sending groups in the token. Most IdPs expose raw tokens through their administrator console — for example, Okta's **Token Preview** and Entra's **Token Configuration**.
+- Confirm the scope or attribute name in your snippet matches the IdP's emission.
+- Check Auth0's real-time logs during a login attempt for errors in the mapping.
+
+Once `user.groups` is populated, sign in to Seqera as the test user. Their delegated-Team memberships should reflect their IdP group membership immediately.

platform-cloud/docs/getting-started/idp-delegation/delegate-a-team.md

@@ -0,0 +1,72 @@
+---
+title: "Delegate a Team to an IdP group"
+description: "Map a Seqera Team to an identity provider group so membership is controlled at the IdP."
+date created: "2026-05-12"
+last updated: "2026-05-12"
+tags: [sso, idp-delegation, teams, administration, cloud-pro]
+---
+
+When you delegate a Team to an identity provider (IdP) group, the IdP becomes the sole authority for who belongs to that Team. Seqera evaluates each user's IdP claims at every SSO login and adds or removes them from the Team automatically.
+
+For the runtime model behind delegation, see [IdP delegation overview](./overview).
+
+## Before you begin
+
+- An active SSO connection on your organization. See [Single sign-on (SSO)](../single-sign-on).
+- A populated IdP group catalog. See [Manage your IdP group catalog](./group-catalog/overview).
+- An Auth0 connection mapping that emits the `groups` claim. See [Auth0 connection mapping](./auth0-connection-mapping).
+- Organization owner access to your Seqera organization.
+
+:::info
+If your organization doesn't have SSO configured, the **IdP Group** field appears on the Team form but is disabled. Cloud Basic organization owners see an upgrade prompt when selecting the field.
+:::
+
+## Delegate a Team
+
+1. From the organization's landing page, open the **Teams** tab.
+2. Select the Team you want to delegate, then **Edit**.
+3. In the **IdP Group** field, select a group from the dropdown. The dropdown is populated from your organization's IdP group catalog.
+4. Select **Update** to save.
+
+The same IdP group can be assigned to more than one Team. Each Team can reference exactly one IdP group.
+
+## What changes when a Team is delegated
+
+After you delegate a Team:
+
+- Membership becomes immutable in the Seqera UI. The **Add member** and **Remove member** controls are hidden.
+- The Team cannot be deleted. To delete a delegated Team, clear the **IdP Group** field first.
+- The Team's name, description, avatar, and **IdP Group** value remain editable.
+- Existing manual workspace and role assignments on the Team are preserved.
+- The Team is marked **Managed in IdP** in the Teams list.
+
+## What happens at login
+
+On every SSO login, Seqera evaluates each delegated Team against the user's `groups` claim and updates membership accordingly:
+
+- **Match found** — the user is added to the Team if they aren't already a member.
+- **No match** and the user was previously a member — they're removed from the Team.
+- **No match** and the user was never a delegation-driven member — no change.
+
+Users added manually to a Team with no **IdP Group** value keep their membership regardless of their IdP claims.
+
+If the user's token has no `groups` claim, or the claim is malformed, Seqera treats it as no group memberships and revokes any delegation-driven Team memberships the user previously had. To diagnose claim issues, see [Auth0 connection mapping](./auth0-connection-mapping).
+
+## Stop delegating a Team
+
+To convert a delegated Team back to manual management:
+
+1. Open the Team's **Edit** page.
+2. Clear the **IdP Group** field.
+3. Select **Update** to save.
+
+Existing members are kept. The **Add member** and **Remove member** controls become available again, and the Team can be deleted as normal.
+
+## Workspace and role assignment
+
+Delegation controls who belongs to the Team. It does **not** assign the Team to workspaces or grant roles. After delegation:
+
+- Assign the Team to a workspace using the workspace **Participants** page.
+- Set the Team's workspace role separately. See [User roles](../../orgs-and-teams/roles).
+
+This separation is intentional: the IdP owns membership, but the organization owns access policy.

platform-cloud/docs/getting-started/idp-delegation/group-catalog/manual-google-workspace.md

@@ -0,0 +1,61 @@
+---
+title: "Manual entry for Google Workspace"
+description: "Populate Seqera's IdP group catalog manually for Google Workspace organizations."
+date created: "2026-05-12"
+last updated: "2026-05-12"
+tags: [sso, google-workspace, idp-delegation, administration, cloud-pro]
+---
+
+Google Workspace doesn't expose a SCIM 2.0 group provisioning API, so the Platform group catalog is populated manually for Google Workspace organizations. This guide explains the format Platform 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. To set up SSO, see [Single sign-on (SSO)](../../single-sign-on).
+
+## 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 Platform catalog must match that email exactly — for example:
+
+```
+nextflow-admins@yourcompany.com
+```
+
+The value is case-insensitive but must include the full domain. Platform 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 Platform.
+4. Copy the **Group email** value at the top of the group's details page.
+
+## Add the group to Seqera
+
+1. In Platform, 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. Select **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](../delegate-a-team).
+
+## Verify the value at login
+
+If a delegated team isn't picking up users you expect, the most common cause is a mismatch between the value you entered and the value Google Workspace actually emits in the user's token.
+
+To inspect the value:
+
+1. Sign in to a Cloud Pro test account using SSO.
+2. In your Auth0 tenant, open **Monitoring**, then **Logs**, and find the **Success Login** event for your test user.
+3. Look for `user.groups` in the event details. The values listed there are the exact strings Platform matches against the catalog.
+
+## 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 Platform. If you delete a group in workspace, 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.
+
+:::tip
+A manually-entered group is automatically promoted to SCIM-managed if your IdP later pushes the same group via SCIM. If you migrate from Google Workspace to an IdP that supports SCIM, your existing delegations continue to work without reconfiguration.
+:::

platform-cloud/docs/getting-started/idp-delegation/group-catalog/manual-keycloak.md

@@ -0,0 +1,66 @@
+---
+title: "Manual entry for Keycloak"
+description: "Populate Seqera's IdP group catalog manually for Keycloak realms."
+date created: "2026-05-12"
+last updated: "2026-05-12"
+tags: [sso, keycloak, idp-delegation, administration, cloud-pro]
+---
+
+Keycloak doesn't expose a SCIM 2.0 group provisioning API by default, so the Platform group catalog is populated manually for Keycloak realms. This guide explains the format Platform 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. To set up SSO, see [Single sign-on (SSO)](../../single-sign-on).
+- A **Group Membership** mapper configured on the client scope your Platform connection uses, so the `groups` claim is included in tokens.
+
+## 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 Platform. The path shown in the breadcrumb is the value Keycloak emits when **Full group path** is **ON**.
+
+## Add the group to Platform
+
+1. In Platform, 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. Select **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](../delegate-a-team).
+
+## 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 Cloud Pro test account using SSO.
+2. In your Auth0 tenant, open **Monitoring**, then **Logs**, and find the **Success Login** event for your test user.
+3. Look for `user.groups` in the event details. The values listed there are the exact strings Platform matches against the catalog.
+
+If you see no `groups` claim in the Auth0 log, your Keycloak Group Membership mapper isn't attached to the client scope. See [Auth0 connection mapping](../auth0-connection-mapping) for the upstream scope and attribute requirements.
+
+## Limitations
+
+- Keycloak doesn't push group changes to Platform automatically. If you rename a group in Keycloak, update the catalog entry in Platform. 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.
+
+:::tip
+A manually-entered group is automatically promoted to SCIM-managed if your IdP later pushes the same group via SCIM. If you adopt a Keycloak SCIM extension in the future, your existing delegations continue to work without reconfiguration.
+:::