30 lines
2.9 KiB
Text
30 lines
2.9 KiB
Text
[id="con-sso-docker_{context}"]
|
|
|
|
[[_docker]]
|
|
|
|
=== Docker registry v2 authentication
|
|
|
|
[NOTE]
|
|
====
|
|
Docker authentication is disabled by default. To enable docker authentication, see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}.
|
|
====
|
|
[role="_abstract"]
|
|
link:https://distribution.github.io/distribution/spec/auth/[Docker Registry V2 Authentication] is a protocol, similar to OIDC, that authenticates users against Docker registries. {project_name}'s implementation of this protocol lets Docker clients use a {project_name} authentication server authenticate against a registry. This protocol uses standard token and signature mechanisms but it does deviate from a true OIDC implementation. It deviates by using a very specific JSON format for requests and responses as well as mapping repository names and permissions to the OAuth scope mechanism.
|
|
|
|
==== Docker authentication flow
|
|
The authentication flow is described in the link:https://distribution.github.io/distribution/spec/auth/token/[Docker API documentation]. The following is a summary from the perspective of the {project_name} authentication server:
|
|
|
|
* Perform a `docker login`.
|
|
* The Docker client requests a resource from the Docker registry. If the resource is protected and no authentication token is in the request, the Docker registry server responds with a 401 HTTP message with some information on the permissions that are required and the location of the authorization server.
|
|
* The Docker client constructs an authentication request based on the 401 HTTP message from the Docker registry. The client uses the locally cached credentials (from the `docker login` command) as part of the link:https://datatracker.ietf.org/doc/html/rfc2617[HTTP Basic Authentication] request to the {project_name} authentication server.
|
|
* The {project_name} authentication server attempts to authenticate the user and return a JSON body containing an OAuth-style Bearer token.
|
|
* The Docker client receives a bearer token from the JSON response and uses it in the authorization header to request the protected resource.
|
|
* 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: {project_name} does not create a browser SSO session after successful authentication with the Docker protocol. The browser SSO session does not use the Docker protocol as it cannot refresh tokens or obtain the status of a token or session from the {project_name} server; therefore a browser SSO session is not necessary. For more details, see the <<_transient-session, transient session>> section.
|
|
|
|
==== {project_name} Docker Registry v2 Authentication Server URI Endpoints
|
|
|
|
{project_name} has one endpoint for all Docker auth v2 requests.
|
|
|
|
`http(s)://authserver.host{kc_realms_path}/{realm-name}/protocol/docker-v2`
|