More Docker. Easy Access. New Streamlined Plans. Learn more.

Create an SSO connection

Subscription: Business
For: Administrators

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.

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 an account set up with an IdP
  • You have completed the steps in the Configure single sign-on guide

Step one: Create an SSO connection in Docker

Availability: The Admin Console is in Early Access

Note

Before creating an SSO connection in Docker, you must verify at least one domain.


  1. Sign in to the Admin Console.
  2. Select your organization or company from the Choose profile page. 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.

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.


  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.

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 connection:


  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.
  7. Optional. Select a default team to provision users to and select Next.
  8. Verify your SSO connection details and select Create Connection.

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.
  2. Select your organization or company from the Choose profile page. 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.

Note

When SSO is enforced, users can't use passwords to access the Docker CLI. Users must use a personal access token (PAT) for authentication to access the Docker CLI.

More resources

The following videos demonstrate how to enforce SSO.

What's next