master
7b5bdcf4d3
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes. - Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes. - Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables. - Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
175 lines
8.5 KiB
Markdown
175 lines
8.5 KiB
Markdown
# StellaOps Console - Admin Workspace
|
|
|
|
> **Audience:** Authority Guild, Console admins, support engineers, tenant operators.
|
|
> **Scope:** Tenant management, role mapping, token lifecycle, integrations, fresh-auth prompts, security guardrails, offline behaviour, and compliance checklist for Sprint 23.
|
|
|
|
The Admin workspace centralises Authority-facing controls: tenants, roles, API clients, tokens, and integrations. It surfaces RBAC mappings, token issuance logs, and bootstrap flows with the same offline-first guarantees as the rest of the console.
|
|
|
|
---
|
|
|
|
## 1. Access and prerequisites
|
|
|
|
- **Route:** `/console/admin` with sub-routes for tenants, users, roles, tokens, integrations, audit, and bootstrap.
|
|
- **Scopes:**
|
|
- `ui.admin` (base access)
|
|
- `authority:tenants.read` / `authority:tenants.write`
|
|
- `authority:roles.read` / `authority:roles.write`
|
|
- `authority:tokens.read` / `authority:tokens.revoke`
|
|
- `authority:clients.read` / `authority:clients.write`
|
|
- `authority:audit.read` (view audit trails)
|
|
- **Fresh-auth:** Sensitive actions (token revoke, bootstrap key issue, signing key rotation) require fresh-auth challenge.
|
|
- **Dependencies:** Authority service (`/internal/*` APIs), revocation export, JWKS, licensing posture endpoint, integration config store.
|
|
|
|
---
|
|
|
|
## 2. Layout overview
|
|
|
|
```
|
|
+--------------------------------------------------------------------+
|
|
| Header: Tenant picker - environment badge - security banner |
|
|
+--------------------------------------------------------------------+
|
|
| Tabs: Tenants | Roles & Scopes | Users & Tokens | Integrations | Audit |
|
|
+--------------------------------------------------------------------+
|
|
| Sidebar: Quick actions (Invite user, Create client, Export revocations)
|
|
| Main panel varies per tab |
|
|
+--------------------------------------------------------------------+
|
|
```
|
|
|
|
The header includes offline status indicator and link to Authority health page.
|
|
|
|
---
|
|
|
|
## 3. Tenants tab
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| **Tenant ID** | Lowercase slug used in tokens and client registrations. |
|
|
| **Display name** | Human-friendly name. |
|
|
| **Status** | `active`, `suspended`, `pending`. Suspended tenants block token issuance. |
|
|
| **Isolation mode** | `dedicated`, `shared`, or `sandbox`. Drives RBAC defaults. |
|
|
| **Default roles** | Roles automatically assigned to new users within the tenant. |
|
|
| **Offline snapshots** | Latest snapshot timestamp, checksum, operator. |
|
|
|
|
Actions:
|
|
|
|
- `Create tenant` (requires `authority:tenants.write`). Form captures display name, slug, isolation mode, default roles, bootstrap contact, optional plan metadata.
|
|
- `Suspend/Resume` toggles token issuance and surfaces audit entry.
|
|
- `Export tenant bundle` downloads tenant-specific revocation + JWKS package for air-gap distribution.
|
|
- CLI parity: `stella auth tenant create --tenant <id>`, `stella auth tenant suspend --tenant <id>`.
|
|
|
|
---
|
|
|
|
## 4. Roles & scopes tab
|
|
|
|
- Table lists roles with mapped scopes and audiences.
|
|
- Inline editor supports adding/removing scopes (with validation).
|
|
- Scope categories: UI, Scanner, Concelier, Excititor, Policy, Attestor, Notifier, Scheduler, Offline kit.
|
|
- Visual diff shows impact of changes on linked clients/users before committing.
|
|
- "Effective permissions" view summarises what each role grants per service.
|
|
- CLI parity: `stella auth role update --role ui.admin --add-scope authority:tokens.revoke`.
|
|
|
|
---
|
|
|
|
## 5. Users & tokens tab
|
|
|
|
Sections:
|
|
|
|
1. **User list** - identity, tenant, roles, last login, MFA status. Actions include reset password (if plugin supports), enforce fresh-auth, disable user.
|
|
2. **Token inventory** - lists active tokens (access/refresh/device). Columns: token ID, type, subject, audience, issued at, expires, status. Toggle to show revoked tokens.
|
|
3. **Token details** drawer shows claims, sender constraint (`cnf`), issuance metadata, revocation history.
|
|
4. **Revoke token** action requires fresh-auth and prompts for reason (incident, user request, compromise).
|
|
5. **Bulk revoke** (per tenant or role) triggers Authority revocation export to ensure downstream services purge caches.
|
|
|
|
Audit entries appear for every user/token change. CLI parity: `stella auth token revoke --token <id>`.
|
|
|
|
---
|
|
|
|
## 6. Integrations tab
|
|
|
|
- **Authority clients** list (service accounts) with grant types, allowed scopes, DPoP/mTLS settings, tenant hints, and rotation status.
|
|
- **Bootstrap bundles** - downloadable templates for new clients/users; includes configuration YAML and CLI instructions.
|
|
- **External IdP connectors** (optional) - displays status for SAML/OIDC plugins; includes metadata upload field and test login result.
|
|
- **Licensing posture** - read-only panel summarising plan tier, entitlement expiry, and contact info (pulled from licensing service).
|
|
- **Notifications** - optional webhook configuration for token events (on revoke, on failure).
|
|
- CLI parity: `stella auth client create --client concelier --grant client_credentials --tenant prod`.
|
|
|
|
---
|
|
|
|
## 7. Audit tab
|
|
|
|
- Timeline view of administrative events (user changes, role updates, token revocations, bootstrap actions, key rotations).
|
|
- Filters: event type, actor, tenant, scope, correlation ID.
|
|
- Export button downloads CSV/JSON for SOC ingestion.
|
|
- "Open in logs" copies search query pre-populated with correlation IDs.
|
|
- CLI parity: `stella auth audit export --from 2025-10-20`.
|
|
|
|
---
|
|
|
|
## 8. Fresh-auth prompts
|
|
|
|
- High-risk actions (revoke all tokens, rotate signing key, create privileged client) trigger modal requiring credential re-entry or hardware key touch.
|
|
- Fresh-auth window is 5 minutes; countdown displayed.
|
|
- UI surface indicates when current session is outside fresh-auth window; sensitive buttons disabled until re-auth.
|
|
- Audit log records fresh-auth events (`authority.fresh_auth.start`, `authority.fresh_auth.success`).
|
|
- CLI parity: `stella auth fresh-auth` obtains short-lived token for scriptable flows.
|
|
|
|
---
|
|
|
|
## 9. Security guardrails
|
|
|
|
- DPoP enforcement reminders for UI clients; console warns if any client lacks sender constraint.
|
|
- mTLS enforcement summary for high-value audiences (Signer/Attestor).
|
|
- Token policy checklists (access token TTL, refresh token policy) with alerts when deviating from defaults.
|
|
- Revocation bundle export status (timestamp, digest, operator).
|
|
- Key rotation panel showing current `kid`, last rotation, next scheduled rotation, and manual trigger button (ties into Authority rotate API).
|
|
- CLI parity: `stella auth signing rotate` for script automation.
|
|
|
|
---
|
|
|
|
## 10. Offline and air-gap behaviour
|
|
|
|
- Offline banner indicates snapshot version; disables direct remote calls.
|
|
- Tenant/role edits queue change manifests; UI instructs users to apply via CLI (`stella auth apply --bundle <file>`).
|
|
- Token inventory shows snapshot state; revoke buttons generate scripts for offline Authority host.
|
|
- Integrations tab offers manual download/upload for client definitions and IdP metadata.
|
|
- Audit exports default to local storage with checksum output for transfer.
|
|
|
|
---
|
|
|
|
## 11. Screenshot coordination
|
|
|
|
- Placeholders:
|
|
- ``
|
|
- ``
|
|
- ``
|
|
- Capture real screenshots with Authority Guild once Sprint 23 UI is final (tracked in `#console-screenshots`, 2025-10-26 entry). Provide both light and dark theme variants.
|
|
|
|
---
|
|
|
|
## 12. References
|
|
|
|
- `/docs/modules/authority/architecture.md` - Authority architecture.
|
|
- `/docs/11_AUTHORITY.md` - Authority service overview.
|
|
- `/docs/security/authority-scopes.md` - scope definitions.
|
|
- `/docs/ui/policies.md` - policy approvals requiring fresh-auth.
|
|
- `/docs/ui/console-overview.md` - navigation shell.
|
|
- `/docs/modules/cli/guides/authentication.md` (pending) and `/docs/modules/cli/guides/policy.md` for CLI flows.
|
|
- `/docs/modules/scheduler/operations/worker.md` for integration with scheduler token rotation.
|
|
|
|
---
|
|
|
|
## 13. Compliance checklist
|
|
|
|
- [ ] Tenants, roles/scopes, and token management documented with actions and CLI parity.
|
|
- [ ] Integrations and audit views covered.
|
|
- [ ] Fresh-auth prompts and guardrails described.
|
|
- [ ] Security controls (DPoP, mTLS, key rotation, revocations) captured.
|
|
- [ ] Offline behaviour explained with script guidance.
|
|
- [ ] Screenshot placeholders and coordination noted.
|
|
- [ ] References validated.
|
|
|
|
---
|
|
|
|
*Last updated: 2025-10-26 (Sprint 23).*
|
|
|