From 754cfd07500d1ccb68f9779d5f3681b0d8d052b3 Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Thu, 1 Jun 2017 15:05:37 +0200 Subject: [PATCH] Updates to Docker docs --- book-product.json | 6 ++- book.json | 6 ++- securing_apps/SUMMARY.adoc | 7 +-- securing_apps/topics/docker/config-file.adoc | 15 ------ .../topics/docker/docker-overview.adoc | 49 +++++++++++++++++++ .../topics/docker/quickstart-zip.adoc | 21 -------- .../topics/docker/variable-override.adoc | 11 ----- server_admin/SUMMARY.adoc | 4 +- server_admin/topics/sso-protocols/docker.adoc | 2 +- server_installation/topics/profiles.adoc | 4 +- 10 files changed, 64 insertions(+), 61 deletions(-) delete mode 100644 securing_apps/topics/docker/config-file.adoc delete mode 100644 securing_apps/topics/docker/quickstart-zip.adoc delete mode 100644 securing_apps/topics/docker/variable-override.adoc diff --git a/book-product.json b/book-product.json index f68042115f..6516cce70c 100755 --- a/book-product.json +++ b/book-product.json @@ -38,7 +38,11 @@ }, "installguide": { "name": "Server Installation and Configuration", - "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/SNAPSHOT/html-single/server-installation-and-configuration-guide/" + "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/SNAPSHOT/html-single/server-installation-and-configuration-guide/", + "profile": { + "name": "Profiles", + "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/SNAPSHOT/html-single/server-installation-and-configuration-guide/#profiles" + } }, "adapterguide": { "name": "Securing Applications and Services Guide", diff --git a/book.json b/book.json index 216c274254..d0fbc6f407 100755 --- a/book.json +++ b/book.json @@ -36,7 +36,11 @@ }, "installguide": { "name": "Server Installation and Configuration", - "link": "https://keycloak.gitbooks.io/documentation/content/server_installation/index.html" + "link": "https://keycloak.gitbooks.io/documentation/content/server_installation/index.html", + "profile": { + "name": "Profiles", + "link": "https://keycloak.gitbooks.io/documentation/content/server_installation/topics/profiles.html" + } }, "adapterguide": { "name": "Securing Applications and Services Guide", diff --git a/securing_apps/SUMMARY.adoc b/securing_apps/SUMMARY.adoc index 231afa5f36..20070156e1 100644 --- a/securing_apps/SUMMARY.adoc +++ b/securing_apps/SUMMARY.adoc @@ -87,11 +87,6 @@ .... 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/docker/docker-overview.adoc[Docker] .. link:securing_apps/topics/client-registration.adoc[Client Registration] ... link:securing_apps/topics/client-registration/client-registration-cli.adoc[Client Registration CLI] diff --git a/securing_apps/topics/docker/config-file.adoc b/securing_apps/topics/docker/config-file.adoc deleted file mode 100644 index 9a97806b64..0000000000 --- a/securing_apps/topics/docker/config-file.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[[_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. diff --git a/securing_apps/topics/docker/docker-overview.adoc b/securing_apps/topics/docker/docker-overview.adoc index 707373f7f2..120f714d1c 100644 --- a/securing_apps/topics/docker/docker-overview.adoc +++ b/securing_apps/topics/docker/docker-overview.adoc @@ -1,6 +1,55 @@ == Docker Registry Configuration +NOTE: Docker authentication is disabled by default. To enable see link:{{book.installguide.profile.link}}[{{book.installguide.profile.name}}]. + 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]. + + + +=== 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. + + +=== 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. + + +=== 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 \ No newline at end of file diff --git a/securing_apps/topics/docker/quickstart-zip.adoc b/securing_apps/topics/docker/quickstart-zip.adoc deleted file mode 100644 index 6c00f6d6b7..0000000000 --- a/securing_apps/topics/docker/quickstart-zip.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[[_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 - diff --git a/securing_apps/topics/docker/variable-override.adoc b/securing_apps/topics/docker/variable-override.adoc deleted file mode 100644 index 2f98b7a87f..0000000000 --- a/securing_apps/topics/docker/variable-override.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[[_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. diff --git a/server_admin/SUMMARY.adoc b/server_admin/SUMMARY.adoc index 4da9d6a124..61cc563ff2 100644 --- a/server_admin/SUMMARY.adoc +++ b/server_admin/SUMMARY.adoc @@ -34,9 +34,7 @@ ... 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/sso-protocols/docker.adoc[Docker] .. 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] diff --git a/server_admin/topics/sso-protocols/docker.adoc b/server_admin/topics/sso-protocols/docker.adoc index b6cf66db5d..9f45f799dd 100644 --- a/server_admin/topics/sso-protocols/docker.adoc +++ b/server_admin/topics/sso-protocols/docker.adoc @@ -2,7 +2,7 @@ === 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`. +NOTE: Docker authentication is disabled by default. To enable see link:{{book.installguide.profile.link}}[{{book.installguide.profile.name}}]. 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. diff --git a/server_installation/topics/profiles.adoc b/server_installation/topics/profiles.adoc index 9c6341ae26..cc746975d6 100755 --- a/server_installation/topics/profiles.adoc +++ b/server_installation/topics/profiles.adoc @@ -1,4 +1,4 @@ -[[_app_server_cli]] +[[_profiles]] == Profiles @@ -32,9 +32,9 @@ profile=preview The features that can be enabled and disabled are: * Authorization - authorization services +* Docker - authentication protocol for Docker Registry * 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.