From 17b4141220cc582fdf6cc79af45380a3fc76e3c3 Mon Sep 17 00:00:00 2001 From: Sarah Sanders Date: Tue, 22 Oct 2024 16:42:27 -0700 Subject: [PATCH 1/6] Update Configure and Connect SSO docs --- .../manuals/admin/organization/insights.md | 4 +- content/manuals/admin/organization/onboard.md | 4 +- .../faqs/single-sign-on/domain-faqs.md | 2 +- .../security/faqs/single-sign-on/idp-faqs.md | 2 +- .../for-admins/enforce-sign-in/_index.md | 3 +- .../security/for-admins/provisioning/scim.md | 2 +- .../for-admins/single-sign-on/_index.md | 20 +- .../for-admins/single-sign-on/configure.md | 77 +++++++ .../single-sign-on/configure/_index.md | 69 ------ .../single-sign-on/configure/configure-idp.md | 177 ---------------- .../for-admins/single-sign-on/connect.md | 198 ++++++++++++++++-- .../for-admins/single-sign-on/troubleshoot.md | 4 +- .../security/security-announcements.md | 2 +- 13 files changed, 278 insertions(+), 286 deletions(-) create mode 100644 content/manuals/security/for-admins/single-sign-on/configure.md delete mode 100644 content/manuals/security/for-admins/single-sign-on/configure/_index.md delete mode 100644 content/manuals/security/for-admins/single-sign-on/configure/configure-idp.md diff --git a/content/manuals/admin/organization/insights.md b/content/manuals/admin/organization/insights.md index 29b6f44f3e4..5301d2aadbc 100644 --- a/content/manuals/admin/organization/insights.md +++ b/content/manuals/admin/organization/insights.md @@ -7,7 +7,7 @@ title: Insights > [!NOTE] > Insights requires a [Docker Business > subscription](/subscription/core-subscription/details/#docker-business) and -> administrators must [enforce sign-in](/security/for-admins/enforce-sign-in/) +> administrators must [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) > to ensure that users sign in with an account associated with their > organization. @@ -64,7 +64,7 @@ The chart contains the following data. |:-----------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Total active users | The number of users that have actively used Docker Desktop and either signed in with a Docker account that has a license in your organization or signed in to a Docker account with an email address from a domain associated with your organization.

Users who don’t sign in to an account associated with your organization are not represented in the data. To ensure users sign in with an account associated with your organization, you can [enforce sign-in](/security/for-admins/enforce-sign-in/). | | Active with license | The number of users that have actively used Docker Desktop and have signed in to a Docker account with a license in your organization. | -| Active without license | The number of users that have actively used Docker Desktop, are linked to a Docker account with an email address from a domain associated with your organization, and don’t have a license assigned to their account.

Users without a license don’t receive the benefits of your subscription. You can use [domain audit](/security/for-admins/domain-audit/) to identify users without a license. You can also use [Just-in-Time provisioning](/security/for-admins/provisioning/just-in-time/) or [SCIM](/security/for-admins/provisioning/scim/) to help automatically provision users with a license. Note that when SSO is configured and [enforced](/security/for-admins/single-sign-on/connect/#optional-enforce-sso), active without license will be 0. | +| Active without license | The number of users that have actively used Docker Desktop, are linked to a Docker account with an email address from a domain associated with your organization, and don’t have a license assigned to their account.

Users without a license don’t receive the benefits of your subscription. You can use [domain audit](/security/for-admins/domain-audit/) to identify users without a license. You can also use [Just-in-Time provisioning](/security/for-admins/provisioning/just-in-time/) or [SCIM](/security/for-admins/provisioning/scim/) to help automatically provision users with a license. Note that when SSO is configured and enforced, active without license will be 0. | | Users opted out of analytics | The number of users that are a member of your organization that have opted out of sending analytics.

When users opt out of sending analytics, you won't see any of their data in Insights. To ensure that the data includes all users, you can use [Settings Management](/desktop/hardened-desktop/settings-management/) to set `analyticsEnabled` for all your users. | | Active users (graph) | The view over time for total active users. | diff --git a/content/manuals/admin/organization/onboard.md b/content/manuals/admin/organization/onboard.md index 9761713a313..37d1d7c0fa5 100644 --- a/content/manuals/admin/organization/onboard.md +++ b/content/manuals/admin/organization/onboard.md @@ -67,8 +67,8 @@ To add a member, invite a user and assign them the member role. For more details Configuring SSO and SCIM is optional and only available to Docker Business subscribers. To upgrade a Docker Team subscription to a Docker Business subscription, see [Upgrade your subscription](/subscription/upgrade/). You can manage your members in your identity provider and automatically provision them to your Docker organization with SSO and SCIM. See the following for more details. - - [Configure SSO](/security/for-admins/single-sign-on/) to authenticate and add members when they sign in to Docker through your identity provider. - - Optional: [Enforce SSO](/security/for-admins/single-sign-on/connect/#optional-enforce-sso) to ensure that when users sign in to Docker, they must use SSO. + - [Configure SSO](/manuals/security/for-admins/single-sign-on/configure.md) to authenticate and add members when they sign in to Docker through your identity provider. + - Optional: [Enforce SSO](/manuals/security/for-admins/single-sign-on/connect.md) to ensure that when users sign in to Docker, they must use SSO. > [!NOTE] > > Enforcing single sign-on (SSO) and [Step 5: Enforce sign-in for Docker diff --git a/content/manuals/security/faqs/single-sign-on/domain-faqs.md b/content/manuals/security/faqs/single-sign-on/domain-faqs.md index b493dcc5ea7..a991edc7452 100644 --- a/content/manuals/security/faqs/single-sign-on/domain-faqs.md +++ b/content/manuals/security/faqs/single-sign-on/domain-faqs.md @@ -18,7 +18,7 @@ You can do it one time to add the domain to a connection. If your organization e ### Is adding domain required to configure SSO? What domains should I be adding? And how do I add it? -Adding and verifying a domain is required to enable and enforce SSO. See [Step one: Add and verify your domain](/security/for-admins/single-sign-on/configure/#step-one-add-and-verify-your-domain) to learn how to specify the email domains that are allowed to authenticate through your server. This should include all email domains users will use to access Docker. Public domains, for example `gmail.com` or `outlook.com`, are not permitted. Also, the email domain should be set as the primary email. +Adding and verifying a domain is required to enable and enforce SSO. See [Configure single sign-on](/manuals/security/for-admins/single-sign-on/configure.md) for more information. This should include all email domains users will use to access Docker. Public domains, for example `gmail.com` or `outlook.com`, are not permitted. Also, the email domain should be set as the primary email. ### Is IdP-initiated authentication supported? diff --git a/content/manuals/security/faqs/single-sign-on/idp-faqs.md b/content/manuals/security/faqs/single-sign-on/idp-faqs.md index 2049523fb5b..d67ccab424b 100644 --- a/content/manuals/security/faqs/single-sign-on/idp-faqs.md +++ b/content/manuals/security/faqs/single-sign-on/idp-faqs.md @@ -14,7 +14,7 @@ No. You can only configure Docker SSO to work with a single IdP. A domain can on ### Is it possible to change my identity provider after configuring SSO? -Yes. You must delete your existing IdP configuration in your Docker SSO connection and then [configure SSO using your new IdP](/security/for-admins/single-sign-on/configure/configure-idp/). If you had already turned on enforcement, you should turn off enforcement before updating the provider SSO connection. +Yes. You must delete your existing IdP configuration in your Docker SSO connection and then [configure SSO using your new IdP](/manuals/security/for-admins/single-sign-on/connect.md). If you had already turned on enforcement, you should turn off enforcement before updating the provider SSO connection. ### What information do I need from my identity provider to configure SSO? diff --git a/content/manuals/security/for-admins/enforce-sign-in/_index.md b/content/manuals/security/for-admins/enforce-sign-in/_index.md index 99037a42bc9..9435cd369db 100644 --- a/content/manuals/security/for-admins/enforce-sign-in/_index.md +++ b/content/manuals/security/for-admins/enforce-sign-in/_index.md @@ -39,8 +39,7 @@ following occurs: ## Enforcing sign-in versus enforcing single sign-on (SSO) -[Enforcing -SSO](/security/for-admins/single-sign-on/connect#optional-enforce-sso) and +[Enforcing SSO](/manuals/security/for-admins/single-sign-on/connect.md) and enforcing sign-in are different features. The following table provides a description and benefits when using each feature. diff --git a/content/manuals/security/for-admins/provisioning/scim.md b/content/manuals/security/for-admins/provisioning/scim.md index d53764060ef..39840827168 100644 --- a/content/manuals/security/for-admins/provisioning/scim.md +++ b/content/manuals/security/for-admins/provisioning/scim.md @@ -36,7 +36,7 @@ For additional details about supported attributes and SCIM, see [Docker Hub API > [!IMPORTANT] > -> SSO uses Just-in-Time (JIT) provisioning by default. If you [enable SCIM](scim.md#set-up-scim), JIT values still overwrite the attribute values set by SCIM provisioning whenever users log in. To avoid conflicts, make sure your JIT values match your SCIM values. For more information, see [SSO attributes](../single-sign-on/configure/configure-idp.md#sso-attributes). +> SSO uses Just-in-Time (JIT) provisioning by default. If you [enable SCIM](scim.md#set-up-scim), JIT values still overwrite the attribute values set by SCIM provisioning whenever users log in. To avoid conflicts, make sure your JIT values match your SCIM values. For more information, see > [!TIP] > diff --git a/content/manuals/security/for-admins/single-sign-on/_index.md b/content/manuals/security/for-admins/single-sign-on/_index.md index 3975b9eb148..51de20f7f2e 100644 --- a/content/manuals/security/for-admins/single-sign-on/_index.md +++ b/content/manuals/security/for-admins/single-sign-on/_index.md @@ -12,7 +12,7 @@ weight: 10 Single sign-on (SSO) lets users access Docker by authenticating using their identity providers (IdPs). SSO is available for a whole company, and all associated organizations within that company, or an individual organization that has a Docker Business subscription. To upgrade your existing account to a Docker Business subscription, see [Upgrade your subscription](/subscription/upgrade/). -## How it works +## How SSO works When you enable SSO, Docker supports a IdP-initiated SSO flow for user login. Instead of users authenticating using their Docker username and password, they are redirected to your identity provider's authentication page to sign in. Users must sign in to Docker Hub or Docker Desktop to initiate the SSO authentication process. @@ -23,27 +23,27 @@ The following diagram shows how SSO operates and is managed in Docker Hub and Do ## How to set it up SSO is configured using the following steps: -1. Configure SSO by creating and verifying a domain in Docker. -2. Create your SSO connection in Docker and your IdP. +1. [Configure SSO](../single-sign-on/configure.md) by creating and verifying a domain in Docker. +2. [Create your SSO connection](../single-sign-on/connect.md) in Docker and your IdP. 3. Cross-connect Docker and your IdP. 4. Test your connection. 5. Provision users. -6. Optional. Enforce sign-in. -7. Manage your SSO configuration. +6. Optional. [Enforce sign-in](../enforce-sign-in/_index.md). +7. [Manage your SSO configuration](../single-sign-on/manage.md). Once your SSO configuration is complete, a first-time user can sign in to Docker Hub or Docker Desktop using their company's domain email address. Once they sign in, they are added to your company, assigned to an organization, and if necessary, assigned to a team. ## Prerequisites Before configuring SSO, ensure you meet the following prerequisites: -* To ensure users are aware of the sign in change, you must first notify your company about the new SSO login procedures. -* Verify that your members have Docker Desktop version 4.4.2 or later installed on their machines. -* If your organization is planning to [enforce SSO](/security/for-admins/single-sign-on/connect/#optional-enforce-sso), members using the Docker CLI are required to [create a Personal Access Token (PAT)](/docker-hub/access-tokens/) to sign in. The PAT will be used instead of their username and password. Docker plans to deprecate signing in to the CLI with a password in the future, so using a PAT will be required to prevent issues with authentication. For more details see the [security announcement](/security/security-announcements/#deprecation-of-password-logins-on-cli-when-sso-enforced). +* Notify your company about the new SSO sign in procedures. +* Verify that all users have Docker Desktop version 4.4.2 or later installed. +* If your organization is planning to [enforce SSO](../enforce-sign-in/_index.md), members using the Docker CLI are required to [create a Personal Access Token (PAT)](/docker-hub/access-tokens/). The PAT will be used instead of their username and password. Docker plans to deprecate signing in to the CLI with a password in the future, so using a PAT will be required to prevent issues with authentication. For more details see the [security announcement](/security/security-announcements/#deprecation-of-password-logins-on-cli-when-sso-enforced). * Ensure all your Docker users have a valid user on your IdP with the same email address as their Unique Primary Identifier (UPN). * Confirm that all CI/CD pipelines have replaced their passwords with PATs. * For your service accounts, add your additional domains or enable it in your IdP. ## What's next? -- Start [configuring SSO](configure/_index.md) in Docker -- Explore the [FAQs](../../../security/faqs/single-sign-on/faqs.md) +- Start [configuring SSO](../../for-admins/single-sign-on/configure.md) in Docker +- Explore the [FAQs](../../../security/faqs/single-sign-on/_index.md) diff --git a/content/manuals/security/for-admins/single-sign-on/configure.md b/content/manuals/security/for-admins/single-sign-on/configure.md new file mode 100644 index 00000000000..a5bda5c29b5 --- /dev/null +++ b/content/manuals/security/for-admins/single-sign-on/configure.md @@ -0,0 +1,77 @@ +--- +description: Learn how to configure single sign-on for your organization or company. +keywords: configure, sso, docker hub, hub, docker admin, admin, security +title: Configure single sign-on +linkTitle: Configure +aliases: +- /docker-hub/domains/ +- /docker-hub/sso-connection/ +- /docker-hub/enforcing-sso/ +- /single-sign-on/configure/ +- /admin/company/settings/sso-configuration/ +- /admin/organization/security-settings/sso-configuration/ +--- + +Get started creating a single sign-on (SSO) connection for your organization or company. This guide walks through the steps to add and verify the domains your members use to sign in to Docker. + +## Step one: Add your domain + +{{< tabs >}} +{{< tab name="Admin Console" >}} + +{{< include "admin-early-access.md" >}} + +1. Sign in to the [Admin Console](https://admin.docker.com/). +2. Select your organization or company from the left-hand drop-down menu. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. +3. Under **Security and access**, select **Domain management**. +4. Select **Add a domain**. +5. Enter your domain in the text box and select **Add domain**. +6. The pop-up modal will prompt you with steps to verify your domain. Copy the **TXT Record Value**. + +{{< /tab >}} +{{< tab name="Docker Hub" >}} + +1. Sign in to [Docker Hub](https://hub.docker.com/). +2. Select **Organizations** and then your organization from the list. +3. On your organization page, select **Settings** and then **Security**. +4. Select **Add a domain**. +5. Enter your domain in the text box and select **Add domain**. +6. The pop-up modal will prompt you with steps to verify your domain. Copy the **TXT Record Value**. + +{{< /tab >}} +{{< /tabs >}} + +## Step two: Verify your domain + +Verifying your domain ensures Docker knows you own it. Domain verification is done by adding your Docker TXT Record Value to your domain host. The TXT Record Value proves ownership, which signals the Domain Name System (DNS) to add this record. It can take up to 72 hours for DNS to recognize the change. When the change is reflected in DNS, Docker will automatically check the record to confirm your ownership. + +{{< tabs >}} +{{< tab name="Admin Console" >}} + +{{< include "admin-early-access.md" >}} + +1. Navigate to your domain host, create a new TXT record, and paste the **TXT Record Value** from Docker. +2. TXT record verification can take 72 hours. Once you have waited for TXT record verification, return to the **Domain management** page of the Admin Console and select **Verify** next to your domain name. + +{{< /tab >}} +{{< tab name="Docker Hub" >}} + +1. Navigate to your domain host, create a new TXT record, and paste the **TXT Record Value** from Docker. +2. TXT Record Verification can take 72 hours. Once you have waited for TXT record verification, return to the **Security** page of Docker Hub and select **Verify** next to your domain name. + +{{< /tab >}} +{{< /tabs >}} + +Once you have added and verified your domain, you are ready to create an SSO connection between Docker and your identity provider (IdP). + +## More resources + +The following videos walk through verifying your domain to create your SSO connection in Docker. + +- [Video: Verify your domain for SSO with Okta](https://youtu.be/c56YECO4YP4?feature=shared&t=529) +- [Video: Verify your domain for SSO with Azure AD (OIDC)](https://youtu.be/bGquA8qR9jU?feature=shared&t=496) + +## What's next? + +[Connect Docker and your IdP](../single-sign-on/connect.md). + diff --git a/content/manuals/security/for-admins/single-sign-on/configure/_index.md b/content/manuals/security/for-admins/single-sign-on/configure/_index.md deleted file mode 100644 index 2d623bd53b5..00000000000 --- a/content/manuals/security/for-admins/single-sign-on/configure/_index.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -description: Learn how to configure single sign-on for your organization or company. -keywords: configure, sso, docker hub, hub, docker admin, admin, security -title: Configure single sign-on -linkTitle: Configure -aliases: -- /docker-hub/domains/ -- /docker-hub/sso-connection/ -- /docker-hub/enforcing-sso/ -- /single-sign-on/configure/ -- /admin/company/settings/sso-configuration/ -- /admin/organization/security-settings/sso-configuration/ ---- - -Get started creating a single sign-on (SSO) connection for your organization or company. - -The steps to set up your SSO configuration are: - -1. [Add and verify the domain or domains](#step-one-add-and-verify-your-domain) that your members use to sign in to Docker. -2. [Create your SSO connection](#step-two-create-an-sso-connection-in-docker) in Docker. -3. [Configure your IdP](./configure-idp.md) to work with Docker. -4. [Complete your SSO connection](../connect/_index.md) in Docker. - -This page walks through steps 1 and 2 using Docker Hub or the Admin Console. To configure SSO for a company, use the Admin Console. - -## Step one: Add and verify your domain - -{{< tabs >}} -{{< tab name="Admin Console" >}} - -{{< include "admin-early-access.md" >}} - -{{% admin-domains product="admin" %}} - -{{< /tab >}} -{{< tab name="Docker Hub" >}} - -{{% admin-domains product="hub" %}} - -{{< /tab >}} -{{< /tabs >}} - -## Step two: Create an SSO connection in Docker - -{{< tabs >}} -{{< tab name="Admin Console" >}} - -{{< include "admin-early-access.md" >}} - -{{% admin-sso-config product="admin" %}} - -{{< /tab >}} -{{< tab name="Docker Hub" >}} - -{{% admin-sso-config product="hub" %}} - -{{< /tab >}} -{{< /tabs >}} - -## More resources - -The following videos walk through verifying your domain to create your SSO connection in Docker. - -- [Video: Verify your domain for SSO with Okta](https://youtu.be/c56YECO4YP4?feature=shared&t=529) -- [Video: Verify your domain for SSO with Azure AD (OIDC)](https://youtu.be/bGquA8qR9jU?feature=shared&t=496) - -## What's next? - -[Continue configuration in your IdP](./configure-idp.md). diff --git a/content/manuals/security/for-admins/single-sign-on/configure/configure-idp.md b/content/manuals/security/for-admins/single-sign-on/configure/configure-idp.md deleted file mode 100644 index a759675e7e8..00000000000 --- a/content/manuals/security/for-admins/single-sign-on/configure/configure-idp.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -description: Learn how to set up SSO in your IdP and take the next steps for enabling SSO. -keywords: configure, sso, docker hub, hub, docker admin, admin, security -title: Configure your IdP ---- - -The steps to set up your SSO configuration are: - -1. [Add and verify the domain or domains](/security/for-admins/single-sign-on/configure#step-one-add-and-verify-your-domain) that your members use to sign in to Docker. -2. [Create your SSO connection](/security/for-admins/single-sign-on/configure#step-two-create-an-sso-connection-in-docker) in Docker. -3. [Configure your IdP](#step-three-configure-your-idp-to-work-with-docker) to work with Docker. -4. [Complete your SSO connection](/security/for-admins/single-sign-on/connect/) in Docker. - -This page walks through step 3 for common IdPs. - -## Prerequisites - -Make sure you have completed the following before you begin: - -- Your domain is verified -- You have created your SSO connection in Docker -- You have copied the necessary fields from Docker to paste in your IdP: - - SAML: **Entity ID**, **ACS URL** - - Azure AD (OIDC): **Redirect URL** - -## SSO attributes - -When a user signs in using SSO, Docker obtains the following attributes from the IdP: - -- **Email address** - unique identifier of the user -- **Full name** - name of the user -- **Groups (optional)** - list of groups to which the user belongs -- **Docker Org (optional)** - the organization to which the user belongs -- **Docker Team (optional)** - the team within an organization that a user has been added to -- **Docker Role (optional)** - the role for the user that grants their permissions in an organization - -If you use SAML for your SSO connection, Docker obtains these attributes from the SAML assertion message. Your IdP may use different naming for SAML attributes than those in the previous list. The following table lists the possible SAML attributes that can be present in order for your SSO connection to work. - -> [!IMPORTANT] -> ->SSO uses Just-in-Time (JIT) provisioning by default. If you [enable SCIM](../../provisioning/scim.md), JIT values still overwrite the attribute values set by SCIM provisioning whenever users log in. To avoid conflicts, make sure your JIT values match your SCIM values. For example, to make sure that the full name of a user displays in your organization, you would set a `name` attribute in your SAML attributes and ensure the value includes their first name and last name. The exact method for setting these values (for example, constructing it with `user.firstName + " " + user.lastName`) varies depending on your IdP. - -> [!TIP] -> -> Optional Just-in-Time (JIT) provisioning is available when you use the Admin Console and enable SCIM. With this feature, you can avoid conflicts between SCIM and JIT by disabling JIT provisioning in your SSO connection. See [SSO authentication with JIT provisioning disabled](/security/for-admins/provisioning/just-in-time/#sso-authentication-with-jit-provisioning-disabled). - -You can also configure attributes to override default values, such as default team or organization. See [role mapping](../../provisioning/scim.md#set-up-role-mapping). - -| SSO attribute | SAML assertion message 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` | - -> [!IMPORTANT] -> -> If none of the email address attributes listed in the previous table are found, SSO returns an error. Also, if the `Full name` attribute isn't set, then the name will be displayed as the value of the `Email address`. - -## Step three: Configure your IdP to work with Docker - -The user interface for your IdP may differ slightly from the following steps. You can refer to the documentation for your IdP to verify. - -{{< tabs >}} -{{< tab name="Okta" >}} - -See [More resources](#more-resources) for a video overview on how to set up SSO with SAML in Okta. - -1. Go to the Okta admin portal. -2. Go to **Applications > Applications > Create App Integration**. -3. Select **SAML 2.0**, then select **Next**. -4. Enter App Name "Docker Hub" and optionally upload a logo for the app, then select **Next**. -5. To configure SAML, enter the following into Okta: - - ACS URL: Single Sign On URL - - Entity ID: Audience URI (SP Entity ID) - - Name ID format: `EmailAddress` - - Application username: `Email` - - Update application on: `Create or Update` - - Attribute Statements: `add`. You can define your attribute statement like the following: - - | Attribute name | Name format | Value | - | :------------- | :---------- | :--------------------------------------- | - | name | Unspecified | username.firstName + " " + user.lastName | - -6. Select **Next**. -7. Select **I'm an Okta customer adding an internal app**. -8. Select **Finish**. -9. After you create the app, go to your app and select **View SAML setup instructions**. -10. Here you can find the **SAML Sign-in URL** and the **x509 Certificate**. Open the certificate file in a text editor and paste the contents of the file in the **x509 Certificate** field in Docker Hub or Admin Console. Then, copy the value of the **SAML Sign-in URL** and paste it into the corresponding field in Docker Hub or Admin Console. - -{{< /tab >}} -{{< tab name="Entra ID SAML 2.0" >}} - -> [!TIP] -> -> When you create the application for your SSO connection in Entra ID (formerly Azure AD) we recommend that you don't assign the app to all the users in the directory. -> Instead, you can create a security group and assign the app to the group. This way, you can control who in your organization has access to Docker. -> To change the default setting for assignment, go to the main properties for your app and find the **Assignment required** setting. Set it to **Yes**. - -See [More resources](#more-resources) for a video overview on how to set up SSO with SAML in Entra ID (formerly Azure AD). - -1. Go to Azure AD admin portal. -2. Go to **Default Directory > Add > Enterprise Application > Create your own application**. -3. Enter “Docker” for application name and select **non-gallery** option. -4. After the application is created, go to **Single Sign-On** and select **SAML**. -5. Select **Edit** on the **Basic SAML configuration** section. -6. Add the following settings from Docker Hub: - - Entity ID: Identifier - - ACS URL: Reply URL -7. Save configuration. -8. From section **SAML Signing Certificate** download **Certificate (Base64)**. -9. Open the certificate file in a text editor and paste the contents of the file in the **x509 Certificate** field in Docker Hub or Admin Console. -10. From the section **Set up Docker**, copy **Login URL** and paste it into the **SAML Sign-in URL** field in Docker Hub or Admin Console. - -{{< /tab >}} -{{< tab name="Azure Connect (OIDC)" >}} - -See [More resources](#more-resources) for a video overview on how to set up SSO with Azure Connect (OIDC). - -### Create app registration - -1. Go to Azure AD admin portal. -2. Select **App Registration > New Registration**. -3. Enter “Docker Hub SSO” or similar for the application name. -4. Under **Supported account types**, specify who can use this application or access the app. -5. In the **Redirect URI** section, select **Web** from the dropdown menu and paste the **Redirect URI** value from the Docker console into this field. -6. Select **Register** to register the app. -7. Take note of the **Client ID** from the app's overview page. You need this information to continue configuring SSO on Docker Hub. - -### Create client secrets for your Docker app - -1. Go to the Docker Hub SSO app that you created in the previous steps, then select **Certificates & secrets**. -2. Select **+ New client secret**. -3. Specify the description of the secret and set how long the keys can be used on Azure. -4. Select **Add** to continue. -5. Copy the secret **Value** field and keep it somewhere safe so you can use it to configure Docker SSO later on. - -### Configure API permission for Docker SSO and grant admin consent - -1. Go to the Docker Hub SSO app that you created in the previous steps. -2. Navigate to the **API permission** category in your app settings. -3. Select **Grant admin consent for YOUR TENANT NAME > Yes**. -4. Next, you need to add additional permissions. Select **Add a permission**. -5. Select **Delegated permissions**. -6. Then, search for `User.Read`, and select this option. -7. Select **Add permissions**. - -You can verify admin consent was granted for each permission correctly by checking the **Status** column. - -### Assign users to the SSO app - -1. Navigate to your Azure AD dashboard, then select **Enterprise Applications > APP NAME**. -2. Select **1. Assign users and groups**. -3. Add users that will be allowed to use the app. - -In the Docker console, paste the following values obtained in the previous steps to continue configuration: - -- **Client ID** -- **Client Secret** -- **Azure AD Domain** - -{{< /tab >}} -{{< /tabs >}} - -## More resources - -The following videos demonstrate how to configure your IdP with your Docker SSO connection. - -- [Video: SSO connection with Okta](https://youtu.be/c56YECO4YP4?feature=shared&t=633) -- [Video: SSO connection with Azure Connect (OIDC)](https://youtu.be/bGquA8qR9jU?feature=shared&t=630) -- [Video: SSO connection with Entra ID (Azure) SAML](https://youtu.be/bGquA8qR9jU?feature=shared&t=1246) - -## What's next? - -[Complete your connection](../connect/_index.md) in the Docker console, then test your connection. diff --git a/content/manuals/security/for-admins/single-sign-on/connect.md b/content/manuals/security/for-admins/single-sign-on/connect.md index 5096e986650..8ad348061bc 100644 --- a/content/manuals/security/for-admins/single-sign-on/connect.md +++ b/content/manuals/security/for-admins/single-sign-on/connect.md @@ -1,45 +1,208 @@ --- description: Learn how to complete your single-sign on connection and next steps for enabling SSO. keywords: configure, sso, docker hub, hub, docker admin, admin, security -title: Complete your single sign-on connection +title: Create an SSO connection linkTitle: Connect --- -The steps to set up your SSO configuration are: +Creating a single sign-on (SSO) connection requires setting up the connection in Docker first, followed by setting up the connection in your identity provider (IdP). This guide provides steps for setting up your SSO connection in Docker and your IdP. -1. [Add and verify the domain or domains](/security/for-admins/single-sign-on/configure#step-one-add-and-verify-your-domain) that your members use to sign in to Docker. -2. [Create your SSO connection](/security/for-admins/single-sign-on/configure#step-two-create-an-sso-connection-in-docker) in Docker. -3. [Configure your IdP](/security/for-admins/single-sign-on/configure/configure-idp#step-three-configure-your-idp-to-work-with-docker) to work with Docker. -4. [Complete your SSO connection](#step-four-complete-your-sso-connection) in Docker. - -This page walks you through the final steps of creating your SSO connection. You can then test your connection and optionally enforce SSO for your organization. +> [!TIP] +> +> This guide requires copying and pasting values in both Docker and your IdP. To ensure a seamless connection process, complete all the steps in this guide in one session and keep separate browsers open for both Docker and your IdP. ## Prerequisites Make sure you have completed the following before you begin: - Your domain is verified -- You have created your SSO connection in Docker -- You configured your IdP using the appropriate values from your Docker connection -- You have pasted the following from your IdP into the settings in the Docker console: - - SAML: **SAML Sign-on URL**, **x509 Certificate** - - Azure AD (OIDC): **Client ID**, **Client Secret**, **Azure AD Domain** +- You have an account set up with an IdP +- You have completed the steps in the [Configure single sign-on](../single-sign-on/configure.md) guide + +## Step one: Complete an SSO connection in Docker -## Step four: Complete your SSO connection +>[!NOTE] +> +> Before creating an SSO connection in Docker, you must verify at least one domain. {{< tabs >}} {{< tab name="Admin Console" >}} -{{% admin-sso-connect product="admin" %}} +{{< include "admin-early-access.md" >}} + +1. Sign in to the [Admin Console](https://admin.docker.com/). +2. Select your organization or company from the left-hand drop-down menu. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. +3. Under Security and access, select **SSO and SCIM**. +4. Select **Create Connection** and provide a name for the connection. +5. Select an authentication method, **SAML** or **Azure AD (OIDC)**. +6. Copy the following fields to add to your IdP: + - Okta SAML: **Entity ID**, **ACS URL** + - Azure OIDC: **Redirect URL** +7. Keep this window open so you can paste the connection information from your IdP here at the end of this guide. {{< /tab >}} {{< tab name="Docker Hub" >}} -{{% admin-sso-connect product="hub" %}} +1. Sign in to Docker Hub. +2. Select **Organizations** and then your organization from the list. +3. On your organization page, select **Settings** and then **Security**. +4. In the SSO connection table, select **Create Connection** and provide a name for the connection. +5. Select an authentication method, **SAML** or **Azure AD (OIDC)**. +6. Copy the following fields to add to your IdP: + - Okta SAML: **Entity ID**, **ACS URL** + - Azure OIDC: **Redirect URL** +7. Keep this window open so you can paste the connection information from your IdP here at the end of this guide. {{< /tab >}} {{< /tabs >}} +## Step two: Create an SSO connection in your IdP + +The user interface for your IdP may differ slightly from the following steps. Refer to the documentation for your IdP to verify. + +{{< tabs >}} +{{< tab name="Okta SAML" >}} + +1. Sign in to your Okta account. +2. Select **Admin** to open the Okta Admin portal. +3. From the left-hand navigation, select **Administration**. +4. Select **Administration** and then **Create App Integration**. +5. Select **SAML 2.0** and then **Next**. +6. Enter "Docker Hub" as your **App Name**. +7. Optional. Upload a logo. +8. Select **Next**. +9. Enter the following values from Docker into their corresponding Okta fields: + - Docker ACS URL: **Single Sign On URL** + - Docker Entity ID: **Audience URI (SP Entity ID)** +10. Configure the following settings in Okta: + - Name ID format: `EmailAddress` + - Application username: `Email` + - Update application on: `Create and update` +11. Select **Next**. +12. Select the **This is an internal app that we have created** checkbox. +13. Select **Finish**. + +{{< /tab >}} +{{< tab name="Entra ID SAML 2.0" >}} + +1. Sign in to your Azure AD admin portal. +2. Select **Default Directory** and then **Add**. +3. Choose **Enterprise Application** and select **Create your own application**. +4. Enter "Docker" for application name and select the **non-gallery** option. +5. After the application is created, go to **Single Sign-On** and select **SAML**. +6. Select **Edit** on the **Basic SAML configuration** section. +7. Enter the following values from Docker into their corresponding Azure fields: + - Docker Entity ID: **Identifier** + - Docker ACS URL: **Reply URL** +8. Save configuration. +9. From the **SAML Signing Certificate** section, download your **Certificate (Base64)**. + +{{< /tab >}} +{{< tab name="Azure Connect (OIDC)" >}} + +To create an Azure Connect (OIDC) connection, you must create an app registration, client secrets, and configure API permissions for Docker: + +### Create app registration + +1. Sign in to your Azure AD admin portal. +2. Select **App Registration** and then **New Registration**. +3. Enter "Docker Hub SSO" or similar for application name. +4. Under **Supported account types**, specify who can use this application or access the app. +5. In the **Redirect URI** section, select **Web** from the drop-down menu and paste the **Redirect URI** value from the Docker console into this field. +6. Select **Register** to register the app. +7. Copy the **Client ID** from the app's overview page. You need this information to continue configuring SSO in Docker. + +### Create client secrets + +1. Open your app in Azure AD and select **Certificates & secrets**. +2. Select **+ New client secret**. +3. Specify the description of the secret and set how long keys can be used. +4. Select **Add** to continue. +5. Copy the secret **Value** field. You need this to continue configuring SSO in Docker. + +## Configure API permissions + +1. Open your app in Azure AD and navigate to your app settings. +2. Select **API permission** and then **Grant admin consent for [your tenant name]**. +3. Select **Yes** to confirm. +4. After confirming, select **Add a permission** and then **Delegated permissions**. +5. Search for `User.Read` and select this option. +6. Select **Add permissions** to confirm. +7. Verify admin consent was granted for each permission by checking the **Status** column. + +{{< /tab >}} +{{< /tabs >}} + +## Step three: Connect Docker and your IdP + +After creating your connection in Docker and your IdP, you can cross-connect them to complete your SSO connect: + +{{< tabs >}} +{{< tab name="Okta SAML" >}} + +1. Open your app you created in Okta and select **View SAML setup instructions**. +2. Copy the following values from the Okta SAML setup instruction page: + - **SAML Sign-in URL** + - **x509 Certificate** +3. Open Docker Hub or the Admin Console. Your SSO configuration page should still be open from Step one of this guide. +4. Select **Next** to open the **Update single-sign on connection** page. +5. Paste your Okta **SAML Sign-in URL** and **x509 Certificate** values in Docker. +6. Select **Next** to complete the SSO connection. + +{{< /tab >}} +{{< tab name="Entra ID SAML 2.0" >}} + +1. Open your app in Azure AD. +2. Open your downloaded **Certificate (Base64)** in a text editor. +3. Copy the following values: + - From Azure AD: **Login URL** + - Copy your the contents of your **Certificate (Base64)** file from your text editor +4. Open Docker Hub or the Admin Console. Your SSO configuration page should still be open from Step one of this guide. +5. Paste your **Login URL** and **Certificate (Base64)** values in Docker. +6. Select **Next** to complete the SSO connection. + +{{< /tab >}} +{{< tab name="Azure Connect (OIDC)" >}} + +1. Open Docker Hub or the Admin Console. Your SSO configuration page should still be open from Step one of this guide. +2. Paste the following values from Azure AD in to Docker: + - **Client ID** + - **Client Secret** + - **Azure AD Domain** +3. Select **Next** to complete the SSO connection. + +{{< /tab >}} +{{< /tabs >}} + +## Step four: Test your connection + +After you've completed the SSO connection process in Docker, we recommend testing it: + +1. Open an incognito browser. +2. Sign in to the Admin Console using your **domain email address**. +3. The browser will redirect to your IdP's login page to authenticate. +4. Authenticate through your domain email instead of using your Docker ID. + +You can also test your SSO connection through the command-line interface (CLI). If you want to test through the CLI, your users must have a personal access token (PAT). + + +## Optional: Enforce SSO + +>[!IMPORTANT] +> +> If SSO isn't enforced, users can choose to sign in with either their Docker username and password or SSO. + +Enforcing SSO requires users to use SSO when signing into Docker. This centralizes authentication and enforces policies set by the IdP. + +1. Sign in to the [Admin Console](https://admin.docker.com/). +2. Select your organization or company from the left-hand drop-down menu. Note that when an organization is part of a company, you must select the company and configure the domain for the organization at the company level. +3. Under Security and access, select **SSO and SCIM**. +4. In the SSO connections table, select the **Action** icon and then **Enable enforcement**. When SSO is enforced, your users are unable to modify their email address and password, convert a user account to an organization, or set up 2FA through Docker Hub. If you want to use 2FA, you must enable 2FA through your IdP. +5. Continue with the on-screen instructions and verify you've completed all tasks. +6. Select **Turn on enforcement** to complete. + +Your users must now sign in to Docker with SSO. + ## More resources The following videos demonstrate how to enforce SSO. @@ -50,4 +213,5 @@ The following videos demonstrate how to enforce SSO. ## What's next -Learn how you can [manage your SSO connection](../single-sign-on/manage.md), domain, and users for your organization or company. +- [Provision users](../provisioning/_index.md) +- [Enforce sign-in](../enforce-sign-in/_index.md) diff --git a/content/manuals/security/for-admins/single-sign-on/troubleshoot.md b/content/manuals/security/for-admins/single-sign-on/troubleshoot.md index 68e5490e1a7..630da9fe3d3 100644 --- a/content/manuals/security/for-admins/single-sign-on/troubleshoot.md +++ b/content/manuals/security/for-admins/single-sign-on/troubleshoot.md @@ -97,9 +97,7 @@ Possible solutions: * Make sure the IdP SSO connection is returning the correct UPN value as part of the assertion attributes (attributes mapping). * Add and verify all domains and subdomains that are used as UPN by your IdP - and associate them to your Docker SSO connection. For more details, see [Add - and verify your - domain](/security/for-admins/single-sign-on/configure/#step-one-add-and-verify-your-domain). + and associate them to your Docker SSO connection. For more details, see [Configure single sign-on](../single-sign-on/configure.md). ### Unable to find session diff --git a/content/manuals/security/security-announcements.md b/content/manuals/security/security-announcements.md index f19466c4448..ddabcc75081 100644 --- a/content/manuals/security/security-announcements.md +++ b/content/manuals/security/security-announcements.md @@ -24,7 +24,7 @@ We strongly encourage you to update to Docker Desktop [4.34.2](https://docs.dock _Last updated July, 2024_ -When [SSO enforcement](/security/for-admins/single-sign-on/connect/#optional-enforce-sso) was first introduced, Docker provided a grace period to continue to let passwords be used on the Docker CLI when authenticating to Docker Hub. This was allowed so organizations could more easily use SSO enforcement. It is recommended that administrators configuring SSO encourage users using the CLI [to switch over to Personal Access Tokens](/security/for-admins/single-sign-on/#prerequisites) in anticipation of this grace period ending. +When [SSO enforcement](/manuals/security/for-admins/single-sign-on/connect.md) was first introduced, Docker provided a grace period to continue to let passwords be used on the Docker CLI when authenticating to Docker Hub. This was allowed so organizations could more easily use SSO enforcement. It is recommended that administrators configuring SSO encourage users using the CLI [to switch over to Personal Access Tokens](/security/for-admins/single-sign-on/#prerequisites) in anticipation of this grace period ending. On September 16, 2024 the grace period will end and passwords will no longer be able to authenticate to Docker Hub via the Docker CLI when SSO is enforced. Affected users are required to switch over to using PATs to continue signing in. From 37524649fe974a8012051d3773d6b325e063928b Mon Sep 17 00:00:00 2001 From: Sarah Sanders Date: Tue, 22 Oct 2024 16:55:19 -0700 Subject: [PATCH 2/6] Small typo and formatting fixes --- content/manuals/security/for-admins/single-sign-on/connect.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/security/for-admins/single-sign-on/connect.md b/content/manuals/security/for-admins/single-sign-on/connect.md index 8ad348061bc..25213af791b 100644 --- a/content/manuals/security/for-admins/single-sign-on/connect.md +++ b/content/manuals/security/for-admins/single-sign-on/connect.md @@ -120,7 +120,7 @@ To create an Azure Connect (OIDC) connection, you must create an app registratio 4. Select **Add** to continue. 5. Copy the secret **Value** field. You need this to continue configuring SSO in Docker. -## Configure API permissions +### Configure API permissions 1. Open your app in Azure AD and navigate to your app settings. 2. Select **API permission** and then **Grant admin consent for [your tenant name]**. @@ -213,5 +213,5 @@ The following videos demonstrate how to enforce SSO. ## What's next -- [Provision users](../provisioning/_index.md) +- [Provision users](/manuals/security/for-admins/provisioning/_index.md) - [Enforce sign-in](../enforce-sign-in/_index.md) From ebc43b2739bc7be0a4083ca541b54574a80721a3 Mon Sep 17 00:00:00 2001 From: Sarah Sanders Date: Wed, 23 Oct 2024 08:57:11 -0700 Subject: [PATCH 3/6] Update cross-connect steps --- .../security/for-admins/single-sign-on/connect.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/content/manuals/security/for-admins/single-sign-on/connect.md b/content/manuals/security/for-admins/single-sign-on/connect.md index 25213af791b..c99a74fede5 100644 --- a/content/manuals/security/for-admins/single-sign-on/connect.md +++ b/content/manuals/security/for-admins/single-sign-on/connect.md @@ -147,7 +147,9 @@ After creating your connection in Docker and your IdP, you can cross-connect the 3. Open Docker Hub or the Admin Console. Your SSO configuration page should still be open from Step one of this guide. 4. Select **Next** to open the **Update single-sign on connection** page. 5. Paste your Okta **SAML Sign-in URL** and **x509 Certificate** values in Docker. -6. Select **Next** to complete the SSO connection. +6. Select **Next**. +7. Optional. Select a default team to provision users to and select **Next**. +8. Verify your SSO connection details and select **Create Connection**. {{< /tab >}} {{< tab name="Entra ID SAML 2.0" >}} @@ -159,7 +161,9 @@ After creating your connection in Docker and your IdP, you can cross-connect the - Copy your the contents of your **Certificate (Base64)** file from your text editor 4. Open Docker Hub or the Admin Console. Your SSO configuration page should still be open from Step one of this guide. 5. Paste your **Login URL** and **Certificate (Base64)** values in Docker. -6. Select **Next** to complete the SSO connection. +6. Select **Next**. +7. Optional. Select a default team to provision users to and select **Next**. +8. Verify your SSO connection details and select **Create Connection**. {{< /tab >}} {{< tab name="Azure Connect (OIDC)" >}} @@ -169,7 +173,9 @@ After creating your connection in Docker and your IdP, you can cross-connect the - **Client ID** - **Client Secret** - **Azure AD Domain** -3. Select **Next** to complete the SSO connection. +3. Select **Next**. +7. Optional. Select a default team to provision users to and select **Next**. +8. Verify your SSO connection details and select **Create Connection**. {{< /tab >}} {{< /tabs >}} From 0a5b91bcbb842539ae42062b0974184030fc52d9 Mon Sep 17 00:00:00 2001 From: Sarah Sanders Date: Wed, 23 Oct 2024 09:01:12 -0700 Subject: [PATCH 4/6] Fixed numbered list issue --- content/manuals/security/for-admins/single-sign-on/connect.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/security/for-admins/single-sign-on/connect.md b/content/manuals/security/for-admins/single-sign-on/connect.md index c99a74fede5..03ba43fa837 100644 --- a/content/manuals/security/for-admins/single-sign-on/connect.md +++ b/content/manuals/security/for-admins/single-sign-on/connect.md @@ -174,8 +174,8 @@ After creating your connection in Docker and your IdP, you can cross-connect the - **Client Secret** - **Azure AD Domain** 3. Select **Next**. -7. Optional. Select a default team to provision users to and select **Next**. -8. Verify your SSO connection details and select **Create Connection**. +4. Optional. Select a default team to provision users to and select **Next**. +5. Verify your SSO connection details and select **Create Connection**. {{< /tab >}} {{< /tabs >}} From 1aeb546f7995db397e3c3d13f8c2c39fdd29f9ae Mon Sep 17 00:00:00 2001 From: Sarah Sanders Date: Thu, 24 Oct 2024 15:07:20 -0700 Subject: [PATCH 5/6] Update content/manuals/security/for-admins/single-sign-on/connect.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/manuals/security/for-admins/single-sign-on/connect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/security/for-admins/single-sign-on/connect.md b/content/manuals/security/for-admins/single-sign-on/connect.md index 03ba43fa837..7e950126e52 100644 --- a/content/manuals/security/for-admins/single-sign-on/connect.md +++ b/content/manuals/security/for-admins/single-sign-on/connect.md @@ -135,7 +135,7 @@ To create an Azure Connect (OIDC) connection, you must create an app registratio ## Step three: Connect Docker and your IdP -After creating your connection in Docker and your IdP, you can cross-connect them to complete your SSO connect: +After creating your connection in Docker and your IdP, you can cross-connect them to complete your SSO connection: {{< tabs >}} {{< tab name="Okta SAML" >}} From 07d6ce0f4b139dba807c76323c273956f7827192 Mon Sep 17 00:00:00 2001 From: Sarah Sanders Date: Thu, 24 Oct 2024 15:07:34 -0700 Subject: [PATCH 6/6] Update content/manuals/security/for-admins/single-sign-on/connect.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/manuals/security/for-admins/single-sign-on/connect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/security/for-admins/single-sign-on/connect.md b/content/manuals/security/for-admins/single-sign-on/connect.md index 7e950126e52..1c95c487975 100644 --- a/content/manuals/security/for-admins/single-sign-on/connect.md +++ b/content/manuals/security/for-admins/single-sign-on/connect.md @@ -19,7 +19,7 @@ Make sure you have completed the following before you begin: - You have an account set up with an IdP - You have completed the steps in the [Configure single sign-on](../single-sign-on/configure.md) guide -## Step one: Complete an SSO connection in Docker +## Step one: Create an SSO connection in Docker >[!NOTE] >