Project: Distribution (Provisioning / Container Registry)
File: nginx.md

description: Restricting access to your registry using a nginx proxy keywords: registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication, TLS, recipe, advanced title: Authenticate proxy with nginx 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. Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO mechanism fronting their internal http portal. If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native . 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 nginx authentication backend should be fairly easy to implement once you are done with the example. We also implement push restriction (to a limited user group) for the sake of the example. Again, you should modify this to fit your mileage. 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. Note: It is not recommended to bind your registry to `localhost:5000` without authentication. This creates a potential loophole in your registry security. As a result, anyone who can log on to the server where your registry is running can push images without authentication. Furthermore, introducing an extra http layer in your communication pipeline makes it more complex to deploy, maintain, and debug. Make sure the extra complexity is

For instance, Amazon's Elastic Load Balancer (ELB) in HTTPS mode already sets the following client header: ```none X-Real-IP X-Forwarded-For X-Forwarded-Proto ``` So if you have an Nginx instance sitting behind it, remove these lines from the example config below: ```none proxysetheader Host $http_host; # required for docker client's sake proxysetheader X-Real-IP $remote_addr; # pass on real client's IP proxysetheader X-Forwarded-For $proxyaddxforwardedfor; proxysetheader X-Forwarded-Proto $scheme; ``` Otherwise Nginx resets the ELB's values, and the requests are not routed properly. For more information, see . Review the , then follow these steps. Create the required directories ```console $ mkdir -p auth data ``` Create the main nginx configuration. Paste this code block into a new file called `auth/nginx.conf`: ```conf events { worker_connections 1024; } http { upstream docker-registry { server registry:5000; } map $upstreamhttpdockerdistributionapiversion $dockerdistributionapiversion { '' 'registry/2.0'; } server { listen 443 ssl; server_name myregistrydomain.com; ssl_certificate /etc/nginx/conf.d/domain.crt; sslcertificatekey /etc/nginx/conf.d/domain.key; ssl_protocols TLSv1.1 TLSv1.2; ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; sslpreferserver_ciphers on; sslsessioncache shared:SSL:10m; clientmaxbody_size 0; chunkedtransferencoding on; location /v2/ { if ($httpuseragent ~ "^(docker\/1\.(3|4|5(?!\.[0-9]-dev))|Go ).*$" ) { return 404; } auth_basic "Registry realm"; authbasicuser_file /etc/nginx/conf.d/nginx.htpasswd; addheader 'Docker-Distribution-Api-Version' $dockerdistributionapiversion always; proxy_pass http://docker-registry; proxysetheader Host $http_host; # required for docker client's sake proxysetheader X-Real-IP $remote_addr; # pass on real client's IP proxysetheader X-Forwarded-For $proxyaddxforwardedfor; proxysetheader X-Forwarded-Proto $scheme; proxyreadtimeout 900; } } } ``` Create a password file `auth/nginx.htpasswd` for "testuser" and "testpassword". ```console $ docker run --rm --entrypoint htpasswd httpd -Bbn testuser testpassword > auth/nginx.htpasswd ``` > Note: If you do not want to use `bcrypt`, you can omit the `-B` parameter. Copy your certificate files to the `auth/` directory. ```console $ cp domain.crt auth $ cp domain.key auth ``` Create the compose file. Paste the following YAML into a new file called `docker-compose.yml`. ```yaml version: "3" services: nginx: image: "nginx:alpine" ports: 5043:443 depends_on: registry volumes: ./auth:/etc/nginx/conf.d ./auth/nginx.conf:/etc/nginx/nginx.conf:ro registry: image: registry:2 volumes: ./data:/var/lib/registry ``` Now, start your stack: ```consonle $ docker-compose up -d ``` Login with a "push" authorized user (using `testuser` and `testpassword`), then tag and push your first image: ```console $ docker login -u=testuser -p=testpassword -e=root@example.ch myregistrydomain.com:5043 $ docker tag ubuntu myregistrydomain.com:5043/test $ docker push myregistrydomain.com:5043/test $ docker pull myregistrydomain.com:5043/test ```