StellaOps Authority

Verified against commit 942a18727c (2026-09-26, DOC-2 of SPRINT_20260926_001). Re-verify by reading the evidence paths listed in the Evidence section of architecture.md.

Service wiring (image, database and role, compose profile, bundle presence) is generated in the service inventory; this dossier does not restate it.

Authority is the StellaOps OIDC/OAuth2 control plane. It mints the short-lived, optionally sender-constrained operational tokens (OpToks) that every StellaOps service, CLI, and UI uses to authenticate to one another. The source default access-token lifetime is 2 minutes (Authority:AccessTokenLifetime); the release bundle overrides it to 30 minutes.

Source: src/Authority/StellaOps.Authority/StellaOps.Authority (deployable authority, alias authority.stella-ops.local). It also hosts the folded issuer-directory surface; the standalone IssuerDirectory host is retired.

Audience: platform operators configuring identity providers and tenancy, and service/integration authors who need to understand the token, scope, and admin surfaces Authority exposes.

Recent changes

• 2026-10-18 - Users of every tenant sign in through the Standard provider (PCD-875, source only). The Console admin API creates a local user in the tenant of the request, but the Standard provider looked usernames up only in its configured tenantId (and, under seed-admin recovery, its fallback tenants), so a user of any other tenant was refused with invalid_grant. Usernames are unique per tenant, so the provider now looks the account up first in the tenant the caller names with the tenant parameter (password grant and /authorize), or in the tenant of the token being redeemed or refreshed, and then in its configured tenant. The token is still bound to the verified account’s home tenant, and another tenant is still refused unless the account is a global administrator. A user homed outside the configured tenant must name its tenant; the interactive login form now carries the tenant parameter from the rendered form to the sign-in. See user sign-in account lookup.
• 2026-10-13 - Bounded human scope issuance (CCP-080, source only). Interactive and password issuance share the compiled role union and client/request ceilings. Unknown roles grant no product scopes. The additive Release Approver and Decision Signing Enrollee roles grant only release:publish and authority:signing-keys.enroll, respectively. Ordinary interactive login excludes release:gate-bypass. See the issuance contract and proposed acceptance assignments.
• 2026-10-01 - Resource-server metadata refresh keeps the last-known-good keys (PCD-202). Every service that uses AddStellaOpsResourceServerAuthentication caches Authority’s discovery and JWKS in StellaOpsAuthorityConfigurationManager. JwtBearer asks that cache to refresh whenever a token names a signing key it lacks, which every forged bearer does. The request now marks the cache stale without discarding it, and is honoured at most once per five minutes (Microsoft.IdentityModel’s default refresh interval). If the refresh fails within OfflineCacheTolerance, validation continues on the cached keys and the next fetch waits up to five minutes, still bounded by the tolerance. Before, a forged token discarded the cache and its offline fallback, so the next request depended on a cold fetch and answered 503 when Authority’s metadata was slow or unreachable. A changed Authority or JWKS address still discards the cache. A legitimately rotated key is picked up on its first token, or within five minutes if a refresh was honoured just before.
• 2026-09-25 - Console redirect URIs follow the install origin (DAY-2). The Standard seed writes stella-ops-ui redirect and post-logout URIs against the reserved origin https://public-origin.invalid and declares publicOriginsEnvironmentVariable: "STELLAOPS_CONSOLE_PUBLIC_ORIGINS". The Standard plugin expands each URI once per listed origin and fails startup closed when the variable is unset, empty or malformed. The release bundle renders the variable from STELLA_PUBLIC_HOST/STELLA_BIND_ADDRESS, STELLA_HTTPS_PORT and optional STELLA_CONSOLE_ADDITIONAL_ORIGINS. The console client now allows attest:read and the console no longer requests retired remediation:* scopes; StellaOpsUiConsoleClientConformanceTests pins every console scope request source as a subset of the client allow-list.
• 2026-09-25 - Break-glass per-call introspection (BGI-1). The router gateway introspects every request whose token carries findings:recovery as the confidential client stellaops-gateway-introspection (ops.health, audience api://gateway-introspection), refuses with the standard problem response when the token is inactive, and exposes the Doctor check doctor.router.break-glass.introspection-identity. Only stellaops-break-glass-operator lists the introspection client among its audiences. The Authority-side contract is in architecture.md § 3.3.
• 2026-09-26 - Standard seed pins (DEF-10). Descriptor pin tests now expect the seeded grants: stellaops-integrations-web carries api://policy-engine and policy:read in both Standard files, and console-workspace carries catalog:replicate for the air-gap posture replica. The AUTH-16 rollback compose overlays no longer request retired remediation scopes, and the bundle staging control for the Authority client seed is covered by devops/release/bundle/tools/test_stage_config_authority_seed.py.
• 2026-09-21 - Credential retention. Expiry cleanup uses bounded batches, tenant-scoped connections where required, and explicit expiry protection. Unknown-expiry OIDC records remain protected and are reported by Doctor; capacity pressure never authorizes eviction of valid credentials. See retention classes and verification.
• 2026-08-19 - Per-client resource-plan claim. Standard-plugin bootstrapClients entries may carry an optional singular plan property. Client-credentials issuance projects configured values as stellaops:plan and omits the claim for unassigned clients; removing the committed property removes the persisted assignment at the next bootstrap reconciliation.
• 2026-07-19 - Built-in Console role assignment consistency. User updates accept roles advertised by the compiled GetDefaultRoles() catalog even when an installation has no duplicate tenant-local role-table row. Tenant-created roles still require persisted role records. This keeps the Users editor, role list, metadata persistence, and authorization-code scope catalog aligned.
• 2026-07-19 - Console admin fresh-auth enforcement. Tenant-scoped Console admin mutations enforce the RequireFreshAuth() contract: auth_time must be no more than five minutes old, with one minute of allowed future clock skew. Missing, invalid, stale, or excessively future claims fail with 401 fresh_auth_required; read-only admin routes remain available without step-up so operators can inspect state before reauthenticating to mutate it.
• 2026-07-18 - Global identity-provider admin API. Global administrators can list, create, update, delete, enable, disable, apply, status-check, and preflight LDAP/OIDC/SAML configuration under /console/admin/identity-providers. The surface is process-global (no tenant header), requires ui.admin plus authority:idp.read or authority:idp.write, requires fresh authentication for mutations, rejects inline secret material, and reports typed mounted/admitted/loaded/healthy status. Candidate connection tests run through the mounted signed provider bundle without persistence.
• 2026-07-15 - Front-door-safe login hero. The embedded interactive-login hero is also served anonymously at /connect/assets/img/stella-identity.png, so the gateway-routed authorization page receives Authority’s placement-specific sunrise image instead of the Console’s legacy /assets identity artwork.
• 2026-06-13 - LDAP native runtime package hook. Authority image build paths now pass an Authority-only EXTRA_RUNTIME_PACKAGES build argument for the Linux OpenLDAP client runtime package (AUTHORITY_LDAP_NATIVE_PACKAGE, default libldap-2.5-0). This keeps OIDC/SAML/LDAP provider assemblies in signed mounted bundles while ensuring an Authority image rebuilt from the offline package source can initialize System.DirectoryServices.Protocols. Local IdP runtime proof still requires the rebuilt/imported Authority image plus local fixture images for quay.io/keycloak/keycloak:24.0 and osixia/openldap:1.5.0.
• 2026-06-12 - Standard plugin crypto publish boundary. The standard local identity-provider plugin registers host-owned default crypto services directly and no longer references StellaOps.Cryptography.DependencyInjection. The shared crypto DI package itself also compiles optional regional/simulator provider registrations only behind StellaOpsEnableOptionalCryptoProviders=true, so the base Authority publish graph is not allowed to inherit GOST/SM/PQ/simulator/CSP provider payloads through standard local auth.
• 2026-06-11 - Provider admission and future MFA registry guard. Authority provider admission now rejects any enabled descriptor whose declared assembly identity does not match the cataloged provider type, before registrar activation. The operator registry keeps TOTP/WebAuthn/Email/SMS MFA entries disabled because those provider boundaries are cataloged as future work; MFA can still be satisfied by a loaded identity-provider plugin that reports the mfa capability.
• 2026-06-05 - Auth.ServerIntegration crypto boundary. The resource-server integration library no longer references the shared StellaOps.Configuration package. It binds StellaOpsResourceServerOptions directly from Microsoft.Extensions.Configuration, so downstream services such as SmRemote do not pull the shared crypto DI package or optional regional/simulator crypto provider projects through Authority validation helpers.
• 2026-07-23 - One Authority config root. Base, recommended, harness, and IdP-testing compose surfaces now share /app/etc/authority/plugins, backed by devops/etc/authority/plugins/. Plugin overlays may change the executable scan root to /app/plugins/authority, but they do not redirect the configuration directory. Standard bootstrap and LDAP/OIDC/SAML/harness/ registry config therefore converge from one tracked source.
• 2026-06-03 - /connect/authorize route ownership. Authority maps the interactive authorization-code+PKCE login handler at both /authorize and /connect/authorize. This matches the discovery/OpenIddict endpoint configuration and the compose Platform environment settings consumed by the Console.
• 2026-04-30 — Tenant compliance profiles. Authority tenant views and console-admin tenant summaries expose a nullable complianceProfile for DORA, NIS2, and CRA filtering. Console admin create/update validates LEIs offline using the ISO 17442 checksum and stores the normalized profile in tenant metadata. Runtime consumers read the source-owned nullable profile via GET /api/v1/tenants/{tenantId}/compliance-profile without receiving operator settings, deployment posture, or secret refs. See tenant-model.mdand tenant-compliance-profile-v1.md.
• 2026-04-29 — VEX SSE fails closed. Authority Console no longer presents /console/vex/events as live VEX SSE. Until a durable tenant-scoped VEX event source exists, the endpoint fails closed with 501 vex_events_stream_unsupported, records authority.console.vex.events, and callers must poll /console/vex/statements.
• 2026-04-24 — No silent in-memory/null defaults. Production-like Authority composition no longer binds remaining in-memory/null runtime defaults: timestamping stores fail closed without explicit local/test opt-in; Auth client token cache resolution requires a file/messaging cache outside Development/Testing (or when no host environment is registered); NullAuthoritySessionAccessor is guarded by environment or Authority:Storage:AllowNullSessionAccessor=true (the release bundle sets it to true); direct IssuerDirectory in-memory registration requires an explicit local/test gate; and production Authority/Postgres adapters depend on the neutral StellaOps.Authority.Persistence.Stores contracts rather than the local in-memory store namespace.
• 2026-04-16 — Durable DPoP state. Authority no longer uses live in-memory DPoP replay or nonce state outside Testing; non-testing DPoP-enabled runtime now requires durable Valkey-backed state, with restart-survival proof in AuthorityDpopRuntimeTests. The AU1–AU10 and RR1–RR10 gap-remediation package landed under gaps/ with deliverable map and evidence layout.

Responsibilities

• Expose authorization-code+PKCE, client-credentials, password, and refresh-token flows with optional DPoP or mTLS sender-constraint binding. (Device-code is configured for lifetime only via SetDeviceCodeLifetime; AllowDeviceCodeFlow is not enabled, so device-code is not yet an active grant — see Program.cs.)
• Project an explicitly configured client resource plan as stellaops:plan on client-credentials tokens; never invent a plan for an unassigned client.
• Manage signing keys and JWKS rotation. (PoE/entitlement enforcement is owned by Signer, not Authority.)
• Emit structured audit events (via StellaOps.Audit.Emission to the Timeline unified audit store) and enforce tenant-aware scope policies.
• Provide a plugin surface for custom identity providers and credential validators (standard, LDAP, OIDC, SAML).

Source of truth: human token issuance intersects requested scopes, the client ceiling, and compiled role grants through AuthorityHumanScopeResolver. The authority.permissions table is the RBAC catalog consumed by the Console Admin role editor and is not consulted at JWT issuance time. See human scope issuance, StellaOps.Auth.Abstractions/StellaOpsScopes.cs, and architecture.md §4.3.

Key components

• StellaOps.Authority web host (OpenIddict server — AddOpenIddict().AddServer(...) in Program.cs).
• Identity-provider plugins, each shipping a registrar + IIdentityProviderPlugin:
  • StellaOps.Authority.Plugin.Standard (PluginType => "standard") — first-party local credential store.
  • StellaOps.Authority.Plugin.Ldap (PluginType => "ldap").
  • StellaOps.Authority.Plugin.Oidc (OidcIdentityProviderPlugin).
  • StellaOps.Authority.Plugin.Saml (SamlIdentityProviderPlugin).
• StellaOps.Auth.Abstractions — canonical scope catalog (StellaOpsScopes) and telemetry metadata (AuthorityTelemetry).
• StellaOps.Auth.ServerIntegration - resource-server validation (AddStellaOpsResourceServerAuthentication) used by Authority’s own admin endpoints and by downstream services. This library intentionally does not depend on StellaOps.Configuration or crypto provider DI; downstream resource servers must not receive optional regional/simulator crypto provider payloads merely by enabling Authority JWT validation.
• StellaOps.Authority.Persistence — PostgreSQL stores + embedded Migrations/**/*.sql (auto-migrated on startup).
• StellaOps.IssuerDirectory.* — issuer directory core, infrastructure, API (StellaOps.IssuerDirectory.Api), persistence (schema issuer) and client. The API is mapped by the Authority host when IssuerDirectory:Fold:Enabled is true (source default false; the dev estate sets it in devops/compose/docker-compose.authority.yml; the release bundle does not set it at the verified commit, see architecture.md § 21.4). The standalone IssuerDirectory host is frozen under src/__Obsoleted/Authority/StellaOps.IssuerDirectory.WebService/. Its dossier is issuer-directory/.
• Telemetry and audit pipeline feeding Security/Observability stacks.

HTTP surface (verified against source)

OAuth/OIDC endpoints (registered on the OpenIddict server in Program.cs):

Authority also serves the conventional /connect/token, /connect/introspect, /connect/revoke, /connect/revocation and /connect/logout forms. The legacy /oauth/token, /oauth/introspect and /oauth/revoke aliases were removed on 2026-09-27 (PCD-78); Authority no longer rewrites or serves them. /connect/authorize is mapped directly in Authority to the custom interactive login shell so browser clients using the Platform-advertised URL do not fall through to the SPA/404 path.

Operational and administrative endpoints (minimal-API routes in the Authority host):

The admin audit list endpoint (GET /console/admin/audit) is deprecated (Sunset 2027-10-19) with successor GET /api/v1/audit/events?modules=authority on Timeline. The compatibility proxy preserves the authenticated tenant and decoded filters, and its shared Timeline client authenticates the service hop with a short-lived signed identity envelope carrying only timeline:read. A missing envelope key fails before HTTP; upstream failures return a sealed 502 timeline_audit_unavailable response rather than exposing transport or storage detail.

Scope catalog

• The canonical scope set is StellaOps.Auth.Abstractions/StellaOpsScopes.cs — the JWT authorization surface (StellaOpsScopes.All is reflection-built from the public string consts and registered with OpenIddict alongside openid/email/profile/offline_access).
• Examples: authority:tenants.read / .write, authority:users.read / .write, authority:roles.read / .write, authority:clients.read / .write, authority:tokens.read, authority:tokens.revoke, authority:branding.read / .write, authority:idp.read / .write, authority.audit.read, authority.revocation.read, ui.read, ui.admin, plus per-module scopes (policy, vuln, vex, advisory, graph, scanner, signer, attest, orch, packs, export, notify, crypto, registry, etc.).
• Scheduler uses the canonical claim values scheduler:read and scheduler:operate; orch:* claims do not authorize Scheduler. Interactive Release Operations Steward tokens may carry both Scheduler claims, while Service Release Contributor tokens may carry scheduler:read only. The Console must derive Scheduler visibility and controls from the issued scheduler:* claims rather than role labels or orch:* aliases.
• The four professional interactive roles use one canonical AuthorityInteractiveRoleGrantCatalog for both Console Admin role display and authorization-code issuance. Executive Assurance Viewer and Security Risk Manager tokens are intersected with their respective assurance-read and risk-analysis bundles, so unrelated ui.admin, release write/publish, operate, and approve scopes are stripped even when the Console client requests them. The Security Risk Manager bundle includes tenant-scoped registry:read for the Images inventory; it does not grant registry plan/cache administration or integration writes.
• vuln:read was deleted (2026-09-02, P8-14) — vuln:view (VulnView) is the read scope; migration S056 retires the seeded permission row.
• The curated OpenAPI contract is src/Api/StellaOps.Api.OpenApi/authority/openapi.yaml (the architecture conformance fixture reads this copy).

Integrations & dependencies

• Every resource server validates Authority JWTs through StellaOps.Auth.ServerIntegration.
• Console (stella-ops-ui) and CLI (stellaops-cli) for interactive login; service clients from the Standard-plugin bootstrapClients file for machine-to-machine tokens.
• Router gateway: validates tokens at the front door, relays identity envelopes, and introspects break-glass tokens.
• Timeline: audit sink (AddAuditEmission) and successor of the admin audit list.
• Platform: projects the tenant catalogue from Authority’s catalog-changes feed into shared.tenants.
• Registry token service: consumes the stellaops:plan claim.

Operational notes

• PostgreSQL (schema authority, plus schema issuer for the folded issuer directory) for tenant, client, and token state, auto-migrated on startup from the embedded Migrations/**/*.sql resources in StellaOps.Authority.Persistence (AddAuthorityPostgresStorage wires AddStartupMigrations). Connection: Authority:Storage:ConnectionString, which compose sets from STELLAOPS_POSTGRES_AUTHORITY_CONNECTION (STELLAOPS_AUTHORITY_AUTHORITY__STORAGE__CONNECTIONSTRING). No compose init script carries Authority DDL.
• Core tables (Migrations/001_v1_authority_baseline.sql — the collapsed pre-1.0 chain; the old per-feature files sit under Migrations/_archived/pre_1.0/ and are excluded from embedding): authority.tenants, users, roles, permissions, role_permissions, user_roles, api_keys, tokens, refresh_tokens, sessions, bootstrap_invites, service_accounts, clients, client_tenants, revocations, login_attempts, oidc_tokens, oidc_refresh_tokens, revocation_export_state, verdict_manifests; later numbered migrations add identity_provider_configs (019), the issuer schema (024) and break_glass_events (025). (The deprecated audit, airgap_audit, and offline_kit_audit tables are created and then dropped inside the same baseline — audit lives in timeline.unified_audit_events.) Most tenant-scoped tables are RLS-protected via authority_app.require_current_tenant() (session var app.tenant_id). S*-prefixed migrations are scope/seed/client migrations applied when Authority:Bootstrap:Enabled is true; the collapsed seed baseline is S001_v1_authority_operational_baseline.sql.
• Non-local production runtime must not rely on in-memory/null persistence defaults. Use PostgreSQL for Authority/IssuerDirectory, Valkey-backed DPoP state, and file or messaging Auth client token caches. In-memory harnesses are Development/Testing only unless a documented compatibility gate is set.
• Authority store interfaces are owned by StellaOps.Authority.Persistence.Stores; the in-memory store namespace contains only local/test implementations and the compatibility driver shim.
• Standard plugin bootstrap provisioning retries transient storage failures during startup so first-party clients converge after PostgreSQL becomes reachable. defaultAdminBootstrap creates or repairs the admin user from STELLAOPS_ADMIN_PASS (required by the release bundle).
• Signing key material is loaded from pluggable sources (IAuthoritySigningKeySource): a file source (FileAuthoritySigningKeySource) is always registered, and a KMS source (KmsAuthoritySigningKeySource, file-backed AddFileKms) is added when signing.keySource (or an additional key’s source) is kms. Default algorithm ES256. Rotation runbook: operations/key-rotation.md.
• Telemetry: OpenTelemetry resource service.name = stellaops-authority, service.namespace = stellaops; ActivitySource and Meter both named StellaOps.Authority (AuthorityTelemetry). Monitoring runbook (operations/monitoring.md) and offline-import Grafana JSON (operations/grafana-dashboard.json).

Related resources

• Backup & restore: operations/backup-restore.md
• Key rotation: operations/key-rotation.md
• Monitoring: operations/monitoring.md(Grafana JSON for offline import: operations/grafana-dashboard.json)
• Bootstrap modes: operations/bootstrap-modes.md
• Break-glass account: operations/break-glass-account.md
• Client identities and the stellaops-cli scope ceiling (which client an operator mints through, and why the product CLI client carries only what CLI verbs need): operations/stellaops-cli-scope-census.md
• Crypto-provider contract: crypto-provider-contract.md
• Tenant model: tenant-model.md
• Client secret rotation: operations/client-secret-rotation.md
• Retention classes: retention-classification.md
• Gap-remediation packages: gaps/2025-12-04-auth-gaps-au1-au10.md, gaps/2025-12-04-rekor-receipt-gaps-rr1-rr10.md

Evidence

The claims in this README are backed by the Evidence table in architecture.md. Additional README-specific sources: