Understanding Distribution’s Three Authentication Methods

Distribution is an OCI‑compliant artifact registry that implements authentication via a strategy pattern with three methods: htpasswd, silly, and token.

htpasswd

The htpasswd method stores credentials in a file. The default user is docker and the password is generated randomly and stored as a bcrypt hash. Configuration example:

auth:
   htpasswd:
      realm: harbor-registry-basic-realm
      path: /etc/registry/passwd

During startup the system checks whether the file at path exists; if it does not, the file is created with the default user and a bcrypt‑hashed random password.

Each incoming request passes through the configured access controller for permission verification.

The controller first looks for an Authorization header; if the header is missing, the request is treated as unauthenticated.

If credentials are present, they are compared with the stored file contents. Before comparison the system verifies whether the file has been modified; if it has, the file is regenerated.

silly

The silly method is a lightweight test mode. It grants access when the request’s Authorization header exists and is non‑empty.

token

The token method delegates authentication to an external token service, enabling centralized resource and permission management. Configuration example:

auth:
  token:
    realm: https://localhost:5011/auth
    service: Authentication
    issuer: Sample Issuer
    rootCertBundle: /mnt/local/certs/RootCA.crt

During startup the system validates the token parameters and the TLS certificate.

When a request arrives, authentication information is extracted from the Header. If no credentials are provided, the behavior depends on the autoRedirect flag and the configured realm URL.

If authentication fails, Distribution returns a 401 response with a WWW-Authenticate header that indicates how the client can obtain a token from the auth service.

If autoRedirect is enabled, the client is redirected to the Distribution host’s token endpoint ( https://%s/auth/token); otherwise the client follows the configured realm URL.

Example: an unauthenticated user attempts to Push the image samalba/my-app . The registry responds with: scope: authorization scope service: authorization service realm: authentication service

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Docker-Distribution-Api-Version: registry/2.0
Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:samalba/my-app:pull,push"
Date: Thu, 10 Sep 2015 19:32:31 GMT
Content-Length: 235
Strict-Transport-Security: max-age=31536000

{"errors":[{"code":"UNAUTHORIZED","message":"access to the requested resource is not authorized","detail":[{"Type":"repository","Name":"samalba/my-app","Action":"pull"},{"Type":"repository","Name":"samalba/my-app","Action":"push"}]}]}