Console Admin RBAC Architecture

Audience: engineers and operators working with the Authority-backed Console admin surface, and anyone reasoning about Stella Ops scopes and role bundles. Source of truth: the canonical scope catalog is StellaOpsScopes.cs; the seeded role bundles are ConsoleAdminEndpointExtensions.GetDefaultRoles(). Where this doc and the code disagree, the code wins — several rows below are explicitly marked proposed vs seeded.

1. Purpose

• Provide a unified, Authority-backed admin surface for tenants, users, roles, clients, tokens, and audit.
• Expose the same capabilities to UI and CLI while preserving offline-first operation.
• Normalize scope and role bundles, including Scanner producer roles, for consistent RBAC across modules.
• Align tenant assignment and selection behavior with ADR-002 — multi-tenant same-API-key selection.

2. Scope

• Authority admin APIs and data model used by the Console Admin workspace.
• Role and scope taxonomy, including scanner roles.
• Audit, fresh-auth, and offline export/import workflow.
• UI integration contract (routes, scopes, and API paths).

Non-goals:

• Replacing external IdP user lifecycle workflows (SAML/OIDC remains primary for enterprise identity).
• Exposing privileged mTLS-only admin endpoints directly to the browser.

3. Core Architecture

3.1 Authority admin tiers

• /console/admin: the implemented admin surface. Every endpoint requires the ui.admin scope (enforced at the route-group level via RequireStellaOpsScopes(StellaOpsScopes.UiAdmin)), plus the per-resource authority:* scope on each operation. Mutating operations additionally call RequireFreshAuth(). A tenant header filter resolves the active tenant. Verified in src/Authority/StellaOps.Authority/StellaOps.Authority/Console/Admin/ConsoleAdminEndpointExtensions.cs.
• /api/admin: a legacy alias group that mirrors the user-management endpoints (/api/admin/users) with the same ui.admin + authority:users.* scope requirements and tenant/fresh-auth filters. Same data model and audit log as /console/admin.

NOTE (doc-vs-code): an earlier draft described a separate /admin tier gated by mTLS plus an authority.admin scope. Neither exists in source: there is no authority.admin scope constant in StellaOpsScopes.cs, and the Console admin endpoints are not bound to an mTLS-only route group. Authority does support mutual-TLS sender-constrained tokens generally (AuthorityClientCertificateValidator), but the Console admin tiers above authorize on bearer scopes, not client certificates. The /api/admin alias is the only second tier, and it uses the same UI scopes — not mTLS.

3.2 Entities and ownership

Authority remains the source of truth for:

• Tenant: id, display name, status, isolation mode, default roles.
• Installation: installation id, tenant binding, bootstrap metadata.
• Role: id, display name, scopes[], audiences[], flags (interactive-only, requires fresh-auth).
• User: subject, status, display name, tenant assignments, roles per tenant.
• Client: client id, grant types, auth method, allowed scopes, audiences, tenant hint.
• Token record: access/refresh/device metadata, revocation status.
• Audit events: immutable admin and auth events.

3.3 Fresh-auth

High-risk mutating operations are wired to a fresh-auth gate via RequireFreshAuth() in code:

• Tenant create / update / suspend / resume (and operator-compliance mutations)
• Token revocation (bulk or admin)
• Role create / edit
• Client create / update / secret rotation
• User create / update / enable / disable
• Branding apply (PUT)

Authority enforces these operations against the authenticated principal’s auth_time claim. The claim must be a Unix timestamp no more than five minutes old; timestamps more than one minute in the future are also rejected. Missing, invalid, stale, or excessively future authentication returns HTTP 401 with code fresh_auth_required. Read-only admin routes do not apply this filter, so an older session may inspect state but must reauthenticate before changing it. The general Console admin and process-global identity-provider admin surfaces use the same five-minute/one-minute contract.

4. Scope and Role Taxonomy

4.1 Console admin scopes

Admin scopes (Authority-managed, all defined in StellaOpsScopes.cs):

• authority:tenants.read, authority:tenants.write
• authority:users.read, authority:users.write
• authority:roles.read, authority:roles.write
• authority:clients.read, authority:clients.write
• authority:tokens.read, authority:tokens.revoke
• authority.audit.read — note the dot before audit. The audit-read scope is the only Authority admin scope that uses dot separators (authority.audit.read, alongside the older authority.users.manage, authority.clients.manage, authority.revocation.read); all the tenant/user/role/client/token/branding scopes use the colon-prefixed authority:<resource>.<verb> form. There is no authority:audit.read (colon-form) scope.
• authority:branding.read, authority:branding.write
• authority:idp.read, authority:idp.write
• ui.admin (console access for admin views)

