libre.sh/keycloak-scim
2
0
Fork 0
Code Issues 14 Pull requests Releases Packages Activity Actions 6

Merge pull request #1 from stianst/dockerProtocol

Browse source 
Updates to Docker docs
This commit is contained in:
Josh C 2017-06-02 11:15:30 -05:00 committed by GitHub
commit 7c8317b2d8
10 changed files with 64 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
book-product.json
View file

@ -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",

6
book.json
View file

@ -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",

7
securing_apps/SUMMARY.adoc
View file

@ -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]

15
securing_apps/topics/docker/config-file.adoc
View file

@ -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.

49
securing_apps/topics/docker/docker-overview.adoc
View file

@ -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

21
securing_apps/topics/docker/quickstart-zip.adoc
View file

@ -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

11
securing_apps/topics/docker/variable-override.adoc
View file

@ -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.

4
server_admin/SUMMARY.adoc
View file

@ -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]

2
server_admin/topics/sso-protocols/docker.adoc
View file

@ -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.

4
server_installation/topics/profiles.adoc
View file

@ -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.