stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
f98cea3bcfb4730b238ab8605ce6d48c2998aa44
git.stella-ops.org/docs/ui/admin.md
master 15b4a1de6a feat: Document completed tasks for KMS, Cryptography, and Plugin Libraries 
- Added detailed task completion records for KMS interface implementation and CLI support for file-based keys.
- Documented security enhancements including Argon2id password hashing, audit event contracts, and rate limiting configurations.
- Included scoped service support and integration updates for the Plugin platform, ensuring proper DI handling and testing coverage.
2025-10-31 14:37:45 +02:00

8.4 KiB
Raw Blame History

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 (captures pending upload):
    • docs/assets/ui/admin/tenants-placeholder.png
    • docs/assets/ui/admin/roles-placeholder.png
    • docs/assets/ui/admin/tokens-placeholder.png
  • 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).