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(). Every route requires the X-StellaOps-TenantId header, which TenantHeaderFilter validates and which is the request tenant (section 3.5). Verified in src/Authority/StellaOps.Authority/StellaOps.Authority/Console/Admin/ConsoleAdminEndpointExtensions.cs.
• There is no /api/admin tier and no /api/admin/users alias; no such route is mapped (the last dead prefix branch was removed on 2026-08-24).

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 surface above authorizes on bearer scopes, not client certificates.

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.

3.4 Tenant boundary: tenant administrator and global administrator

The authority:* scopes are granted per tenant, so a holder of role/console-admin is a tenant administrator of the tenant its token is bound to. Only a global administrator (a user with is_global_admin, whose tokens carry stellaops:admin=true) administers the installation across tenants. Both facts are read from the authenticated principal only: the caller’s tenant is its stellaops:tenant claim, never the tenant header, a query value or the request body; global-admin status is resolved the same way the identity-provider admin group resolves it.

A tenant administrator:

• reads and changes only its own tenant’s catalog entry: GET /console/admin/tenants lists only that entry, and PATCH, the operator-compliance routes, suspend and resume for any other tenant return HTTP 403 cross_tenant_admin_forbidden before the tenant is looked up;
• cannot create a tenant (HTTP 403 global_admin_required);
• registers clients only for its own tenant (an assignment to another tenant returns HTTP 403 cross_tenant_admin_forbidden) and only with scopes its own token carries (HTTP 403 client_scope_not_held, listing the scopes); a client update caps only the scopes it adds;
• can update or rotate only a client the client list shows it. A client of another tenant returns HTTP 404 client_not_found, the same answer as a missing client, and no secret is minted. A client that also serves another tenant returns HTTP 403 cross_tenant_admin_forbidden;
• cannot set or clear isGlobalAdmin on any user (HTTP 403 global_admin_required). Resending the user’s current value is not a change.

A global administrator keeps all of these operations and is not subject to the client scope cap. The first global administrator is the bootstrap administrator the Standard plugin creates from STELLAOPS_ADMIN_PASS; that path does not use the Console admin API. Every refusal writes an authority.admin.* audit event with outcome Failure and the refusal code as reason.

3.5 Tenant header (PCD-868)

TenantHeaderFilter validates X-StellaOps-TenantId on the /console, /console/admin, /console/admin/branding, air-gap audit and /api/v1/tenants groups:

• A principal that is not a global administrator may name only the tenant in its own stellaops:tenant claim; any other value is HTTP 403. A principal without a tenant claim cannot pick a tenant by header (403). When the token also carries stellaops:allowed_tenants, the header must be in that list too. A global administrator may name any tenant.
• The /console/admin and /api/v1/tenants groups require the header: without it the filter answers HTTP 400 tenant_header_missing. The user, role and client-list routes no longer fall back to a tenantId query value or to the default tenant.
• On the /console groups the handler answers 400 tenant_header_missing and writes its audit event.
• GET /api/v1/tenants/{tenantId}/compliance-profile, /submission-authorizations and /assurance-packs also require the route tenant to equal the header tenant (403 otherwise).

Through the gateway the header is always set from the validated principal, so these refusals reach only direct callers.

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 compiled built-in role bundles are the twelve 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, role/release-approver, role/decision-signing-enrollee. 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.

Human token issuance uses the compiled additive role union for both interactive and password flows, bounded by requested scopes and the actual client ceiling. Unknown/custom roles do not grant product scopes merely because the catalog stores a scope list. role/release-approver grants only release:publish and role/decision-signing-enrollee grants only authority:signing-keys.enroll. Neither changes the base professional bundles or grants gate bypass. Ordinary interactive login excludes release:gate-bypass for all roles. See the human issuance contract for source tests and the proposed, still unprovisioned acceptance identities.

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):

Every scope referenced in the §4.3 catalog is 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:

• 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.
• 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).

Tenant boundary (section 3.4): create is global-admin only; every {tenantId} route refuses a tenant other than the caller’s own unless the caller is a global administrator.

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 from the validated tenant header; there is no tenantId query parameter)
• POST /console/admin/users (local users only)
• PATCH /console/admin/users/{userId}
• POST /console/admin/users/{userId}/disable
• POST /console/admin/users/{userId}/enable

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

Only a global administrator sets or changes isGlobalAdmin on create or update (section 3.4).

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.

The user is created in the tenant of the request. A user of a tenant other than the Standard provider’s configured tenantId (default) signs in by naming that tenant (tenant on the password grant or the authorize request) through a client assigned to it; the same username may exist in several tenants, and the named tenant selects the account. See Authority § 3.2b.

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

Update and rotate apply the list’s tenant visibility filter to the caller’s own tenant; tenant assignments and requested scopes are bounded as described in section 3.4.

5.5 Tokens and audit

• GET /console/admin/tokens
• POST /console/admin/tokens/revoke
• GET /console/admin/audit

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

Tenant binding (PCD-876): all three act on the tenant in the caller’s stellaops:tenant claim. A global administrator may select another tenant with the X-StellaOps-TenantId header that TenantHeaderFilter validated, and otherwise gets its claim tenant. No query parameter selects a tenant: the former tenantId query accepted any tenant in the stellaops:allowed_tenants claim, which for a password-grant token is the client’s tenant list rather than the user’s, and was removed. A request that resolves no tenant returns HTTP 400 tenant_required; the revoke route no longer runs unscoped in that case.

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 (internal QA playbook, not published in this documentation)
• ADR-002 — multi-tenant same-API-key selection