vbatts/registry
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Merge pull request #897 from dmp42/5.all-ur-proxy-are-belong-to-us

Browse source 
Starting with recipes
This commit is contained in:
Richard Scothern 2015-08-24 11:28:17 -07:00
commit 7a4920d8e5
4 changed files with 309 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

234
docs/apache.md Normal file
View file

@ -0,0 +1,234 @@
<!--[metadata]>
+++
title = "Authenticating proxy with apache"
description = "Restricting access to your registry using a proxy"
keywords = ["registry, service, images, repository, authentication"]
+++
<![end-metadata]-->
# 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 <<EOF > 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
<IfModule ssl_module>
SSLRandomSeed startup builtin
SSLRandomSeed connect builtin
</IfModule>
<IfModule unixd_module>
User daemon
Group daemon
</IfModule>
ServerAdmin you@example.com
ErrorLog /proc/self/fd/2
LogLevel warn
<IfModule log_config_module>
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%h %l %u %t \"%r\" %>s %b" common
<IfModule logio_module>
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio
</IfModule>
CustomLog /proc/self/fd/1 common
</IfModule>
ServerRoot "/usr/local/apache2"
Listen 5043
<Directory />
AllowOverride none
Require all denied
</Directory>
<VirtualHost *:5043>
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
<Location /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
<Limit GET HEAD>
Require valid-user
</Limit>
# Write access to docker-deployer only
<Limit POST PUT DELETE PATCH>
Require group pusher
</Limit>
</Location>
</VirtualHost>
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 <<EOF > 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

4
docs/deploying.md
View file

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

67
docs/nginx.md
View file

@ -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 <<EOF > auth/registry.conf
cat <<EOF > 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.

32
docs/recipes.md Normal file
View file

@ -0,0 +1,32 @@
<!--[metadata]>
+++
title = "Recipes for Registry"
description = "Fun stuff to do with your registry"
keywords = ["registry, service, images, repository, recipe"]
+++
<![end-metadata]-->
# 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)