Updated SSO (#13977)

* Updated SSO

* Fixed links

* fixed broken link

* updated SSO link

* Apply suggestions from code review

Co-authored-by: Usha Mandya <47779042+usha-mandya@users.noreply.github.com>

* updated prerequisite

Co-authored-by: Usha Mandya <47779042+usha-mandya@users.noreply.github.com>

Single-Sign-on/faqs.md

@@ -0,0 +1,162 @@
+---
+description: Single Sign-on FAQs
+keywords: Docker, Docker Hub, SSO FAQs, single sign-on
+title: Single Sign-on FAQs
+toc_max: 2
+---
+
+## General
+
+### Q: How does Docker SSO work?
+
+Docker Single Sign-on (SSO) allows users to authenticate using their identity providers (IdPs) to access Docker. Docker currently supports Azure AD and identity providers that support SAML 2.0. When you enable SSO, users are redirected to your provider’s authentication page to authenticate using their email and password.
+
+### Q: What SSO flows are supported by Docker?
+
+Docker currently supports Service Provider Initiated (SP-initiated) SSO flow. This means, users must sign in to Docker Hub or Docker Desktop to initiate the SSO authentication process.
+
+### Q: Can I enable SSO in all organizations?
+
+You can enable SSO on organizations that are part of the Docker Business subscription.
+
+### Q: We currently have a Docker Team subscription. How do we enable SSO?
+
+Docker SSO is available with a Docker Business subscription. To enable SSO, you must first upgrade your subscription to a Docker Business subscription. To learn how to upgrade your existing account, see [Upgrade your subscription](/subscription/upgrade/){:target="blank" rel="noopener" class=""}.
+
+### Q: Where can I find detailed instructions on how to configure Docker SSO?
+
+For step by step instructions, see [Configure Single Sign-on](index.md).
+
+### Q: Is it possible to use more than one IdP with Docker SSO?
+
+No. You can only configure Docker SSO to work with a single IdP. A domain can only be associated with a single IdP.Docker currently supports Azure AD and identity providers that support SAML 2.0
+
+### Q: Is it possible to change my identity provider after configuring SSO?
+
+Yes. You must delete your existing IdP configuration in Docker Hub and follow the instructions to [configure SSO](index.md) using your IdP.
+
+###  Q: Is Docker SSO available for all paid subscriptions?
+
+Docker SSO is only available with the Docker Business subscription. [Upgrade](/subscription/upgrade/){:target="blank" rel="noopener" class=""} your existing subscription to start using Docker SSO.
+
+### Q: Does Docker SSO support multi-factor authentication (MFA)?
+
+When SSO is being used by an organization, MFA is determined at the idP level and not the Docker system.
+
+### Q: How does service accounts work with SSO?
+
+Service accounts work like any other user when SSO is turned on. If the service account is using an email for a domain with SSO turned on, it needs a [PAT](/docker-hub/access-tokens/) for CLI and API usage.
+
+
+## Configuration
+
+### Q: What information do I need from my Identity providers to configure SSO?
+
+To enable SSO in Docker, you need the following from your IdP:
+
+* **SAML 2.0**: Entity ID, ACS URL, Single Logout URL and Certificate Download URL
+* **Azure AD**: Client ID, Client Secret, AD Domain
+
+### Q: Is DNS verification required to enable SSO?
+
+Yes. You must verify a domain before using it with an SSO connection.
+
+### Q: Does Docker SSO support authenticating through the command line?
+
+Yes. When SSO is enabled, you can access the Docker CLI through Personal Access Tokens (PATs).  Each user must create a PAT to access the CLI. To learn how to create a PAT, see [Managing access tokens](/docker-hub/access-tokens/). Before we transition to PATs, CLI can continue logging in using their personal credentials until early next year to mitigate the risk of interrupting CI/CD pipelines.
+
+###  Q:  How does SSO affect our automation systems and CI/CD pipelines?
+
+Before enforcing SSO, you must create PATs for automation systems and CI/CD pipelines and use the tokens instead of a password.
+
+When SSO is enforced, password-based authentication no longer works on your automation systems and CI/CD pipelines.
+
+### Q: Do I need a specific version of Docker Desktop for SSO?
+
+Yes, all users in your organization must upgrade to Docker Desktop version 4.4.0 or higher. Users on older versions of Docker Desktop will not be able to sign in after enforcing SSO.
+
+### Q: Does SAML authentication require additional attributes?
+
+You must provide an email address as an attribute to authenticate via SAML. The ‘Name’ attribute is currently optional.
+
+### Q: When SAML SSO is enforced, at what stage is the login required to be tracked through SAML? At runtime or install time?
+
+Runtime for Docker Desktop if it’s configured to require authentication to the organization.
+
+## Managing users
+
+### Q: How do I manage users when using SSO?
+
+Users are managed through organizations in Docker Hub. When you configure SSO in Docker, you need to make sure an account exists for each user in your IdP account. When a user signs into Docker for the first time using their domain email address, they will be automatically added to the organization after a successful authentication.
+
+### Q: Do I need to manually add users to my organization?
+
+No, you don’t need to manually add users to your organization in Docker Hub. You just need to make sure an account for your users exists in your IdP and then invite them to your organization using the **Invite Member** option in Docker Hub.
+
+When a user signs into Docker for the first time using their domain email address, they will be automatically added to the organization after a successful authentication.
+
+### Q: Can users in my organization use different email addresses to authenticate via SSO?
+
+During the SSO setup, you’ll have to specify the company email domains that are allowed to authenticate. All users in your organization must authenticate using the email domain specified during SSO setup. Some of your users may want to maintain a different account for their personal projects.
+
+Users with a public domain email address will be added as guests.
+
+### Q: Can Docker Org Owners/Admins approve users to an organization and use a seat, rather than having them automatically added when SSO Is enabled?
+
+Admins and organization owners can currently approve users by configuring their permissions through their IdP. That is, if the user account is configured in the IdP, the user will be automatically added to the organization in Docker Hub as long as there’s an available seat.
+
+### Q: How will users be made aware that they are being made a part of a Docker Org?
+
+When SSO is enabled, users will be prompted to authenticate through SSO the next time they try to sign in to Docker Hub or Docker Desktop. The system will see the end-user has a domain email associated with the docker ID they are trying to authenticate with, and prompts them to sign in with SSO email and credentials instead.
+
+If users attempt to log in through the CLI, they must authenticate using a personal access token (PAT).
+
+### Q: Is it possible to force users of Docker Desktop to authenticate, and/or authenticate using their company’s domain?
+
+Yes. Admins can force users to authenticate with Docker Desktop by provisioning a registry.json configuration file. The registry.json file will force users to authenticate as a user that is configured in the **allowedOrgs** list in the **registry.json file**.
+
+Once SSO enforcement is set up on their DB org on Hub, when the user is forced to auth with Docker Desktop, the SSO enforcement will also force users to authenticate through SSO with their IdP (instead of authenticating using their username and password).
+
+Users may still be able to authenticate as a "guest" account to the organization using a non-domain email address. However, they can only authenticate as guests if that non-domain email was invited to the organization by the organization owner
+
+### Q: Is it possible to convert existing users from non-SSO to SSO accounts?
+
+Yes, you can convert existing users to an SSO account. To convert users from a non-SSO account:
+
+* Ensure your users have a company domain email address and they have an account in your IdP
+* Verify that all users have Docker Desktop version 4.4.0 or higher installed on their machines
+* Each user has created a PAT to replace their passwords to allow them to log in through Docker CLI
+* Confirm that all CI/CD pipelines automation systems have replaced their passwords with PATs.
+
+For detailed prerequisites and for instructions on how to enable SSO, see [Configure Single Sign-on](index.md).
+
+### Q: What impact can users expect once we start onboarding them to SSO accounts?
+
+When SSO is enabled and enforced, your users just have to sign in using the email address and password.
+
+### Q: Is Docker SSO fully synced with Active Directory (AD)?
+
+Docker doesn’t currently support a full sync with AD. That is, if a user leaves the organization, administrators must sign in to Docker Hub and manually remove the user from the organization.
+
+Additionally, you can use our APIs to complete this process.
+
+
+## Troubleshooting
+
+### Q: What happens if my IdP goes down when SSO is enabled?
+
+It is not possible to access Docker Hub when your IdP is down. However, you can access Docker Hub images from the CLI using your Personal Access Token. Or, if you had an existing account before the SSO enforcement, you can use your username and password to access Docker Hub images during the grace period for your organization.
+
+### Q: What happens when I turn off SSO for my organization?
+
+When you turn off SSO, authentication through your Identity Provider will no longer be required to access Docker. Users may continue to log in through Single Sign-On as well as Docker ID and password.
+
+### Q: What happens if my existing certificate expires?
+
+If your existing certificate has expired, you need to contact your identity provider to generate a new x509 certificate. The new certificate must be added to the SSO configuration settings page on Docker Hub.
+
+
+
+
+
+

Single-Sign-on/index.md

@@ -0,0 +1,97 @@
+---
+description: Single Sign-on
+keywords: Single Sign-on, SSO, sign-on
+title: Configure Single Sign-on
+---
+
+Docker Single Sign-on (SSO) allows users to authenticate using their identity providers (IdPs) to access Docker. Docker currently supports SAML 2.0 and Azure AD IdPs through Auth0. You can enable SSO on organization's that are part of the Docker Business subscription. To upgrade your existing account to a Docker Business subscription, see [Upgrade your subscription](../subscription/upgrade/){:target="blank" rel="noopener" class=""}.
+
+When SSO is enabled, users are redirected to your provider’s authentication page to authenticate using SSO. They cannot authenticate using their personal login credentials (Docker ID and password).
+
+Before enabling SSO in Docker Hub, administrators must work with their identity provider to configure their IdP to work with Docker Hub. Docker provides the Assertion Consumer Service (ACS) URL and the Entity ID. Administrators use this information to establish a connection between their IdP server and Docker Hub.
+
+After establishing the connection between the IdP server and Docker Hub, administrators log into the organization in Docker Hub and complete the SSO enablement process. See the section Enable SSO in Docker Hub for detailed instructions.
+
+To enable SSO in Docker Hub, you need the following:
+
+* **SAML 2.0**: Entity ID, ACS URL, Single Logout URL and Certificate Download URL
+* **Azure AD**: Client ID (a unique identifier for your registered AD application), Client Secret (a string used to gain access to your registered Azure AD application), and AD Domain details
+
+We currently support enabling SSO on a single organization. If you have any users in your organization with a different domain (including social domains), they will be added to the organization as guests.
+
+## SSO prerequisites
+
+* You must first notify your company about the new SSO login procedures. Some of your users may want to maintain a different account for their personal projects.
+* Verify that your org members have Docker Desktop version 4.4.0 installed on their machines.
+* Each org member must [create a Personal Access Token] (PAT)  to replace their passwords.
+* Confirm that all CI/CD pipelines have replaced their passwords with PATs.
+* Test SSO using your domain email address and IdP password to successfully log in and log out of Docker Hub.
+
+## Configure SSO
+
+To configure SSO, log into [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"} to obtain the **ACS URL** and **Entity IDs** to complete the IdP server configuration process. You can only configure SSO with a single IdP.  When this is complete, log back into [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"} and complete the SSO enablement process.
+
+### Identity provider configuration
+
+1. Log into [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"} as an administrator and navigate to Organizations and select the organization that you want to enable SSO on.
+2. Click **Settings** and select the Security tab.
+3. Select an authentication method based on your identity provider.
+    Note: Docker currently supports **SAML 2.0** and **Azure AD**.
+4. Copy the ID and/or URL in the **Identity Provider Set Up**.
+    Note: for SAML 2.0, copy the Entity ID and ACS URL. For Azure AD, copy your Redirect URL/Reply URL.
+5. Log into your IdP to complete the IdP server configuration process. Refer to your IdP documentation for detailed instructions.
+6. Complete the fields in the **Configuration Settings** section and click **Save**.
+
+![SSO SAML](images/sso-saml.png){:width="500px"}
+
+### Domain
+
+1. Click **Add Domain** and specify the email domains that are allowed to authenticate via your server.
+    Note: This should include all email domains users will use to access Docker. Public domains are not permitted, such as gmail.com, outlook.com, etc. Also, the email domain should be set as the primary email.
+2. Click **Send Verification** to receive an email for the domains you have specified and verify your domain.
+
+### Test your SSO configuration
+
+After you’ve completed the SSO configuration process in Docker Hub, you can test the configuration when you log into Docker Hub using an incognito browser. Login using your domain email address and IdP password.  You will then get redirected to your identity provider’s login page to authenticate.
+
+1. Authenticate via email instead of using your Docker ID, and test the login process.
+2. To authenticate via CLI, your users must have a PAT before you enforce SSO for CLI users.
+
+## Enforce SSO in Docker Hub
+
+Before you enforce SSO in Docker Hub, you must complete the following:
+Test SSO by logging in and out successfully, confirm that all members in your org have upgraded to Docker Desktop version 4.4.0, PATs are created for each member,  CI/CD passwords are converted to PAT.
+
+Admins can force users to authenticate with Docker Desktop by provisioning a registry.json configuration file. The registry.json file will force users to authenticate as a user that is configured in the allowedOrgs list in the registry.json file. For info on how to configure a registry.json file see Configure registry.json.
+
+1. On the Single Sign-On page in Docker Hub, click **Turn ON Enforcement** to enable your SSO.
+2. When SSO is enforced, your members are unable to modify their email address and password, convert a user account to an organization, or set up 2FA through Docker Hub. You must enable 2FA through your IdP.
+    Note: If you want to turn off SSO and revert back to Docker’s built-in authentication, click **Turn OFF Enforcement**. Your members aren’t forced to authenticate through your IdP and can log into Docker using their personal credentials.
+
+    ![Enforced](images/sso-enforce.png){:width="500px"}
+
+## Managing users when SSO is enabled
+
+To add a member to your organization:
+1. Create an account for your members in your IdP.
+2. Add and invite your members to your organization.
+    Note: when the first-time user logs into Docker using their domain email address, they are then added to your organization.
+
+To add a guest to your organization in Docker Hub if they aren’t verified through your IdP:
+
+1. Go to **Organizations** in Docker Hub, and select your organization.
+2. Click **Add Member**, enter the email address, and select a team from the drop-down list.
+3. Click **Add** to confirm.
+
+## Remove members from the SSO organization
+
+To remove a member from an organization:
+
+1. Log into Docker Hub as an administrator of your organization.
+Select the organization from the list. The organization page displays a list of members.
+2. Click the **x** next to a member’s name to remove them from all the teams in the organization.
+3. Click **Remove** to confirm. The member will receive an email notification confirming the removal.
+    Note: when you remove a member from an SSO organization, they are unable to log in using their email address.
+
+## FAQs
+To learn more see our [FAQs](faqs.md).

_data/toc.yaml

@@ -1352,6 +1352,12 @@ manuals:
             title: Recover your Docker Hub account
           - path: /docker-hub/2fa/new-recovery-code/
             title: Generate a new recovery code
+      - sectiontitle: Single-Sign-on
+        section:
+          -  path: /single-sign-on/
+             title: Configure Single Sign-on
+          -  path: /single-sign-on/faqs/
+             title: Single Sign-on Faqs
   - path: /docker-hub/download-rate-limit/
     title: Download rate limit
   - sectiontitle: Administration