From 5ec464bc9e4d0287043289220c6eab3a437c0ab7 Mon Sep 17 00:00:00 2001 From: Alexa Date: Wed, 23 Sep 2026 15:33:30 -0500 Subject: [PATCH 1/6] docs: refresh provisioning overview page The provisioning overview had an unfocused title, a thin SEO description, long unwrapped lines, and an attribute list that mixed required and optional fields into prose. Retitle the page to 'User provisioning overview', expand the description and keywords, wrap body text at 80 characters, and move the SSO attributes into a table with a required column. Co-authored-by: Cursor --- .../manuals/security/provisioning/_index.md | 108 ++++++++++-------- 1 file changed, 62 insertions(+), 46 deletions(-) diff --git a/content/manuals/security/provisioning/_index.md b/content/manuals/security/provisioning/_index.md index 3604309d8237..1295d043927d 100644 --- a/content/manuals/security/provisioning/_index.md +++ b/content/manuals/security/provisioning/_index.md @@ -1,87 +1,103 @@ --- -description: Learn about provisioning users for your SSO configuration. -keywords: provision users, provisioning, JIT, SCIM, group mapping, sso, docker admin, admin, security -title: Provision users +description: >- + Provision Docker organization users with SCIM, JIT, group mapping, or + auto-provisioning, and map SSO and SAML attributes from your identity + provider. +keywords: provision users, user provisioning, JIT, SCIM, group mapping, + auto-provisioning, SSO, SAML, identity provider, dockerOrg, dockerRole, + dockerTeam, dockerSessionMinutes, Docker Home, admin, security +title: User provisioning overview linkTitle: Provision weight: 30 aliases: - - /security/for-admins/provisioning/ - - /enterprise/security/provisioning/ - - /platform/security/provisioning/ + - /security/for-admins/provisioning/ + - /enterprise/security/provisioning/ + - /platform/security/provisioning/ grid: - - title: "Add and manage domains" - description: "Add, verify, and manage domains to control user access and enable auto-provisioning." + - title: Add and manage domains + description: Add, verify, and manage domains for auto-provisioning. icon: globe-alt link: "domain-management/" - - title: "SCIM provisioning" - description: "Enable continuous user data synchronization between your IdP and Docker. Best for larger organizations." + - title: SCIM provisioning + description: Sync user data between your IdP and Docker with SCIM. icon: arrow-path link: "scim/" - - title: "Just-in-Time (JIT) provisioning" - description: "Set up automatic user creation on first sign-in. Ideal for smaller teams with minimal setup requirements." + - title: Just-in-Time (JIT) provisioning + description: Create user accounts automatically on first SSO sign-in. icon: clock link: "just-in-time/" - - title: "Auto-provisioning" - description: "Associate members to an organization when email addresses match a verified domain." + - title: Auto-provisioning + description: Add users whose email addresses match a verified domain. icon: user-group link: "auto-provisioning/" --- {{< summary-bar feature_name="SSO" >}} -After configuring your SSO connection, the next step is to provision users. This process ensures that users can access your organization through automated user management. +After you configure single sign-on (SSO), provision users so they can +access your organization through automated account management. -This page provides an overview of user provisioning and the supported provisioning methods. +## Provisioning methods -## What is provisioning? - -Provisioning helps manage users by automating tasks like account creation, updates, and deactivation based on data from your identity provider (IdP). There are several methods for user provisioning, each offering benefits for different organizational needs: +Provisioning automates account creation, updates, and deactivation using +data from your identity provider (IdP). Docker supports the following +methods: | Provisioning method | Description | Default setting in Docker | Recommended for | -| :--- | :--- | :------------- | :--- | -| System for Cross-domain Identity Management (SCIM) | Continuously syncs user data between your IdP and Docker, ensuring user attributes remain updated without manual intervention | Disabled by default | Larger organizations or environments with frequent changes in user information or roles | -| Group mapping | Maps user groups from your IdP to specific roles and permissions within Docker, enabling fine-grained access control based on group membership | Disabled by default | Organizations requiring strict access control and role-based user management | -| Just-in-Time (JIT) | Automatically creates and provisions user accounts when they first sign in via SSO | Enabled by default | Organizations needing minimal setup, smaller teams, or low-security environments | -| Auto-provision | Adds users when email addresses match a verified domain | Disabled by default | Orgs without SSO that need to add existing Docker users by domain | +| :--- | :--- | :--- | :--- | +| System for Cross-domain Identity Management (SCIM) | Syncs user data between your IdP and Docker so attributes stay current without manual updates | Disabled by default | Large organizations or frequent changes in users or roles | +| Group mapping | Maps IdP groups to Docker roles and permissions based on group membership | Disabled by default | Organizations that assign access from IdP group membership | +| Just-in-Time (JIT) | Creates and provisions user accounts when they first sign in with SSO | Enabled by default | Organizations that need minimal setup or smaller teams | +| Auto-provision | Adds users whose email addresses match a verified domain | Disabled by default | Organizations without SSO that add existing Docker users by domain | ## Default provisioning setup -By default, Docker enables JIT provisioning when you configure an SSO connection. With JIT enabled, user accounts are automatically created the first time a user signs in using your SSO flow. +Docker turns on JIT provisioning when you configure an SSO connection. +With JIT on, Docker creates a user account the first time the user signs +in through SSO. -JIT provisioning may not provide sufficient control or security for some organizations. In such cases, SCIM or group mapping can be configured to give administrators more control over user access and attributes. +If you need more control over user access and attributes, configure SCIM +or group mapping. ## SSO attributes -When a user signs in through SSO, Docker obtains several attributes from your IdP to manage the user's identity and permissions. These attributes include: +When a user signs in through SSO, Docker reads attributes from your IdP +to set identity and permissions: -- Email address: The unique identifier for the user -- Full name: The user's complete name -- Groups: Optional. Used for group-based access control -- Docker Org: Optional. Specifies the organization the user belongs to -- Docker Team: Optional. Defines the team the user belongs to within the organization -- Docker Role: Optional. Determines the user's permissions within Docker -- Docker session minutes: Optional. Sets the session duration before users must re-authenticate with their IdP. Must be a positive integer greater than 0. If not provided, default session timeouts apply +| Attribute | Required | Description | +| :--- | :--- | :--- | +| Email address | Yes | Unique identifier for the user | +| Full name | Yes | User's complete name | +| Groups | No | Group-based access control | +| Docker Org | No | Organization the user belongs to | +| Docker Team | No | Team within the organization | +| Docker Role | No | Permissions in Docker | +| Docker session minutes | No | Session duration, in minutes, before users must re-authenticate with their IdP. Must be a positive integer greater than 0. If omitted, default session timeouts apply | > [!NOTE] > -> Default session timeouts apply when Docker session minutes is not specified. Docker Desktop sessions expire after 90 days or 30 days of inactivity. Docker Hub and Docker Home sessions expire after 24 hours. +> Default session timeouts apply when Docker session minutes is not +> specified. Docker Desktop sessions expire after 90 days or 30 days of +> inactivity. Docker Hub and Docker Home sessions expire after 24 hours. ## SAML attribute mapping -If your organization uses SAML for SSO, Docker retrieves these attributes from the SAML assertion message. Different IdPs may use different names for these attributes. +If your organization uses SAML for SSO, Docker reads these attributes +from the SAML assertion. Identity providers may use different names for +the same attributes. -| SSO Attribute | SAML Assertion Message Attributes | +| SSO attribute | SAML assertion attributes | | :--- | :--- | -| Email address | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"`, `email` | -| Full name | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"`, `name`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"` | -| Groups (optional) | `"http://schemas.xmlsoap.org/claims/Group"`, `"http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"`, `Groups`, `groups` | -| Docker Org (optional) | `dockerOrg` | -| Docker Team (optional) | `dockerTeam` | -| Docker Role (optional) | `dockerRole` | -| Docker session minutes (optional) | `dockerSessionMinutes`, must be a positive integer > 0 | +| Email address | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"`, `email` | +| Full name | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"`, `name`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"` | +| Groups (optional) | `"http://schemas.xmlsoap.org/claims/Group"`, `"http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"`, `Groups`, `groups` | +| Docker Org (optional) | `dockerOrg` | +| Docker Team (optional) | `dockerTeam` | +| Docker Role (optional) | `dockerRole` | +| Docker session minutes (optional) | `dockerSessionMinutes`, must be a positive integer greater than 0 | ## Next steps -Choose the provisioning method that best fits your organization's needs: +Choose the provisioning method that fits your organization: -{{< grid >}} \ No newline at end of file +{{< grid >}} From 6d6942ee5314abc3aa3023cdd77abe1248bcc06b Mon Sep 17 00:00:00 2001 From: Alexa Date: Wed, 23 Sep 2026 15:35:48 -0500 Subject: [PATCH 2/6] docs: clarify how JIT interacts with SCIM and auto-provisioning The provisioning overview described each method in isolation, so readers could not tell that JIT overwrites SCIM attributes or that JIT wins over auto-provisioning on an SSO domain. Add a precedence list under the default setup, link each method from the comparison table, note that auto-provisioning only adds existing Docker accounts, and point to the provisioning troubleshooting page. Co-authored-by: Cursor --- .../manuals/security/provisioning/_index.md | 25 +++++++++++++------ 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/content/manuals/security/provisioning/_index.md b/content/manuals/security/provisioning/_index.md index 1295d043927d..78467d312f29 100644 --- a/content/manuals/security/provisioning/_index.md +++ b/content/manuals/security/provisioning/_index.md @@ -45,10 +45,10 @@ methods: | Provisioning method | Description | Default setting in Docker | Recommended for | | :--- | :--- | :--- | :--- | -| System for Cross-domain Identity Management (SCIM) | Syncs user data between your IdP and Docker so attributes stay current without manual updates | Disabled by default | Large organizations or frequent changes in users or roles | -| Group mapping | Maps IdP groups to Docker roles and permissions based on group membership | Disabled by default | Organizations that assign access from IdP group membership | -| Just-in-Time (JIT) | Creates and provisions user accounts when they first sign in with SSO | Enabled by default | Organizations that need minimal setup or smaller teams | -| Auto-provision | Adds users whose email addresses match a verified domain | Disabled by default | Organizations without SSO that add existing Docker users by domain | +| [System for Cross-domain Identity Management (SCIM)](/manuals/security/provisioning/scim/_index.md) | Syncs user data between your IdP and Docker so attributes stay current without manual updates | Disabled by default | Large organizations, or frequent changes in users and roles | +| [Group mapping](/manuals/security/provisioning/scim/group-mapping.md) | Syncs IdP groups with Docker organizations and teams. Works with a SAML SSO connection, or with SCIM | Disabled by default | Organizations that assign teams from IdP group membership | +| [Just-in-Time (JIT)](/manuals/security/provisioning/just-in-time.md) | Creates a user account the first time a user signs in through SSO | Enabled by default | Organizations that want minimal setup, or smaller teams | +| [Auto-provision](/manuals/security/provisioning/auto-provisioning.md) | Adds existing Docker users to your organization when their email address matches a verified domain. It doesn't create accounts | Disabled by default | Organizations that add existing Docker users by domain | ## Default provisioning setup @@ -56,13 +56,19 @@ Docker turns on JIT provisioning when you configure an SSO connection. With JIT on, Docker creates a user account the first time the user signs in through SSO. -If you need more control over user access and attributes, configure SCIM -or group mapping. +JIT takes precedence over the other methods: + +- When SCIM is also enabled, the values from the SSO sign-in flow + overwrite the attributes that SCIM sets. To make SCIM the source of + truth for roles and team assignment, + [turn off JIT](/manuals/security/provisioning/just-in-time.md#disable-jit-provisioning). +- For a domain that belongs to an SSO connection, JIT adds the user + instead of auto-provisioning. ## SSO attributes -When a user signs in through SSO, Docker reads attributes from your IdP -to set identity and permissions: +Each time a user signs in through SSO, Docker reads attributes from your +IdP to set the user's identity and permissions: | Attribute | Required | Description | | :--- | :--- | :--- | @@ -101,3 +107,6 @@ the same attributes. Choose the provisioning method that fits your organization: {{< grid >}} + +If users get the wrong role or team after you change methods, see +[Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). From 9c03ea0eb6beea5c2cb0dd6d6adac4646a972daa Mon Sep 17 00:00:00 2001 From: Alexa Date: Wed, 23 Sep 2026 16:03:05 -0500 Subject: [PATCH 3/6] docs: document how JIT and SCIM interact Admins who enable SCIM while JIT is on by default had no canonical guidance on overwrite and removal risks, and related FAQs mixed SCIM with auto-provisioning. Put the recommended-source decision and both-enabled rules on the SCIM overview, then cross-link from JIT, SCIM setup, the provisioning overview, troubleshooting, and Security FAQs. Co-authored-by: Cursor --- content/manuals/faqs/security.md | 48 ++++++++--- .../manuals/security/provisioning/_index.md | 30 ++++--- .../provisioning/auto-provisioning.md | 2 +- .../provisioning/domain-management.md | 9 +- .../security/provisioning/just-in-time.md | 19 ++++- .../security/provisioning/scim/_index.md | 83 ++++++++++++++----- .../provisioning/scim/provision-scim.md | 14 ++-- .../provisioning/troubleshoot-provisioning.md | 30 ++++++- 8 files changed, 171 insertions(+), 64 deletions(-) diff --git a/content/manuals/faqs/security.md b/content/manuals/faqs/security.md index ffa5fee6550c..87e4964b2f65 100644 --- a/content/manuals/faqs/security.md +++ b/content/manuals/faqs/security.md @@ -94,17 +94,37 @@ If SSO is turned on but not enforced, users can fall back to username/password a Yes, bot accounts need seats like regular users, requiring a non-aliased domain email in the IdP and using a seat in Docker Hub. You can add bot accounts to your IdP and create access tokens to replace other credentials. +### How can I troubleshoot an Entra ID SSO connection error? + +Confirm that you've configured the necessary API permissions in Entra ID for your SSO connection. You need to grant administrator consent within your Entra ID tenant. See [Entra ID (formerly Azure AD) documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal#grant-admin-consent-in-app-registrations). + +## Provisioning + ### Does SAML SSO use Just-in-Time provisioning? -The SSO implementation uses Just-in-Time (JIT) provisioning by default. You can optionally turn off JIT in Docker Home if you turn on auto-provisioning using SCIM. See [Just-in-Time provisioning](/manuals/security/provisioning/just-in-time.md). +Yes. Docker turns on Just-in-Time (JIT) provisioning when you configure an SSO +connection. You can turn off JIT after you configure and test SCIM. See +[Just-in-Time provisioning](/manuals/security/provisioning/just-in-time.md). -### How can I troubleshoot an Entra ID SSO connection error? +### Can I use JIT and SCIM together? -Confirm that you've configured the necessary API permissions in Entra ID for your SSO connection. You need to grant administrator consent within your Entra ID tenant. See [Entra ID (formerly Azure AD) documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal#grant-admin-consent-in-app-registrations). +Yes, but Docker recommends using one provisioning source. When both are +enabled, JIT applies attributes during sign-in and SCIM applies attributes on +its synchronization schedule. Review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit) +before enabling both. + +### How can I give a user immediate access with SCIM? + +If your IdP supports Provision on Demand, use it to synchronize the user +before the next scheduled SCIM synchronization. This provides immediate +provisioning without enabling JIT. ### Do I need to manually add users to my organization? -No, you don't need to manually add users to your organization. Just ensure user accounts exist in your IdP. When users sign in to Docker with their domain email address, they're automatically added to the organization after successful authentication. +Not when JIT, SCIM, or auto-provisioning is configured for the user. If you +turn off JIT without configuring SCIM, users must already be organization +members or have pending invitations before they sign in through SSO. ### Can users use different email addresses to authenticate through SSO? @@ -129,11 +149,13 @@ For detailed instructions, see [Configure single sign-on](/manuals/security/auth ### Is Docker SSO fully synced with the IdP? -Docker SSO provides Just-in-Time (JIT) provisioning by default. Users are provisioned when they authenticate with SSO. If users leave the organization, administrators must manually [remove the user](/manuals/accounts/organization/manage/members.md#remove-a-member-from-the-organization) from the organization. - -[SCIM](/manuals/security/provisioning/scim/_index.md) provides full synchronization with users and groups. When using SCIM, the recommended configuration is to turn off JIT so all auto-provisioning is handled by SCIM. +Not with JIT alone. JIT provisions users when they authenticate, but it +doesn't deprovision users who leave your IdP. Administrators must +[remove those users](/manuals/accounts/organization/manage/members.md#remove-a-member-from-the-organization) +manually. -Additionally, you can use the [Docker Hub API](/reference/api/hub/latest.md) to complete this process. +[SCIM](/manuals/security/provisioning/scim/_index.md) provides continuous user +and group synchronization, including automatic deprovisioning. ### How does turning off Just-in-Time provisioning affect user sign-in? @@ -143,11 +165,17 @@ See [SSO authentication with JIT provisioning disabled](/manuals/security/provis ### Can someone join an organization without an invitation? -Not without SSO. Joining requires an invite from an organization owner. When SSO is enforced, users with verified domain emails can automatically join the organization when they sign in. +Yes. JIT can add users when they sign in through SSO, SCIM can provision users +assigned in the IdP, and auto-provisioning can add existing Docker users whose +email addresses match a verified domain. Without an automatic provisioning +method, an organization owner must invite the user. ### What happens to existing licensed users when SCIM is turned on? -Turning on SCIM doesn't immediately remove or modify existing licensed users. They retain current access and roles, but you'll manage them through your IdP after SCIM is active. If SCIM is later turned off, previously SCIM-managed users remain in Docker but are no longer automatically updated based on your IdP. +Turning on SCIM doesn't convert existing manually or JIT-provisioned users into +SCIM-managed users. They retain their access and roles until you migrate or +remove them. To move JIT-provisioned users under SCIM lifecycle management, +see [Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md). ### Is user information visible in Docker Hub? diff --git a/content/manuals/security/provisioning/_index.md b/content/manuals/security/provisioning/_index.md index 78467d312f29..a2457611cd37 100644 --- a/content/manuals/security/provisioning/_index.md +++ b/content/manuals/security/provisioning/_index.md @@ -43,27 +43,25 @@ Provisioning automates account creation, updates, and deactivation using data from your identity provider (IdP). Docker supports the following methods: -| Provisioning method | Description | Default setting in Docker | Recommended for | +| Provisioning method | When it runs | Lifecycle management | Default setting | | :--- | :--- | :--- | :--- | -| [System for Cross-domain Identity Management (SCIM)](/manuals/security/provisioning/scim/_index.md) | Syncs user data between your IdP and Docker so attributes stay current without manual updates | Disabled by default | Large organizations, or frequent changes in users and roles | -| [Group mapping](/manuals/security/provisioning/scim/group-mapping.md) | Syncs IdP groups with Docker organizations and teams. Works with a SAML SSO connection, or with SCIM | Disabled by default | Organizations that assign teams from IdP group membership | -| [Just-in-Time (JIT)](/manuals/security/provisioning/just-in-time.md) | Creates a user account the first time a user signs in through SSO | Enabled by default | Organizations that want minimal setup, or smaller teams | -| [Auto-provision](/manuals/security/provisioning/auto-provisioning.md) | Adds existing Docker users to your organization when their email address matches a verified domain. It doesn't create accounts | Disabled by default | Organizations that add existing Docker users by domain | +| [System for Cross-domain Identity Management (SCIM)](/manuals/security/provisioning/scim/_index.md) | On the IdP's synchronization schedule or through Provision on Demand | Creates and updates users, synchronizes configured groups, and deprovisions users | Disabled | +| [Just-in-Time (JIT)](/manuals/security/provisioning/just-in-time.md) | When a user signs in through SSO | Creates users and applies attributes from the SSO assertion. It doesn't deprovision users | Enabled when you configure SSO | +| [Auto-provisioning](/manuals/security/provisioning/auto-provisioning.md) | When an existing Docker user signs in with an email address from a verified domain | Adds the user to the organization. It doesn't create or deprovision accounts | Disabled | -## Default provisioning setup +[Group mapping](/manuals/security/provisioning/scim/group-mapping.md) assigns +users to Docker organizations and teams. Use it with SAML SSO or SCIM. You can +also invite users manually when automatic provisioning isn't configured. -Docker turns on JIT provisioning when you configure an SSO connection. -With JIT on, Docker creates a user account the first time the user signs -in through SSO. +## Default provisioning setup -JIT takes precedence over the other methods: +Docker turns on JIT provisioning when you configure an SSO connection. If you +also enable SCIM, Docker recommends choosing one provisioning source to manage +users and attributes. Before configuring SCIM, review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit). -- When SCIM is also enabled, the values from the SSO sign-in flow - overwrite the attributes that SCIM sets. To make SCIM the source of - truth for roles and team assignment, - [turn off JIT](/manuals/security/provisioning/just-in-time.md#disable-jit-provisioning). -- For a domain that belongs to an SSO connection, JIT adds the user - instead of auto-provisioning. +For a domain that belongs to an SSO connection, JIT adds the user instead of +auto-provisioning. ## SSO attributes diff --git a/content/manuals/security/provisioning/auto-provisioning.md b/content/manuals/security/provisioning/auto-provisioning.md index 5775aba77022..039f3e55da62 100644 --- a/content/manuals/security/provisioning/auto-provisioning.md +++ b/content/manuals/security/provisioning/auto-provisioning.md @@ -42,7 +42,7 @@ The **Auto-provisioning** column will update to **Enabled** for the domain. ### Disable auto-provisioning -To disable auto-provisioning for a user: +To disable auto-provisioning for a domain: 1. Sign in to [Docker Home](https://app.docker.com) and select your organization. If your organization is part of a company, select the company diff --git a/content/manuals/security/provisioning/domain-management.md b/content/manuals/security/provisioning/domain-management.md index f21a26a218cd..f5b49235b59f 100644 --- a/content/manuals/security/provisioning/domain-management.md +++ b/content/manuals/security/provisioning/domain-management.md @@ -117,10 +117,13 @@ CSV file. For more information on bulk inviting users, see ## Auto-provisioning -[Auto-provisioning](/manuals/security/provisioning/auto-provisioning.md) uses verified domains to associate organization members with email address that match the verified domains. To override auto-provisioning, you can configure one of the two alternative methods: +[Auto-provisioning](/manuals/security/provisioning/auto-provisioning.md) adds +existing Docker users to an organization when their email addresses match a +verified domain. For domains that belong to an SSO connection, Just-in-Time +(JIT) provisioning takes precedence over auto-provisioning. -- [Just-in-Time (JIT)](/manuals/security/provisioning/just-in-time.md) provisioning -- [System for Cross-domain Identity Management (SCIM)](/manuals/security/provisioning/scim/_index.md) +To compare JIT, SCIM, and auto-provisioning, see the +[user provisioning overview](/manuals/security/provisioning/_index.md). ## Delete a domain diff --git a/content/manuals/security/provisioning/just-in-time.md b/content/manuals/security/provisioning/just-in-time.md index c6b3af2d9ae2..249d434ce220 100644 --- a/content/manuals/security/provisioning/just-in-time.md +++ b/content/manuals/security/provisioning/just-in-time.md @@ -11,9 +11,16 @@ aliases: {{< summary-bar feature_name="SSO" >}} -Just-in-Time (JIT) provisioning streamlines user onboarding by automatically creating and updating user accounts during SSO authentication. This eliminates manual account creation and ensures users have immediate access to your organization's resources. JIT verifies that users belong to the organization and assigns them to the appropriate teams based on your identity provider (IdP) configuration. When you create your SSO connection, JIT provisioning is turned on by default. +Just-in-Time (JIT) provisioning creates and updates user accounts during SSO +authentication. JIT verifies that users belong to the organization and assigns +them to teams based on your identity provider (IdP) configuration. JIT doesn't +deprovision users. -This page explains how JIT provisioning works, SSO authentication flows, and how to disable JIT provisioning. +When you create an SSO connection, Docker turns on JIT provisioning by +default. Before adding SCIM, review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit). + +This page explains the SSO authentication flows with JIT turned on and off. ## Prerequisites @@ -64,7 +71,10 @@ The following graphic provides an overview of SSO authentication with JIT disabl > [!WARNING] > -> Disabling JIT provisioning may disrupt your users' access and workflows. With JIT disabled, users will not be automatically added to your organization. Users must already be a member of the organization or have a pending invitation to successfully sign in through SSO. To auto-provision users with JIT disabled, [use SCIM](./scim.md). +> Disabling JIT provisioning may disrupt your users' access and workflows. With +> JIT disabled, users aren't automatically added to your organization during +> SSO sign-in. Users must be organization members, have pending invitations, or +> be provisioned through SCIM to sign in successfully. You may want to disable JIT provisioning for reasons such as the following: @@ -80,6 +90,7 @@ Users are provisioned with JIT by default. If you enable SCIM, you can disable J ## Next steps -- Configure [SCIM provisioning](/manuals/security/provisioning/scim/_index.md) for advanced user management. +- Review [how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit) + before you configure SCIM. - Set up [group mapping](/manuals/security/provisioning/scim/group-mapping.md) to automatically assign users to teams. - Review [Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). diff --git a/content/manuals/security/provisioning/scim/_index.md b/content/manuals/security/provisioning/scim/_index.md index 68cc5743cd27..c8217fbcf682 100644 --- a/content/manuals/security/provisioning/scim/_index.md +++ b/content/manuals/security/provisioning/scim/_index.md @@ -2,8 +2,11 @@ title: SCIM overview linkTitle: SCIM weight: 10 -description: Learn how System for Cross-domain Identity Management works and how to set it up. -keywords: SCIM, SSO, user provisioning, de-provisioning, role mapping, assign users +description: >- + Learn how SCIM provisions and deprovisions Docker users, how it interacts + with JIT provisioning, and how to choose a provisioning source. +keywords: SCIM, SSO, user provisioning, deprovisioning, JIT, role mapping, + assign users, identity provider, Provision on Demand aliases: - /security/for-admins/scim/ - /security/for-admins/provisioning/scim/ @@ -12,13 +15,10 @@ aliases: {{< summary-bar feature_name="SSO" >}} -Automate user management for your Docker organization using System for -Cross-domain Identity Management (SCIM). SCIM automatically provisions and -de-provisions users, synchronizes team memberships, and keeps your Docker -organization in sync with your identity provider. - -This page shows you how to automate user provisioning and de-provisioning for -Docker using SCIM. +System for Cross-domain Identity Management (SCIM) synchronizes users and +groups between your identity provider (IdP) and Docker. It supports automated +provisioning, profile updates, and deprovisioning throughout the user +lifecycle. ## Prerequisites @@ -37,8 +37,7 @@ application in your identity provider, SCIM deactivates and removes them from your Docker organization. In addition to provisioning and removal, SCIM also syncs profile updates like -name changes made in your identity provider. You can use SCIM alongside Docker's -default Just-in-Time (JIT) provisioning or on its own with JIT disabled. +name changes made in your identity provider. SCIM automates: @@ -46,17 +45,63 @@ SCIM automates: - Updating user profiles - Removing and deactivating users - Re-activating users -- Group mapping +- Synchronizing groups when group mapping is configured > [!NOTE] > -> SCIM only manages users provisioned through your identity provider after -> SCIM is enabled. It cannot remove users who were manually added to your Docker -> organization before SCIM was set up. -> -> To remove those users, delete them manually from your Docker organization. -> For more information, see -> [Manage organization members](/manuals/accounts/organization/manage/members.md). +> Enabling SCIM doesn't convert manually added users into SCIM-managed users. +> SCIM only provides full lifecycle management for users it provisions. + +## Choose how SCIM works with JIT + +Docker turns on Just-in-Time (JIT) provisioning when you configure an SSO +connection. Before you enable SCIM, choose whether SCIM or JIT will own user +provisioning. + +Docker recommends using one provisioning source. Using SCIM without JIT keeps +the IdP directory authoritative for user creation, attributes, group +membership, and deprovisioning. + +### Use SCIM without JIT + +With JIT turned off, SCIM provisions users on the IdP's synchronization +schedule instead of when users sign in. This configuration provides continuous +attribute updates and automatic deprovisioning. + +If your IdP supports Provision on Demand, you can trigger an immediate sync for +a user who needs access before the next scheduled synchronization. + +Configure and test SCIM before you +[turn off JIT](/manuals/security/provisioning/just-in-time.md#disable-jit-provisioning). + +### Use SCIM with JIT + +JIT and SCIM run independently: + +- JIT reads the SSO assertion and applies its values when a user signs in. +- SCIM reads users, attributes, and group membership from the IdP on its + synchronization schedule. + +When both are enabled, values applied during sign-in can overwrite values that +SCIM set. A JIT-provisioned user who isn't in the SCIM-mapped IdP group can +also be removed from the Docker organization during the next SCIM +synchronization. + +If you keep both enabled: + +- Match each user's email address exactly between the SSO assertion and SCIM. +- Add every user who can be provisioned through JIT to the SCIM-mapped group. +- Keep roles, organizations, teams, and group membership consistent in the + IdP. +- Monitor users and assignments for changes after sign-in and SCIM + synchronization. + +Keeping a JIT-provisioned user in the mapped group doesn't convert the account +to SCIM lifecycle management. To let SCIM manage the account, follow +[Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md). + +For help diagnosing attribute or membership changes, see +[Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). ## Next steps diff --git a/content/manuals/security/provisioning/scim/provision-scim.md b/content/manuals/security/provisioning/scim/provision-scim.md index 2fb04f0e2448..06c2a5496686 100644 --- a/content/manuals/security/provisioning/scim/provision-scim.md +++ b/content/manuals/security/provisioning/scim/provision-scim.md @@ -1,7 +1,9 @@ --- title: Set up SCIM provisioning linkTitle: Setup -description: Learn how System for Cross-domain Identity Management works and how to set it up. +description: Configure SCIM user provisioning and role mapping for Docker with Okta or Microsoft Entra ID. +keywords: SCIM setup, user provisioning, role mapping, Okta, Microsoft Entra ID, + identity provider, Docker Home weight: 10 aliases: - /platform/security/provisioning/scim/provision-scim/ @@ -31,13 +33,9 @@ For additional details about supported attributes and SCIM, see > [!IMPORTANT] > -> By default, Docker uses Just-in-Time (JIT) provisioning for SSO. If SCIM is -> enabled, JIT values still take precedence and will overwrite attribute values -> set by SCIM. To avoid conflicts, make sure your JIT attribute values match -> your SCIM values. -> -> Alternatively, you can disable JIT provisioning to rely solely on SCIM. -> For details, see [Just-in-Time](/manuals/security/provisioning/just-in-time.md). +> Docker turns on Just-in-Time (JIT) provisioning by default when you configure +> SSO. Before setting up SCIM, decide which method will manage provisioning and +> review [how SCIM works with JIT](./_index.md#choose-how-scim-works-with-jit). ## Enable SCIM in Docker diff --git a/content/manuals/security/provisioning/troubleshoot-provisioning.md b/content/manuals/security/provisioning/troubleshoot-provisioning.md index b61089a19d7b..585e4a6dc23b 100644 --- a/content/manuals/security/provisioning/troubleshoot-provisioning.md +++ b/content/manuals/security/provisioning/troubleshoot-provisioning.md @@ -16,8 +16,9 @@ This page helps troubleshoot common user provisioning issues including user role ### Error message -Typically, this scenario does not produce an error message in Docker or your -IdP. This issue usually surfaces as incorrect role or team assignment. +This scenario doesn't usually produce an error message in Docker or your IdP. +A role or team assignment may be incorrect or may revert after the user signs +in or SCIM synchronizes. ### Causes @@ -65,6 +66,29 @@ If you prefer to keep JIT enabled: This option requires strict coordination between SSO and SCIM attributes in your IdP configuration. +## JIT-provisioned user is removed after a SCIM sync + +### Cause + +JIT and SCIM are both enabled, and the user isn't in the IdP group that SCIM +maps to the Docker organization. SCIM treats the mapped group as the +organization roster and removes the user's organization membership during +synchronization. + +### Solution + +If you keep both methods enabled: + +1. Add every user who can be provisioned through JIT to the SCIM-mapped group. +1. Make sure each user's email address matches exactly between the SSO + assertion and SCIM. +1. Trigger a SCIM synchronization in your IdP. +1. Confirm that the user belongs to the expected organization and teams. + +To avoid coordinating two provisioning sources, use SCIM without JIT. Review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit) +before changing the configuration. + ## SCIM updates don't apply to existing users ### Causes @@ -83,5 +107,5 @@ existing user: > [!WARNING] > -> Deleting a user removes their resource ownership (e.g., repositories). +> Deleting a user removes their resource ownership, such as repositories. > Transfer ownership before removing the user. From 1a1f2d7a7d7480506cb24d49af08567906237544 Mon Sep 17 00:00:00 2001 From: Alexa Date: Fri, 25 Sep 2026 10:17:42 -0500 Subject: [PATCH 4/6] docs: clarify SCIM provisioning and its relationship to JIT The SCIM pages described provisioning behavior inconsistently: the overview didn't explain how SCIM and JIT interact, group mapping didn't distinguish what SAML SSO sends at sign-in from what SCIM syncs on a schedule, and the setup and migration pages used stale Entra ID naming, mixed numbered-list styles, and long unwrapped lines. Rewrote the four SCIM pages for accuracy and consistency: added a section on choosing how SCIM works with JIT, separated the SSO and SCIM group-mapping paths, corrected the Okta and Microsoft Entra ID setup values and links, and normalized front matter, list numbering, and line wrapping. Co-authored-by: Cursor --- .../security/provisioning/scim/_index.md | 50 +++--- .../provisioning/scim/group-mapping.md | 168 ++++++++++-------- .../provisioning/scim/migrate-scim.md | 146 ++++++++------- .../provisioning/scim/provision-scim.md | 133 +++++++------- 4 files changed, 262 insertions(+), 235 deletions(-) diff --git a/content/manuals/security/provisioning/scim/_index.md b/content/manuals/security/provisioning/scim/_index.md index c8217fbcf682..ddf650296e0f 100644 --- a/content/manuals/security/provisioning/scim/_index.md +++ b/content/manuals/security/provisioning/scim/_index.md @@ -1,12 +1,12 @@ --- -title: SCIM overview +title: SCIM provisioning overview linkTitle: SCIM weight: 10 description: >- - Learn how SCIM provisions and deprovisions Docker users, how it interacts - with JIT provisioning, and how to choose a provisioning source. + Provision, update, and deprovision Docker users with SCIM, and choose how + SCIM works with Just-in-Time provisioning. keywords: SCIM, SSO, user provisioning, deprovisioning, JIT, role mapping, - assign users, identity provider, Provision on Demand + group mapping, identity provider, Provision on Demand, Okta, Entra ID aliases: - /security/for-admins/scim/ - /security/for-admins/provisioning/scim/ @@ -16,9 +16,9 @@ aliases: {{< summary-bar feature_name="SSO" >}} System for Cross-domain Identity Management (SCIM) synchronizes users and -groups between your identity provider (IdP) and Docker. It supports automated -provisioning, profile updates, and deprovisioning throughout the user -lifecycle. +groups between your identity provider (IdP) and Docker. It provisions +accounts, syncs profile updates, and deprovisions users throughout the +account lifecycle. ## Prerequisites @@ -29,22 +29,21 @@ Before you begin, you must have: ## How SCIM works -SCIM automates user provisioning and de-provisioning for Docker through your -identity provider. After you enable SCIM, any user assigned to your -Docker application in your identity provider is automatically provisioned and -added to your Docker organization. When a user is removed from the Docker -application in your identity provider, SCIM deactivates and removes them from -your Docker organization. +After you enable SCIM, any user assigned to your Docker application in the +identity provider is provisioned and added to your Docker organization. SCIM +syncs profile updates from the identity provider, such as name changes, and +reactivates users who are reassigned to the application. If group mapping is +configured, SCIM also synchronizes groups. -In addition to provisioning and removal, SCIM also syncs profile updates like -name changes made in your identity provider. +When a user is removed from the Docker application, SCIM deactivates and +removes them from your Docker organization. SCIM automates: - Creating users - Updating user profiles - Removing and deactivating users -- Re-activating users +- Reactivating users - Synchronizing groups when group mapping is configured > [!NOTE] @@ -68,9 +67,8 @@ With JIT turned off, SCIM provisions users on the IdP's synchronization schedule instead of when users sign in. This configuration provides continuous attribute updates and automatic deprovisioning. -If your IdP supports Provision on Demand, you can trigger an immediate sync for -a user who needs access before the next scheduled synchronization. - +If your IdP supports Provision on Demand, you can trigger an immediate sync +for a user who needs access before the next scheduled synchronization. Configure and test SCIM before you [turn off JIT](/manuals/security/provisioning/just-in-time.md#disable-jit-provisioning). @@ -100,11 +98,13 @@ Keeping a JIT-provisioned user in the mapped group doesn't convert the account to SCIM lifecycle management. To let SCIM manage the account, follow [Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md). -For help diagnosing attribute or membership changes, see -[Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). - ## Next steps -- [Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md) if users were provisioned with Just-in-Time (JIT) before you enabled SCIM. -- [Group mapping](/manuals/security/provisioning/scim/group-mapping.md) to sync identity provider groups with members. -- [Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md) for SCIM, JIT, and attribute issues. +- [Set up SCIM provisioning](/manuals/security/provisioning/scim/provision-scim.md) + to enable SCIM in Docker and your identity provider. +- [Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md) + if users were provisioned with Just-in-Time (JIT) before you enabled SCIM. +- [Group mapping](/manuals/security/provisioning/scim/group-mapping.md) to + sync identity provider groups with Docker teams. +- [Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md) + for SCIM, JIT, and attribute issues. diff --git a/content/manuals/security/provisioning/scim/group-mapping.md b/content/manuals/security/provisioning/scim/group-mapping.md index 9813891d9ab6..c348ffb69fad 100644 --- a/content/manuals/security/provisioning/scim/group-mapping.md +++ b/content/manuals/security/provisioning/scim/group-mapping.md @@ -1,26 +1,35 @@ --- -title: Group mapping -description: Automate team membership by syncing identity provider groups with Docker Teams -keywords: Group Mapping, SCIM, Docker Admin, admin, security, team management, user provisioning, identity provider +title: Map identity provider groups to Docker teams +linkTitle: Group mapping +description: >- + Automate Docker team membership by mapping groups from your identity + provider with SSO or SCIM. +keywords: group mapping, SCIM, SSO, Docker teams, team management, + user provisioning, identity provider, Okta, Microsoft Entra ID aliases: -- /admin/company/settings/group-mapping/ -- /admin/organization/security-settings/group-mapping/ -- /security/for-admins/group-mapping/ -- /security/for-admins/provisioning/scim/group-mapping/ -- /platform/security/provisioning/group-mapping/ -- /platform/security/provisioning/scim/group-mapping/ + - /admin/company/settings/group-mapping/ + - /admin/organization/security-settings/group-mapping/ + - /security/for-admins/group-mapping/ + - /security/for-admins/provisioning/scim/group-mapping/ + - /platform/security/provisioning/group-mapping/ + - /platform/security/provisioning/scim/group-mapping/ weight: 20 --- {{< summary-bar feature_name="SSO" >}} -Group mapping automatically synchronizes user groups from your identity provider (IdP) with teams in your Docker organization. For example, when you add a developer to the "backend-team" group in your IdP, they're automatically added to the corresponding team in Docker +Group mapping synchronizes groups from your identity provider (IdP) with teams +in your Docker organization. For example, when you add a developer to the +`moby:backend` group in your IdP, Docker adds them to the `backend` team in the +`moby` organization. -This page explains how group mapping works, and how to set up group mapping. +Use group mapping to manage team membership through SAML SSO, SCIM, or both. > [!TIP] > -> Group mapping is ideal for adding users to multiple organizations or multiple teams within one organization. If you don't need to set up multi-organization or multi-team assignment, SCIM [user-level attributes](provision-scim.md#set-up-role-mapping) may be a better fit for your needs. +> Use group mapping to add users to multiple organizations or teams. To assign +> each user to one organization or team, you can use SCIM +> [user-level attributes](provision-scim.md#set-up-role-mapping). ## Prerequisites @@ -31,25 +40,27 @@ Before you begin, you must have: ## How group mapping works -Group mapping keeps your Docker Teams synchronized with your IdP groups through these key components: +Group mapping uses IdP attributes to keep Docker team membership synchronized: -- Authentication flow: When users sign in through SSO, your IdP shares user attributes with Docker including email, name, and group memberships. -- Automatic updates: Docker uses these attributes to create or update user profiles and manage team assignments based on IdP group changes. -- Unique identification: Docker uses email addresses as unique identifiers, so each Docker account must have a unique email address. -- Team synchronization: Users' team memberships in Docker automatically reflect changes made in your IdP groups. +- With SAML SSO, the IdP sends group membership when a user signs in. +- With SCIM, the IdP synchronizes group membership on its provisioning + schedule. +- Docker identifies users by email address. Each Docker account must have a + unique email address. +- Docker creates teams when a mapped group references a team that doesn't + exist. ## Set up group mapping -Group mapping setup involves configuring your identity provider to share group -information with Docker. This requires: +To configure group mapping: -- Creating groups in your IdP using Docker's naming format -- Configuring attributes so your IdP sends group data during authentication -- Adding users to the appropriate groups -- Testing the connection to ensure groups sync properly +- Create groups in your IdP using Docker's naming format +- Configure your IdP to send group data +- Add users to the groups +- Test that membership synchronizes -You can use group mapping with SSO only, or with both SSO and SCIM for enhanced -user lifecycle management. +You can use group mapping with SAML SSO alone or with SCIM for user lifecycle +management. ### Group naming format @@ -65,11 +76,11 @@ Docker creates teams automatically if they don't already exist when groups sync. ### Supported attributes | Attribute | Description | -|:--------- | :---------- | +| :--- | :--- | | `id` | Unique ID of the group in UUID format. This attribute is read-only. | -| `displayName` | Name of the group following the group mapping format: `organization:team`. | +| `displayName` | Group name in the `organization:team` format. | | `members` | A list of users that are members of this group. | -| `members(x).value` | Unique ID of the user that is a member of this group. Members are referenced by ID. | +| `members(x).value` | Unique ID of a user in the group. | ## Configure group mapping with SSO @@ -77,79 +88,91 @@ Use group mapping with SSO connections that use the SAML authentication method. > [!NOTE] > -> Group mapping with SSO isn't supported with the Azure AD (OIDC) authentication method. SCIM isn't required for these configurations. +> Group mapping through SSO isn't supported with the Microsoft Entra ID OIDC +> authentication method. Use SCIM to synchronize groups for OIDC connections. {{< tabs >}} {{< tab name="Okta" >}} -The user interface for your IdP may differ slightly from the following steps. Refer to the [Okta documentation](https://help.okta.com/oie/en-us/content/topics/apps/define-group-attribute-statements.htm) to verify. +The IdP interface may differ from these steps. For more information, see the +[Okta documentation](https://help.okta.com/oie/en-us/content/topics/apps/define-group-attribute-statements.htm). To set up group mapping: 1. Sign in to Okta and open your application. 1. Navigate to the **SAML Settings** page for your application. -1. In the **Group Attribute Statements (optional)** section, configure like the following: +1. In **Group Attribute Statements (optional)**, configure these values: - **Name**: `groups` - **Name format**: `Unspecified` - - **Filter**: `Starts with` + `organization:` where `organization` is the name of your organization - The filter option will filter out the groups that aren't affiliated with your Docker organization. + - **Filter**: **Starts with** and `organization:`, where `organization` is + your Docker organization name 1. Create your groups by selecting **Directory**, then **Groups**. -1. Add your groups using the format `organization:team` that matches the names of your organization(s) and team(s) in Docker. -1. Assign users to the group(s) that you create. +1. Add groups in the `organization:team` format that match your Docker + organization and team names. +1. Assign users to the groups. -The next time you sync your groups with Docker, your users will map to the Docker groups you defined. +The next time users sign in, Docker maps them to the teams you defined. {{< /tab >}} {{< tab name="Entra ID" >}} -The user interface for your IdP may differ slightly from the following steps. Refer to the [Entra ID documentation](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes) to verify. +The IdP interface may differ from these steps. For more information, see the +[Microsoft Entra ID documentation](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims). To set up group mapping: 1. Sign in to Entra ID and open your application. 1. Select **Manage**, then **Single sign-on**. 1. Select **Add a group claim**. -1. In the Group Claims section, select **Groups assigned to the application** with the source attribute **Cloud-only group display names (Preview)**. +1. In **Group Claims**, select **Groups assigned to the application** with the + source attribute **Cloud-only group display names**. 1. Select **Advanced options**, then the **Filter groups** option. 1. Configure the attribute like the following: - **Attribute to match**: `Display name` - **Match with**: `Contains` - **String**: `:` 1. Select **Save**. -1. Select **Groups**, **All groups**, then **New group** to create your group(s). -1. Assign users to the group(s) that you create. +1. Select **Groups** > **All groups** > **New group** to create your groups. +1. Assign users to the groups. -The next time you sync your groups with Docker, your users will map to the Docker groups you defined. +The next time users sign in, Docker maps them to the teams you defined. {{< /tab >}} {{< /tabs >}} ## Configure group mapping with SCIM -Use group mapping with SCIM for more advanced user lifecycle management. Before you begin, make sure you [set up SCIM](./provision-scim.md#enable-scim) first. +Use group mapping with SCIM to synchronize membership on your IdP's +provisioning schedule. Before you begin, +[set up SCIM](./provision-scim.md#enable-scim-in-docker). {{< tabs >}} {{< tab name="Okta" >}} -The user interface for your IdP may differ slightly from the following steps. Refer to the [Okta documentation](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-enable-group-push.htm) to verify. +The IdP interface may differ from these steps. For more information, see the +[Okta documentation](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-enable-group-push.htm). To set up your groups: 1. Sign in to Okta and open your application. 1. Select **Applications**, then **Provisioning**, and **Integration**. -1. Select **Edit** to enable groups on your connection, then select **Push groups**. -1. Select **Save**. Saving this configuration will add the **Push Groups** tab to your application. +1. Select **Edit**, enable **Push Groups**, then select **Save**. The + **Push Groups** tab appears in your application. 1. Create your groups by navigating to **Directory** and selecting **Groups**. -1. Add your groups using the format `organization:team` that matches the names of your organization(s) and team(s) in Docker. -1. Assign users to the group(s) that you create. -1. Return to the **Integration** page, then select the **Push Groups** tab to open the view where you can control and manage how groups are provisioned. +1. Add groups in the `organization:team` format that match your Docker + organization and team names. +1. Assign users to the groups. +1. Return to **Integration**, then select **Push Groups**. 1. Select **Push Groups**, then **Find groups by rule**. 1. Configure the groups by rule like the following: - - Enter a rule name, for example `Sync groups with Docker Hub` - - Match group by name, for example starts with `docker:` or contains `:` for multi-organization - - If you enable **Immediately push groups by rule**, sync will happen as soon as there's a change to the group or group assignments. Enable this if you don't want to manually push groups. + - Enter a rule name, such as `Sync groups with Docker`. + - Match groups by name. For example, use **Starts with** and `moby:`, or + **Contains** and `:` for multiple organizations. + - To sync after changes to groups or assignments, enable + **Immediately push groups by rule**. -Find your new rule under **By rule** in the **Pushed Groups** column. The groups that match that rule are listed in the groups table on the right-hand side. +Find the rule under **By rule** in the **Pushed Groups** column. Matching groups +appear in the groups table. To push the groups from this table: @@ -160,40 +183,45 @@ To push the groups from this table: {{< /tab >}} {{< tab name="Entra ID" >}} -The user interface for your IdP may differ slightly from the following steps. Refer to the [Entra ID documentation](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes) to verify. - -Complete the following before configuring group mapping: +The IdP interface may differ from these steps. For more information, see the +[Microsoft Entra ID documentation](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups). 1. Sign in to Entra ID and go to your application. 1. In your application, select **Provisioning**, then **Mappings**. 1. Select **Provision Microsoft Entra ID Groups**. -1. Select **Show advanced options**, then **Edit attribute list**. -1. Update the `externalId` type to `reference`, then select the **Multi-Value** checkbox and choose the referenced object attribute `urn:ietf:params:scim:schemas:core:2.0:Group`. -1. Select **Save**, then **Yes** to confirm. -1. Go to **Provisioning**. -1. Toggle **Provision Status** to **On**, then select **Save**. +1. Set **Enabled** to **Yes**. +1. Confirm these attribute mappings: + - `displayName` to `displayName` + - `objectId` to `externalId` + - `members` to `members` +1. Select **Save**. Next, set up group mapping: -1. Go to the application overview page. -1. Under **Provision user accounts**, select **Get started**. +1. Go to **Users and groups**. 1. Select **Add user/group**. -1. Create your group(s) using the `organization:team` format. -1. Assign the group to the provisioning group. -1. Select **Start provisioning** to start the sync. +1. Select groups that use the `organization:team` format. +1. Select **Assign**. +1. Go to **Provisioning** and select **Start provisioning**. -To verify, select **Monitor**, then **Provisioning logs** to see that your groups were provisioned successfully. In your Docker organization, you can check that the groups were correctly provisioned and the members were added to the appropriate teams. +To verify the sync, select **Monitor**, then **Provisioning logs**. In Docker +Home, confirm that members appear in the mapped teams. {{< /tab >}} {{< /tabs >}} -Once complete, a user who signs in to Docker through SSO is automatically added to the organizations and teams mapped in the IdP. +After synchronization, Docker adds users to the organizations and teams mapped +in the IdP. > [!TIP] > -> [Enable SCIM](provision-scim.md) to take advantage of automatic user provisioning and de-provisioning. If you don't enable SCIM users are only automatically provisioned. You have to de-provision them manually. +> [Enable SCIM](provision-scim.md) to provision and deprovision users +> automatically. Group mapping through SSO manages team membership but doesn't +> deprovision users. ## Next steps -- [Assign roles](/manuals/security/roles-and-permissions/core-roles.md) to members of your org. -- [Enforce sign in](/manuals/enterprise/security/enforce-sign-in.md), if needed. +- [Assign roles](/manuals/security/roles-and-permissions/core-roles.md) to + organization members. +- [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in.md) for your + organization. diff --git a/content/manuals/security/provisioning/scim/migrate-scim.md b/content/manuals/security/provisioning/scim/migrate-scim.md index 9a6a52f6337e..266a33924675 100644 --- a/content/manuals/security/provisioning/scim/migrate-scim.md +++ b/content/manuals/security/provisioning/scim/migrate-scim.md @@ -1,43 +1,41 @@ --- title: Migrate JIT to SCIM linkTitle: Migrate -description: Learn how to migrate from just-in-time (JIT) to SCIM. +description: >- + Migrate JIT-provisioned Docker users to SCIM for automated user lifecycle + management and deprovisioning. +keywords: JIT to SCIM migration, SCIM provisioning, user deprovisioning, + identity provider, Docker Home, user lifecycle management weight: 30 aliases: - /platform/security/provisioning/scim/migrate-scim/ --- -If you already have users provisioned through Just-in-Time (JIT) and want to -enable full SCIM lifecycle management, you need to migrate them. Users -originally created by JIT cannot be automatically de-provisioned through SCIM, -even after SCIM is enabled. +{{< summary-bar feature_name="SSO" >}} + +Migrate users created through Just-in-Time (JIT) provisioning so System for +Cross-domain Identity Management (SCIM) can manage their full account +lifecycle. Enabling SCIM doesn't convert existing JIT-provisioned users into +SCIM-managed users. ## Why migrate -Organizations using JIT provisioning may encounter limitations with user -lifecycle management, particularly around de-provisioning. Migrating to SCIM -provides: +Migrating users from JIT to SCIM provides: -- Automatic user de-provisioning when users leave your organization. This is - the primary benefit for large organizations that need full automation. +- Automatic user deprovisioning when users leave your organization - Continuous synchronization of user attributes - Centralized user management through your identity provider -- Enhanced security through automated access control +- Automated access removal > [!IMPORTANT] > -> Users originally created through JIT provisioning cannot be automatically -> de-provisioned by SCIM, even after SCIM is enabled. To enable full lifecycle -> management including automatic de-provisioning through your identity provider, -> you must manually remove these users so SCIM can re-create them with proper -> lifecycle management capabilities. - -This migration is most critical for larger organizations that require fully -automated user de-provisioning when employees leave the company. +> SCIM can't deprovision users originally created through JIT. You must remove +> these users from the Docker organization so SCIM can provision them again as +> SCIM-managed users. ## Prerequisites -Before migrating, ensure you have: +Before migrating, you must have: - SCIM configured and tested in your organization - A maintenance window for the migration @@ -50,29 +48,26 @@ Before migrating, ensure you have: ## Prepare for migration -### Transfer ownership +### Review roles and access -Before removing users, ensure that any repositories, teams, or organization -resources they own are transferred to another administrator or service account. -When a user is removed from the organization, any resources they own may -become inaccessible. +Removing a member revokes their access to the organization's resources and +teams. Record each user's role and team memberships so you can verify access +after SCIM provisions the user again. -1. Review repositories, organization resources, and team ownership for affected - users. -2. Transfer ownership to another administrator. +1. Review the roles and team memberships of affected users. +1. Confirm that the organization has an owner who isn't part of the migration. > [!WARNING] > -> If ownership is not transferred, repositories owned by removed users may -> become inaccessible when the user is removed. Ensure all critical resources -> are transferred before proceeding. +> Don't remove the only organization owner. Assign the Owner role to another +> member before you begin the migration. ### Verify identity provider configuration -1. Confirm all JIT-provisioned users are assigned to the Docker application in - your identity provider. -2. Verify identity provider group to Docker Team mappings are configured and - tested. +1. Confirm that all JIT-provisioned users are assigned to the Docker + application in your identity provider. +1. Verify that identity provider group-to-Docker-team mappings are configured + and tested. Users not assigned to the Docker application in your identity provider are not re-created by SCIM after removal. @@ -83,11 +78,11 @@ Export a list of JIT-provisioned users from Docker Home: 1. Sign in to [Docker Home](https://app.docker.com) and select your organization. -2. Select **Members**. -3. Select **Export members** to download the member list as CSV for backup and - reference. +1. Select **Members**. +1. Select the **Download** icon to start the export. +1. Open the email from Docker and use the link to download the CSV file. -Keep this CSV list of JIT-provisioned users as a rollback reference if needed. +Keep the CSV as a record of the users included in the migration. ## Complete the migration @@ -99,11 +94,13 @@ Keep this CSV list of JIT-provisioned users as a rollback reference if needed. > organization. Do not disable JIT until you have verified SCIM is working > correctly. -1. Sign in to [Docker Home](https://app.docker.com) and select your organization. -2. Select **Identity & auth**, then **SSO and SCIM**. -3. In the SSO connections table, select the **Actions** menu for your connection. -4. Select **Disable JIT provisioning**. -5. Select **Disable** to confirm. +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. +1. Select **Identity & auth**, then **SSO and SCIM**. +1. In the **SSO connections** table, select the **Actions** menu for your + connection. +1. Select **Disable JIT provisioning**. +1. Select **Disable** to confirm. Disabling JIT prevents new users from being automatically added through SSO during the migration. @@ -112,43 +109,39 @@ during the migration. > [!IMPORTANT] > -> Users originally created through JIT provisioning cannot be automatically -> de-provisioned by SCIM, even after SCIM is enabled. To enable full lifecycle -> management including automatic de-provisioning through your identity provider, -> you must manually remove these users so SCIM can re-create them with proper -> lifecycle management capabilities. +> Removing users temporarily interrupts their access. Confirm that SCIM is +> working before you remove them. -This step is most critical for large organizations that require fully automated -user de-provisioning when employees leave the company. - -1. Sign in to [Docker Home](https://app.docker.com) and select your organization. -2. Select **Members**. -3. Identify and remove JIT-provisioned users in manageable batches. -4. Monitor for any errors during removal. +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. +1. Select **Members**. +1. Identify and remove JIT-provisioned users in manageable batches. +1. Monitor for errors during removal. > [!TIP] > -> To efficiently identify JIT users, compare the member list exported before -> SCIM was enabled with the current member list. Users who existed before SCIM -> was enabled were likely provisioned via JIT. +> Use the member export, IdP assignments, and provisioning logs to identify +> JIT-provisioned users. Don't remove users based only on when they joined the +> organization. ### Verify SCIM re-provisioning -After removing JIT users, SCIM automatically re-creates user accounts: +After removing JIT-provisioned users, trigger a synchronization in your IdP, +then verify that SCIM provisions the users again: -1. In your identity provider system log, confirm "create app user" events for - Docker. -2. In Docker Home under **Members**, confirm users reappear with SCIM provisioning. -3. Verify users are added to the correct teams via group mapping. +1. In your identity provider's provisioning logs, confirm successful user + creation events for Docker. +1. In Docker Home under **Members**, confirm that users reappear. +1. Verify that group mapping adds users to the correct teams. ### Validate user access Perform post-migration validation: 1. Select a subset of migrated users to test sign-in and access. -2. Verify team membership matches identity provider group assignments. -3. Confirm repository access is restored. -4. Test that de-provisioning works correctly by removing a test user from your +1. Verify that team membership matches identity provider group assignments. +1. Confirm that repository access is restored. +1. Test deprovisioning by removing a test user from your identity provider. Keep audit exports and logs for compliance purposes. @@ -157,10 +150,9 @@ Keep audit exports and logs for compliance purposes. After completing the migration: -- All users in your organization are SCIM-provisioned -- User de-provisioning works reliably through your identity provider +- Migrated users are SCIM-provisioned +- User deprovisioning works through your identity provider - No new JIT users are created -- Consistent identity lifecycle management is maintained ## Troubleshoot migration issues @@ -168,15 +160,17 @@ If a user fails to reappear after removal: 1. Check that the user is assigned to the Docker application in your identity provider. -2. Verify SCIM is enabled in both Docker and your identity provider. -3. Trigger a manual SCIM sync in your identity provider. -4. Check provisioning logs in your identity provider for errors. +1. Verify SCIM is enabled in both Docker and your identity provider. +1. Trigger a manual SCIM sync in your identity provider. +1. Check provisioning logs in your identity provider for errors. For more troubleshooting guidance, see [Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). ## Next steps -- Set up [Group mapping](/manuals/security/provisioning/scim/group-mapping.md). -- [Assign roles](/manuals/security/roles-and-permissions/core-roles.md) to members of your org. -- [Enforce sign in](/manuals/enterprise/security/enforce-sign-in.md), if needed. +- Set up [group mapping](/manuals/security/provisioning/scim/group-mapping.md). +- [Assign roles](/manuals/security/roles-and-permissions/core-roles.md) to + organization members. +- [Enforce sign-in](/manuals/enterprise/security/enforce-sign-in.md) for your + organization. diff --git a/content/manuals/security/provisioning/scim/provision-scim.md b/content/manuals/security/provisioning/scim/provision-scim.md index 06c2a5496686..03be32284c91 100644 --- a/content/manuals/security/provisioning/scim/provision-scim.md +++ b/content/manuals/security/provisioning/scim/provision-scim.md @@ -1,7 +1,9 @@ --- title: Set up SCIM provisioning -linkTitle: Setup -description: Configure SCIM user provisioning and role mapping for Docker with Okta or Microsoft Entra ID. +linkTitle: Set up +description: >- + Configure SCIM user provisioning and role mapping for Docker with Okta or + Microsoft Entra ID. keywords: SCIM setup, user provisioning, role mapping, Okta, Microsoft Entra ID, identity provider, Docker Home weight: 10 @@ -13,20 +15,19 @@ aliases: ## Supported attributes -SCIM uses attributes (name, email, etc.) to sync user information between your -identity provider and Docker. Properly mapping these attributes in your identity -provider ensures that user provisioning works smoothly and prevents issues like -duplicate user accounts -when using single sign-on. +System for Cross-domain Identity Management (SCIM) uses attributes to sync user +information between your identity provider (IdP) and Docker. Map these +attributes to provision users and prevent duplicate accounts when using single +sign-on (SSO). Docker supports the following SCIM attributes: -| Attribute | Description | -| :---------------- | :-------------------------------------------------------------------------------- | -| `userName` | User's primary email address, used as the unique identifier | -| `name.givenName` | User's first name | -| `name.familyName` | User's surname | -| `active` | Indicates if a user is enabled or disabled, set to "false" to de-provision a user | +| Attribute | Description | +| :--- | :--- | +| `userName` | User's primary email address, used as the unique identifier | +| `name.givenName` | User's first name | +| `name.familyName` | User's surname | +| `active` | Indicates whether a user is enabled. Set to `false` to deprovision a user | For additional details about supported attributes and SCIM, see [Docker Hub API SCIM reference](/reference/api/hub/latest/#tag-scim). @@ -34,7 +35,7 @@ For additional details about supported attributes and SCIM, see > [!IMPORTANT] > > Docker turns on Just-in-Time (JIT) provisioning by default when you configure -> SSO. Before setting up SCIM, decide which method will manage provisioning and +> SSO. Before setting up SCIM, decide which method manages provisioning and > review [how SCIM works with JIT](./_index.md#choose-how-scim-works-with-jit). ## Enable SCIM in Docker @@ -50,20 +51,17 @@ To enable SCIM: ## Enable SCIM in your IdP -The user interface for your identity provider may differ slightly from the -following steps. You can refer to the documentation for your identity provider -to verify. For additional details, see the documentation for your identity -provider: +The IdP interface may differ from these steps. For more information, see your +IdP's documentation: - [Okta](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SCIM.htm) -- [Entra ID/Azure AD SAML 2.0](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/user-provisioning) +- [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/user-provisioning) > [!NOTE] > -> Microsoft does not currently support SCIM and OIDC in the same non-gallery -> application in Entra ID. This page provides a verified workaround using a -> separate non-gallery app for SCIM provisioning. While Microsoft does not -> officially document this setup, it is widely used and supported in practice. +> Microsoft Entra ID doesn't support SCIM and OIDC in the same non-gallery +> application. For OIDC connections, create a separate non-gallery application +> for SCIM provisioning. {{< tabs >}} {{< tab name="Okta" >}} @@ -75,16 +73,15 @@ provider: 1. On the application page, select the **General** tab, then **Edit App Settings**. 1. Enable SCIM provisioning, then select **Save**. -1. Navigate to the **Provisioning**, then select **Edit SCIM Connection**. +1. Select **Provisioning**, then **Edit SCIM Connection**. 1. To configure SCIM in Okta, set up your connection using the following values and settings: - - SCIM Base URL: SCIM connector base URL (copied from Docker Home) - - Unique identifier field for users: `email` - - Supported provisioning actions: **Push New Users** and + - **SCIM connector base URL**: The **SCIM Base URL** from Docker Home + - **Unique identifier field for users**: `email` + - **Supported provisioning actions**: **Push New Users** and **Push Profile Updates** - - Authentication Mode: HTTP Header - - SCIM Bearer Token: HTTP Header Authorization Bearer Token - (copied from Docker Home) + - **Authentication Mode**: **HTTP Header** + - **Authorization**: The **API Token** from Docker Home 1. Select **Test Connector Configuration**. 1. Review the test results and select **Save**. @@ -111,7 +108,7 @@ provisioning. ### Step one: Create a separate SCIM app -1. In the Azure Portal, go to **Microsoft Entra ID** > +1. In the Microsoft Entra admin center, go to **Microsoft Entra ID** > **Enterprise Applications** > **New application**. 1. Select **Create your own application**. 1. Name your application and choose @@ -133,7 +130,7 @@ Next, [set up role mapping](#set-up-role-mapping). {{< /tab >}} {{< tab name="Entra ID (SAML 2.0)" >}} -1. In the Azure Portal, go to **Microsoft Entra ID** > +1. In the Microsoft Entra admin center, go to **Microsoft Entra ID** > **Enterprise Applications**, and select your Docker SAML app. 1. Select **Provisioning** > **Get started**. 1. Set **Provisioning Mode** to **Automatic**. @@ -150,8 +147,9 @@ Next, [set up role mapping](#set-up-role-mapping). ## Set up role mapping -You can assign [Docker roles](/manuals/security/roles-and-permissions/_index.md) to -users by adding optional SCIM attributes in your IdP. These attributes override +You can assign +[Docker roles](/manuals/security/roles-and-permissions/core-roles.md) to users +by adding optional SCIM attributes in your IdP. These attributes override default role and team values set in your SSO configuration. > [!NOTE] @@ -162,21 +160,23 @@ default role and team values set in your SSO configuration. The following table lists the supported optional user-level attributes: -| Attribute | Possible values | Notes | -| ------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `dockerRole` | `member`, `editor`, or `owner` | If not set, the user defaults to the `member` role. Setting this attribute overrides the default.

