Scopes and Roles

Canonical Reference: The single authoritative source of truth for scope strings is the StellaOps.Auth.Abstractions.StellaOpsScopes class (src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsScopes.cs), which currently declares 150+ distinct scopes (StellaOpsScopes.All is reflected from its public const string fields). For prose descriptions, surface mappings, and role/configuration examples see authority-scopes.md — note that the narrative catalogue there may lag the const list, so reconcile against StellaOpsScopes when in doubt.

This document defines the scope taxonomy and how scopes map to roles across StellaOps. It is intentionally cross-cutting and does not attempt to list every module-specific scope; the StellaOpsScopes const list, module dossiers, and gateway contracts are the source of truth for per-surface requirements.

Terms

Scope Naming Conventions

Most scopes follow an <area>:<verb> shape, but the catalog is not uniform — both the separator and the verb set vary by module. Treat the canonical const list in StellaOps.Auth.Abstractions.StellaOpsScopes as the source of truth for the exact string; the conventions below are descriptive, not normative.

Examples that appear across current contracts and module dossiers (verified against StellaOpsScopes):

Typical Role Shapes (Tenant-Local)

Exact role names vary per deployment, but the intent is stable:

Default role catalog (shipped bundles)

Authority ships a concrete default role catalog that the Console role editor exposes; it is defined by ConsoleAdminEndpointExtensions.GetDefaultRoles() (each RoleBundle maps a role/<id> to an explicit scope set). These are the seeded bundles — operators can still assemble custom roles from any scope in the authority.permissions catalog. As of this writing the shipped bundles are:

Role IDDisplay nameScope bundle (from source)
role/console-viewerConsole Viewerui.read
role/console-adminConsole Adminui.read, ui.admin, and the full authority:* management set (tenants, users, roles, clients, tokens, branding, idp read/write/revoke) plus authority.audit.read
role/executive-assurance-viewerExecutive Assurance Viewerui.read, release:read, policy:read, policy:audit, findings:read, evidence:read, replay:read, graph:read, export.viewer, authority.audit.read, timeline:read, platform.context.read, attest:read, release.policy.read
role/release-operations-stewardRelease Operations Stewardui.read, release:read, release:write, orch:read, orch:operate, scheduler:read, scheduler:operate, scanner:read, scanner:scan, sbom:read, policy:read, findings:read, evidence:read, timeline:read, platform.context.read, release.policy.read
role/security-risk-managerSecurity Risk Managerui.read, release:read, scanner:read, scanner:scan, sbom:read, registry:read, integration:read, findings:read, vuln:view, vuln:investigate, policy:read, policy:simulate, evidence:read, graph:read, advisory:read, vex:read, vexhub:read, timeline:read, remediation:read
role/service-release-contributorService Release Contributorui.read, ui.preferences.read, ui.preferences.write, release:read, release:write, orch:read, scheduler:read, scanner:read, scanner:scan, sbom:read, policy:read, findings:read, evidence:read, vuln:view, timeline:read, platform.context.read (ABAC-constrained — see Product User Shapes; deliberately excludes release:publish, release:bypass, ui.admin, policy:approve, orch:operate)
role/scanner-viewerScanner Viewerscanner:read
role/scanner-operatorScanner Operatorscanner:read, scanner:scan, scanner:export
role/scanner-signed-sbom-writerScanner Signed SBOM Writerscanner.signed-sbom-material.write
role/scanner-adminScanner Adminscanner:read, scanner:scan, scanner:export, scanner:write

The four professional bundles are the shared lists in AuthorityInteractiveRoleGrantCatalog, which authorization-code issuance also applies. Of the scopes the Console requests for the approval-policy editor and the federation pages, only release.policy.read is in a professional bundle (Executive Assurance Viewer and Release Operations Steward). release.policy.manage can set an approval policy to auto-approve, which removes the human approval that release:publish guards, so it is granted separately like release:publish; telemetry:participation:read|write (current-tenant telemetry consent) and platform:federation:read|write (installation federation) are administration grants. Administrator-family roles receive every scope the Console requests and the stella-ops-ui client allows, and so does a principal whose roles interactive issuance does not recognize (for example only the seeded operator or auditor role).

Product User Shapes

The common product-facing users map onto these role shapes, and each corresponds to a concrete role/* bundle in the default catalog above:

Service release contributor access must be ABAC-constrained. The supported attribute keys are fixed by ConsoleAdminEndpointExtensions.DeveloperAbacAttributeKeys: serviceIds, repositoryIds, imageNamespaces (service ownership), environmentIds and maxEnvironmentType (allowed target environments), and directUpdateAllowed (whether the environment permits direct updates or only promotion requests). Release Orchestrator re-checks those claims when a contributor calls POST /api/v1/release-orchestrator/deployments for a direct update or POST /api/v1/release-orchestrator/approvals/developer-requests for an approval request. A mutable tag is not enough; contributor update actions require an immutable sha256: candidate digest. Release Orchestrator decides both paths on its own records: the named release must be recorded in the caller’s tenant and owned by the contributor, the target environment is the one a deploy would reach, and the digest must be one the release records. A newly built digest is a change to a released bundle: the contributor creates the successor version through POST /api/v1/release-orchestrator/releases/{releaseId}/versions/from-artifact-update (authorized on the owned source component) and then deploys or requests approval for that version; the approval-request path does not turn an unrecorded digest into an approval for a derived release key. Administrator roles do not create contributor ownership: a session that carries the contributor role or any contributor claim is evaluated as a contributor against its own claims, whatever other roles it holds.

Authority admin user summaries include the supported service-release ABAC attributes, and the Console user editor exposes them when role/service-release-contributor or the developer role is selected. The developer / role/release-developer family uses the existing developer allow-list in AuthorityHumanScopeResolver; that list and the Service Release Contributor bundle remain distinct. Administrators must confirm mixed grants that combine service-release contribution with broad admin, operator, bypass, publisher, or policy-approver roles. LDAP and Active Directory mappings should attach the same attributes from directory claims or synchronized user metadata instead of using role/console-admin as a shortcut.

Default setup uses SQL/local users. LDAP Directory and Active Directory can be added as authentication providers and must map directory groups to these role bundles instead of granting role/console-admin to every external user.

Enforcement Model (Where Scopes Are Checked)

Human authorization-code and password issuance use the same compiled, additive role union. Requested scopes and the actual client ceiling both remain binding; an empty ceiling grants nothing. Unknown or missing roles contribute no product scopes. Catalog-only custom roles do not create issuance authority.

role/release-approver adds only release:publish to authorize the existing release approval contract. role/decision-signing-enrollee adds only authority:signing-keys.enroll; enrollment remains subject to its resource and fresh-authentication checks. Neither widens the four base professional bundles. Ordinary interactive login excludes release:gate-bypass, including for an administrator. The separate non-admin operation-bound bypass flow remains a distinct source task. See human scope issuance for exact assignments proposed for later acceptance and the source-only boundary.

References