Skip to content

Authorization

Entrepot’s access model is deliberately small: actions, roles that group actions, and role bindings that grant a role to a subject on the repositories matching a pattern.

Action Allows
read Download, browse, search; read repository settings.
write Upload and overwrite (where the repository allows redeploys); queue scans.
delete Delete assets, components, versions (npm unpublish, DELETE requests).
admin Everything on the matched repositories.

Built-in roles:

Role Actions
viewer read
developer read, write
maintainer read, write, delete
admin read, write, delete, admin

Custom roles are any combination of actions:

Terminal window
curl -fsS -H "Authorization: Bearer $ADMIN" -X POST https://entrepot.example.com/api/v1/roles \
-d '{"name":"publisher","description":"Publish but never delete","actions":["read","write"]}'

A binding has a role, a subject and a repository pattern.

subjectType subject Matches
user an OIDC username (alice), or a service account (sa:jenkins) that user
group an OIDC group (from auth.oidc.groupsClaim) every member
gitlab_policy a GitLab trust policy name every CI job whose id_token matches the policy
authenticated empty anyone who is logged in
Terminal window
api() { curl -fsS -H "Authorization: Bearer $ADMIN" -H 'Content-Type: application/json' "$@"; }
E=https://entrepot.example.com
api -X POST $E/api/v1/role-bindings -d '{"role":"viewer","subjectType":"authenticated","repositoryPattern":"*"}'
api -X POST $E/api/v1/role-bindings -d '{"role":"developer","subjectType":"group","subject":"developers","repositoryPattern":"*-internal"}'
api -X POST $E/api/v1/role-bindings -d '{"role":"maintainer","subjectType":"group","subject":"platform","repositoryPattern":"npm-*|pypi-*"}'
api -X POST $E/api/v1/role-bindings -d '{"role":"developer","subjectType":"user","subject":"sa:jenkins","repositoryPattern":"docker-internal"}'

Bindings are immutable: to change one, delete it and create a new one (Terraform does this for you). Manage them in the UI under Administration → Roles & bindings.

Repository patterns are globs over repository names, anchored at both ends and case-sensitive:

Pattern Matches
* every repository
npm-* npm-internal, npm-proxy, …
*-internal every hosted -internal repository
pypi-internal|pypi-proxy either of the two (| separates alternatives)
team-? team-a, team-b, … (? is one character)

Name your repositories so that patterns stay simple — for example <format>-<purpose> or <team>-<format>.

A subject is a system administrator — blob stores, repositories, roles, scanners, security settings — when:

  • it holds a binding of a role containing admin on the pattern *, or
  • it is an OIDC user in auth.adminGroups or auth.adminUsers, or
  • it uses the bootstrap token.

A token with scopes that don’t include admin never acts as an administrator, even if its owner is one.

Repositories with anonymousRead: true can be read by anyone — unless auth.anonymousAccess is set to false, in which case they are readable by any authenticated user instead. Anonymous requests can never write.

  • Group repositories are authorised as a whole. Read access to a group grants read access to everything served through it, from any member, as in Nexus. Don’t put private hosted repositories into a group that is anonymously readable or readable by a wider audience than the members.
  • Repositories you can’t read look like 404 in the management API, so names aren’t disclosed.
  • Scopes cap tokens. A request is allowed only if the token’s scopes include the action and a binding grants it.
  • Changes apply within seconds. Bindings are cached for about five seconds and invalidated on change.
  • The API tells you what you can do. Every repository returned by the API has a permissions array with the caller’s actions on it.