The console Identity Providers route requires ui.admin together with authority:idp.read. Its create, update, delete, enable/disable, test, and apply controls require authority:idp.write and use the same fresh-authentication contract as the Authority mutation endpoints. Legacy platform.idp.read and platform.idp.admin claims do not authorize this Authority-owned surface.

4.2 Scanner scope and role bundles

Scanner scopes and role bundles (all five scopes exist in StellaOpsScopes.cs; the four scanner roles are seeded built-ins in GetDefaultRoles()):

• Scopes: scanner:read, scanner:scan, scanner:export, scanner.signed-sbom-material.write, scanner:write
• Role bundles (scopes here match the code exactly):
  • role/scanner-viewer -> scanner:read
  • role/scanner-operator -> scanner:read, scanner:scan, scanner:export
  • role/scanner-signed-sbom-writer -> scanner.signed-sbom-material.write
  • role/scanner-admin -> scanner:read, scanner:scan, scanner:export, scanner:write

Doc-vs-code (catalog table below): §4.3 augments these scanner bundles with findings:read and aoc:verify. The seeded GetDefaultRoles() catalog does not include those extra scopes on the scanner roles — the built-ins carry only the scanner:* scopes listed here. The §4.3 entries with findings:read/aoc:verify are proposed, not the seeded reality.

Compatibility:

• The signed-SBOM material endpoint uses the dedicated scanner.signed-sbom-material.write scope, which is preserved separately from scanner:write.

4.3 Module role bundle catalog

Role bundles are grouped by module and map to existing Authority scopes unless noted.

Seeded vs. proposed (doc-vs-code, important). The only role bundles actually seeded as built-ins by Authority today are the ten returned by ConsoleAdminEndpointExtensions.GetDefaultRoles(): role/console-viewer, role/console-admin, role/executive-assurance-viewer, role/release-operations-steward, role/security-risk-manager, role/service-release-contributor, role/scanner-viewer, role/scanner-operator, role/scanner-signed-sbom-writer, role/scanner-admin. Every other row in the module table below (Policy, Concelier, Excititor, Notify, Scheduler, Orchestrator, Graph, Vuln Explorer, Export Center, Advisory AI, Signals, Evidence Locker, Observability, Issuer Directory, Task Packs, Airgap, Exceptions, Attestor, Signer, SBOM, Release, Zastava, and the operator/auditor Operator Verify rows) is a proposed/reference bundle: the underlying scopes generally exist in StellaOpsScopes.cs, but the role itself is not seeded as a built-in. Operators can recreate any of these as custom roles via POST /console/admin/roles (which accepts any catalog scope and auto-creates the permission rows). The role IDs marked (new) in the Scheduler rows refer to a no-longer-accurate “scope is new” annotation — see the Missing-scopes note in this section. Where a proposed row’s scopes differ from a seeded built-in (notably the Scanner rows, which the table augments with findings:read/aoc:verify that the seeded scanner roles do not carry), treat the seeded GetDefaultRoles() definition as authoritative.

Service-contributor deployment is a scoped release-control case, not an admin case. Use role/service-release-contributor for users who can update or request updates for their own microservice images in allowed environments. That role must be paired with ABAC constraints such as serviceIds, repositoryIds, imageNamespaces, environmentIds, and maxEnvironmentType; do not grant broad release:publish, release:bypass, ui.admin, orch:operate, or policy:approve just to enable self-service updates. Authority also narrows interactive console authorization-code grants for role/service-release-contributor and legacy role/release-developer principals to the self-service allow-list, so a broad UI client request does not mint admin/publisher/approval scopes for a contributor.

Console administrators manage those attributes from Identity & Access > Users. Selecting role/service-release-contributor opens fields for service IDs, repository IDs, image namespaces, environment IDs, maximum environment type, and directUpdateAllowed. The Authority admin API persists these values under user metadata attributes, returns them in user summaries, and the standard/LDAP/AD claim enrichers can project them into issued tokens. The UI blocks save until the administrator explicitly confirms any combination of service-release contribution with broad admin, operator, bypass, publisher, or approver roles. Built-in roles returned by GetDefaultRoles() are valid user-update assignments even when an installation has no matching tenant-local role-table row; their authoritative scope bundles remain the compiled catalog. Tenant-created roles still require a persisted role row before assignment.

