Add documentation for Docker protocol

.gitignore

@@ -52,3 +52,6 @@ target
 ############
 build/
 
+# vim
+######
+*.swp

securing_apps/SUMMARY.adoc

@@ -87,5 +87,11 @@
  .... link:securing_apps/topics/saml/java/MigrationFromOlderVersions.adoc[Migration from older versions]
  {% endif %}
  ... link:securing_apps/topics/saml/mod-auth-mellon.adoc[mod_auth_mellon Apache HTTPD Module]
+ {% if book.community %}
+ . link:topics/docker/docker-overview.adoc[Docker]
+ .. link:topics/docker/config-file.adoc[Config File Installation]
+ .. link:topics/docker/variable-override.adoc[Variable Override Installation]
+ .. link:topics/docker/quickstart-zip.adoc[Quickstart .zip Installation]
+ {% endif %}
  .. link:securing_apps/topics/client-registration.adoc[Client Registration]
  ... link:securing_apps/topics/client-registration/client-registration-cli.adoc[Client Registration CLI]

securing_apps/topics/docker/config-file.adoc

@@ -0,0 +1,15 @@
+[[_docker_config_file]]
+
+=== Docker Registry Configuration File Installation
+
+For users with more advanced docker registry configurations, it is generally recommended to provide your own registry configuration file.  The {{book.project.name}} docker provider supports this mechanism via the _Registry Config File_ Format Option.  Choosing this option will generate output similar to the following:
+
+	auth:
+	  token:
+	    realm: http://localhost:8080/auth/auth/realms/master/protocol/docker-v2/auth
+	    service: docker-test
+	    issuer: http://localhost:8080/auth/auth/realms/master
+
+This output can then be copied into any existing registry config file.  See the link:https://docs.docker.com/registry/configuration/[registry config file specification] for more information on how the file should be set up, or start with href:https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml[a basic example].
+
+WARNING: Don't forget to configure the `rootcertbundle` field with the location of the {{book.project.name}} realm's pulic certificate.  The auth configuration will not work without this argument.

securing_apps/topics/docker/docker-overview.adoc

@@ -0,0 +1,6 @@
+
+== Docker Registry Configuration
+
+This section describes how you can configure a Docker registry to use {{book.project.name}} as its authentication server.
+
+Fore more information on how to set up and configure a Docker registry, see the link:https://docs.docker.com/registry/configuration/[Docker Registry Configuration Guide].

securing_apps/topics/docker/quickstart-zip.adoc

@@ -0,0 +1,21 @@
+[[_docker_compose_yaml]]
+
+=== Docker Compose YAML File
+
+WARNING: This installation method is meant to be an easy way to get a docker registry authenticating against a keycloak server.  It is intended for development purposes only and should never be used in a production or production-like environment.
+
+The zip file installation mechanism provides a quickstart for developers who want to understand how the keycloak server can interact with the docker registry.  In order to configure:
+
+ 1. From the desired realm, create a client configuration.  At this point you won't have a docker registry - the quickstart will take care of that part.
+ 1. Choose the "Docker Compose YAML" option from the installation tab and download the .zip file
+ 1. Unzip the archive to the desired location, and open the directory.
+ 1. Start the docker registry with `docker-compose up`
+
+INFO: it is recommended that you configure the docker registry client in a realm other than 'master', since the HTTP Basic auth flow will not present forms.
+
+Once the above configuration has taken place, and the keycloak server and docker registry are running, docker authentication should be successful:
+
+	[user ~]# docker login localhost:5000 -u $username
+	Password: *******
+	Login Succeeded
+

securing_apps/topics/docker/variable-override.adoc

@@ -0,0 +1,11 @@
+[[_docker_variable_override]]
+
+=== Docker Registry Environment Variable Override Installation
+
+Often times it is appropriate to use a simple environment variable override for develop or POC Docker registries.  While this apporach is usually not recommended for production use, it can be helpful when one requires quick-and-dirty way to stand up a registry.  Simply use the _Variable Override_ Format Option from the client installation tab, and an output should appear like the one below:
+
+    REGISTRY_AUTH_TOKEN_REALM: http://localhost:8080/auth/auth/realms/master/protocol/docker-v2/auth
+    REGISTRY_AUTH_TOKEN_SERVICE: docker-test
+    REGISTRY_AUTH_TOKEN_ISSUER: http://localhost:8080/auth/auth/realms/master
+
+WARNING: Don't forget to configure the `REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE` override with the location of the {{book.project.name}} realm's pulic certificate.  The auth configuration will not work without this argument.

server_admin/SUMMARY.adoc

@@ -34,6 +34,9 @@
 ... link:server_admin/topics/sso-protocols/oidc.adoc[OpenID Connect]
 ... link:server_admin/topics/sso-protocols/saml.adoc[SAML]
 ... link:server_admin/topics/sso-protocols/saml-vs-oidc.adoc[OIDC vs. SAML]
+{% if book.community %}
+... link:topics/sso-protocols/docker.adoc[Docker]
+{% endif %}
 .. link:server_admin/topics/clients.adoc[Managing Clients]
 ... link:server_admin/topics/clients/client-oidc.adoc[OIDC Clients]
 .... link:server_admin/topics/clients/oidc/confidential.adoc[Confidential Client Credentials]

server_admin/topics/sso-protocols/docker.adoc

@@ -0,0 +1,25 @@
+[[_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`
+

server_installation/topics/profiles.adoc

@@ -34,6 +34,7 @@ The features that can be enabled and disabled are:
 * Authorization - authorization services
 * Impersonation - ability for admins to impersonate users
 * Script - write custom authenticators using JavaScript
+* Docker - use docker-v2 authentication protocol
 
 {% if book.product %}
 The product profile disables authorization and script.