Authentication
Every client — browser, pip, npm, docker, Terraform, GitLab CI — goes
through one authenticator. It turns the request’s credentials into a
principal (a user, a service account, a CI job or the bootstrap
superuser), which authorization then evaluates.
| Credential | How it is sent | Identity |
|---|---|---|
| UI session | entrepot_session cookie after OIDC login |
the OIDC user |
Entrepot API token (ent_…) |
Authorization: Bearer, or as the password in Basic auth (any username) |
the token’s user or service account, limited to the token’s scopes |
| OIDC access token | Authorization: Bearer (or Basic password) |
the OIDC user, e.g. from Keycloak |
GitLab CI/CD id_token |
Authorization: Bearer (or Basic password) |
the CI job, mapped to GitLab trust policies |
| Registry token | issued by /v2/token to Docker clients |
whatever authenticated at /v2/token |
| Bootstrap token | Authorization: Bearer |
break-glass superuser |
Rules that apply to all of them:
- Requests without credentials are anonymous. They can read repositories
with
anonymousRead: true, as long asauth.anonymousAccessis enabled (the default). - Credentials that are present but invalid are rejected with
401— never silently downgraded to anonymous. - Verified bearer JWTs are cached briefly, so OIDC and GitLab tokens don’t cost a signature check on every request of a busy client.
Check what Entrepot makes of a credential with GET /api/v1/me:
curl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" https://entrepot.example.com/api/v1/me{"kind":"user","name":"alice","groups":["entrepot-admins"],"policies":[],"scopes":[],"admin":true}Single sign-on (OIDC)
Section titled “Single sign-on (OIDC)”People sign in to the UI through your identity provider with the authorization code flow and PKCE. Keycloak is the reference setup — see Keycloak (OIDC) setup — but any provider with OIDC discovery works: Dex, Okta, Entra ID, Auth0, or GitLab itself.
Discovery is lazy and retried, so Entrepot starts even if the identity
provider is down. Group membership comes from the claim named by
auth.oidc.groupsClaim and drives role bindings.
Members of auth.adminGroups (and users in auth.adminUsers) are system
administrators.
OIDC access tokens
Section titled “OIDC access tokens”Access tokens issued by the same provider are accepted directly as bearer
tokens, for example from scripts that use Keycloak’s client-credentials flow.
A token is accepted when its azp is the configured client ID, or its aud
contains one of auth.oidc.bearerAudiences (default: the client ID).
TOKEN=$(curl -fsS https://keycloak.example.com/realms/platform/protocol/openid-connect/token \ -d grant_type=client_credentials -d client_id=build-bot -d client_secret="$SECRET" | jq -r .access_token)curl -H "Authorization: Bearer $TOKEN" https://entrepot.example.com/api/v1/meAPI tokens and service accounts
Section titled “API tokens and service accounts”Entrepot issues its own tokens (ent_…) for people and for
service accounts — non-human users for systems that can’t use OIDC or
GitLab id_tokens. Tokens can be restricted with scopes and an expiry, and are
stored as SHA-256 hashes. See API tokens & service accounts.
GitLab CI/CD id_tokens
Section titled “GitLab CI/CD id_tokens”Jobs present the short-lived OIDC token GitLab issues them. Entrepot verifies it against the GitLab instance’s JWKS and maps the job to every trust policy whose conditions match its claims. See GitLab CI and GitLab trust policies.
Docker registry tokens
Section titled “Docker registry tokens”Docker clients follow the registry token protocol: an anonymous request to
/v2/ gets a 401 with a Bearer challenge pointing at /v2/token, where the
client authenticates with Basic auth (docker login) or anonymously and
receives a short-lived registry token. Registry tokens are signed with a key
derived from auth.sessionSecret, which is why that secret must be the same
on all replicas.
Bootstrap token
Section titled “Bootstrap token”auth.bootstrapToken (or ENTREPOT_AUTH_BOOTSTRAPTOKEN, or a file named by
ENTREPOT_AUTH_BOOTSTRAPTOKEN_FILE) is a superuser bearer token for
first-time setup and emergencies:
curl -H "Authorization: Bearer $BOOTSTRAP_TOKEN" https://entrepot.example.com/api/v1/meUse it to create the first role bindings or service accounts, then remove it
once OIDC admin groups or bindings are in place. With the Helm chart, put it
under the key bootstrap-token in auth.existingSecret (or set
auth.bootstrapToken) and delete it again afterwards.
Browser security
Section titled “Browser security”- Session cookies are
HttpOnlyandSameSite=Lax, andSecurewhen the base URL is https. They are encrypted with AES-GCM using a key derived fromauth.sessionSecret, and lastauth.sessionTTL(default12h). - State-changing API requests that authenticate with the cookie must send
X-Entrepot-CSRF: 1. A cross-site page can’t set that header without a CORS preflight, and Entrepot never allows those. - The UI also offers Sign in with an API token, which turns a token into a session.
Reverse proxies
Section titled “Reverse proxies”Set server.baseURL to the external URL — it is used for OIDC redirects, the
Docker token realm, rewritten package metadata and as the default GitLab
audience. If baseURL is empty, URLs are derived from each request; behind a
proxy that rewrites the host or scheme, set
server.trustForwardedHeaders: true so X-Forwarded-Proto/Host are
honoured.