In this blog post, we'll explore how to configure Docker Hub Single Sign-On (SSO) with Azure OpenID Connect (OIDC). Docker Hub SSO enables users to access Docker Hub and other services with a single set of credentials. By integrating Docker Hub SSO with Azure OIDC, you can simplify the authentication process and improve security by leveraging Azure's identity management capabilities. We'll cover the steps involved in configuring Docker Hub SSO with Azure OIDC, including setting up an Azure AD tenant, configuring the Docker Hub SSO settings, and testing the SSO integration. By the end of this blog post, you'll have a comprehensive understanding of how to configure Docker Hub SSO with Azure OIDC, enabling you to streamline access to Docker Hub and other services for your users.

Azure OIDC Login Flow

Azure OpenID Connect (OIDC), a popular authentication protocol, builds upon the OAuth2 authorization protocol to provide standardized message flows for identity services. Its goal is to simplify the authentication process for developers, enabling them to verify the user's identity across various applications without managing password files. For secure authentication, a trusted agent is required to check the user's session or credentials, often provided through a system browser for native apps. Additionally, OIDC allows for consent-based access to protected resources, which only needs to be granted once and remains valid until manually revoked by the user or admin. The figure below shows the SSO login flow with Azure OIDC.

OIDC expands the functionality of the OAuth 2.0 authorization protocol by serving as an additional authentication protocol. By utilizing an ID token security token, OIDC enables single sign-on (SSO) between applications that use OAuth, simplifying the authentication process.

Before configuring Docker Hub SSO with Azure OIDC, its worth to note the requirements you will need to configure both from Docker Hub and Azure. Here's the list of requirements you will need to configure Docker Hub SSO with Azure OIDC.

Requirements

1. Azure Subscription with an Azure AD configured (Users base + preferrably configured with custom domain) - obviously with the right RBAC permission to configure AAD tenant.
2. Domain Name - in this tutorial, I will be using the azureoidc.ga domain. You can use other Domain Host such as Azure DNS Zone, Cloudflare or even an in-house Domain Host service from your domain registrar.
3. Docker Business subscription - This is the most important part before configuring SSO. SSO and SCIM features are only available to Docker Business subscribers only.

There are a few steps to configure Docker Hub SSO with Azure OIDC. The steps are listed as shown below:

1. Create App Registration for Docker Hub App on Azure AD
   
2. Create Client Secrets for Docker Hub SSO App
   
3. Configure API permission for Docker Hub SSO to grant admin consent for Azure AD tenant.
   
4. Assigning users to the SSO App.
   
5. Configure SSO connection on Docker Hub
   
6. Enforce SSO for users (optional)
   
7. Test the SSO connection
   

Go to Azure AD portal and click on “App Registration” > “New Registration”

Name the App to “Docker Hub SSO” or pick any name you wish for the app. You also need to specify the configuration for:

1. Who can use this application or access the app.

2. Redirect URI - fill in the URI field with https://login.docker.com/login/callback (obtained from Docker Hub SSO config page) and select “Web” from the dropdown menu.

Please take note of the Client ID from the App’s overview Page. We will need this information to configure SSO on Docker Hub later on.

B. Create Client Secrets for Docker Hub SSO App

Navigate to the Docker Hub SSO App and click on the “Certificates & Secrets” section and Click on “Client secrets” > “+ New Client Secret”

C. Configure API permission for Docker Hub SSO to grant admin consent for Azure AD tenant.

Navigate to “API Permission” category on the Docker Hub SSO App settings and click on “Grant admin consent for [AAD Tenant Name]” > “Yes”

D. Assigning users to the SSO App.

Navigate to Azure AD dashboard and click on Enterprise Applications > [App Name]

E. Configure SSO connection on Docker Hub

Navigate to the Docker Hub SSO configuration page and click on Azure AD (OIDC) as the authentication method.

Add the Azure AD domain and verify it from the configuration page. You need to paste the TXT record into your DNS Host and click on Verify button to verify domain on Docker Hub.

Once you verified the domain, Docker Hub should show the message "Domain xxxx.com has been verified" and you can proceed to the next step.

F. Enforce SSO for users (optional)

You can choose to enforce users who have the azureoidc.ga email domain to sign in to Docker Hub via SSO by turning on SSO enforcement in the SSO settings on Docker Hub.

Please note that an unenforced SSO org will let users as follows:

1. Users logging in with username and password will still be able to authenticate from Docker Hub - https://hub.docker.com (no SSO authentication)

2. Users logging in with their azureoidc.ga email domain will be redirected to Azure IdP login page to complete authentication process.

G. Test the SSO connection

Sign in with an email address that have azureoidc.ga email domain from http://hub.docker.com/login. The allowed users should be redirected to https://login.microsoftonline.com/azureoidc.ga to complete authentication process on Azure.

Thats it! Configuring Docker Hub SSO on Azure AD OIDC should be easy if you already know how to create an App Registration on Azure. However, if you still require further help with configuring SSO on Docker Hub, you can reach out to Docker Support from: https://hub.docker.com/support/contact/ . Thank you for reading this blog post and I hope the guide helps you in any way!