docs: authentication & authorization system design (epic #79) #95

2026-07-02T00:51:53+10:00

unkinben commented

2026-07-02 00:51:53 +10:00

Part of #79

Why

The management API and proxy are fully open. Before writing security-sensitive code, this establishes the architecture for review.

What

docs/auth.md covers:

Principals: service accounts (static + Vault-issued dynamic tokens) and users (OIDC/LDAP via the UI).
Tokens: aapi_-prefixed, stored only as SHA-256.
ACL model: (path_pattern, capability) grants; resource paths like remote/<remote>/<path> and admin/...; capabilities read/create/write/delete; route→(resource,capability) mapping.
Default-open: AUTH_ENFORCE=false default; observe-only middleware; anonymous principal seeded with * so enabling enforcement still stays open until grants are tightened.
Vault: mint/revoke endpoints + a companion vault-plugin-secrets-artifactapi engine modelled on vault-plugin-secrets-litellm (vault/sdk, OpenBao-compatible).
Data model: additive service_accounts / auth_tokens / acl_grants tables.
Phased delivery (6 PRs) and cross-repo work (terraform-vault, argocd-apps, terraform-provider-artifactapi, terraform-authentik/ldap).

Part of #79 ## Why The management API and proxy are fully open. Before writing security-sensitive code, this establishes the architecture for review. ## What `docs/auth.md` covers: - **Principals**: service accounts (static + Vault-issued dynamic tokens) and users (OIDC/LDAP via the UI). - **Tokens**: `aapi_`-prefixed, stored only as SHA-256. - **ACL model**: `(path_pattern, capability)` grants; resource paths like `remote/<remote>/<path>` and `admin/...`; capabilities `read`/`create`/`write`/`delete`; route→(resource,capability) mapping. - **Default-open**: `AUTH_ENFORCE=false` default; observe-only middleware; anonymous principal seeded with `*` so enabling enforcement still stays open until grants are tightened. - **Vault**: mint/revoke endpoints + a companion `vault-plugin-secrets-artifactapi` engine modelled on `vault-plugin-secrets-litellm` (vault/sdk, OpenBao-compatible). - **Data model**: additive `service_accounts` / `auth_tokens` / `acl_grants` tables. - **Phased delivery** (6 PRs) and cross-repo work (terraform-vault, argocd-apps, terraform-provider-artifactapi, terraform-authentik/ldap). ## Next On approval I will implement phase 1 (data model + observe-only principal resolution), which changes no behaviour. No code changes; docs only.

unkinben added 1 commit 2026-07-02 00:51:53 +10:00

docs: design for authentication & authorization system

ci/woodpecker/pr/pre-commit Pipeline was successful

Details

ci/woodpecker/pr/build Pipeline was successful

Details

ci/woodpecker/pr/test Pipeline was successful

Details

67cedf9bba

Add docs/auth.md describing the default-open auth/authz design: service
account and user principals, hashed bearer tokens, a path+capability ACL
model (read/write/delete/create), an observe-only enforcement middleware
gated by AUTH_ENFORCE, Vault mint/revoke integration with a companion
vault-plugin-secrets-artifactapi engine, OIDC/LDAP user login, and a
phased delivery plan.

Refs #79

ci/woodpecker/pr/pre-commit Pipeline was successful

Required

Details

ci/woodpecker/pr/build Pipeline was successful

Required

Details

ci/woodpecker/pr/test Pipeline was successful

Required

Details

This pull request can be merged automatically.

This branch is out-of-date with the base branch

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin benvin/auth-design-doc:benvin/auth-design-doc

git checkout benvin/auth-design-doc

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: unkin/artifactapi#95