Skip to content

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 as auth.anonymousAccess is 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:

Terminal window
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}

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.

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

Terminal window
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/me

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.

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

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:

Terminal window
curl -H "Authorization: Bearer $BOOTSTRAP_TOKEN" https://entrepot.example.com/api/v1/me

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

  • Session cookies are HttpOnly and SameSite=Lax, and Secure when the base URL is https. They are encrypted with AES-GCM using a key derived from auth.sessionSecret, and last auth.sessionTTL (default 12h).
  • 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.

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.