Complete your single sign-on connection

Table of contents

The steps to set up your SSO configuration are:

  1. Add and verify the domain or domains that your members use to sign in to Docker.
  2. Create your SSO connection in Docker.
  3. Configure your IdP to work with Docker.
  4. 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.

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

Step four: Complete your SSO connection

Beta feature

Optional Just-in-Time (JIT) provisioning is available in Private Beta when you use the Admin Console. If you're participating in this program, you have the option to turn off this default provisioning and disable JIT. This configuration is recommended if you're using SCIM to auto-provision users. See SSO authentication with JIT provisioning disabled.

  1. In the Admin Console, select the verified domains you want to apply the connection to.

  2. To provision your users, select the organization(s) and/or team(s).

  3. Beta feature - Choose how you want to provision users by enabling Just-in-Time (JIT) provisioning (default), or disabling JIT provisioning.

  4. Review your summary and select Create Connection.

Test your SSO configuration

After you’ve completed the SSO configuration process in Docker, you can test the configuration when you sign in to the Admin Console using an incognito browser. Sign in to the Admin Console using your domain email address. You are then redirected to your IdP's login page to authenticate.

  1. Authenticate through email instead of using your Docker ID, and test the login process.
  2. To authenticate through CLI, your users must have a PAT before you enforce SSO for CLI users.

Important

SSO has Just-in-Time (JIT) provisioning enabled by default, unless you have disabled it. This means your users are auto-provisioned to your organization on Docker Hub.

You can change this on a per-app basis. To prevent auto-provisioning users, you can create a security group in your IdP and configure the SSO app to authenticate and authorize only those users that are in the security group. Follow the instructions provided by your IdP:

The SSO connection is now created. You can continue to set up SCIM without enforcing SSO log-in. For more information about setting up SCIM, see Set up SCIM.

Optional: Enforce SSO

  1. Sign in to the Admin Console.

  2. Select your organization or company in the left navigation drop-down menu, and then select SSO & SCIM.

  3. 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. You must enable 2FA through your IdP.

  4. Continue with the on-screen instructions and verify that you’ve completed the tasks.

  5. Select Turn on enforcement to complete.

Your users must now sign in to Docker with SSO.

Important

If SSO isn't enforced, users can choose to sign in with either their Docker ID or SSO.

  1. In Docker Hub, select the verified domains you want to apply the connection to.
  2. To provision your users, select the organization(s) and/or team(s).
  3. Review your summary and select Create Connection.

Test your SSO configuration

After you’ve completed the SSO configuration process in Docker, you can test the configuration when you sign in to Docker Hub using an incognito browser. Sign in to Docker Hub using your domain email address. You are then redirected to your IdP's login page to authenticate.

  1. Authenticate through email instead of using your Docker ID, and test the login process.
  2. To authenticate through CLI, your users must have a PAT before you enforce SSO for CLI users.

Important

SSO has Just-in-Time (JIT) provisioning enabled by default, unless you have disabled it. This means your users are auto-provisioned to your organization on Docker Hub.

You can change this on a per-app basis. To prevent auto-provisioning users, you can create a security group in your IdP and configure the SSO app to authenticate and authorize only those users that are in the security group. Follow the instructions provided by your IdP:

The SSO connection is now created. You can continue to set up SCIM without enforcing SSO log-in. For more information about setting up SCIM, see Set up SCIM.

Optional: Enforce SSO

  1. Sign in to Docker Hub.

  2. Navigate to the SSO settings page for your organization or company.

    • Organization: Select Organizations, your organization, Settings, and then Security.
    • Company: Select Organizations, your company, and then Settings.

  3. 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. You must enable 2FA through your IdP.

  4. Continue with the on-screen instructions and verify that you’ve completed the tasks.

  5. Select Turn on enforcement to complete.

Your users must now sign in to Docker with SSO.

Important

If SSO isn't enforced, users can choose to sign in with either their Docker ID or SSO.

More resources

The following videos demonstrate how to enforce SSO.

What's next

Learn how you can manage your SSO connection, domain, and users for your organization or company.