diff --git a/platform-enterprise_docs/enterprise-sidebar.json b/platform-enterprise_docs/enterprise-sidebar.json index 7ca12d593..6c52186a2 100644 --- a/platform-enterprise_docs/enterprise-sidebar.json +++ b/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", diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/claim-mapping.md b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/claim-mapping.md new file mode 100644 index 000000000..ffb0db3f3 --- /dev/null +++ b/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. diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/manual-google-workspace.md b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/manual-google-workspace.md new file mode 100644 index 000000000..0c09fef84 --- /dev/null +++ b/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). diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/manual-keycloak.md b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/manual-keycloak.md new file mode 100644 index 000000000..b902c2d56 --- /dev/null +++ b/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). diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/overview.md b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/overview.md new file mode 100644 index 000000000..6865ecb4e --- /dev/null +++ b/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. diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/scim-entra-id.md b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/scim-entra-id.md new file mode 100644 index 000000000..957bfd179 --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/scim-entra-id.md @@ -0,0 +1,93 @@ +--- +title: "SCIM provisioning with Entra ID" +description: "Configure Microsoft Entra ID to push group memberships to Seqera Platform Enterprise over SCIM 2.0." +date: "2026-05-12" +tags: [sso, scim, entra-id, idp-delegation, administration, enterprise] +--- + +Configure Microsoft Entra ID (formerly Azure AD) to push your tenant's groups to Seqera Platform Enterprise over SCIM 2.0. Once provisioning is enabled, the groups you assign to your Seqera enterprise application appear in Seqera's IdP group catalog and stay in sync with renames, additions, and deletions automatically. + +## Before you begin + +- An Entra ID enterprise application configured as your Seqera SSO connection. See [Entra ID authentication](../../entra). +- Organization owner access to your Seqera organization. +- Administrator access to your Entra ID tenant with permission to manage application provisioning. + +## Get the Seqera SCIM connection details + +1. In Seqera, open **Organization settings** and select **Manage single sign-on**, then **Group mapping**. +2. Copy the **SCIM endpoint URL** — it has the form `https:///orgs//scim/v2`. +3. Select **Generate token** to issue a SCIM bearer token. Copy it immediately; you can't view it again after closing the dialog. + +:::caution +The bearer token grants write access to your group catalog. Store it in a secrets manager and rotate it on a schedule. To rotate, generate a new token in Seqera and update Entra ID's configuration; the previous token is revoked when the new one is issued. +::: + +## Enable provisioning in Entra ID + +1. Sign in to the Azure portal and open **Entra ID**, then **Enterprise applications**. +2. Select the application that fronts your Seqera SSO connection. +3. Open **Provisioning** and select **Get started**. +4. Set **Provisioning Mode** to **Automatic**. +5. Under **Admin Credentials**, provide: + - **Tenant URL** — the Seqera SCIM endpoint URL from the previous section. + - **Secret Token** — the Seqera bearer token from the previous section. +6. Select **Test Connection**. Entra ID should report success. +7. Save. + +## Scope and start provisioning + +1. With **Provisioning** still open, expand **Settings**. +2. Set **Scope** to **Sync only assigned users and groups**. +3. Save, then set **Provisioning Status** to **On**. +4. Return to the application's **Users and groups** tab and assign the groups you want Seqera to receive. + +Entra ID runs an initial cycle within minutes and then syncs incrementally every ~40 minutes. + +## Group display names vs object IDs + +:::caution +By default, Entra ID emits group **object GUIDs** in the `groups` claim, not display names. You have two options: + +- **Recommended** — configure Entra ID to emit display names. In the application's **Token configuration**, add a **groups claim** and select **sAMAccountName** as the source where supported, or use a custom claims policy. This makes catalog entries and audit logs human-readable. +- **Alternative** — accept the default GUID emission. Use the GUID as the **IdP Group** value on each Team. This works but makes the catalog harder to read. + +Pick one approach for your tenant and use it consistently. The GUID and the display name don't both flow at the same time. +::: + +## Verify in Seqera + +1. Return to Seqera's **Group mapping** panel. +2. Refresh the page. The assigned Entra ID groups should appear in the catalog list after the first provisioning cycle. +3. Open any Team's edit form. The **IdP Group** dropdown is now populated with the synced groups. + +If groups don't appear, open the **Provisioning logs** for the application in Entra ID and review any failed actions. + +## Group rename and delete behavior + +Renames and deletes propagate automatically through SCIM: + +- **Rename** — the next provisioning cycle updates the catalog row's display name. Delegated Teams that reference the group continue to work without interruption. +- **Delete** — Entra ID issues a SCIM `DELETE` for the group, or removes the assignment from the enterprise application. Seqera removes the catalog row and synchronously purges members from any delegated Team that referenced it. The affected Teams remain in place with empty membership and an orphaned-team warning. + +## Troubleshooting + +### Groups appear in Entra ID but not in Seqera + +Confirm the bearer token configured in Entra ID matches the latest token Seqera issued. If you generated a new token after configuring Entra ID, the previous one is revoked. + +### Provisioning logs show `401 Unauthorized` + +The bearer token is invalid or expired. Generate a new token in Seqera and replace it in Entra ID. + +### The catalog shows GUID-style identifiers instead of group names + +Entra ID is emitting object IDs rather than display names. See the **Group display names vs object IDs** caution above for the two options. + +### `409 Conflict` on a specific group + +A group with the same display name already exists in another organization on the same Enterprise instance. See [Multi-organization routing](../multi-org-routing) for the cross-organization uniqueness rule and conflict resolution. + +### A group is assigned to the application but doesn't sync + +Confirm the provisioning scope is set to **Sync only assigned users and groups** and that the group is actually listed under **Users and groups**, not just nested in another assigned group. diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/scim-okta.md b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/scim-okta.md new file mode 100644 index 000000000..ff9e89257 --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/group-catalog/scim-okta.md @@ -0,0 +1,71 @@ +--- +title: "SCIM provisioning with Okta" +description: "Configure Okta to push group memberships to Seqera Platform Enterprise over SCIM 2.0." +date: "2026-05-12" +tags: [sso, scim, okta, idp-delegation, administration, enterprise] +--- + +Configure Okta to push your organization's groups to Seqera Platform Enterprise over SCIM 2.0. Once provisioning is enabled, your Okta group directory appears in Seqera's IdP group catalog and stays in sync with renames, additions, and deletions automatically. + +## Before you begin + +- An Okta application configured as your Seqera SSO connection. See [Okta authentication](../../okta). +- Organization owner access to your Seqera organization. +- Administrator access to your Okta tenant. + +## Get the Seqera SCIM connection details + +1. In Seqera, open **Organization settings** and select **Manage single sign-on**, then **Group mapping**. +2. Copy the **SCIM endpoint URL** — it has the form `https:///orgs//scim/v2/Groups`. +3. Select **Generate token** to issue a SCIM bearer token. Copy it immediately; you can't view it again after closing the dialog. + +:::caution +The bearer token grants write access to your group catalog. Store it in a secrets manager and rotate it on a schedule. To rotate, generate a new token in Seqera and update Okta's configuration; the previous token is revoked when the new one is issued. +::: + +## Enable provisioning in Okta + +1. Sign in to your Okta administrator console. +2. Open **Applications**, then select the application that fronts your Seqera SSO connection. +3. Open the **Provisioning** tab and select **Configure API integration**. +4. Select **Enable API integration** and provide: + - **Base URL** — the Seqera SCIM endpoint URL from the previous section, with `/Groups` removed (Okta appends the resource path). + - **API token** — the Seqera bearer token from the previous section. +5. Select **Test API Credentials**. Okta should report a successful connection. +6. Save. + +## Enable group push + +1. With the application still open, switch to the **Push Groups** tab. +2. Select **Push Groups**, then **Find groups by name** (or **By rule** for dynamic group sets). +3. Select the Okta groups you want available in Seqera. +4. Confirm the push. Okta sends an initial provisioning batch. + +## Verify in Seqera + +1. Return to Seqera's **Group mapping** panel. +2. Refresh the page. The pushed Okta groups should appear in the catalog list within a few seconds. +3. Open any Team's edit form. The **IdP Group** dropdown is now populated with the synced groups. + +If groups don't appear, check the **Push Groups** status column in Okta for error details, and confirm that the **Provisioning** tab shows **Push Groups: ON**. + +## Group rename and delete behavior + +Renames and deletes propagate automatically: + +- **Rename** — the next SCIM push updates the catalog row's display name. Delegated Teams that reference the group continue to work without interruption. +- **Delete** — Okta issues a SCIM `DELETE` for the group. Seqera removes the catalog row and synchronously purges members from any delegated Team that referenced it. The affected Teams remain in place with empty membership and an orphaned-team warning. + +## Troubleshooting + +### Groups appear in Okta but not in Seqera + +Confirm the bearer token in Okta matches the latest token Seqera issued. If you generated a new token after configuring Okta, the previous one is revoked. + +### `401 Unauthorized` from Okta logs + +The bearer token is invalid or expired. Generate a new token in Seqera and replace it in Okta. + +### `409 Conflict` on a specific group + +A group with the same display name already exists in another organization on the same Enterprise instance. See [Multi-organization routing](../multi-org-routing) for the cross-organization uniqueness rule and conflict resolution. diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/multi-org-routing.md b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/multi-org-routing.md new file mode 100644 index 000000000..cc629a475 --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/multi-org-routing.md @@ -0,0 +1,54 @@ +--- +title: "Multi-organization routing" +description: "How IdP delegation resolves users to organizations in single-organization and multi-organization Enterprise installations." +date: "2026-05-12" +tags: [sso, idp-delegation, enterprise, administration] +--- + +Cloud Pro tokens carry an `org_id` claim that scopes every IdP delegation evaluation to a single organization. Enterprise SSO tokens don't carry such a claim, so the platform routes by deployment topology and relies on a cross-organization uniqueness invariant on group display names. + +Read this page if your Enterprise instance hosts more than one organization, or you anticipate hosting more than one in the future. + +## Topology decision table + +| Topology | How users are routed | Group-name uniqueness | +|----------|----------------------|------------------------| +| **No SSO** | Not applicable. | Not applicable. | +| **Single organization** | Trivially scoped to the single organization. | Not enforced — there is no second organization to collide with. | +| **Multi-organization** | Evaluated against every organization the user is a member of. | **Enforced** — group display names must be unique across all organizations on the instance. | + +## The uniqueness invariant + +In a multi-organization Enterprise instance, when an administrator adds a group to the catalog (manually or through SCIM), Seqera checks the group's display name against every other organization's catalog on the instance. If another organization already has a row with the same display name, the operation fails: + +- **Manual add** — the form rejects the value with a `409 Conflict` and a message naming the conflicting organization. +- **SCIM push** — the SCIM endpoint returns `409 Conflict` for that group. The IdP's provisioning agent retries and surfaces the error in its administrator console. + +This is the mechanism that lets Seqera resolve a `groups` claim back to a specific organization's catalog at login. Without it, two organizations could both have a group called `engineering` and Seqera couldn't determine which delegation rules to apply. + +:::info +On Cloud Pro, the uniqueness check is skipped because the `org_id` claim disambiguates without it. +::: + +## Resolving a conflict + +If a group-name conflict prevents you from adding a group: + +- Coordinate with the conflicting organization's owner to rename one of the groups in the upstream IdP. The rename propagates via SCIM (or is re-entered manually), and the catalog row becomes available again. +- If renaming isn't possible, namespace the group in your IdP — for example, prefix the group with the organization's name (`acme-engineering` instead of `engineering`). + +There is no per-organization override. Uniqueness is enforced at the instance level. + +## Cross-organization users + +A user who's a member of multiple organizations on the same instance is evaluated against every organization's delegated Teams at login. Because group display names are guaranteed unique, each `groups` claim value resolves to exactly one organization's catalog — there's no ambiguity. The user is added to delegated Teams in any organization where their groups match. + +## Operator guidance for new instances + +For new multi-organization Enterprise deployments, establish a naming convention for IdP groups before onboarding the first organization. Common patterns: + +- **Organization prefix** — `acme-eng-admins`, `beta-eng-admins`. Easy to read; explicit ownership. +- **Reverse-DNS namespace** — `io.acme.eng.admins`. Compact; aligns with IdP best practice. +- **Functional grouping with project codes** — `eng-NF-admins` where `NF` denotes a project. Useful when groups span organizations but require unique names. + +Document the convention in your organization onboarding checklist so administrators avoid `409 Conflict` errors when they configure delegation. diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/overview.md b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/overview.md new file mode 100644 index 000000000..33d2179c1 --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/authentication/idp-delegation/overview.md @@ -0,0 +1,78 @@ +--- +title: "IdP delegation overview" +description: "Map Seqera Teams to identity provider (IdP) groups so membership is controlled at the IdP and evaluated on every SSO login." +date: "2026-05-12" +tags: [sso, idp-delegation, teams, administration, enterprise] +--- + +IdP delegation lets you map a Seqera Team to a group in your identity provider (IdP). After you delegate a Team, the IdP becomes the sole authority for membership: every time a user signs in through SSO, Seqera reads the `groups` claim from their token and updates the user's delegated-Team memberships to match. + +IdP delegation requires an active SSO connection. To set up SSO before configuring delegation, see [Authentication](../overview). + +## How it works + +Delegation has three components that you configure once per organization. + +### 1. The IdP group catalog + +Seqera maintains a per-organization catalog of IdP groups. The catalog populates the **IdP Group** dropdown on the Team form, so organization owners can select an IdP group when delegating a Team. Groups appear in the catalog as soon as they're synced or entered — before any user has signed in. + +The catalog is populated in one of two ways: + +- **SCIM 2.0 push** — your IdP pushes its group directory to Seqera's per-organization SCIM endpoint. Used with Okta and Entra ID. +- **Manual entry** — for IdPs that don't support SCIM group sync (Google Workspace, Keycloak), an organization owner enters group identifiers in the catalog UI. + +A manually-entered group is automatically promoted to SCIM-managed if your IdP later pushes the same group. See [Manage your IdP group catalog](./group-catalog/overview). + +### 2. The `groups` claim + +At login, Seqera reads the user's IdP claims to decide which delegated Teams they belong to. The `groups` claim must be present in the token and must contain the same group identifiers as your catalog. + +Unlike Cloud Pro — which authenticates through Auth0 and requires a connection-level mapping — Enterprise reads the IdP's tokens directly. Configure the claim at the IdP itself. See [IdP claim mapping](./claim-mapping). + +### 3. The Team's `IdP Group` field + +When an organization owner sets the **IdP Group** field on a Team, the Team becomes delegated. This: + +- Marks the Team as "Managed in IdP" in the Teams list. +- Hides the **Add member** and **Remove member** controls. +- Blocks Team deletion until the field is cleared. +- Leaves the Team's name, description, avatar, and workspace assignments editable. + +The same IdP group can be assigned to more than one Team. Each Team can reference exactly one IdP group. See [Delegate a Team to an IdP group](../../../../orgs-and-teams/teams#delegate-a-team-to-an-idp-group). + +## What happens at login + +On every SSO login, Seqera evaluates each delegated Team in your organization against the user's `groups` claim: + +- **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. + +Manual assignments to non-delegated Teams are never touched by this evaluation. 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. + +## Multi-organization deployments + +Cloud Pro tokens carry an `org_id` claim that scopes evaluation to a single organization. Enterprise SSO tokens do not, so the platform routes by deployment topology and enforces a cross-organization uniqueness invariant on group display names. See [Multi-organization routing](./multi-org-routing) for the rules and conflict resolution. + +## Audit trail + +Delegation activity is recorded in the [audit log](../../../../monitoring/audit-logs): + +- Setting, changing, or clearing the **IdP Group** field on a Team produces a `team_updated` event with the previous and new value of `idpGroup`. +- Each delegation-driven membership change at login produces a `team_member_added` or `team_member_removed` event. +- Group catalog operations produce `scimGroupCreated`, `scimGroupUpdated`, and `scimGroupDeleted` events so you can correlate catalog changes with downstream membership changes. + +SCIM-originated entries — operations performed by your IdP's provisioning agent against Seqera's SCIM endpoint — are attributed to a **System** operator rather than to a named administrator, because they authenticate with a SCIM bearer token. To correlate a SCIM event with a specific administrator action, match by `displayName` and timestamp against your IdP's provisioning logs. + +## Set up delegation + +Complete these steps in order. Each step links to a dedicated guide. + +1. [Configure authentication](../overview) for your Enterprise instance if you haven't already. +2. [Populate the IdP group catalog](./group-catalog/overview) — choose SCIM push or manual entry depending on your IdP. +3. [Configure the IdP to emit the `groups` claim](./claim-mapping) so it reaches Seqera at login. +4. If your instance hosts multiple organizations, review the [multi-organization routing rules](./multi-org-routing). +5. [Delegate a Team to an IdP group](../../../../orgs-and-teams/teams#delegate-a-team-to-an-idp-group). diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/overview.md b/platform-enterprise_docs/enterprise/configuration/authentication/overview.md index fe8e1486c..10bbda7e9 100644 --- a/platform-enterprise_docs/enterprise/configuration/authentication/overview.md +++ b/platform-enterprise_docs/enterprise/configuration/authentication/overview.md @@ -43,6 +43,10 @@ In your OpenID provider settings, specify the following URL as a callback addres https:///oauth/callback/oidc ``` +:::note +If you plan to use IdP-delegated Teams, your OIDC token must include a `groups` claim. See [IdP claim mapping](./idp-delegation/claim-mapping) for the per-IdP configuration steps. +::: + ## Root users Root users have administrative access to all Platform resources. Configure root users by their user ID or email address in a comma-separated list: @@ -154,3 +158,16 @@ tower: - "*@your-company.example.com" - "specific-user@another-company.example.net" ``` + +## IdP delegation and group claims + +Seqera Platform Enterprise supports IdP-delegated Teams: organization owners can map a Seqera Team to an IdP group, after which the IdP becomes the sole authority for who belongs to that Team. Memberships are evaluated on every SSO login. + +For delegation to work, your IdP must: + +- Push or expose its group directory to Seqera. See [Manage your IdP group catalog](./idp-delegation/group-catalog/overview) for the SCIM 2.0 push and manual-entry options. +- Include a `groups` claim in the tokens it issues. See [IdP claim mapping](./idp-delegation/claim-mapping) for protocol-specific guidance. + +Once those two pieces are in place, see [IdP delegation overview](./idp-delegation/overview) for the runtime model and [Delegate a Team to an IdP group](../../../orgs-and-teams/teams#delegate-a-team-to-an-idp-group) for the administrator procedure. + +If your Enterprise instance hosts more than one organization, review the [multi-organization routing rules](./idp-delegation/multi-org-routing) before configuring delegation. diff --git a/platform-enterprise_docs/orgs-and-teams/teams.md b/platform-enterprise_docs/orgs-and-teams/teams.md new file mode 100644 index 000000000..f6451d4fa --- /dev/null +++ b/platform-enterprise_docs/orgs-and-teams/teams.md @@ -0,0 +1,96 @@ +--- +title: "Teams" +description: "Create and manage Teams in a Seqera Platform Enterprise organization, including IdP-delegated Teams." +date: "2026-05-12" +tags: [teams, organizations, administration, sso, idp-delegation, enterprise] +--- + +**Teams** allow organization owners to group members and collaborators together into a single unit and to manage them as a whole. Apply a workspace role to a Team and every member inherits that access. See [User roles](./roles) for the available roles. + +:::note +If your organization has [single sign-on (SSO)](../enterprise/configuration/authentication/overview) configured, the Team form includes an **IdP Group** field. Leave it empty to manage Team membership manually, or select an IdP group to delegate membership to your identity provider. See [Delegate a Team to an IdP group](#delegate-a-team-to-an-idp-group). +::: + +## Create a Team + +To create a new Team: + +1. Go to the **Teams** tab in the sidebar of the organization landing page. +2. Select **Add Team**. +3. Enter the **Name** of the Team. +4. Optionally, add the **Description** and the Team's **Avatar**. +5. Select **Add**. + +To add members to the Team, select **Edit**, then **Members of team**, then **Add member**. Enter the name or email address of an organization member or collaborator. + +## Edit a Team + +1. Open the **Teams** tab and select the Team you want to edit. +2. Select **Edit**. +3. Update the **Name**, **Description**, **Avatar**, or membership. +4. Select **Update** to save. + +The same surface is used to delete a Team. The **Delete** action is disabled for delegated Teams; clear the **IdP Group** field first. + +## Delegate a Team to an IdP group + +Organizations with an active SSO connection can delegate Team membership to an identity provider (IdP) group. Once a Team is delegated, the IdP becomes the sole authority for who belongs — Seqera evaluates each user's IdP claims at every SSO login and adjusts membership automatically. + +For the runtime model behind delegation, see [IdP delegation overview](../enterprise/configuration/authentication/idp-delegation/overview). + +### Before you begin + +- An active SSO connection on your organization. See [Authentication](../enterprise/configuration/authentication/overview). +- A populated IdP group catalog. See [Manage your IdP group catalog](../enterprise/configuration/authentication/idp-delegation/group-catalog/overview). +- An IdP that emits the `groups` claim in OIDC or SAML tokens. See [IdP claim mapping](../enterprise/configuration/authentication/idp-delegation/claim-mapping). +- Organization owner access to your Seqera organization. + +### Delegate the 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 [IdP claim mapping](../enterprise/configuration/authentication/idp-delegation/claim-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 doesn't 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](./roles). + +This separation is intentional: the IdP owns membership, but the organization owns access policy.