26 lines
2.7 KiB
Text
26 lines
2.7 KiB
Text
|
[[_docker]]
|
||
|
|
|
||
|
|
=== Docker Registry v2 Authentication
|
||
|
|
|
||
|
|
WARNING: Docker authentication is a community-supported feature and is disabled by default. Administrators will have to enable this feature before use. To enable, append the following the to server startup script: `-Dkeycloak.profile.feature.docker=enabled`.
|
||
|
|
|
||
|
|
link:https://docs.docker.com/registry/spec/auth/[Docker Registry V2 Authentciation] is an OIDC-Like protocol used to authenticate users against a Docker registry. {{book.project.name}}'s implementation of this protocol allows for a {{book.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 they {{book.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://tools.ietf.org/html/rfc2617[HTTP Basic Authentication] request to the {{book.project.name}} authentication server.
|
||
|
|
- The {{book.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 recieves the new request for the protected resource with the token from the {{book.project.name}} server, the registry validates the token and grants access to the requested resource (if appropriate).
|
||
|
|
|
||
|
|
==== {{book.project.name}} Docker Registry v2 Authentication Server URI Endpoints
|
||
|
|
|
||
|
|
{{book.project.name}} really only has one endpoint for all Docker auth v2 requests.
|
||
|
|
|
||
|
|
`http(s)://authserver.host/auth/realms/\{realm-name}/protocol/docker-v2`
|
||
|
|
|