From 065bda79bb91a813b1896f921bf018f28b2d7766 Mon Sep 17 00:00:00 2001 From: Olivier Gambier Date: Tue, 18 Aug 2015 19:51:57 -0700 Subject: [PATCH] Starting with recipes - apache recipe - streamline nginx recipe - recipes file Signed-off-by: Olivier Gambier --- docs/apache.md | 234 ++++++++++++++++++++++++++++++++++++++++++++++ docs/deploying.md | 4 +- docs/nginx.md | 67 +++++++------ docs/recipes.md | 32 +++++++ 4 files changed, 309 insertions(+), 28 deletions(-) create mode 100644 docs/apache.md create mode 100644 docs/recipes.md diff --git a/docs/apache.md b/docs/apache.md new file mode 100644 index 000000000..d81409014 --- /dev/null +++ b/docs/apache.md @@ -0,0 +1,234 @@ + + +# Authenticating proxy with apache + +## Use-case + +People already relying on an apache proxy to authenticate their users to other services might want to leverage it and have Registry communications tunneled through the same pipeline. + +Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO mechanism fronting their internal http portal. + +### Alternatives + +If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](deploying.md#native-basic-auth). + +### Solution + +With the method presented here, you implement basic authentication for docker engines in a reverse proxy that sits in front of your registry. + +While we use a simple htpasswd file as an example, any other apache authentication backend should be fairly easy to implement once you are done with the exemple. + +We also implement push restriction (to a limited user group) for the sake of the exemple. Again, you should modify this to fit your mileage. + +### Gotchas + +While this model gives you the ability to use whatever authentication backend you want through the secondary authentication mechanism implemented inside your proxy, it also requires that you move TLS termination from the Registry to the proxy itself. + +Furthermore, introducing an extra http layer in your communication pipeline will make it more complex to deploy, maintain, and debug, and will possibly create issues. + +## Setting things up + +Read again [the requirements](recipes.md#requirements). + +Ready? + +Run the following script: + +``` +mkdir -p auth +mkdir -p data + +# This is the main apache configuration you will use +cat < auth/httpd.conf +LoadModule headers_module modules/mod_headers.so + +LoadModule authn_file_module modules/mod_authn_file.so +LoadModule authn_core_module modules/mod_authn_core.so +LoadModule authz_groupfile_module modules/mod_authz_groupfile.so +LoadModule authz_user_module modules/mod_authz_user.so +LoadModule authz_core_module modules/mod_authz_core.so +LoadModule auth_basic_module modules/mod_auth_basic.so +LoadModule access_compat_module modules/mod_access_compat.so + +LoadModule log_config_module modules/mod_log_config.so + +LoadModule ssl_module modules/mod_ssl.so + +LoadModule proxy_module modules/mod_proxy.so +LoadModule proxy_http_module modules/mod_proxy_http.so + +LoadModule unixd_module modules/mod_unixd.so + + + SSLRandomSeed startup builtin + SSLRandomSeed connect builtin + + + + User daemon + Group daemon + + +ServerAdmin you@example.com + +ErrorLog /proc/self/fd/2 + +LogLevel warn + + + LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined + LogFormat "%h %l %u %t \"%r\" %>s %b" common + + + LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio + + + CustomLog /proc/self/fd/1 common + + +ServerRoot "/usr/local/apache2" + +Listen 5043 + + + AllowOverride none + Require all denied + + + + + ServerName myregistrydomain.com + + SSLEngine on + SSLCertificateFile /usr/local/apache2/conf/domain.crt + SSLCertificateKeyFile /usr/local/apache2/conf/domain.key + + ## SSL settings recommandation from: https://raymii.org/s/tutorials/Strong_SSL_Security_On_Apache2.html + # Anti CRIME + SSLCompression off + + # POODLE and other stuff + SSLProtocol all -SSLv2 -SSLv3 -TLSv1 + + # Secure cypher suites + SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH + SSLHonorCipherOrder on + + Header always set "Docker-Distribution-Api-Version" "registry/2.0" + Header onsuccess set "Docker-Distribution-Api-Version" "registry/2.0" + RequestHeader set X-Forwarded-Proto "https" + + ProxyRequests off + ProxyPreserveHost on + + # no proxy for /error/ (Apache HTTPd errors messages) + ProxyPass /error/ ! + + ProxyPass /v2 http://registry:5000/v2 + ProxyPassReverse /v2 http://registry:5000/v2 + + + Order deny,allow + Allow from all + AuthName "Registry Authentication" + AuthType basic + AuthUserFile "/usr/local/apache2/conf/httpd.htpasswd" + AuthGroupFile "/usr/local/apache2/conf/httpd.groups" + + # Read access to authentified users + + Require valid-user + + + # Write access to docker-deployer only + + Require group pusher + + + + + +EOF + +# Now, create a password file for "testuser" and "testpassword" +docker run --entrypoint htpasswd httpd:2.4 -Bbn testuser testpassword > auth/httpd.htpasswd +# Create another one for "testuserpush" and "testpasswordpush" +docker run --entrypoint htpasswd httpd:2.4 -Bbn testuserpush testpasswordpush >> auth/httpd.htpasswd + +# Create your group file +echo "pusher: testuserpush" > auth/httpd.groups + +# Copy over your certificate files +cp domain.crt auth +cp domain.key auth + +# Now create your compose file + +cat < docker-compose.yml +apache: + image: "httpd:2.4" + hostname: myregistrydomain.com + ports: + - 5043:5043 + links: + - registry:registry + volumes: + - `pwd`/auth:/usr/local/apache2/conf + +registry: + image: registry:2 + ports: + - 127.0.0.1:5000:5000 + volumes: + - `pwd`/data:/var/lib/registry + +EOF +``` + +## Starting and stopping + +Now, start your stack: + + docker-compose up -d + +Login with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image: + + docker login myregistrydomain.com:5043 + docker tag ubuntu myregistrydomain.com:5043/test + docker push myregistrydomain.com:5043/test + +Now, login with a "pull-only" user (using `testuser` and `testpassword`), then pull back the image: + + docker login myregistrydomain.com:5043 + docker pull myregistrydomain.com:5043/test + +Verify that the "pull-only" can NOT push: + + docker push myregistrydomain.com:5043/test + +### Docker still complains about the certificate? + +That's certainly because you are using a self-signed certificate, despite the warnings. + +If you really insist on using these, you have to trust it at the OS level. + +Usually, on Ubuntu this is done with: + + cp auth/domain.crt /usr/local/share/ca-certificates/myregistrydomain.com.crt + update-ca-certificates + +... and on RedHat with: + + cp auth/domain.crt /etc/pki/ca-trust/source/anchors/myregistrydomain.com.crt + update-ca-trust + +Now: + + * `service docker stop && service docker start` (or any other way you use to restart docker) + * `docker-compose up -d` to bring your registry up diff --git a/docs/deploying.md b/docs/deploying.md index ba4e37bf7..c33356320 100644 --- a/docs/deploying.md +++ b/docs/deploying.md @@ -166,7 +166,7 @@ And then push and pull images as an authenticated user. ### Alternatives -1. You may want to leverage more advanced basic auth implementations through a proxy design, in front of the registry. You will find an example of such design in the [nginx proxy documentation](nginx.md). +1. You may want to leverage more advanced basic auth implementations through a proxy design, in front of the registry. You will find examples of such patterns in the [recipes list](recipes.md). 2. Alternatively, the Registry also supports delegated authentication, redirecting users to a specific, trusted token server. That approach requires significantly more investment, and only make sense if you want to fully configure ACLs and more control over the Registry integration into your global authorization and authentication systems. @@ -192,6 +192,7 @@ registry: REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt REGISTRY_HTTP_TLS_KEY: /certs/domain.key REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /var/lib/registry + REGISTRY_AUTH: htpasswd REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm volumes: @@ -212,6 +213,7 @@ You will find more specific and advanced informations in the following sections: - [Configuration reference](configuration.md) - [Working with notifications](notifications.md) + - [Advanced "recipes"](recipes.md) - [Registry API](spec/api.md) - [Storage driver model](storagedrivers.md) diff --git a/docs/nginx.md b/docs/nginx.md index b512ec7d0..fc0094d02 100644 --- a/docs/nginx.md +++ b/docs/nginx.md @@ -8,29 +8,34 @@ keywords = ["registry, service, images, repository, authentication"] # Authenticating proxy with nginx -With this method, you implement basic authentication in a reverse proxy that sits in front of your registry. -While this model gives you the ability to use whatever authentication backend you want through a secondary authentication mechanism implemented inside your proxy, it also requires that you move TLS termination from the Registry to the proxy itself. +## Use-case -Furthermore, introducing an extra http layer in your communication pipeline will make it more complex to deploy, maintain, and debug, and will possibly create issues (typically, nginx does buffer client requests to disk, opening the door to a host of problems if you are dealing with huge images and a lot of traffic). +People already relying on a nginx proxy to authenticate their users to other services might want to leverage it and have Registry communications tunneled through the same pipeline. -### Requirements +Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO mechanism fronting their internal http portal. -You should have followed entirely the basic [deployment guide](deploying.md). +### Alternatives -If you have not, please take the time to do so. +If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](deploying.md#native-basic-auth). -At this point, it's assumed that: +### Solution - * you understand Docker security requirements, and how to configure your docker engines properly - * you have installed Docker Compose - * it's HIGHLY recommended that you get a certificate from a known CA instead of self-signed certificates - * inside the current directory, you have a X509 `domain.crt` and `domain.key`, for the CN `myregistrydomain.com` (or whatever domain name you want to use) - * be sure you have stopped and removed any previously running registry (typically `docker stop registry && docker rm -v registry`) +With the method presented here, you implement basic authentication for docker engines in a reverse proxy that sits in front of your registry. -### Setting things up +While we use a simple htpasswd file as an example, any other nginx authentication backend should be fairly easy to implement once you are done with the exemple. -Read again the requirements. +We also implement push restriction (to a limited user group) for the sake of the exemple. Again, you should modify this to fit your mileage. + +### Gotchas + +While this model gives you the ability to use whatever authentication backend you want through the secondary authentication mechanism implemented inside your proxy, it also requires that you move TLS termination from the Registry to the proxy itself. + +Furthermore, introducing an extra http layer in your communication pipeline will make it more complex to deploy, maintain, and debug, and will possibly create issues. + +## Setting things up + +Read again [the requirements](recipes.md#requirements). Ready? @@ -41,7 +46,7 @@ mkdir -p auth mkdir -p data # This is the main nginx configuration you will use -cat < auth/registry.conf +cat < auth/nginx.conf upstream docker-registry { server registry:5000; } @@ -54,6 +59,12 @@ server { ssl_certificate /etc/nginx/conf.d/domain.crt; ssl_certificate_key /etc/nginx/conf.d/domain.key; + # Recommandations from https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html + ssl_protocols TLSv1.1 TLSv1.2; + ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; + ssl_prefer_server_ciphers on; + ssl_session_cache shared:SSL:10m; + # disable any limits to avoid HTTP 413 for large image uploads client_max_body_size 0; @@ -69,7 +80,7 @@ server { # To add basic authentication to v2 use auth_basic setting plus add_header auth_basic "Registry realm"; - auth_basic_user_file /etc/nginx/conf.d/htpasswd; + auth_basic_user_file /etc/nginx/conf.d/nginx.htpasswd; add_header 'Docker-Distribution-Api-Version' 'registry/2.0' always; proxy_pass http://docker-registry; @@ -83,7 +94,7 @@ server { EOF # Now, create a password file for "testuser" and "testpassword" -htpasswd -bn testuser testpassword > auth/htpasswd +docker run --entrypoint htpasswd httpd:2.4 -bn testuser testpassword > auth/nginx.htpasswd # Copy over your certificate files cp domain.crt auth @@ -105,23 +116,25 @@ registry: image: registry:2 ports: - 127.0.0.1:5000:5000 - environment: - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data volumes: - - `pwd`/data:/data + - `pwd`/data:/var/lib/registry EOF ``` -### Starting and stopping +## Starting and stopping -That's it. You can now: +Now, start your stack: - * `docker-compose up -d` to start your registry - * `docker login myregistrydomain.com:5043` (using `testuser` and `testpassword`) - * `docker tag ubuntu myregistrydomain.com:5043/toto` - * `docker push myregistrydomain.com:5043/toto` + docker-compose up -d -### Docker still complains about the certificate? +Login with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image: + + docker login myregistrydomain.com:5043 + docker tag ubuntu myregistrydomain.com:5043/test + docker push myregistrydomain.com:5043/test + docker pull myregistrydomain.com:5043/test + +## Docker still complains about the certificate? That's certainly because you are using a self-signed certificate, despite the warnings. diff --git a/docs/recipes.md b/docs/recipes.md new file mode 100644 index 000000000..97ace668b --- /dev/null +++ b/docs/recipes.md @@ -0,0 +1,32 @@ + + +# Recipes + +You will find here a list of "recipes", end-to-end scenarios for exotic or otherwise advanced use-cases. + +Most users are not expected to have a use for these. + +## Requirements + +You should have followed entirely the basic [deployment guide](deploying.md). + +If you have not, please take the time to do so. + +At this point, it's assumed that: + + * you understand Docker security requirements, and how to configure your docker engines properly + * you have installed Docker Compose + * it's HIGHLY recommended that you get a certificate from a known CA instead of self-signed certificates + * inside the current directory, you have a X509 `domain.crt` and `domain.key`, for the CN `myregistrydomain.com` + * be sure you have stopped and removed any previously running registry (typically `docker stop registry && docker rm -v registry`) + +## The List + + * [using Apache as an authenticating proxy](apache.md) + * [using Nginx as an authenticating proxy](nginx.md)