Choose htpasswd when a handful of people and pipelines need a shared, simple login over TLS. Choose token authentication when you have many users, a central identity system, or a need for different rights per repository. The registry supports one provider at a time, so the decision matters up front.
What each one is
htpasswd is basic authentication against a local file of bcrypt hashes. The registry reads the file named in auth.htpasswd.path, and clients send a username and password with every request.
Token authentication delegates the decision to a separate auth service. The registry sends unauthenticated clients to that service, which checks identity and issues a signed token. The registry then verifies the token. The configuration needs realm, service, issuer and rootcertbundle.
The registry also has a silly provider, but the docs describe it as development only. It checks that an Authorization header is present, not what it says.
Side by side
| Question | htpasswd | token |
|---|---|---|
| Setup effort | Minutes | A separate service to build or run |
| Where identities live | A file on the registry host | Your auth service |
| Per repository rights | Not expressed in the file | Decided by the auth service |
| Credential rotation | Edit the file for each user | Handled by the token service |
| Works without TLS | No, passwords travel in headers | Still needs TLS in practice |
The Distribution docs say token auth is more complex to set up, and they point to an authenticating proxy as another route for advanced needs.
How to decide
Ask four questions.
- How many humans and pipelines need access? Past a dozen or so, editing a file by hand gets error prone.
- Do you need read only roles? Deploy systems often should pull but never push. A flat file cannot express that.
- Do you already run central identity? If so, token auth lets the registry follow it, and offboarding someone removes registry access in the same step.
- Who will operate the auth service? A token service is one more thing to patch and monitor. If nobody owns it, a simple setup that is well run beats a clever one that is neglected.
If you pick htpasswd
Keep the file out of the image and out of version control. Generate hashes with bcrypt, since the registry accepts nothing else. Give each pipeline its own account so logs and revocation are meaningful. Pair it with TLS, because the docs warn that basic auth sends passwords in HTTP headers.
If you pick token auth
Protect the signing key and the root certificate bundle like any other signing material. Short token lifetimes limit damage from a leak. Make sure the auth service logs every grant, because the registry sees only the token.
Moving later
You can change providers, but every client login changes with it. Plan the cutover: create the new accounts, update CI secrets, then switch. Keep the old path available for a short window and watch the access log for stragglers.
If you want an inventory of what is stored behind either setup, Safeguard's container image scanning and SBOM generation can help, and the free scan is at gold.safeguard.sh/scan.
Quick check
Can I run htpasswd and token auth together?
No. The configuration reference says only one authentication provider can be configured at a time.
Is token auth more secure than htpasswd?
Not automatically. It allows finer rights and central control, but it adds a service and a signing key that you must protect.
Sources
Last reviewed: 19 October 2026.
