stephan
47290d2d8f
- added /update/enroll endpoint and enrollment logic - migrated update client to v1 api endpoints and bearer auth - implemented remote status reporting in backend and scripts - updated requirements and project status
92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
ID: DOC_000006 | Version: 0.1.0 | Status: Draft
|
|
|
|
# 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.
|