The customer-facing default bundles are professional functions rather than job titles:

Scope availability (reconciled against StellaOpsScopes.cs):

This subsection previously tracked scopes that “must be added to Authority”. As of this reconciliation, every scope referenced in the §4.3 catalog is already defined as a const in src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsScopes.cs, so the catalog rows describe enforceable scopes — what remains aspirational is the seeding of most module role bundles (see the seeded-vs-proposed note at the top of §4.3), not the scopes themselves.

Confirmed present in the catalog (was previously listed as “missing/new”):

• Scanner: scanner:read, scanner:scan, scanner:export, scanner.signed-sbom-material.write, scanner:write. The dedicated signed-SBOM material writer scope is kept distinct from scanner:write.
• Scheduler: scheduler:read, scheduler:operate, scheduler:admin (no longer “not yet defined” — they exist).
• Authority admin: authority:tenants.read|write, authority:users.read|write, authority:roles.read|write, authority:clients.read|write, authority:tokens.read|revoke, authority:branding.read|write, authority:idp.read|write, and the dot-form authority.audit.read.
• UI admin: ui.admin.
• Attestor: attest:read, attest:create, attest:admin.
• Signer: signer:read, signer:sign, signer:rotate, signer:admin.
• SBOM: sbom:read, sbom:write, sbom:attest.
• Release: release:read, release:write, release:publish, release:bypass.
• Zastava: zastava:read, zastava:trigger, zastava:admin.
• Graph: graph:admin (alongside graph:read|write|export|simulate).
• Exceptions: exceptions:read, exceptions:approve, and exceptions:write all exist (the catalog also defines exceptions:request).

Caveat (gateway enforcement vs. scope existence): a scope being defined in StellaOpsScopes.cs only means an issued OpTok may carry it (token issuance filters requested scopes against authority.clients.allowed_scopes; the authority.permissions RBAC catalog is not consulted at issuance — see the class remarks in StellaOpsScopes.cs). It does not by itself guarantee that every downstream service enforces the scope on its endpoints; verify per-service authorization policies against the owning module when that guarantee matters.

5. Console Admin API Surface

5.1 Tenants

• GET /console/admin/tenants
• POST /console/admin/tenants
• PATCH /console/admin/tenants/{tenantId}
• POST /console/admin/tenants/{tenantId}/suspend
• POST /console/admin/tenants/{tenantId}/resume
• GET /console/admin/tenants/{tenantId}/operator-compliance
• PUT /console/admin/tenants/{tenantId}/operator-compliance
• POST /console/admin/tenants/{tenantId}/operator-compliance/approvers
• DELETE /console/admin/tenants/{tenantId}/operator-compliance/approvers/{approverId}

Scopes: authority:tenants.read (read/list/operator-compliance read), authority:tenants.write (create/update/suspend/resume and all operator-compliance mutations).

Suspension has an additional invariant beyond scope and fresh-auth checks: the normalized target tenant must differ from the tenant resolved by TenantHeaderFilter for the authenticated request. Attempting to suspend the active context returns sealed HTTP 409 application/problem+json with code active_tenant_suspend_forbidden and performs no repository update, shared-tenant propagation, or success audit. An operator must switch to a different tenant context before suspending the former tenant.

5.2 Users

• GET /console/admin/users (tenant resolved from the tenant header / TenantHeaderFilter, not a tenantId query param)
• POST /console/admin/users (local users only)
• PATCH /console/admin/users/{userId}
• POST /console/admin/users/{userId}/disable
• POST /console/admin/users/{userId}/enable

Legacy alias (same handlers, same scopes/filters): GET /api/admin/users and POST /api/admin/users. The 201 Location header reflects whichever prefix was called (/api/admin/users/{id} vs /console/admin/users/{id}).

Scopes: authority:users.read (list), authority:users.write (create/update/disable/enable).

POST /console/admin/users requires a non-blank password for local users. Missing or blank passwords return HTTP 400 with error=password_required and code=PASSWORD_REQUIRED so QA and clients can assert the exact contract. The created account is hashed with Argon2id and a authority.admin.users.password.set audit row is emitted alongside authority.admin.users.create. DELETE of the last enabled user in a tenant is rejected with error=last_admin_user (HTTP 400) to avoid lockout.

5.3 Roles and scopes