For role definitions, see [Roles and permissions](/manuals/security/roles-and-permissions/_index.md). | -| `dockerOrg` | Docker `organizationName` (e.g., `moby`) | Overrides the default organization configured in your SSO connection.

If unset, the user is provisioned to the default organization. If `dockerOrg` and `dockerTeam` are both set, the user is provisioned to the team within the specified organization. | -| `dockerTeam` | Docker `teamName` (e.g., `developers`) | Provisions the user to the specified team in the default or specified organization. If the team doesn't exist, it is automatically created.

You can still use [group mapping](group-mapping.md) to assign users to multiple teams across organizations. | +| Attribute | Possible values | Notes | +| :--- | :--- | :--- | +| `dockerRole` | `member`, `editor`, or `owner` | Overrides the default role. If unset, the user has the `member` role | +| `dockerOrg` | Docker organization name, such as `moby` | Overrides the default organization. If `dockerOrg` and `dockerTeam` are set, the user is provisioned to the team in this organization | +| `dockerTeam` | Docker team name, such as `developers` | Provisions the user to the team in the default or specified organization. Docker creates the team if it doesn't exist. You can also use [group mapping](group-mapping.md) to assign users to multiple teams or organizations | -The external namespace used for these attributes is: `urn:ietf:params:scim:schemas:extension:docker:2.0:User`. -This value is required in your identity provider when creating custom SCIM attributes for Docker. +The external namespace for these attributes is +`urn:ietf:params:scim:schemas:extension:docker:2.0:User`. Enter this value when +you create custom SCIM attributes for Docker in your IdP. {{< tabs >}} {{< tab name="Okta" >}} ### Step one: Set up role mapping in Okta -1. Setup [SSO](/manuals/security/authentication/single-sign-on/connect.md) and SCIM first. +1. Set up [SSO](/manuals/security/authentication/single-sign-on/connect.md) and + SCIM. 1. In the Okta admin portal, go to **Directory**, select **Profile Editor**, and then **User (Default)**. 1. Select **Add Attribute** and configure the values for the role, organization, @@ -185,14 +185,15 @@ This value is required in your identity provider when creating custom SCIM attri 1. Select **Add Attribute** and enter the required values. The **External Name** and **External Namespace** must be exact. - The external name values for organization/team/role mapping are - `dockerOrg`, `dockerTeam`, and `dockerRole` respectively, as listed in the previous table. + `dockerOrg`, `dockerTeam`, and `dockerRole`, as listed in the previous + table. - The external namespace is the same for all of them: `urn:ietf:params:scim:schemas:extension:docker:2.0:User`. 1. After creating the attributes, navigate to the top of the page and select **Mappings**, then **Okta User to YOUR APP**. 1. Go to the newly created attributes and map the variable names to the external - names, then select **Save Mappings**. If you're using JIT provisioning, continue - to the following steps. + names, then select **Save Mappings**. If you're using JIT provisioning, + continue to the following steps. 1. Navigate to **Applications** and select **YOUR APP**. 1. Select **General**, then **SAML Settings**, and **Edit**. 1. Select **Step 2** and configure the mapping from the user attribute to the @@ -215,22 +216,22 @@ If a user doesn't already have attributes set up, users who are added to the group will inherit these attributes upon provisioning. {{< /tab >}} -{{< tab name="Entra ID/Azure AD (SAML 2.0 and OIDC)" >}} +{{< tab name="Entra ID (SAML 2.0 and OIDC)" >}} ### Step one: Configure attribute mappings 1. Complete the [SCIM provisioning setup](/manuals/security/provisioning/scim/provision-scim.md#enable-scim-in-docker). -1. In the Azure Portal, open **Microsoft Entra ID** > +1. In the Microsoft Entra admin center, open **Microsoft Entra ID** > **Enterprise Applications**, and select your SCIM application. 1. Go to **Provisioning** > **Mappings** > - **Provision Azure Active Directory Users**. + **Provision Microsoft Entra ID Users**. 1. Add or update the following mappings: - `userPrincipalName` -> `userName` - `mail` -> `emails.value` - Optional. Map `dockerRole`, `dockerOrg`, or `dockerTeam` using one of the [mapping methods](/manuals/security/provisioning/scim/provision-scim.md#set-up-role-mapping). 1. Remove any unsupported attributes to prevent sync errors. -1. Optional. Go to **Mappings** > **Provision Azure Active Directory Groups**: +1. Optional. Go to **Mappings** > **Provision Microsoft Entra ID Groups**: - If group provisioning causes errors, set **Enabled** to **No**. - If enabling, test group mappings carefully. 1. Select **Save** to apply mappings. @@ -248,8 +249,9 @@ or `owner`. 1. In the **Edit Attribute** view, set the mapping type to **Expression**. 1. In the **Expression** field: 1. If your App Roles match Docker roles exactly, use: - SingleAppRoleAssignment([appRoleAssignments]) - 1. If they don't match, use a switch expression: `Switch(SingleAppRoleAssignment([appRoleAssignments]), "My Corp Admins", "owner", "My Corp Editors", "editor", "My Corp Users", "member")` + `SingleAppRoleAssignment([appRoleAssignments])` + 1. If they don't match, use a switch expression: + `Switch(SingleAppRoleAssignment([appRoleAssignments]), "My Corp Admins", "owner", "My Corp Editors", "editor", "My Corp Users", "member")` 1. Set: - **Target attribute**: `urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerRole` - **Match objects using this attribute**: No @@ -278,7 +280,7 @@ Use this method if you need to map multiple attributes (`dockerRole` + - Set **Apply this mapping** to **Always**. 1. Save your changes. -To assign values, you'll need to use the Microsoft Graph API. +Assign extension attribute values with Microsoft Graph. ### Step three: Assign users and groups @@ -305,15 +307,19 @@ PATCH https://graph.microsoft.com/v1.0/users/{user-id} Content-Type: application/json { - "extensionAttribute1": "owner", - "extensionAttribute2": "moby", - "extensionAttribute3": "developers" + "onPremisesExtensionAttributes": { + "extensionAttribute1": "owner", + "extensionAttribute2": "moby", + "extensionAttribute3": "developers" + } } ``` > [!NOTE] > -> You must use a different extension attribute for each SCIM field. +> You must use a different extension attribute for each SCIM field. Microsoft +> Graph can update these attributes for cloud-only users that haven't +> previously been synchronized from an on-premises directory. {{< /tab >}} {{< /tabs >}} @@ -321,7 +327,7 @@ Content-Type: application/json See the documentation for your IdP for additional details: - [Okta](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-add-custom-user-attributes.htm) -- [Entra ID/Azure AD](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes#provisioning-a-custom-extension-attribute-to-a-scim-compliant-application) +- [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes#provisioning-a-custom-extension-attribute-to-a-scim-compliant-application) ## Test SCIM provisioning @@ -339,10 +345,10 @@ After completing role mapping, you can test the configuration manually. confirm SCIM settings in the app. {{< /tab >}} -{{< tab name="Entra ID/Azure AD (OIDC and SAML 2.0)" >}} +{{< tab name="Entra ID (OIDC and SAML 2.0)" >}} -1. In the Azure Portal, go to **Microsoft Entra ID** > **Enterprise Applications**, - and select your SCIM app. +1. In the Microsoft Entra admin center, go to **Microsoft Entra ID** > + **Enterprise Applications**, and select your SCIM app. 1. Go to **Provisioning** > **Provision on demand**. 1. Select a user or group and choose **Provision**. 1. Confirm that the user appears in the Docker @@ -354,10 +360,9 @@ After completing role mapping, you can test the configuration manually. ## Disable SCIM -If SCIM is disabled, any user provisioned through SCIM will remain in the -organization. Future changes for your users will not sync from your IdP. -User de-provisioning is only possible when manually removing the user from the -organization. +When you disable SCIM, users provisioned through SCIM remain in the +organization, but changes from your IdP stop syncing. To deprovision these +users, remove them manually from the organization. To disable SCIM: From 854f1c57c0c698137dcb0764282b9b711677e788 Mon Sep 17 00:00:00 2001 From: Alexa Date: Wed, 30 Sep 2026 16:07:12 -0500 Subject: [PATCH 5/6] docs: correct how SCIM manages existing users The provisioning docs said SCIM could not manage or deprovision users created through JIT or added manually, and they attributed removal and attribute conflicts to the wrong mechanism. Describe SCIM as able to link and deprovision members whose email domain is verified on the SSO connection, correct deactivation and team-sync behavior, and align the JIT and SCIM toggle steps with the UI. Co-authored-by: Cursor --- content/manuals/faqs/security.md | 31 +-- .../authentication/single-sign-on/manage.md | 2 +- .../manuals/security/provisioning/_index.md | 2 +- .../security/provisioning/scim/_index.md | 62 ++++-- .../provisioning/scim/migrate-scim.md | 194 +++++++----------- .../provisioning/scim/provision-scim.md | 25 ++- .../provisioning/troubleshoot-provisioning.md | 115 ++++++----- 7 files changed, 211 insertions(+), 220 deletions(-) diff --git a/content/manuals/faqs/security.md b/content/manuals/faqs/security.md index 87e4964b2f65..31faee161291 100644 --- a/content/manuals/faqs/security.md +++ b/content/manuals/faqs/security.md @@ -109,10 +109,10 @@ connection. You can turn off JIT after you configure and test SCIM. See ### Can I use JIT and SCIM together? Yes, but Docker recommends using one provisioning source. When both are -enabled, JIT applies attributes during sign-in and SCIM applies attributes on -its synchronization schedule. Review -[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit) -before enabling both. +enabled, sign-in and SCIM sync can each change a user's full name and team +memberships, so those values can move back and forth. Before you enable both, +review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit). ### How can I give a user immediate access with SCIM? @@ -122,9 +122,10 @@ provisioning without enabling JIT. ### Do I need to manually add users to my organization? -Not when JIT, SCIM, or auto-provisioning is configured for the user. If you -turn off JIT without configuring SCIM, users must already be organization -members or have pending invitations before they sign in through SSO. +Not when JIT, SCIM, or auto-provisioning covers the user. If none of those +methods applies, for example when JIT is turned off and the user isn't +assigned to the Docker application in your IdP, an organization owner must +invite the user. ### Can users use different email addresses to authenticate through SSO? @@ -159,7 +160,10 @@ and group synchronization, including automatic deprovisioning. ### How does turning off Just-in-Time provisioning affect user sign-in? -When JIT is turned off (available with SCIM in Docker Home), users must be organization members or have pending invitations to access Docker. Users who don't meet these criteria get an "Access denied" error and need administrator invitations. +You can turn off JIT only while SCIM is enabled. With JIT turned off, users +must already be members, have a pending invitation, or be provisioned through +SCIM. Users who don't meet these criteria get an "Access denied" error and +need an administrator to invite them. See [SSO authentication with JIT provisioning disabled](/manuals/security/provisioning/just-in-time.md#sso-authentication-with-jit-provisioning-disabled). @@ -172,10 +176,13 @@ method, an organization owner must invite the user. ### What happens to existing licensed users when SCIM is turned on? -Turning on SCIM doesn't convert existing manually or JIT-provisioned users into -SCIM-managed users. They retain their access and roles until you migrate or -remove them. To move JIT-provisioned users under SCIM lifecycle management, -see [Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md). +SCIM can manage and deprovision organization members whose email domain is +verified on the SSO connection, including users created through JIT or added +manually. When your IdP pushes a user with a matching email address, SCIM +links the existing Docker account. Members whose email domain isn't verified +on the connection stay outside SCIM. To use SCIM as the only provisioning +source, see +[Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md). ### Is user information visible in Docker Hub? diff --git a/content/manuals/security/authentication/single-sign-on/manage.md b/content/manuals/security/authentication/single-sign-on/manage.md index c931de7b1030..ff0d480aa292 100644 --- a/content/manuals/security/authentication/single-sign-on/manage.md +++ b/content/manuals/security/authentication/single-sign-on/manage.md @@ -106,7 +106,7 @@ Docker supports the following provisioning methods: when they sign in via SSO - SCIM provisioning: Sync users and groups from your identity provider to Docker - Group mapping: Sync user groups from your identity provider with teams in your Docker organization -- Manual provisioning: Turn off automatic provisioning and manually invite users +- Manual invitations: Invite users directly. You can turn off JIT only after you enable SCIM. For more information on provisioning methods, see [Provision users](/manuals/security/provisioning/_index.md). diff --git a/content/manuals/security/provisioning/_index.md b/content/manuals/security/provisioning/_index.md index a2457611cd37..4a105528e618 100644 --- a/content/manuals/security/provisioning/_index.md +++ b/content/manuals/security/provisioning/_index.md @@ -47,7 +47,7 @@ methods: | :--- | :--- | :--- | :--- | | [System for Cross-domain Identity Management (SCIM)](/manuals/security/provisioning/scim/_index.md) | On the IdP's synchronization schedule or through Provision on Demand | Creates and updates users, synchronizes configured groups, and deprovisions users | Disabled | | [Just-in-Time (JIT)](/manuals/security/provisioning/just-in-time.md) | When a user signs in through SSO | Creates users and applies attributes from the SSO assertion. It doesn't deprovision users | Enabled when you configure SSO | -| [Auto-provisioning](/manuals/security/provisioning/auto-provisioning.md) | When an existing Docker user signs in with an email address from a verified domain | Adds the user to the organization. It doesn't create or deprovision accounts | Disabled | +| [Auto-provisioning](/manuals/security/provisioning/auto-provisioning.md) | When an existing Docker user signs in or verifies their email, and that address uses a verified domain | Adds the user to the organization. It doesn't create or deprovision accounts | Disabled | [Group mapping](/manuals/security/provisioning/scim/group-mapping.md) assigns users to Docker organizations and teams. Use it with SAML SSO or SCIM. You can diff --git a/content/manuals/security/provisioning/scim/_index.md b/content/manuals/security/provisioning/scim/_index.md index ddf650296e0f..54937b49aa0b 100644 --- a/content/manuals/security/provisioning/scim/_index.md +++ b/content/manuals/security/provisioning/scim/_index.md @@ -35,21 +35,24 @@ syncs profile updates from the identity provider, such as name changes, and reactivates users who are reassigned to the application. If group mapping is configured, SCIM also synchronizes groups. -When a user is removed from the Docker application, SCIM deactivates and -removes them from your Docker organization. +When a user is no longer assigned to the Docker application in the IdP, +SCIM deactivates the Docker account. SCIM automates: - Creating users - Updating user profiles -- Removing and deactivating users +- Deactivating users - Reactivating users - Synchronizing groups when group mapping is configured > [!NOTE] > -> Enabling SCIM doesn't convert manually added users into SCIM-managed users. -> SCIM only provides full lifecycle management for users it provisions. +> After you enable SCIM, it can manage and deprovision any organization member +> whose email domain is verified on the SSO connection. That includes users +> created through JIT or added manually. When your IdP pushes a user with a +> matching email address, SCIM links the existing Docker account. Members +> whose email domain isn't verified on the connection stay outside SCIM. ## Choose how SCIM works with JIT @@ -74,28 +77,43 @@ Configure and test SCIM before you ### Use SCIM with JIT -JIT and SCIM run independently: +JIT and SCIM run independently. While JIT is on, you still assign users to +the Docker application and maintain group mappings in your IdP. -- JIT reads the SSO assertion and applies its values when a user signs in. -- SCIM reads users, attributes, and group membership from the IdP on its - synchronization schedule. +Two values can change back and forth when both are enabled: -When both are enabled, values applied during sign-in can overwrite values that -SCIM set. A JIT-provisioned user who isn't in the SCIM-mapped IdP group can -also be removed from the Docker organization during the next SCIM -synchronization. +- Full name. Each SSO sign-in writes the name from the SSO assertion to the + Docker account. If SCIM set a different name, for example the IdP profile + says "Jon Smith" but the assertion sends "Jonathan Smith", sign-in replaces + the SCIM value. The next SCIM sync can set it back. +- Team membership. At sign-in, JIT reads the `groups` or `dockerTeam` value + from the SSO assertion and adds the user to those teams. It never removes + teams. SCIM group sync makes each mapped `organization:team` group's + membership match the IdP group exactly. If JIT added a user to a team that + the IdP group doesn't include, the next sync of that group removes the + user from the team, and the next sign-in adds them back. + +Roles don't move back and forth. JIT sets the organization role only when it +first adds the user. A later SCIM update can change that role, and the next +sign-in leaves the SCIM role in place. + +When a user isn't assigned to the Docker application in the IdP, the next +synchronization deactivates the Docker account. Removing a user from a mapped +`organization:team` group removes that user from the team only. If you keep both enabled: - Match each user's email address exactly between the SSO assertion and SCIM. -- Add every user who can be provisioned through JIT to the SCIM-mapped group. -- Keep roles, organizations, teams, and group membership consistent in the - IdP. -- Monitor users and assignments for changes after sign-in and SCIM - synchronization. - -Keeping a JIT-provisioned user in the mapped group doesn't convert the account -to SCIM lifecycle management. To let SCIM manage the account, follow +- Assign every user who can sign in through SSO to the Docker application in + the IdP. +- Keep the IdP authoritative for roles, organizations, teams, and group + membership. +- After sign-in and after each SCIM synchronization, confirm that full names + and team memberships still match the IdP. + +SCIM links an existing account, including one created through JIT or added +manually, when the IdP pushes a user with a matching email address. To use +SCIM as the only provisioning source, see [Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md). ## Next steps @@ -103,7 +121,7 @@ to SCIM lifecycle management. To let SCIM manage the account, follow - [Set up SCIM provisioning](/manuals/security/provisioning/scim/provision-scim.md) to enable SCIM in Docker and your identity provider. - [Migrate JIT to SCIM](/manuals/security/provisioning/scim/migrate-scim.md) - if users were provisioned with Just-in-Time (JIT) before you enabled SCIM. + to turn off JIT after SCIM is managing your users. - [Group mapping](/manuals/security/provisioning/scim/group-mapping.md) to sync identity provider groups with Docker teams. - [Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md) diff --git a/content/manuals/security/provisioning/scim/migrate-scim.md b/content/manuals/security/provisioning/scim/migrate-scim.md index 266a33924675..2d820429ef28 100644 --- a/content/manuals/security/provisioning/scim/migrate-scim.md +++ b/content/manuals/security/provisioning/scim/migrate-scim.md @@ -2,8 +2,8 @@ title: Migrate JIT to SCIM linkTitle: Migrate description: >- - Migrate JIT-provisioned Docker users to SCIM for automated user lifecycle - management and deprovisioning. + Move from Just-in-Time provisioning to SCIM so your identity provider + manages Docker user lifecycle. keywords: JIT to SCIM migration, SCIM provisioning, user deprovisioning, identity provider, Docker Home, user lifecycle management weight: 30 @@ -13,159 +13,111 @@ aliases: {{< summary-bar feature_name="SSO" >}} -Migrate users created through Just-in-Time (JIT) provisioning so System for -Cross-domain Identity Management (SCIM) can manage their full account -lifecycle. Enabling SCIM doesn't convert existing JIT-provisioned users into -SCIM-managed users. +Move from Just-in-Time (JIT) provisioning to System for Cross-domain Identity +Management (SCIM) as the only source of user provisioning. After SCIM is +enabled, it can manage organization members whose email domain is verified on +the SSO connection, including users created through JIT. When your identity +provider (IdP) pushes a user with a matching email address, SCIM links the +existing Docker account. ## Why migrate -Migrating users from JIT to SCIM provides: +With JIT turned off, your identity provider stays authoritative for who has +access: -- Automatic user deprovisioning when users leave your organization -- Continuous synchronization of user attributes -- Centralized user management through your identity provider -- Automated access removal +- Users are deprovisioned when they leave your organization +- User attributes and group membership stay synchronized with the IdP -> [!IMPORTANT] -> -> SCIM can't deprovision users originally created through JIT. You must remove -> these users from the Docker organization so SCIM can provision them again as -> SCIM-managed users. +Docker recommends SCIM with JIT turned off. If your IdP supports Provision +on Demand, use it when a user needs access before the next scheduled +synchronization. ## Prerequisites -Before migrating, you must have: - -- SCIM configured and tested in your organization -- A maintenance window for the migration - -> [!WARNING] -> -> This migration temporarily disrupts user access. Plan to perform this -> migration during a low-usage window and communicate the timeline to affected -> users. - -## Prepare for migration - -### Review roles and access +Before you migrate: -Removing a member revokes their access to the organization's resources and -teams. Record each user's role and team memberships so you can verify access -after SCIM provisions the user again. +- [Set up and test SCIM](provision-scim.md) in Docker and your IdP. +- Confirm each user's email address matches exactly between the IdP and + Docker. +- In the IdP, set the group memberships and any `dockerRole` values you want + to keep. -1. Review the roles and team memberships of affected users. -1. Confirm that the organization has an owner who isn't part of the migration. +## Assign users in your IdP -> [!WARNING] -> -> Don't remove the only organization owner. Assign the Owner role to another -> member before you begin the migration. +1. Assign every user who should belong to the Docker organization to the + Docker application in your IdP. +1. Confirm that group-to-team mappings are configured and tested. See + [Group mapping](group-mapping.md). -### Verify identity provider configuration +When a user isn't assigned to the Docker application, the next +synchronization deactivates the Docker account. -1. Confirm that all JIT-provisioned users are assigned to the Docker - application in your identity provider. -1. Verify that identity provider group-to-Docker-team mappings are configured - and tested. +## Sync and verify -Users not assigned to the Docker application in your identity provider are not -re-created by SCIM after removal. +Trigger a synchronization, or use Provision on Demand, so SCIM links the +existing accounts. -### Export user records +1. In your IdP's provisioning logs, confirm that provisioning succeeded for + those users. +1. In [Docker Home](https://app.docker.com), select your organization, then + **Members**. +1. Confirm that the users are still members and that their roles and teams + match the IdP. -Export a list of JIT-provisioned users from Docker Home: +To compare the Docker member list with the IdP, export it: -1. Sign in to [Docker Home](https://app.docker.com) and select your - organization. -1. Select **Members**. -1. Select the **Download** icon to start the export. -1. Open the email from Docker and use the link to download the CSV file. +1. On the **Members** page, select **Export members**. +1. The CSV downloads immediately, or Docker emails you a link to download it. -Keep the CSV as a record of the users included in the migration. +## Disable JIT provisioning -## Complete the migration +Turn off JIT after you have verified the linked accounts. You can turn off +JIT only while SCIM is enabled. -### Disable JIT provisioning - -> [!IMPORTANT] -> -> Before disabling JIT, ensure SCIM is fully configured and tested in your -> organization. Do not disable JIT until you have verified SCIM is working -> correctly. - -1. Sign in to [Docker Home](https://app.docker.com) and select your - organization. +1. Go to [Docker Home](https://app.docker.com/) and select your organization + from the top-left account drop-down. 1. Select **Identity & auth**, then **SSO and SCIM**. -1. In the **SSO connections** table, select the **Actions** menu for your - connection. -1. Select **Disable JIT provisioning**. +1. In the **SSO connections** table, select the **Action** icon, then select + **Disable JIT provisioning**. 1. Select **Disable** to confirm. -Disabling JIT prevents new users from being automatically added through SSO -during the migration. - -### Remove JIT-origin users - -> [!IMPORTANT] -> -> Removing users temporarily interrupts their access. Confirm that SCIM is -> working before you remove them. - -1. Sign in to [Docker Home](https://app.docker.com) and select your - organization. -1. Select **Members**. -1. Identify and remove JIT-provisioned users in manageable batches. -1. Monitor for errors during removal. - -> [!TIP] -> -> Use the member export, IdP assignments, and provisioning logs to identify -> JIT-provisioned users. Don't remove users based only on when they joined the -> organization. +With JIT turned off, users must already be members, have a pending +invitation, or be provisioned through SCIM. -### Verify SCIM re-provisioning +## Resolve an unlinked account -After removing JIT-provisioned users, trigger a synchronization in your IdP, -then verify that SCIM provisions the users again: +Members whose email domain isn't verified on the SSO connection stay outside +SCIM. A different email address in the IdP also leaves the existing Docker +account unlinked. -1. In your identity provider's provisioning logs, confirm successful user - creation events for Docker. -1. In Docker Home under **Members**, confirm that users reappear. -1. Verify that group mapping adds users to the correct teams. +1. Compare the email address in the IdP with the Docker account. +1. Confirm that the user's email domain is verified on the SSO connection. +1. Assign the user to the Docker application and run provisioning again. +1. Confirm the user under **Members**. -### Validate user access +If the account is still unlinked, remove that user so SCIM can provision +them again. -Perform post-migration validation: +> [!WARNING] +> +> Removing a user removes their resource ownership, such as repositories. +> Transfer ownership before you remove the user. Don't remove the only +> organization owner. Assign the Owner role to another member first. -1. Select a subset of migrated users to test sign-in and access. -1. Verify that team membership matches identity provider group assignments. -1. Confirm that repository access is restored. -1. Test deprovisioning by removing a test user from your - identity provider. +1. In Docker Home, select **Members** and remove the user. +1. Trigger provisioning from your IdP. +1. Confirm that the user reappears with the expected role and teams. -Keep audit exports and logs for compliance purposes. +For more troubleshooting guidance, see +[Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). ## Migration results -After completing the migration: - -- Migrated users are SCIM-provisioned -- User deprovisioning works through your identity provider -- No new JIT users are created - -## Troubleshoot migration issues - -If a user fails to reappear after removal: +After you turn off JIT: -1. Check that the user is assigned to the Docker application in your identity - provider. -1. Verify SCIM is enabled in both Docker and your identity provider. -1. Trigger a manual SCIM sync in your identity provider. -1. Check provisioning logs in your identity provider for errors. - -For more troubleshooting guidance, see -[Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). +- SCIM manages linked users, including users originally created through JIT +- Your IdP deprovisions users by deactivating their Docker accounts +- Sign-in no longer adds users through JIT ## Next steps diff --git a/content/manuals/security/provisioning/scim/provision-scim.md b/content/manuals/security/provisioning/scim/provision-scim.md index 03be32284c91..e4d9411dd6bb 100644 --- a/content/manuals/security/provisioning/scim/provision-scim.md +++ b/content/manuals/security/provisioning/scim/provision-scim.md @@ -25,6 +25,7 @@ Docker supports the following SCIM attributes: | Attribute | Description | | :--- | :--- | | `userName` | User's primary email address, used as the unique identifier | +| `externalId` | Identifier for the user in your IdP. Docker stores the value | | `name.givenName` | User's first name | | `name.familyName` | User's surname | | `active` | Indicates whether a user is enabled. Set to `false` to deprovision a user | @@ -45,9 +46,13 @@ To enable SCIM: 1. Sign in to [Docker Home](https://app.docker.com). 1. Select **Identity & auth**, then **SSO and SCIM**. 1. In the **SSO connections** table, select the **Actions** icon for your - connection, then select **Setup SCIM**. -1. Copy the **SCIM Base URL** and **API Token** and paste the values into your - IdP. + connection, then select **Enable SCIM**. +1. In the **Enable SCIM provisioning** dialog, select **Enable**. +1. Copy the **SCIM Base URL** and **API Token**, then paste the values into + your IdP. + +To view the **SCIM Base URL** and **API Token** again, select the **Actions** +icon, then **Edit SCIM**. ## Enable SCIM in your IdP @@ -164,7 +169,7 @@ The following table lists the supported optional user-level attributes: | :--- | :--- | :--- | | `dockerRole` | `member`, `editor`, or `owner` | Overrides the default role. If unset, the user has the `member` role | | `dockerOrg` | Docker organization name, such as `moby` | Overrides the default organization. If `dockerOrg` and `dockerTeam` are set, the user is provisioned to the team in this organization | -| `dockerTeam` | Docker team name, such as `developers` | Provisions the user to the team in the default or specified organization. Docker creates the team if it doesn't exist. You can also use [group mapping](group-mapping.md) to assign users to multiple teams or organizations | +| `dockerTeam` | Docker Team name, such as `developers` | Provisions the user to the team in the default or specified organization. Docker creates the team if it doesn't exist. You can also use [group mapping](group-mapping.md) to assign users to multiple teams or organizations | The external namespace for these attributes is `urn:ietf:params:scim:schemas:extension:docker:2.0:User`. Enter this value when @@ -360,16 +365,18 @@ After completing role mapping, you can test the configuration manually. ## Disable SCIM -When you disable SCIM, users provisioned through SCIM remain in the -organization, but changes from your IdP stop syncing. To deprovision these -users, remove them manually from the organization. - -To disable SCIM: +You can disable SCIM only while JIT provisioning is turned on. When SCIM is +off, users remain in the organization, but changes from your IdP stop +syncing. To deprovision these users, remove them manually from the +organization. 1. Sign in to [Docker Home](https://app.docker.com). 1. Select **Identity & auth**, then **SSO and SCIM**. 1. In the **SSO connections** table, select the **Actions** icon. +1. If JIT is off, select **Enable JIT provisioning**, then **Enable**. Open + the **Actions** menu again. 1. Select **Disable SCIM**. +1. Select **Disable** to confirm. ## Next steps diff --git a/content/manuals/security/provisioning/troubleshoot-provisioning.md b/content/manuals/security/provisioning/troubleshoot-provisioning.md index 585e4a6dc23b..cca3cdd7e19b 100644 --- a/content/manuals/security/provisioning/troubleshoot-provisioning.md +++ b/content/manuals/security/provisioning/troubleshoot-provisioning.md @@ -12,100 +12,107 @@ aliases: This page helps troubleshoot common user provisioning issues including user roles, attributes, and unexpected account behavior with SCIM and Just-in-Time (JIT) provisioning. -## SCIM attribute values are overwritten or ignored +## Full name or team membership changes after sign-in ### Error message This scenario doesn't usually produce an error message in Docker or your IdP. -A role or team assignment may be incorrect or may revert after the user signs -in or SCIM synchronizes. +A user's full name changes after they sign in, or a team membership +disappears after a SCIM sync and comes back the next time they sign in. ### Causes -- JIT provisioning is enabled, and Docker is using values from your IdP's - SSO sign in flow to provision the user, which overrides - SCIM-provided attributes. -- SCIM was enabled after the user was already provisioned via JIT, so SCIM - updates don't take effect. +JIT and SCIM are both enabled: + +- Each SSO sign-in writes the full name from the SSO assertion to the Docker + account, replacing a name that SCIM set. The next SCIM sync can set it + back. +- At sign-in, JIT adds the user to the teams the SSO assertion lists. SCIM + group sync makes each mapped `organization:team` group's membership match + the IdP group exactly. If the IdP group doesn't include the user, the next + sync removes the team JIT added, and the next sign-in adds it back. + +Roles aren't affected. JIT sets the organization role only when it first adds +the user. A later SCIM update can change that role, and the next sign-in +leaves the SCIM role in place. ### Affected environments -- Docker organizations using SCIM with SSO -- Users provisioned via JIT prior to SCIM setup +Docker organizations that use SCIM while JIT is still enabled. ### Steps to replicate -1. Enable JIT and SSO for your Docker organization. -1. Sign in to Docker as a user via SSO. -1. Enable SCIM and set role/team attributes for that user. -1. SCIM attempts to update the user's attributes, but the role or team - assignment does not reflect changes. +1. Enable SSO for your Docker organization. JIT is turned on by default. +1. Sign in through SSO with a user whose assertion includes a team. +1. Enable SCIM and synchronize groups that don't include that team. +1. The team membership from sign-in is removed. Signing in again adds it + back. ### Solutions -#### Disable JIT provisioning (recommended) +#### Turn off JIT provisioning (recommended) -1. Sign in to [Docker Home](https://app.docker.com/). -1. Select **Identity & auth**, then **SSO and SCIM**. -1. Find the relevant SSO connection. -1. Select the **actions menu** and choose **Edit**. -1. Disable **Just-in-Time provisioning**. -1. Save your changes. +You can turn off JIT only while SCIM is enabled. Follow +[Disable JIT provisioning](/manuals/security/provisioning/just-in-time.md#disable-jit-provisioning). -With JIT disabled, Docker uses SCIM as the source of truth for user creation -and role assignment. +With JIT turned off, SCIM is the source for user creation, profile updates, +and group membership. -**Keep JIT enabled and match attributes** +#### Keep JIT enabled -If you prefer to keep JIT enabled: +If you keep JIT enabled: -- Make sure your IdP's SSO attribute mappings match the values being sent - by SCIM. -- Avoid configuring SCIM to override attributes already set via JIT. +- Match each user's email address exactly between the SSO assertion and SCIM. +- Send the same team memberships in the SSO assertion that SCIM group mapping + synchronizes. +- Expect each sign-in to update the full name from the SSO assertion. -This option requires strict coordination between SSO and SCIM attributes -in your IdP configuration. +While JIT is on, you still assign users to the Docker application and +maintain group mappings in your IdP. Review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit) +before you keep both enabled. -## JIT-provisioned user is removed after a SCIM sync +## User is deactivated after a SCIM sync ### Cause -JIT and SCIM are both enabled, and the user isn't in the IdP group that SCIM -maps to the Docker organization. SCIM treats the mapped group as the -organization roster and removes the user's organization membership during -synchronization. +The user isn't assigned to the Docker application in the IdP. On the next +synchronization, Docker deactivates the Docker account. Removing the user +from a mapped `organization:team` group removes that user from the team only. ### Solution -If you keep both methods enabled: - -1. Add every user who can be provisioned through JIT to the SCIM-mapped group. -1. Make sure each user's email address matches exactly between the SSO - assertion and SCIM. +1. Assign the user to the Docker application in your IdP. +1. Match the user's email address exactly between the SSO assertion and SCIM. 1. Trigger a SCIM synchronization in your IdP. -1. Confirm that the user belongs to the expected organization and teams. +1. Confirm that the account is active and that the user belongs to the + expected teams. -To avoid coordinating two provisioning sources, use SCIM without JIT. Review +To use one provisioning source, turn off JIT after SCIM is working. You can +turn off JIT only while SCIM is enabled. Review [how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit) -before changing the configuration. +before you change the configuration. ## SCIM updates don't apply to existing users -### Causes +### Cause -User accounts were originally created manually or via JIT, and SCIM is not -linked to manage them. +SCIM can update any organization member whose email domain is verified on the +SSO connection, including users created through JIT or added manually. The +Docker account stays unchanged when that domain isn't verified on the +connection, or when the email address in the IdP differs from the account. ### Solution -SCIM only manages users that it provisions. To allow SCIM to manage an -existing user: +1. Confirm that the user's email domain is verified on the SSO connection. +1. Match the email address in the IdP to the Docker account. +1. Assign the user to the Docker application and trigger provisioning. +1. In [Docker Home](https://app.docker.com), open **Members** and confirm the + user. -1. Remove the user manually from [Docker Home](https://app.docker.com) under **Members**. -1. Trigger provisioning from your IdP. -1. SCIM will re-create the user with correct attributes. +If the account is still unlinked, remove that user and provision them again. > [!WARNING] > -> Deleting a user removes their resource ownership, such as repositories. -> Transfer ownership before removing the user. +> Removing a user removes their resource ownership, such as repositories. +> Transfer ownership before you remove the user. From 5c6ca7a5aa303a30a0cd08057fee4ac173eafae1 Mon Sep 17 00:00:00 2001 From: Alexa Date: Wed, 30 Sep 2026 16:15:23 -0500 Subject: [PATCH 6/6] docs: tier 1 freshness pass on provisioning The JIT page linked group mapping to a heading that is not on the SCIM overview, and several provisioning pages had long unwrapped lines and numbered steps that did not all use 1. Wrap those pages, renumber the JIT flows, point the SCIM link at the setup page, and use the canonical Docker Team name in group mapping. Co-authored-by: Cursor --- content/manuals/faqs/security.md | 14 +++- .../provisioning/auto-provisioning.md | 27 ++++-- .../provisioning/domain-management.md | 46 +++++++--- .../security/provisioning/just-in-time.md | 84 +++++++++++++------ .../provisioning/scim/group-mapping.md | 2 +- .../provisioning/troubleshoot-provisioning.md | 4 +- 6 files changed, 125 insertions(+), 52 deletions(-) diff --git a/content/manuals/faqs/security.md b/content/manuals/faqs/security.md index b78ca06074a7..5bb63ceced7d 100644 --- a/content/manuals/faqs/security.md +++ b/content/manuals/faqs/security.md @@ -125,11 +125,16 @@ invite the user. ### Can users use different email addresses to authenticate through SSO? -All users must authenticate using the email domain specified during SSO setup. Users with email addresses that don't match the verified domain can sign in as guests with username and password if SSO isn't enforced, but only if they've been invited. +All users must authenticate using the email domain specified during SSO setup. +Users with email addresses that don't match the verified domain can sign in as +guests with username and password if SSO isn't enforced, but only if they've +been invited. ### How will users know they're being added to a Docker organization? -When SSO is turned on, users are prompted to authenticate through SSO the next time they sign in to Docker Hub or Docker Desktop. The system detects their domain email and prompts them to sign in with SSO credentials instead. +When SSO is turned on, users are prompted to authenticate through SSO the next +time they sign in to Docker Hub or Docker Desktop. The system detects their +domain email and prompts them to sign in with SSO credentials instead. For CLI access, users must authenticate using personal access tokens. @@ -182,7 +187,10 @@ source, see ### Is user information visible in Docker Hub? -All Docker accounts have public profiles associated with their namespace. If you don't want user information (like full names) to be visible, remove those attributes from your SSO and SCIM mappings, or use different identifiers to replace users' full names. +All Docker accounts have public profiles associated with their namespace. If +you don't want user information (like full names) to be visible, remove those +attributes from your SSO and SCIM mappings, or use different identifiers to +replace users' full names. ## Enforcement diff --git a/content/manuals/security/provisioning/auto-provisioning.md b/content/manuals/security/provisioning/auto-provisioning.md index 25f51d02235d..36afbb2f6f30 100644 --- a/content/manuals/security/provisioning/auto-provisioning.md +++ b/content/manuals/security/provisioning/auto-provisioning.md @@ -8,21 +8,30 @@ aliases: - /enterprise/security/provisioning/auto-provisioning/ --- -Auto-provisioning automatically adds users to your organization when they sign in with email addresses that match your verified domains. You must verify a domain before enabling auto-provisioning. +Auto-provisioning automatically adds users to your organization when they +sign in with email addresses that match your verified domains. You must verify +a domain before enabling auto-provisioning. > [!IMPORTANT] > -> For domains that are part of an SSO connection, Just-in-Time (JIT) provisioning takes precedence over auto-provisioning when adding users to an organization. +> For domains that are part of an SSO connection, Just-in-Time (JIT) +> provisioning takes precedence over auto-provisioning when adding users to an +> organization. ### Overview When auto-provisioning is enabled for a verified domain: -- Users who sign in to Docker with matching email addresses are automatically added to your organization. -- Auto-provisioning only adds existing Docker users to your organization, it doesn't create new accounts. +- Users who sign in to Docker with matching email addresses are automatically + added to your organization. +- Auto-provisioning only adds existing Docker users to your organization, it + doesn't create new accounts. - Users experience no changes to their sign-in process. -- Company and organization owners receive email notifications when new users are added. -- You may need to [manage seats](/manuals/accounts/organization/manage/manage-seats.md) to accommodate new users. +- Company and organization owners receive email notifications when new users + are added. +- You may need to + [manage seats](/manuals/accounts/organization/manage/manage-seats.md) to + accommodate new users. ### Enable auto-provisioning @@ -56,5 +65,7 @@ To disable auto-provisioning for a domain: To choose a different method to provision users, you can set up: -- [SCIM provisioning](/manuals/security/provisioning/scim/_index.md) for advanced user management. -- [Group mapping](/manuals/security/provisioning/scim/group-mapping.md) to assign users to teams automatically. +- [SCIM provisioning](/manuals/security/provisioning/scim/_index.md) for + advanced user management. +- [Group mapping](/manuals/security/provisioning/scim/group-mapping.md) to + assign users to teams automatically. diff --git a/content/manuals/security/provisioning/domain-management.md b/content/manuals/security/provisioning/domain-management.md index 309dc4052cc9..b1eb09ef8691 100644 --- a/content/manuals/security/provisioning/domain-management.md +++ b/content/manuals/security/provisioning/domain-management.md @@ -10,13 +10,19 @@ aliases: {{< summary-bar feature_name="Domain management" >}} -Domain management lets you add and verify domains for your organization, then enable auto-provisioning to automatically add users when they sign in with email addresses that match your verified domains. This approach simplifies user management, ensures consistent security settings, and reduces the risk of unmanaged users accessing Docker without visibility or control. +Domain management lets you add and verify domains for your organization, then +enable auto-provisioning to automatically add users when they sign in with +email addresses that match your verified domains. This approach simplifies +user management, ensures consistent security settings, and reduces the risk of +unmanaged users accessing Docker without visibility or control. -This page provides steps to add and delete domains, configure auto-provisioning, and audit uncaptured users. +This page provides steps to add and delete domains, configure +auto-provisioning, and audit uncaptured users. ## Add and verify a domain -Adding a domain requires verification to confirm ownership. The verification process uses DNS records to prove you control the domain. +Adding a domain requires verification to confirm ownership. The verification +process uses DNS records to prove you control the domain. ### Add a domain @@ -30,11 +36,19 @@ Adding a domain requires verification to confirm ownership. The verification pro ### Verify a domain -Verification confirms that you own the domain by adding a TXT record to your Domain Name System (DNS) host. It can take up to 72 hours for the DNS change to propagate. Docker automatically checks for the record and confirms ownership once the change is recognized. +Verification confirms that you own the domain by adding a TXT record to your +Domain Name System (DNS) host. It can take up to 72 hours for the DNS change to +propagate. Docker automatically checks for the record and confirms ownership +once the change is recognized. > [!TIP] > -> The record name field determines where the TXT record is added in your domain (root or subdomain). For root domains like `example.com`, use `@` or leave the record name empty, depending on your provider. Don't enter values like docker, `docker-verification`, `www`, or your domain name, as these may direct to the wrong place. Check your DNS provider's documentation to verify record name requirements. +> The record name field determines where the TXT record is added in your +> domain (root or subdomain). For root domains like `example.com`, use `@` or +> leave the record name empty, depending on your provider. Don't enter values +> like docker, `docker-verification`, `www`, or your domain name, as these may +> direct to the wrong place. Check your DNS provider's documentation to verify +> record name requirements. Follow the steps for your DNS provider to add the **TXT Record Value**. If your provider isn't listed, use the steps for "Other providers": @@ -42,7 +56,8 @@ your provider isn't listed, use the steps for "Other providers": {{< tabs >}} {{< tab name="AWS Route 53" >}} -1. Add your TXT record to AWS by following [Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html). +1. Add your TXT record to AWS by following + [Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html). 1. Wait up to 72 hours for TXT record verification. 1. Return to the **Domain management** page of the **Identity & auth**, then **Domain management**, and select **Verify** next to @@ -51,7 +66,8 @@ your provider isn't listed, use the steps for "Other providers": {{< /tab >}} {{< tab name="Google Cloud DNS" >}} -1. Add your TXT record to Google Cloud DNS by following [Verifying your domain with a TXT record](https://cloud.google.com/identity/docs/verify-domain-txt). +1. Add your TXT record to Google Cloud DNS by following + [Verifying your domain with a TXT record](https://cloud.google.com/identity/docs/verify-domain-txt). 1. Wait up to 72 hours for TXT record verification. 1. Return to the **Domain management** page of the **Identity & auth**, then **Domain management**, and select **Verify** next to @@ -60,7 +76,8 @@ your provider isn't listed, use the steps for "Other providers": {{< /tab >}} {{< tab name="GoDaddy" >}} -1. Add your TXT record to GoDaddy by following [Add a TXT record](https://www.godaddy.com/help/add-a-txt-record-19232). +1. Add your TXT record to GoDaddy by following + [Add a TXT record](https://www.godaddy.com/help/add-a-txt-record-19232). 1. Wait up to 72 hours for TXT record verification. 1. Return to the **Domain management** page of the **Identity & auth**, then **Domain management**, and select **Verify** next to @@ -81,7 +98,9 @@ your provider isn't listed, use the steps for "Other providers": ## Audit domains for uncaptured users -Domain audit identifies uncaptured users. Uncaptured users are Docker users who have authenticated using an email address associated with your verified domains but aren't members of your Docker organization. +Domain audit identifies uncaptured users. Uncaptured users are Docker users who +have authenticated using an email address associated with your verified +domains but aren't members of your Docker organization. ### Limitations @@ -91,7 +110,8 @@ Domain audit can't identify: - Users who authenticate using an account that doesn't have an email address associated with one of your verified domains -To prevent unidentifiable users from accessing Docker Desktop, [enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). +To prevent unidentifiable users from accessing Docker Desktop, +[enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md). ### Run a domain audit @@ -125,11 +145,13 @@ To compare JIT, SCIM, and auto-provisioning, see the ## Delete a domain -Deleting a domain removes its TXT record value and disables any associated auto-provisioning. +Deleting a domain removes its TXT record value and disables any associated +auto-provisioning. > [!WARNING] > -> Deleting a domain will disable auto-provisioning for that domain and remove verification. This action cannot be undone. +> Deleting a domain will disable auto-provisioning for that domain and remove +> verification. This action cannot be undone. To delete a domain: diff --git a/content/manuals/security/provisioning/just-in-time.md b/content/manuals/security/provisioning/just-in-time.md index 77053fd6be2c..7b7ce4daa009 100644 --- a/content/manuals/security/provisioning/just-in-time.md +++ b/content/manuals/security/provisioning/just-in-time.md @@ -31,39 +31,63 @@ Before you begin, you must have: ## SSO authentication with JIT provisioning enabled -When a user signs in with SSO and you have JIT provisioning enabled, the following steps occur automatically: +When a user signs in with SSO and you have JIT provisioning enabled, the +following steps occur automatically: 1. The system checks if a Docker account exists for the user's email address. - - If an account exists: The system uses the existing account and updates the user's full name if necessary. - - If no account exists: A new Docker account is created using basic user attributes (email, name, and surname). A unique username is generated based on the user's email, name, and random numbers to ensure all usernames are unique across the platform. - -2. The system checks for any pending invitations to the SSO organization. + - If an account exists: The system uses the existing account and updates + the user's full name if necessary. + - If no account exists: A new Docker account is created using basic user + attributes (email, name, and surname). A unique username is generated + based on the user's email, name, and random numbers to ensure all + usernames are unique across the platform. + +1. The system checks for any pending invitations to the SSO organization. - Invitation found: The invitation is automatically accepted. - - Invitation includes a specific group: The user is added to that group within the SSO organization. + - Invitation includes a specific group: The user is added to that group + within the SSO organization. -3. The system verifies if the IdP has shared group mappings during authentication. - - Group mappings provided: The user is assigned to the relevant organizations and teams. - - No group mappings provided: The system checks if the user is already part of the organization. If not, the user is added to the default organization and team configured in the SSO connection. +1. The system verifies if the IdP has shared group mappings during + authentication. + - Group mappings provided: The user is assigned to the relevant + organizations and teams. + - No group mappings provided: The system checks if the user is already + part of the organization. If not, the user is added to the default + organization and team configured in the SSO connection. -The following graphic provides an overview of SSO authentication with JIT enabled: +The following graphic provides an overview of SSO authentication with JIT +enabled: ![JIT provisioning enabled workflow](../images/jit-enabled-flow.svg) ## SSO authentication with JIT provisioning disabled -When JIT provisioning is disabled, the following actions occur during SSO authentication: +When JIT provisioning is disabled, the following actions occur during SSO +authentication: 1. The system checks if a Docker account exists for the user's email address. - - If an account exists: The system uses the existing account and updates the user's full name if necessary. - - If no account exists: A new Docker account is created using basic user attributes (email, name, and surname). A unique username is generated based on the user's email, name, and random numbers to ensure all usernames are unique across the platform. - -2. The system checks for any pending invitations to the SSO organization. - - Invitation found: If the user is a member of the organization or has a pending invitation, sign-in is successful, and the invitation is automatically accepted. - - No invitation found: If the user is not a member of the organization and has no pending invitation, the sign-in fails, and an `Access denied` error appears. The user must contact an administrator to be invited to the organization. - -With JIT disabled, group mapping is only available if you have [SCIM enabled](scim/#enable-scim-in-docker). If SCIM is not enabled, users won't be auto-provisioned to groups. - -The following graphic provides an overview of SSO authentication with JIT disabled: + - If an account exists: The system uses the existing account and updates + the user's full name if necessary. + - If no account exists: A new Docker account is created using basic user + attributes (email, name, and surname). A unique username is generated + based on the user's email, name, and random numbers to ensure all + usernames are unique across the platform. + +1. The system checks for any pending invitations to the SSO organization. + - Invitation found: If the user is a member of the organization or has a + pending invitation, sign-in is successful, and the invitation is + automatically accepted. + - No invitation found: If the user is not a member of the organization and + has no pending invitation, the sign-in fails, and an `Access denied` + error appears. The user must contact an administrator to be invited to + the organization. + +With JIT disabled, group mapping is only available if you have +[SCIM enabled](/manuals/security/provisioning/scim/provision-scim.md#enable-scim-in-docker). +If SCIM is not enabled, users won't be auto-provisioned to groups. + +The following graphic provides an overview of SSO authentication with JIT +disabled: ![JIT provisioning disabled workflow](../images/jit-disabled-flow.svg) @@ -78,19 +102,25 @@ The following graphic provides an overview of SSO authentication with JIT disabl You may want to disable JIT provisioning for reasons such as the following: -- You have multiple organizations, have SCIM enabled, and want SCIM to be the source of truth for provisioning -- You want to control and restrict usage based on your organization's security configuration, and want to use SCIM to provision access +- You have multiple organizations, have SCIM enabled, and want SCIM to be the + source of truth for provisioning +- You want to control and restrict usage based on your organization's + security configuration, and want to use SCIM to provision access -Users are provisioned with JIT by default. If you enable SCIM, you can disable JIT: +Users are provisioned with JIT by default. If you enable SCIM, you can disable +JIT: -1. Go to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down. +1. Go to [Docker Home](https://app.docker.com/) and select your organization + from the top-left account drop-down. 1. Select **Identity & auth**, then **SSO and SCIM**. -1. In the **SSO connections** table, select the **Action** icon, then select **Disable JIT provisioning**. +1. In the **SSO connections** table, select the **Action** icon, then select + **Disable JIT provisioning**. 1. Select **Disable** to confirm. ## Next steps - Review [how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit) before you configure SCIM. -- Set up [group mapping](/manuals/security/provisioning/scim/group-mapping.md) to automatically assign users to teams. +- Set up [group mapping](/manuals/security/provisioning/scim/group-mapping.md) + to automatically assign users to teams. - Review [Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md). diff --git a/content/manuals/security/provisioning/scim/group-mapping.md b/content/manuals/security/provisioning/scim/group-mapping.md index de3ace4f0160..b06a994962bf 100644 --- a/content/manuals/security/provisioning/scim/group-mapping.md +++ b/content/manuals/security/provisioning/scim/group-mapping.md @@ -39,7 +39,7 @@ Before you begin, you must have: ## How group mapping works -Group mapping uses IdP attributes to keep Docker team membership synchronized: +Group mapping uses IdP attributes to keep Docker Team membership synchronized: - With SAML SSO, the IdP sends group membership when a user signs in. - With SCIM, the IdP synchronizes group membership on its provisioning diff --git a/content/manuals/security/provisioning/troubleshoot-provisioning.md b/content/manuals/security/provisioning/troubleshoot-provisioning.md index 5fe292a8d691..3ef7675b0ba1 100644 --- a/content/manuals/security/provisioning/troubleshoot-provisioning.md +++ b/content/manuals/security/provisioning/troubleshoot-provisioning.md @@ -10,7 +10,9 @@ aliases: - /enterprise/security/provisioning/troubleshoot-provisioning/ --- -This page helps troubleshoot common user provisioning issues including user roles, attributes, and unexpected account behavior with SCIM and Just-in-Time (JIT) provisioning. +This page helps troubleshoot common user provisioning issues including user +roles, attributes, and unexpected account behavior with SCIM and Just-in-Time +(JIT) provisioning. ## Full name or team membership changes after sign-in