Authenticate to Docker Registry through OAuth Provider

Hasintha Indrajee
3 min readAug 7, 2019

Have you ever worried about the authentication mechanism which docker registry uses ? If not, probably you might have never used/hosted a private docker registry for your organization. If you have had one, you should have came across what the docker authentication mechanism is. In simple terms if you have ever had a requirement of hosting your own docker registry instance, you might have done some research on how docker registry authenticates users.

Well, you can run a docker registry without authentication turned off. Anybody who wants to push, pull will be able to do so without any validation. This is just for testing purposes.

In an enterprise hosting, you need to authenticate and authorize users to enforce access control. An authentication enabled docker registry will give you back a challenge when you try to do an operation.

This challenge looks similar to Kerberos. It conveys a realm which you have to talk to and scopes you need to have in order to do the operation. Well what is this realm ? This realm is a service where you can talk to and get a token (in this case a JWT) which has the requested scopes. (Fine.. tell me where actually this is). Well this is a separate service which takes care of user authentication and authorization for docker auth.

Simply docker registry doesn’t know how to do authentication or authorization. It delegates the task to an external entity and validates the results based on an assertion. Docker doc [1] well describes how authentication takes place through an external service.

Have you ever heard about “Docker Auth” ?. Docker auth is a service which provides authentication to your docker registry. When you host a docker instance, you need to host a docker auth instance which will act as the authentication realm for your docker registry. Docker auth knows how to communicate with docker daemon which is running in your machine, docker registry and make sure the flow completes while pushing and pulling with credentials.

By default docker auth provides mechanisms to authenticate and authorize your uses through an LDAP or an AD (you can plug your cooperate user store). Also it provides you the ability to authenticate through social login as well. The social login looks bit out of standards where it gives you a temporary password on screen to be entered while pushing and pulling.

Up to now we were discussing some background which might be helpful for our deployment. What we wanted was, authenticate through google, github or any other social login and then keep pushing and pulling from docker registry with proper authentication and authorization. This is what we have used in Cellery Hub project. In order to get the full experience of pushing and pulling through single sign on via social accounts, try out Cellery CLI. This CLI is used to authenticate users through Github and Google, push pull images through that session.

We have our SPA Cellery Hub and CLI app which needs to be logged in seamlessly through Single Sign On. All users are authenticated either through Google or Github. The CLI application will push and pull images while Cellery Hub showcase those image details. Underlying repository in Cellery Hub is a docker registry.

We have hosted a WSO2 Identity Provider as our OAuth Provider which is responsible for federating users through google and github. Our CLI will authenticate to hosted WSO2 IDP through authorization grant type. If you need more information on how to authenticate to CLI through authorization code please refer this article. I am just pointing this because by first looks you might wonder how authorization grant flow without browser involvement ? (don’t forget we are authenticating to a Command Line Application)

Upon authentication, our CLI will get back an OAuth token from hosted IDP and we use this OAuth token to authenticate and authorize to docker registry which is hosted to store images. We have implemented an extension to Docker Auth which talks to WSO2 Identity Server and validates token. If you need the source of this code you can find it in [2]. This is because Docker auth doesn’t have an OOTB mechanism to validate a general OAuth2 token.

Docker Registry deployment which authenticates users through Social Login