[[_docker]]

=== Docker Registry v2 Authentication

NOTE: Docker authentication is disabled by default. To enable see the https://www.keycloak.org/server/features[Enabling and disabling features] guide.

link:https://docs.docker.com/registry/spec/auth/[Docker Registry V2 Authentication] is an OIDC-Like protocol used to authenticate users against a Docker registry.  {project_name}'s implementation of this protocol allows for a {project_name} authentication server to be used by a Docker client to authenticate against a registry.  While this protocol uses fairly standard token and signature mechanisms, it has a few wrinkles that prevent it from being treated as a true OIDC implementation.  The largest deviations include a very specific JSON format for requests and responses as well as the ability to understand how to map repository names and permissions to the OAuth scope mechanism.

==== Docker Auth Flow
The link:https://docs.docker.com/registry/spec/auth/token/[Docker API documentation] best describes and illustrates this process, however a brief summary will be given below from the perspective of the {project_name} authentication server.

NOTE: This flow assumes that a `docker login` command has already been performed

 * The flow begins when the Docker client requests a resource from the Docker registry.  If the resource is protected and no auth token is present in the request, the Docker registry server will respond to the client with a 401 + some information on required permissions and where to find the authorization server.
 * The Docker client will construct an authentication request based on the 401 response from the Docker registry.  The client will then use the locally cached credentials (from a previously run `docker login` command) as part of a link:https://datatracker.ietf.org/doc/html/rfc2617[HTTP Basic Authentication] request to the {project_name} authentication server.
 * The {project_name} authentication server will attempt to authenticate the user and return a JSON body containing an OAuth-style Bearer token.
 * The Docker client will get the bearer token from the JSON response and use it in the Authorization header to request the protected resource.
 * When the Docker registry receives the new request for the protected resource with the token from the {project_name} server, the registry validates the token and grants access to the requested resource (if appropriate).

NOTE: No user session is created on the {project_name} side after successful authentication with the Docker protocol. The Docker protocol is
not used in case of browser SSO session and it does not have a way to refresh token or ask {project_name} server if a particular token/session
is still valid. So creating the session is unnecessary overhead for this protocol. For more details, see the <<_transient-session, transient session>> section.

====  {project_name} Docker Registry v2 Authentication Server URI Endpoints

{project_name} really only has one endpoint for all Docker auth v2 requests.

`http(s)://authserver.host{kc_realms_path}/{realm-name}/protocol/docker-v2`