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

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

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 adds complexity when deploying, maintaining, and debugging.

Setting things up

Read again the requirements.

Ready?

Run the following script:

  1. mkdir -p auth
  2. mkdir -p data
  3. # This is the main apache configuration
  4. cat <<EOF > auth/httpd.conf
  5. LoadModule headers_module modules/mod_headers.so
  6. LoadModule authn_file_module modules/mod_authn_file.so
  7. LoadModule authn_core_module modules/mod_authn_core.so
  8. LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
  9. LoadModule authz_user_module modules/mod_authz_user.so
  10. LoadModule authz_core_module modules/mod_authz_core.so
  11. LoadModule auth_basic_module modules/mod_auth_basic.so
  12. LoadModule access_compat_module modules/mod_access_compat.so
  13. LoadModule log_config_module modules/mod_log_config.so
  14. LoadModule ssl_module modules/mod_ssl.so
  15. LoadModule proxy_module modules/mod_proxy.so
  16. LoadModule proxy_http_module modules/mod_proxy_http.so
  17. LoadModule unixd_module modules/mod_unixd.so
  18. <IfModule ssl_module>
  19. SSLRandomSeed startup builtin
  20. SSLRandomSeed connect builtin
  21. </IfModule>
  22. <IfModule unixd_module>
  23. User daemon
  24. Group daemon
  25. </IfModule>
  26. ServerAdmin you@example.com
  27. ErrorLog /proc/self/fd/2
  28. LogLevel warn
  29. <IfModule log_config_module>
  30. LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
  31. LogFormat "%h %l %u %t \"%r\" %>s %b" common
  32. <IfModule logio_module>
  33. LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio
  34. </IfModule>
  35. CustomLog /proc/self/fd/1 common
  36. </IfModule>
  37. ServerRoot "/usr/local/apache2"
  38. Listen 5043
  39. <Directory />
  40. AllowOverride none
  41. Require all denied
  42. </Directory>
  43. <VirtualHost *:5043>
  44. ServerName myregistrydomain.com
  45. SSLEngine on
  46. SSLCertificateFile /usr/local/apache2/conf/domain.crt
  47. SSLCertificateKeyFile /usr/local/apache2/conf/domain.key
  48. ## SSL settings recommendation from: https://raymii.org/s/tutorials/Strong_SSL_Security_On_Apache2.html
  49. # Anti CRIME
  50. SSLCompression off
  51. # POODLE and other stuff
  52. SSLProtocol all -SSLv2 -SSLv3 -TLSv1
  53. # Secure cypher suites
  54. SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
  55. SSLHonorCipherOrder on
  56. Header always set "Docker-Distribution-Api-Version" "registry/2.0"
  57. Header onsuccess set "Docker-Distribution-Api-Version" "registry/2.0"
  58. RequestHeader set X-Forwarded-Proto "https"
  59. ProxyRequests off
  60. ProxyPreserveHost on
  61. # no proxy for /error/ (Apache HTTPd errors messages)
  62. ProxyPass /error/ !
  63. ProxyPass /v2 http://registry:5000/v2
  64. ProxyPassReverse /v2 http://registry:5000/v2
  65. <Location /v2>
  66. Order deny,allow
  67. Allow from all
  68. AuthName "Registry Authentication"
  69. AuthType basic
  70. AuthUserFile "/usr/local/apache2/conf/httpd.htpasswd"
  71. AuthGroupFile "/usr/local/apache2/conf/httpd.groups"
  72. # Read access to authentified users
  73. <Limit GET HEAD>
  74. Require valid-user
  75. </Limit>
  76. # Write access to docker-deployer only
  77. <Limit POST PUT DELETE PATCH>
  78. Require group pusher
  79. </Limit>
  80. </Location>
  81. </VirtualHost>
  82. EOF
  83. # Now, create a password file for "testuser" and "testpassword"
  84. docker run --entrypoint htpasswd httpd:2.4 -Bbn testuser testpassword > auth/httpd.htpasswd
  85. # Create another one for "testuserpush" and "testpasswordpush"
  86. docker run --entrypoint htpasswd httpd:2.4 -Bbn testuserpush testpasswordpush >> auth/httpd.htpasswd
  87. # Create your group file
  88. echo "pusher: testuserpush" > auth/httpd.groups
  89. # Copy over your certificate files
  90. cp domain.crt auth
  91. cp domain.key auth
  92. # Now create your compose file
  93. cat <<EOF > docker-compose.yml
  94. apache:
  95. image: "httpd:2.4"
  96. hostname: myregistrydomain.com
  97. ports:
  98. - 5043:5043
  99. links:
  100. - registry:registry
  101. volumes:
  102. - `pwd`/auth:/usr/local/apache2/conf
  103. registry:
  104. image: registry:2
  105. ports:
  106. - 127.0.0.1:5000:5000
  107. volumes:
  108. - `pwd`/data:/var/lib/registry
  109. EOF

Starting and stopping

Now, start your stack:

  1. $ docker-compose up -d

Log in with a “push” authorized user (using testuserpush and testpasswordpush), then tag and push your first image:

  1. $ docker login myregistrydomain.com:5043
  2. $ docker tag ubuntu myregistrydomain.com:5043/test
  3. $ docker push myregistrydomain.com:5043/test

Now, log in with a “pull-only” user (using testuser and testpassword), then pull back the image:

  1. $ docker login myregistrydomain.com:5043
  2. $ docker pull myregistrydomain.com:5043/test

Verify that the “pull-only” can NOT push:

  1. $ docker push myregistrydomain.com:5043/test