94 lines
3.2 KiB
Markdown
94 lines
3.2 KiB
Markdown
ID: DOC_000006 | Version: 0.2.2 | Status: Draft
|
||
Archived – superseded by new documentation.
|
||
By: Codex (GPT-5)
|
||
|
||
# Admin Token Operations
|
||
|
||
## Purpose
|
||
This document describes how operators create and manage pre-shared enrollment tokens for clients.
|
||
|
||
## Pre-Shared Token Creation
|
||
Operators generate a single-use enrollment token and share it out-of-band with the client.
|
||
|
||
Recommended properties:
|
||
- Single-use only
|
||
- Short TTL (e.g., 24h)
|
||
- Scoped to `project_id` and optional `client_id`/`software_id`
|
||
|
||
## Admin Interfaces
|
||
We provide both an Admin API and a CLI tool for token operations. A frontend will be added later.
|
||
|
||
### Admin User and Access
|
||
- An admin user must exist to operate token workflows.
|
||
- Initial access uses a local admin token.
|
||
- Later, admin auth will be integrated with the OIDC service.
|
||
|
||
### CLI and Admin API Capabilities
|
||
- Create enrollment tokens
|
||
- List token metadata (no plaintext output)
|
||
- Revoke tokens
|
||
- Export a token as a file for client installation
|
||
|
||
### Local Admin Token (Initial Phase)
|
||
- Admin requests must include `Authorization: Bearer <ADMIN_TOKEN>`.
|
||
- The admin token is stored locally (e.g., `.env`) and never committed.
|
||
|
||
Example `.env` (local only):
|
||
```
|
||
ADMIN_TOKEN=change-me-please
|
||
```
|
||
|
||
Minimal flow (first token):
|
||
1) Set `ADMIN_TOKEN` in `.env`.
|
||
2) Call `POST /v1/admin/enrollment-tokens` with the bearer token.
|
||
3) Export the returned one-time token to a file and hand it to the client.
|
||
|
||
## Admin API (Draft)
|
||
All admin endpoints are authenticated. Initial auth is local; later OIDC.
|
||
|
||
Base path:
|
||
- `/v1/admin`
|
||
|
||
Endpoints:
|
||
- `POST /v1/admin/enrollment-tokens`
|
||
- Create a pre-shared enrollment token.
|
||
- Request: `project_id`, optional `client_id`, optional `software_id`, optional `expires_at`.
|
||
- Response: token metadata + one-time plaintext token.
|
||
- `GET /v1/admin/enrollment-tokens`
|
||
- List token metadata (never return plaintext tokens).
|
||
- Supports filtering by `project_id`, `client_id`, `status` (active/used/expired).
|
||
- `POST /v1/admin/enrollment-tokens/{token_id}/revoke`
|
||
- Revoke a token (marks as revoked or sets `used_at`/`revoked_at`).
|
||
- `GET /v1/admin/enrollment-tokens/{token_id}/export`
|
||
- Export the one-time token to a file download (single use).
|
||
|
||
## CLI (Draft)
|
||
Example commands (names can be adjusted):
|
||
- `update-service admin token create --project <id> [--client <id>] [--software <id>] [--expires <iso8601>]`
|
||
- `update-service admin token list --project <id> [--status active|used|expired|revoked]`
|
||
- `update-service admin token revoke --id <token_id>`
|
||
- `update-service admin token export --id <token_id> --out ./enroll-token.txt`
|
||
|
||
Example format:
|
||
```
|
||
enroll_<random_32_bytes>
|
||
```
|
||
|
||
## Storage and Safety
|
||
- Store only a hash of the enrollment token (never plaintext).
|
||
- Track `created_at`, `expires_at`, and `used_at`.
|
||
- Deny enrollment if `expires_at` is exceeded or `used_at` is set.
|
||
|
||
## Rotation and Revocation
|
||
- Revoke enrollment tokens by invalidating their stored hash.
|
||
- Issue a new enrollment token if the previous one expires or is leaked.
|
||
|
||
## Distribution
|
||
Preferred channels:
|
||
- One-time install code (copy/paste)
|
||
- QR code
|
||
- Encrypted file included in an install bundle
|
||
|
||
## Audit Expectations
|
||
- Log token creation and enrollment usage for traceability.
|