From 0d96fdf0cf1dc68efd8d24beba6968acdf555495 Mon Sep 17 00:00:00 2001 From: Alexa Date: Tue, 3 Nov 2026 12:22:30 -0600 Subject: [PATCH] docs: clarify provisioning choices and where attribute names are set The overview now says who configures provisioning and how the identity provider supplies account, organization, team, and role values. SSO attribute tables move to the connection guide, where those claims are configured. Co-authored-by: Cursor --- content/manuals/faqs/platform.md | 2 +- content/manuals/faqs/security.md | 2 +- content/manuals/platform-release-notes.md | 2 +- .../authentication/single-sign-on/connect.md | 63 +++++++-- .../manuals/security/provisioning/_index.md | 128 +++++++----------- 5 files changed, 108 insertions(+), 89 deletions(-) diff --git a/content/manuals/faqs/platform.md b/content/manuals/faqs/platform.md index 4591c6a0e82b..409f2d183569 100644 --- a/content/manuals/faqs/platform.md +++ b/content/manuals/faqs/platform.md @@ -36,7 +36,7 @@ Docker uses tokens to manage user sessions with different expiration periods: - Docker Desktop: Signs you out after 90 days, or 30 days of inactivity - Docker Hub and Docker Home: Sign you out after 24 hours -Docker also supports your IdP's default session timeout through SAML attributes. For more information, see [SSO attributes](/manuals/security/provisioning/_index.md#sso-attributes). +Docker also supports your IdP's default session timeout through SAML attributes. For more information, see [SSO attributes](/manuals/security/authentication/single-sign-on/connect.md#sso-attributes). ### How does Docker distinguish between employee users and contractor users? diff --git a/content/manuals/faqs/security.md b/content/manuals/faqs/security.md index e83e38646d5b..1173c197cd4b 100644 --- a/content/manuals/faqs/security.md +++ b/content/manuals/faqs/security.md @@ -54,7 +54,7 @@ No specific firewall rules are required as long as `login.docker.com` is accessi ### Does Docker use my IdP's default session timeout? -Yes, Docker supports your IdP's session timeout using a custom `dockerSessionMinutes` SAML attribute instead of the standard `SessionNotOnOrAfter` element. See [SSO attributes](/manuals/security/provisioning/_index.md#sso-attributes) for more information. +Yes, Docker supports your IdP's session timeout using a custom `dockerSessionMinutes` SAML attribute instead of the standard `SessionNotOnOrAfter` element. See [SSO attributes](/manuals/security/authentication/single-sign-on/connect.md#sso-attributes) for more information. ### Can I use multiple identity providers with Docker SSO? diff --git a/content/manuals/platform-release-notes.md b/content/manuals/platform-release-notes.md index b604df6501e1..6dc6ec26b437 100644 --- a/content/manuals/platform-release-notes.md +++ b/content/manuals/platform-release-notes.md @@ -286,7 +286,7 @@ and subscriptions. - [Organization access tokens](/manuals/security/access-tokens/organization-access-tokens.md) are now generally available. - Single sign-on now supports the - [`dockerSessionMinutes` attribute](/manuals/security/provisioning/_index.md#sso-attributes), + [`dockerSessionMinutes` attribute](/manuals/security/authentication/single-sign-on/connect.md#sso-attributes), so a session can follow the identity provider timeout. - Administrators can now [track whether users comply with Docker Desktop settings policies](/manuals/desktop/enterprise/hardened-desktop/settings-management/compliance-reporting.md) diff --git a/content/manuals/security/authentication/single-sign-on/connect.md b/content/manuals/security/authentication/single-sign-on/connect.md index f9236016daa8..e085553b715f 100644 --- a/content/manuals/security/authentication/single-sign-on/connect.md +++ b/content/manuals/security/authentication/single-sign-on/connect.md @@ -7,7 +7,8 @@ description: >- enforcement. keywords: configure sso, set up sso, docker sso setup, docker identity provider, sso enforcement, docker hub, security, - domain verification, SAML, OIDC + domain verification, SAML, OIDC, SSO attributes, SAML attribute mapping, + dockerOrg, dockerRole, dockerTeam, dockerSessionMinutes aliases: - /security/for-admins/single-sign-on/connect/ - /docker-hub/domains/ @@ -171,9 +172,8 @@ for the Okta org. - For **Name ID format**, choose `EmailAddress` - For **Application username**, choose `Email` - For **Update application username on**, choose `Create and update` - - Optional. Add - [SAML attributes](/manuals/security/provisioning/_index.md#sso-attributes), - if required by your org. + - Optional. Add [SAML attributes](#sso-attributes), if required by your + org. 1. For **Feedback**, choose **This is an internal app that we have created** checkbox before finishing. @@ -196,9 +196,8 @@ permissions. creating an SSO connection in Docker: - For the **Identifier** value, paste the Docker Entity ID. - For the **Reply URL** value, paste Docker ACS URL. -1. Optional. Add - [SAML attributes](/manuals/security/provisioning/_index.md#sso-attributes), - if required by your org. +1. Optional. Add [SAML attributes](#sso-attributes), if required by your + org. 1. From the **SAML Signing Certificate** section, download your **Certificate (Base64)**. @@ -263,6 +262,9 @@ Complete the integration by pasting your IdP values into Docker. 1. Return to your opened Docker window for the **Create single sign-on connection** step. Paste in the **SAML Sign-in URL** and **x509 Certificate** values. +1. Select the verified domains for this connection. For a company, select the + organizations to include, then select the default organization to + provision users to. 1. Optional. Select a default team, if required by your org. 1. Review and select **Create connection**. @@ -275,7 +277,9 @@ Complete the integration by pasting your IdP values into Docker. - **Certificate (Base64)** contents 1. Return to Docker Home, then paste the **Login URL** and **Certificate (Base64)** values. -1. Choose your domain from the drop-down. +1. Choose your domain from the drop-down. For a company, select the + organizations to include, then select the default organization to + provision users to. 1. Optional. Select a default team, if required by your org. 1. Review and select **Create connection**. @@ -287,6 +291,9 @@ Complete the integration by pasting your IdP values into Docker. - **Client ID**: the **Application (client) ID** you copied - **Client Secret**: the secret **Value** you copied - **Azure AD Domain** +1. Select the verified domains for this connection. For a company, select the + organizations to include, then select the default organization to + provision users to. 1. Optional. Select a default team, if required by your org. 1. Review and select **Create connection**. @@ -312,6 +319,46 @@ After assigning yourself to an app: If you have multiple IdPs, choose the sign-in option **Continue with SSO**. If you're using the CLI, you must authenticate using a personal access token. +## SSO and SAML attributes + +Each time a user signs in through SSO, Docker reads attributes from your +IdP to set the user's identity and permissions. Docker SSO connections use +SAML 2.0 or Azure AD (OIDC). + +### SSO attributes + +| 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 length, in minutes, before users sign in with the IdP again. Must be a positive integer greater than 0 | + +> [!NOTE] +> +> Docker Desktop sessions last a maximum of 90 days, and expire sooner if +> the session is inactive for 30 consecutive days. Docker Hub and Docker +> Home sessions expire after 24 hours. + +### SAML attribute mapping + +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 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 greater than 0 | + ## Configure multiple IdPs Docker supports multiple identity provider (IdP) configurations by letting you diff --git a/content/manuals/security/provisioning/_index.md b/content/manuals/security/provisioning/_index.md index cfea59f67eae..384e112641ec 100644 --- a/content/manuals/security/provisioning/_index.md +++ b/content/manuals/security/provisioning/_index.md @@ -4,43 +4,26 @@ description: >- 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 + auto-provisioning, SSO, SAML, Azure AD, OIDC, 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/ -grid: - - title: Add and manage domains - description: Add, verify, and manage domains for auto-provisioning. - icon: globe-alt - link: "domain-management/" - - 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: Create user accounts automatically on first SSO sign-in. - icon: clock - link: "just-in-time/" - - 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 you configure single sign-on (SSO), provision users so they can -access your organization through automated account management. +After you configure single sign-on (SSO), choose how Docker creates accounts +and adds users to your organization. Organization owners configure +provisioning. For a company, the company owner configures it. +SSO requires a Docker Business subscription. -## Provisioning methods +## Choose a provisioning method -Provisioning automates account creation, updates, and deactivation using -data from your identity provider (IdP). Docker supports the following -methods: +Provisioning creates and updates accounts from your identity provider (IdP). Docker supports these methods: | Provisioning method | When it runs | Lifecycle management | Default setting | | :--- | :--- | :--- | :--- | @@ -48,63 +31,52 @@ methods: | [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 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 -also invite users manually when automatic provisioning isn't configured. +After you choose a provisioning method, you can enable [group mapping](/manuals/security/provisioning/scim/group-mapping.md) to assign +users to one or more Docker organizations and teams. Group mapping works only +with SAML SSO or SCIM. -## Default provisioning setup - -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). - -For a domain that belongs to an SSO connection, JIT adds the user instead of -auto-provisioning. - -## SSO attributes - -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 | -| :--- | :--- | :--- | -| 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] +> [!IMPORTANT] > -> Default session timeouts apply when Docker session minutes is not -> specified. Docker Desktop sessions last a maximum of 90 days, but expire sooner -> if the session is inactive for 30 consecutive days. Docker Hub and -> Docker Home sessions expire after 24 hours. - -## SAML attribute mapping - -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 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 greater than 0 | +> Using JIT and auto-provisioning on the same domain can cause unexpected +> results. Avoid enabling both for a domain that's part of an SSO connection. + +## Manage JIT and SCIM together + +You must have at least one provisioning method enabled when you configure an SSO connection. By default Docker turns on JIT provisioning. If you want to turn JIT off, then you must have SCIM enabled; conversely, if you want to turn SCIM off, you must re-enable JIT. If you +enable SCIM and JIT together, choose which one manages users and attributes. Review +[how SCIM works with JIT](/manuals/security/provisioning/scim/_index.md#choose-how-scim-works-with-jit) before choosing. + +## Set attribute names in the identity provider + +When a user signs in through SSO, Docker identifies the account and keeps +its email address and full name current based on what the IdP sends. IdPs +use different claim names for those two attributes. In your identity provider, +set the full name and the email address each to a claim name Docker already +accepts. Docker uses the name you set to store the value on the signed-in +user's account. See +[SSO and SAML attributes](/manuals/security/authentication/single-sign-on/connect.md#sso-and-saml-attributes) +for the accepted claim names. + +Organization, team, and role are not attributes you set for SSO sign-in, and +your identity provider does not include them. For SCIM, you create custom +attributes in the identity provider and set the external names to `dockerOrg`, +`dockerTeam`, and `dockerRole`. The IdP sends those names to Docker. Docker +recognizes each name, places the user in that organization and team, and +assigns the role. See +[Set up role mapping](/manuals/security/provisioning/scim/provision-scim.md#set-up-role-mapping) +for how to create the attributes. ## Next steps 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). +- [Add and manage domains](/manuals/security/provisioning/domain-management.md) + to add, verify, and manage domains for auto-provisioning. +- [SCIM provisioning](/manuals/security/provisioning/scim/_index.md) to sync + user data between your IdP and Docker. +- [Just-in-Time (JIT) provisioning](/manuals/security/provisioning/just-in-time.md) + to create user accounts on first SSO sign-in. +- [Auto-provisioning](/manuals/security/provisioning/auto-provisioning.md) to + add users whose email addresses match a verified domain. +- [Troubleshoot provisioning](/manuals/security/provisioning/troubleshoot-provisioning.md) + if users get the wrong role or team after you change methods.