v16: automated service-account token rotation via the admin token API

supernaut kommenterad

2026-07-17 11:52:20 +00:00

Ägare

Tier 1 v16 follow-up (gated on #73 landing). v16 adds an instance-admin token-management API: GET/POST/DELETE /api/v1/admin/users/{user}/tokens over normal site-admin token auth (PR 12323), with token creation dates in responses (PR 12620).

This removes ADR 0024's worst step — the admin password-reset + Basic-auth dance to mint/revoke a PAT for a no-login service account — and enables automated, age-based PAT rotation for gitborg-renovate, gitborg-reconciler, gitborg-runner-controller and gitborg-ci.

Scope:

Verify the reconciler's site-admin token scope covers the new admin token routes (re-check against /api/swagger post-upgrade). — read:admin verified against prod swagger 16.0.0; the token-audit run confirms it lists all accounts' tokens.
Replace the out-of-band mint/revoke procedure with the API. — runbook § Rotate a service-account PAT (mint → vault → apply → verify → revoke by id).
Add age-based rotation (creation date is now exposed). — token-audit role (daily timer) exports token creation-time metrics; ForgejoTokenRotationDue alerts >80d. Live on prod.
Update ADR 0024 + runbook (delete the Basic-auth procedure). — ADR 0024 amended (bitborg-docs); runbook rewritten.

Delivered via PRs #96 (token-audit role + alerts), #108 (readability fix), #109 (vaulted PAT), bitborg-docs #36 (ADR 0024). Fully activated on prod 2026-07-18.

Note: v16's Authorized Integrations (JWT auth without static secrets) may eventually obsolete static PATs — tracked separately in #80, not blocking. Fully autonomous host-side rotation (a timer that mints+delivers without an operator) was deliberately deferred as an ADR-level change (would fight the vault-as-source-of-truth model); the age alert + one-command procedure covers the practical need.

**Tier 1 v16 follow-up** (gated on #73 landing). v16 adds an instance-admin token-management API: `GET/POST/DELETE /api/v1/admin/users/{user}/tokens` over normal site-admin token auth (PR 12323), with token creation dates in responses (PR 12620). This removes ADR 0024's worst step — the admin password-reset + Basic-auth dance to mint/revoke a PAT for a no-login service account — and enables **automated, age-based PAT rotation** for `gitborg-renovate`, `gitborg-reconciler`, `gitborg-runner-controller` and `gitborg-ci`. Scope: - [x] Verify the reconciler's site-admin token scope covers the new admin token routes (re-check against `/api/swagger` post-upgrade). — `read:admin` verified against prod swagger 16.0.0; the token-audit run confirms it lists all accounts' tokens. - [x] Replace the out-of-band mint/revoke procedure with the API. — runbook § *Rotate a service-account PAT* (mint → vault → apply → verify → revoke by id). - [x] Add age-based rotation (creation date is now exposed). — `token-audit` role (daily timer) exports token creation-time metrics; `ForgejoTokenRotationDue` alerts >80d. Live on prod. - [x] Update ADR 0024 + runbook (delete the Basic-auth procedure). — ADR 0024 amended (bitborg-docs); runbook rewritten. Delivered via PRs #96 (token-audit role + alerts), #108 (readability fix), #109 (vaulted PAT), bitborg-docs #36 (ADR 0024). Fully activated on prod 2026-07-18. Note: v16's **Authorized Integrations** (JWT auth without static secrets) may eventually obsolete static PATs — tracked separately in #80, not blocking. *Fully autonomous* host-side rotation (a timer that mints+delivers without an operator) was deliberately deferred as an ADR-level change (would fight the vault-as-source-of-truth model); the age alert + one-command procedure covers the practical need.

supernaut lade till etiketterna

area/identity

ready-for-implementation

type

task

2026-07-17 11:52:30 +00:00

supernaut lade till detta till projektet Bitborg Infrastructure

2026-07-17 11:55:48 +00:00

supernaut refererade till detta ärende

2026-07-17 14:07:19 +00:00

upgrade forgejo 15.0.4 → 16.0.0 #73

supernaut kommenterad

2026-07-17 22:30:32 +00:00

Upphovsperson

Ägare

Progress (branch feat/75-token-rotation, PR pending push):

Done

✅ Verified against prod swagger (16.0.0): GET/POST/DELETE /api/v1/admin/users/{user}/tokens exist with normal token auth, and AccessToken responses carry created_at. write:admin (reconciler-style) covers mint/revoke; read:admin suffices for listing.
✅ Age-based monitoring: new observe-only token-audit role (daily user timer, reconciler shape) lists every service account's tokens and exports gitborg_forgejo_token_created_timestamp_seconds textfile metrics. ForgejoTokenRotationDue (warning) fires when an account's newest token is >80d (alert_token_rotation_due_days); TokenAuditFailed covers the audit itself. Auth = new gitborg-token-audit admin account (ADR 0024 one-admin-per-automation) with a read:admin-only PAT — the audit can never mint or revoke.
✅ API-based rotation procedure replaces the out-of-band dance: runbook § Rotate a service-account PAT (mint → vault → apply role tag → verify → revoke by id). ADR 0024's basic-auth caveat marked superseded (docs branch docs/75-adr-0024-token-api).

Deliberately deferred: fully-autonomous host-side rotation. Every consumer re-renders its token from vault on each apply (renovate.env, reconciler.env, runner-controller podman secret), so a host timer that mints+delivers new tokens makes the next site.yml run write the old, revoked token back — an outage generator. Going autonomous means moving the runtime source of truth from Vault to the host (create-if-missing semantics in 3 roles + self-rotation chicken-and-egg + crash-between-mint-and-deliver recovery) — an ADR-level change that deserves its own decision. The alert + one-command procedure gets ~90% of the value with none of that risk. If we still want full auto, propose it as a follow-up ADR.

Remaining apply-day steps: apply --tags forgejo (creates the account), mint the read:admin PAT, vault as vault_forgejo_token_audit_token, apply --tags token-audit,monitoring.

Progress (branch `feat/75-token-rotation`, PR pending push): **Done** - ✅ Verified against prod swagger (16.0.0): `GET/POST/DELETE /api/v1/admin/users/{user}/tokens` exist with normal token auth, and `AccessToken` responses carry `created_at`. `write:admin` (reconciler-style) covers mint/revoke; `read:admin` suffices for listing. - ✅ **Age-based monitoring**: new observe-only `token-audit` role (daily user timer, reconciler shape) lists every service account's tokens and exports `gitborg_forgejo_token_created_timestamp_seconds` textfile metrics. `ForgejoTokenRotationDue` (warning) fires when an account's newest token is >80d (`alert_token_rotation_due_days`); `TokenAuditFailed` covers the audit itself. Auth = new `gitborg-token-audit` admin account (ADR 0024 one-admin-per-automation) with a **read:admin-only** PAT — the audit can never mint or revoke. - ✅ **API-based rotation procedure** replaces the out-of-band dance: runbook § *Rotate a service-account PAT* (mint → vault → apply role tag → verify → revoke by id). ADR 0024's basic-auth caveat marked superseded (docs branch `docs/75-adr-0024-token-api`). **Deliberately deferred: fully-autonomous host-side rotation.** Every consumer re-renders its token from vault on each apply (`renovate.env`, `reconciler.env`, runner-controller podman secret), so a host timer that mints+delivers new tokens makes the next `site.yml` run write the *old, revoked* token back — an outage generator. Going autonomous means moving the runtime source of truth from Vault to the host (create-if-missing semantics in 3 roles + self-rotation chicken-and-egg + crash-between-mint-and-deliver recovery) — an ADR-level change that deserves its own decision. The alert + one-command procedure gets ~90% of the value with none of that risk. If we still want full auto, propose it as a follow-up ADR. Remaining apply-day steps: apply `--tags forgejo` (creates the account), mint the read:admin PAT, vault as `vault_forgejo_token_audit_token`, apply `--tags token-audit,monitoring`.

supernaut refererade till detta ärende från en incheckning

2026-07-18 07:09:35 +00:00

feat(scripts): Forgejo 2FA / account access-review evidence tool (#79)

supernaut refererade till detta ärende från en incheckning

2026-07-18 07:10:35 +00:00

feat(token-audit): age-based service-account token monitoring (#75)

supernaut refererade till detta ärende

2026-07-18 07:17:38 +00:00

feat(token-audit): age-based service-account token monitoring (#75) #96

supernaut refererade till detta ärende

2026-07-18 07:18:07 +00:00

feat(scripts): Forgejo 2FA / account access-review evidence tool (#79) #99