• GET /console/admin/roles
• POST /console/admin/roles
• PATCH /console/admin/roles/{roleId}
• POST /console/admin/roles/{roleId}/preview-impact

Scopes: authority:roles.read|write

5.4 Clients

• GET /console/admin/clients
• POST /console/admin/clients
• PATCH /console/admin/clients/{clientId}
• POST /console/admin/clients/{clientId}/rotate

Scopes: authority:clients.read|write

5.5 Tokens and audit

• GET /console/admin/tokens (tenant from the tenant header)
• POST /console/admin/tokens/revoke
• GET /console/admin/audit (tenant from the tenant header)

Scopes: authority:tokens.read (list), authority:tokens.revoke (revoke), authority.audit.read (audit list — dot-form scope, not authority:audit.read).

Both token endpoints were stubs until 2026-07-21 (the list always returned [] + "implementation pending", the revoke echoed the request count without revoking — Fable audit #12). They now run against the real IAuthorityTokenStore (authority.oidc_tokens, the same store issuance persists into and TokenValidationHandlers consults):

• List returns the newest access_token/refresh_token rows for the resolved tenant (authorization/device codes are excluded as one-shot handshake artifacts), with limit (default 200, max 1000 via ?limit=) and an exact truncated flag (computed by over-fetching one row). Display status is derived honestly: revoked from the persisted status, expired from expires_at, else active; unknown persisted statuses pass through raw.
• Revoke accepts { tokenIds?[], subject?, clientId?, reason? } — at least one selector required (400 otherwise); selectors combine additively. Subject/client match sets are resolved server-side against the full store (subject cap 1000 newest; client paged 200×25). The response { revokedCount, alreadyRevokedCount, notFoundCount, message } counts REAL valid → revoked transitions — never a request echo. Rows outside the caller’s resolved tenant count as not-found. Revoked tokens are rejected at /token and /introspect immediately and flow into revocation bundles; access tokens already issued to JWT-validating gateways expire on their own schedule.

Deprecation: GET /console/admin/audit carries a Sunset header (2027-10-19) and advertises a successor link to the unified Timeline audit store at /api/v1/audit/events?modules=authority (DeprecatedForTimeline(...) in ConsoleAdminEndpointExtensions). New integrations should read audit from Timeline rather than this endpoint.

5.6 Branding

• GET /console/branding?tenantId=... (public, no auth — runtime theme loading)
• GET /console/admin/branding (admin read, with edit metadata)
• PUT /console/admin/branding (admin update; fresh-auth-wired)
• POST /console/admin/branding/preview (admin preview before apply)

Scopes: authority:branding.read (admin GET / preview), authority:branding.write (PUT). Source: ConsoleBrandingEndpointExtensions.

6. Audit and Observability

• Every admin mutation emits authority.admin.* events with tenant, actor, and trace id.
• Audit export provides deterministic ordering and ISO-8601 timestamps.
• Token revocations emit revocation bundle update markers for downstream caches.

7. Offline-first Administration

NOT IMPLEMENTED / roadmap. This section describes a planned signed-bundle import workflow. As of this reconciliation there is no /admin/bundles/apply endpoint (or any /admin/bundles* route) in the Authority source — searching src/** returns no match. The Console admin surface (/console/admin/*, /api/admin/users) operates against a live Authority instance over bearer scopes; there is no offline change-manifest apply path in code yet. Keep the design below as the intended direction, not as shipped behavior.

• (Planned) Admin changes can be exported as signed bundles for air-gapped import.
• (Planned) The Console produces a change manifest; Authority applies it via a privileged import endpoint. The earlier /admin/bundles/apply (mTLS) path name is not present in source and should be treated as a placeholder until the endpoint is implemented.
• (Planned) UI labels changes as pending when Authority is offline.

8. UI Integration Contract

• Admin workspace routes live under /console/admin/*.
• Admin UI uses /console/admin APIs with DPoP; no mTLS endpoints are called by the browser.
• ui.admin plus specific authority:* scopes are required to render and mutate data.

9. References

• Authority module architecture
• UI / Console module architecture
• Console operator guide (UI_GUIDE)
• Web gateway tenant RBAC contract
• Console Branding architecture — the branding endpoints and authority:branding.* scopes referenced in §5.6.
• Multi-tenant service impact ledger
• Multi-tenant flow sequences
• Multi-tenant rollout and compatibility
• Multi-tenant acceptance matrix
• ADR-002 — multi-tenant same-API-key selection