| description | keywords | title | toc_max |
|---|---|---|---|
Single Sign-on FAQs |
Docker, Docker Hub, SSO FAQs, single sign-on |
Single Sign-on FAQs |
2 |
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.
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.
You can enable SSO on organizations that are part of the Docker Business subscription.
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{:target="blank" rel="noopener" class=""}.
For step by step instructions, see Configure Single Sign-on.
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
Yes. You must delete your existing IdP configuration in Docker Hub and follow the instructions to configure SSO using your IdP.
Docker SSO is only available with the Docker Business subscription. Upgrade{:target="blank" rel="noopener" class=""} your existing subscription to start using Docker SSO.
When SSO is being used by an organization, MFA is determined at the idP level and not the Docker system.
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 for CLI and API usage.
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
Yes. You must verify a domain before using it with an SSO connection.
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. 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.
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.
Yes, all users in your organization must upgrade to Docker Desktop version 4.4.2 or higher. Users on older versions of Docker Desktop will not be able to sign in after enforcing SSO.
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.
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.
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.
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.
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
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.
When SSO is enabled and enforced, your users just have to sign in using the email address and password.
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.
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.
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.
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.