Admin automation: a published API reference and a scoped credential for provisioning #1108

Closed
opened 2026-11-04 03:11:35 +00:00 by Cordy · 5 comments
Owner

Gap (v0.7 feature-gap research, 2026-11-04, decided by Nikola). Since #890 the admin API accepts browser sessions only, so creating accounts, spaces, quotas or shares cannot be scripted, and there is no published API reference.

Competitors. Nextcloud and ownCloud 10 have occ plus the provisioning API; OpenCloud has the LibreGraph API with app tokens (auth-app, graph); Seafile has the admin web API with tokens.

To research and decide when worked on (must respect #890's reasons). A scoped, expiring, audited admin credential (which scopes, where it is created, IP binding, how it is revoked, never usable from a browser) vs a cairnd admin CLI that talks to the state store; which routes are covered; the reference format (OpenAPI generated from the code); rate limits; multi-instance (#742).

Refs: scratch/b7e/backlog/gap-v07/research-v07-gaps.md A15, #890.

**Gap (v0.7 feature-gap research, 2026-11-04, decided by Nikola).** Since #890 the admin API accepts browser sessions only, so creating accounts, spaces, quotas or shares cannot be scripted, and there is no published API reference. **Competitors.** Nextcloud and ownCloud 10 have `occ` plus the provisioning API; OpenCloud has the LibreGraph API with app tokens ([auth-app](https://raw.githubusercontent.com/opencloud-eu/opencloud/main/services/auth-app/README.md), [graph](https://doc.owncloud.com/ocis/7.3/deployment/services/s-list/graph.html)); Seafile has the admin web API with tokens. **To research and decide when worked on (must respect #890's reasons).** A scoped, expiring, audited admin credential (which scopes, where it is created, IP binding, how it is revoked, never usable from a browser) vs a `cairnd admin` CLI that talks to the state store; which routes are covered; the reference format (OpenAPI generated from the code); rate limits; multi-instance (#742). Refs: `scratch/b7e/backlog/gap-v07/research-v07-gaps.md` A15, #890.
Author
Owner

Research done (scratch/b7e/backlog/research-1108.md). Today every admin power needs a browser session (auth.AdminPowers, 147 requireAdmin routes, #890); #890 itself named "a scoped, revocable admin API token" as the follow-up. Nextcloud 34 reached the same conclusion as #890 (app passwords not for management APIs, CVE-2026-77172) but shipped no replacement; Google, Microsoft, GitLab, Forgejo and GitHub use a separate machine credential with named scopes, expiry and review. Incidents (CircleCI, Okta, Cloudflare, Midnight Blizzard, tj-actions) argue for scoped, expiring, audited, revocable keys that cannot escalate. Recommended: native "API keys" (admin-created from a confirmed browser session, shown once, hashed, prefixed for secret scanning, scopes read/change per area, required expiry, optional address list, Bearer only, its own audited actor, off by default) that can never reach file content, settings, admin roles, keys, purge or holds; OpenAPI 3.1 reference for the reachable routes; IdP client credentials and SCIM later. Decisions follow.

Research done (`scratch/b7e/backlog/research-1108.md`). Today every admin power needs a browser session (`auth.AdminPowers`, 147 `requireAdmin` routes, #890); #890 itself named "a scoped, revocable admin API token" as the follow-up. Nextcloud 34 reached the same conclusion as #890 (app passwords not for management APIs, CVE-2026-77172) but shipped no replacement; Google, Microsoft, GitLab, Forgejo and GitHub use a separate machine credential with named scopes, expiry and review. Incidents (CircleCI, Okta, Cloudflare, Midnight Blizzard, tj-actions) argue for scoped, expiring, audited, revocable keys that cannot escalate. Recommended: native "API keys" (admin-created from a confirmed browser session, shown once, hashed, prefixed for secret scanning, scopes read/change per area, required expiry, optional address list, Bearer only, its own audited actor, off by default) that can never reach file content, settings, admin roles, keys, purge or holds; OpenAPI 3.1 reference for the reachable routes; IdP client credentials and SCIM later. Decisions follow.
Author
Owner

Decided by Nikola 2026-11-10: native API keys (admin-created from a confirmed browser session, shown once, hashed, prefixed for secret scanners, scopes per area read/change, expiry required default 90 d max 365, optional address list, Bearer only, its own audited actor with the creator recorded, off by default; never file content, settings, admin roles, encryption keys, purge, holds or other keys). Also: no deleting spaces/accounts in v1; keys unused 90 days stop with notice; instance policy can require address lists; local password reset under the accounts scope (shown once, audited, announced); OpenAPI 3.1 reference kept honest by a route test; 20 req/s burst 100 per key, 429 + Retry-After; SCIM a v1.x follow-up; creating/rotating a key needs the creator's second factor once #1046 ships. Next: mockup.

**Decided by Nikola 2026-11-10:** native API keys (admin-created from a confirmed browser session, shown once, hashed, prefixed for secret scanners, scopes per area read/change, expiry required default 90 d max 365, optional address list, Bearer only, its own audited actor with the creator recorded, off by default; never file content, settings, admin roles, encryption keys, purge, holds or other keys). Also: no deleting spaces/accounts in v1; keys unused 90 days stop with notice; instance policy can require address lists; local password reset under the accounts scope (shown once, audited, announced); OpenAPI 3.1 reference kept honest by a route test; 20 req/s burst 100 per key, 429 + Retry-After; SCIM a v1.x follow-up; creating/rotating a key needs the creator's second factor once #1046 ships. Next: mockup.
Author
Owner

Mockup 1108-api-keys-mockup.html approved by Nikola 2026-11-10 with its open points as recommended (key names by the username rule without "@", no renaming; config-file emergency accounts cannot create keys; a Read level for every area; no deleting app groups by key; rotation restarts the original expiry length, revoked never rotates; the confirm dialog fetches the key challenge on open; admins without a second step may create keys with a nudge and an Admin review flag; address-list keys fail closed when real client addresses are not visible; refusal bell first per key per 24 h; Admin review flags; tab between Groups and Seats). Change: docs stay in the repo only (handbook page docs/handbook/automation-api.md, openapi.yaml in the repo and served by the instance), nothing published on swisscairn.ch now. Next: spec and plan (b6v07, v0.6.406).

Mockup `1108-api-keys-mockup.html` approved by Nikola 2026-11-10 with its open points as recommended (key names by the username rule without "@", no renaming; config-file emergency accounts cannot create keys; a Read level for every area; no deleting app groups by key; rotation restarts the original expiry length, revoked never rotates; the confirm dialog fetches the key challenge on open; admins without a second step may create keys with a nudge and an Admin review flag; address-list keys fail closed when real client addresses are not visible; refusal bell first per key per 24 h; Admin review flags; tab between Groups and Seats). Change: docs stay in the repo only (handbook page `docs/handbook/automation-api.md`, `openapi.yaml` in the repo and served by the instance), nothing published on swisscairn.ch now. Next: spec and plan (b6v07, v0.6.406).
Author
Owner

Spec decisions (2026-11-10), after research on the spec's open points:

  • A key may send a one-time password; if it sends none, Cairn generates one and returns it once.
  • Keys can never reset, disable, rename or change the e-mail of an account that is an administrator by any source (config, admins.json, admin groups).
  • A quota on a new space is accepted only from administrators and keys.
  • Directory usernames may not start with api:, so audit actors are never ambiguous.
  • After a storage restore, every API key pauses until an administrator rotates it (as #904 does for devices).
  • Accounts created by a key: one folded admin notification per key per 24 h, plus a care note in the handbook.
  • Two build fixes found in research:
    • The key check sits inside sign-in, after the seat and home-folder steps, so a key never takes a seat or gets a home folder.
    • Browser detection does not rely on Sec-Fetch-Mode alone, because Node's fetch sends it on every request.
  • String corrections approved. New German strings use "Audit-Protokoll" and "Administration".

Next: spec and plan updated, then build (b6v07).

Spec decisions (2026-11-10), after research on the spec's open points: - A key may send a one-time password; if it sends none, Cairn generates one and returns it once. - Keys can never reset, disable, rename or change the e-mail of an account that is an administrator by any source (config, admins.json, admin groups). - A quota on a new space is accepted only from administrators and keys. - Directory usernames may not start with `api:`, so audit actors are never ambiguous. - After a storage restore, every API key pauses until an administrator rotates it (as #904 does for devices). - Accounts created by a key: one folded admin notification per key per 24 h, plus a care note in the handbook. - Two build fixes found in research: - The key check sits inside sign-in, after the seat and home-folder steps, so a key never takes a seat or gets a home folder. - Browser detection does not rely on `Sec-Fetch-Mode` alone, because Node's fetch sends it on every request. - String corrections approved. New German strings use "Audit-Protokoll" and "Administration". Next: spec and plan updated, then build (b6v07).
Author
Owner

Shipped in v0.6.406 (PR #1157, merge bee68e7c). Live on both dogfoods since 2026-11-11 15:34 UTC: pods ready with no restarts, no new WARN or ERROR lines. /api/v1/openapi.yaml answers 401 without a sign-in, and a junk Bearer key gets 401.

What shipped

  • Keys: native API keys (cairn_ak_…), off by default. An administrator creates them in Users & access › API keys after Confirm it's you, with the second step when they have one. A key is shown once and stored as SHA-256. Each key has scopes (read or change per area), an expiry (90 days by default, 365 at most) and an optional address list.
  • The gate: every key request passes one central check, in this order: keys off, browser signals (never Sec-Fetch-Mode alone), paused after a restore, address, key management, files, scope, then a rate limit of 20/s with a burst of 100.
  • What a key never touches:
    • file content, settings, admin roles, keys, purge or holds;
    • any administrator account, whatever makes it an administrator (config, admins.json, app groups, directory admin groups). That covers create, reset, disable, rename, e-mail, devices and personal quota. If group membership cannot be checked, the key is refused.
  • What a key never sees: public link tokens (it sees lh: hashes instead), the audit folder, or the storage location.
  • Actor and limits: a key acts as api:<name> with the creator recorded. It holds no licence seat and makes no home folder. Keys stop after 90 days without use, and pause after a storage restore until rotated.
  • Around it: the OpenAPI 3.1 reference with a route-table test, and the handbook page docs/handbook/automation-api.md (in the repo only, per the docs rule). Also bell items, Admin review, export rows and audit verbs.

Follow-ups: SCIM 2.0 server and IdP client credentials (phase 2) are filed separately. The backlog holds Keycloak admin groups with more than 500 members, an administrator group's group quota, and an LDAP outage blocking keys for local accounts.

Shipped in **v0.6.406** (PR #1157, merge bee68e7c). Live on both dogfoods since 2026-11-11 15:34 UTC: pods ready with no restarts, no new WARN or ERROR lines. `/api/v1/openapi.yaml` answers 401 without a sign-in, and a junk Bearer key gets 401. **What shipped** - **Keys:** native API keys (`cairn_ak_…`), off by default. An administrator creates them in Users & access › API keys after Confirm it's you, with the second step when they have one. A key is shown once and stored as SHA-256. Each key has scopes (read or change per area), an expiry (90 days by default, 365 at most) and an optional address list. - **The gate:** every key request passes one central check, in this order: keys off, browser signals (never `Sec-Fetch-Mode` alone), paused after a restore, address, key management, files, scope, then a rate limit of 20/s with a burst of 100. - **What a key never touches:** - file content, settings, admin roles, keys, purge or holds; - any administrator account, whatever makes it an administrator (config, `admins.json`, app groups, directory admin groups). That covers create, reset, disable, rename, e-mail, devices and personal quota. If group membership cannot be checked, the key is refused. - **What a key never sees:** public link tokens (it sees `lh:` hashes instead), the audit folder, or the storage location. - **Actor and limits:** a key acts as `api:<name>` with the creator recorded. It holds no licence seat and makes no home folder. Keys stop after 90 days without use, and pause after a storage restore until rotated. - **Around it:** the OpenAPI 3.1 reference with a route-table test, and the handbook page `docs/handbook/automation-api.md` (in the repo only, per the docs rule). Also bell items, Admin review, export rows and audit verbs. **Follow-ups:** SCIM 2.0 server and IdP client credentials (phase 2) are filed separately. The backlog holds Keycloak admin groups with more than 500 members, an administrator group's group quota, and an LDAP outage blocking keys for local accounts.
Cordy closed this issue 2026-11-11 15:37:33 +00:00
Sign in to join this conversation.
No labels
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#1108
No description provided.