Registry Authentication and Token-Based Access Control
Deep dive into OCI registry authentication models: htpasswd basic auth vs OAuth2 JWT token servers, token exchange workflows, and RBAC integrations.
Published on • November 18, 2026
AI Assistant

Container registries store sensitive application code, proprietary binaries, and production secrets. Securing registry endpoints requires a robust authentication and authorization framework.
While simple setups use HTTP Basic Authentication (htpasswd), enterprise OCI registries (such as Docker Hub, Harbor, AWS ECR, and GitHub Container Registry) rely on Token-Based Bearer Authentication using signed JSON Web Tokens (JWT).
In this deep dive, we will compare basic auth against token auth, trace the full OAuth2 JWT token handshake protocol, and explore how enterprise Role-Based Access Control (RBAC) works in container registries.
Authentication Models Compared
+-----------------------------------------------------------------------------------+
| 1. HTTP Basic Authentication (htpasswd) |
| - Credentials (username:password) sent with EVERY HTTP request. |
| - Static, flat user list; no scope enforcement (all users can pull/push all repos)|
| - Best for small development environments. |
+-----------------------------------------------------------------------------------+
| 2. OAuth2 JWT Token Authentication |
| - Central Auth Server issues short-lived, digitally signed Bearer JWTs. |
| - Granular resource scoping (e.g., user X can ONLY pull repo Y for 15 mins). |
| - Integrates with LDAP, Active Directory, Okta, OIDC, and GitHub SSO. |
| - Mandatory standard for production enterprise registries. |
+-----------------------------------------------------------------------------------+
The Token Exchange Sequence (Step-by-Step)
The Docker CLI interacts with token-authenticated registries via a standardized 4-step challenge-response handshake defined by the OCI Distribution Specification:
+------------+ 1. GET /v2/org/app/manifests/v1 +----------+
| | ------------------------------------------------> | Container|
| | <------------------------------------------------ | Registry |
| | 2. 401 Unauthorized +----------+
| | Header: Www-Authenticate: Bearer
| | realm="https://auth.example.com/token",
| Docker | service="container-registry",
| CLI | scope="repository:org/app:pull"
| |
| | 3. GET https://auth.example.com/token?service=...
| | (Passes Basic Auth credentials or PAT)
| | ------------------------------------------------> +----------+
| | <------------------------------------------------ | Auth |
| | 4. Returns Signed JWT Token {"token": "eyJhb..."} | Server |
| | +----------+
| | 5. GET /v2/org/app/manifests/v1
| | Header: Authorization: Bearer eyJhb...
| | ------------------------------------------------> +----------+
| | <------------------------------------------------ | Registry |
| | 200 OK (Downloads manifest/layers) +----------+
+------------+
Step Breakdown:
- Initial Unauthenticated Request: The client requests a manifest or blob from the registry.
- Challenge Received (401): The registry responds with
401 Unauthorizedand specifies the URL of the external token authentication server in theWww-Authenticateheader along with requested scope. - Token Request: The client connects to the Auth Server (
realm), providing user credentials or Personal Access Tokens. - JWT Issuance: If credentials are valid, the Auth Server verifies permissions against an RBAC database and signs a short-lived JWT token containing explicit access scopes.
- Authenticated Request: The client re-sends the original request to the registry with the
Authorization: Bearer <token>header. The registry verifies the cryptographic signature of the token and grants access.
Anatomy of a Registry JWT Token
A decoded registry access token contains standard JWT claims along with custom OCI access scopes:
// JWT Header
{
"typ": "JWT",
"alg": "RS256",
"keyid": "J2BC:9A01:45EF..."
}
// JWT Payload
{
"iss": "auth.example.com",
"sub": "devops-ci-bot",
"aud": "container-registry",
"exp": 1700003600,
"nbf": 1700000000,
"iat": 1700000000,
"access": [
{
"type": "repository",
"name": "org/payment-service",
"actions": ["pull", "push"]
}
]
}
iss(Issuer): Must match the trusted auth server configured in the registry settings.exp(Expiration): Usually set to short durations (e.g., 15 minutes) to minimize exposure if intercepted.access: Array defining exact allowed actions (pull,push,delete) per repository.
Configuring Token Auth in Open-Source Registry (registry:2)
To configure the official registry:2 container image to delegate authentication to an external OAuth2 token service (like Harbor or CESNET docker-auth):
version: '3.8'
services:
registry:
image: registry:2
environment:
REGISTRY_AUTH: token
REGISTRY_AUTH_TOKEN_REALM: "https://auth.example.com/token"
REGISTRY_AUTH_TOKEN_SERVICE: "container-registry"
REGISTRY_AUTH_TOKEN_ISSUER: "auth.example.com"
REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE: /etc/registry/auth-server.crt
volumes:
- ./auth-server.crt:/etc/registry/auth-server.crt:ro
Security Best Practices for Registry Token Auth
- Short Token TTLs: Keep token expiration short (5 to 15 minutes). The Docker CLI automatically handles token refreshes transparently.
- Rotate Auth Signing Keys: Use strong RSA or ECDSA keys to sign JWT tokens, and rotate signing keys periodically.
- Integrate Single Sign-On (SSO): Connect the Auth Server to OIDC/SAML providers (such as Okta, Keycloak, or Azure AD) so access is automatically revoked when an employee leaves the company.
- Audit Token Logs: Monitor authentication logs for failed login attempts or anomalous token requests originating from unknown IP ranges.
Summary
Token-based authentication provides the security foundation for enterprise container registries. By decoupling identity verification from storage handling, registries achieve fine-grained access control, SSO integration, and seamless CI/CD automation.