Authority Scopes & Tenancy

Audience: Authority Core, platform security engineers, DevOps owners. Scope: The canonical OAuth scope catalogue, scope-bundle (role) definitions, tenancy enforcement, and rollout guidance — including the Aggregation-Only Contract (AOC) scopes introduced in Sprint 19.

Canonical source of truth: the scope constants live in src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsScopes.cs. When this table and the code disagree, the code wins. ASP.NET policy names may differ from scope claim values (e.g. dot-form vs. colon-form) — audit against the scope constant.

Authority issues short-lived tokens bound to tenants and scopes. This document lists the canonical scope catalogue, defines the scope bundles (roles) that compose those scopes, describes tenancy propagation, and outlines operational safeguards. The AOC guardrail scopes in Concelier and Excititor (Sprint 19) are part of this catalogue.

1 · Scope catalogue

Scope notes.

• Observability scope bundle (added 2 Nov 2025). obs:read, timeline:read, timeline:write, evidence:create, evidence:read, evidence:hold, attest:read, and obs:incident always require a tenant claim. Gateways must forward X-StellaOps-TenantId (or the configured tenant header) or resource servers will reject the request with tenant_header_missing. The sample authority.yaml assigns these scopes via the observability-* roles; reuse those roles when onboarding new tenants to keep bundles consistent.
• Fresh-auth enforcement (Sprint 55). Authority-issued obs:incident tokens must carry both incident_reason and auth_time. Resource servers enforce a five-minute freshness window and log incident.reason, incident.auth_time, and incident.fresh_auth_satisfied in authority.resource.authorize audit events, enabling /authority/audit/incident to verify activation reason and freshness.
• Legacy vuln:read. It remains available for backwards compatibility and is still emitted on Vuln Explorer permalinks. New clients should request the granular vuln:* scopes above.
• Vuln Explorer attachment tokens reuse the same scopes: issuance requires vuln:investigate, verification honours the caller’s ABAC attributes, and Authority records vuln.attachment.token.* audit events for every issue/verify flow.

1.1 Scope bundles (roles)

• role/concelier-ingest→ advisory:ingest, advisory:read.

• role/excititor-ingest→ vex:ingest, vex:read.

• role/excititor-admin-> vex.admin, vex:read, vexhub:read.

• role/signals-uploader→ signals:write, signals:read, aoc:verify.

• role/aoc-operator→ aoc:verify, advisory:read, vex:read.

• role/policy-engine→ effective:write, findings:read.

• role/cartographer-service→ graph:write, graph:read.

• role/graph-gateway→ graph:read, graph:export, graph:simulate.

• role/console→ ui.read, advisory:read, vex:read, exceptions:read, aoc:verify, findings:read, airgap:status:read, orch:read, vuln:view, vuln:investigate.

• role/console-viewer-> ui.read.

• role/console-admin-> ui.read, ui.admin, authority:tenants.read, authority:users.read, authority:roles.read, authority:clients.read, authority:tokens.read, authority.audit.read, authority:branding.read, authority:idp.read, authority:idp.write.

• role/console-superadmin-> ui.read, ui.admin, authority:tenants.*, authority:users.*, authority:roles.*, authority:clients.*, authority:tokens.*, authority.audit.read, authority:branding.*, authority:idp.*.

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

• role/scheduler-viewer-> scheduler:read (proposed).

• role/scheduler-operator-> scheduler:read, scheduler:operate (proposed).

• role/scheduler-admin-> scheduler:read, scheduler:operate, scheduler:admin (proposed).

• role/ui-console-admin→ ui.read, authority:tenants.read, authority:roles.read, authority:tokens.read, authority:clients.read (paired with write scopes where required).

• role/orch-viewer(Authority role: Orch.Viewer) → orch:read.

• role/orch-operator(Authority role: Orch.Operator) → orch:read, orch:operate.

• role/orch-admin(Authority role: Orch.Admin) → orch:read, orch:operate, orch:quota, orch:backfill.

• role/packs-runner→ packs.read, packs.run.

• role/packs-publisher→ packs.read, packs.write.

• role/packs-approver→ packs.read, packs.approve.

• role/policy-author→ policy:author, policy:read, policy:simulate, findings:read.

• role/policy-reviewer→ policy:review, policy:read, policy:simulate, findings:read.

• role/policy-approver→ policy:approve, policy:review, policy:read, policy:simulate, findings:read.

• role/policy-operator→ policy:operate, policy:run, policy:activate, policy:publish, policy:promote, policy:read, policy:simulate, findings:read.

• role/policy-auditor→ policy:audit, policy:read, policy:simulate, findings:read.

• role/export-viewer(Authority role: Export.Viewer) → export.viewer.

• role/export-operator(Authority role: Export.Operator) → export.viewer, export.operator.

• role/export-admin(Authority role: Export.Admin) → export.viewer, export.operator, export.admin.

• role/notify-viewer(Authority role: Notify.Viewer) → notify.viewer.

• role/notify-operator(Authority role: Notify.Operator) → notify.viewer, notify.operator.

• role/notify-admin(Authority role: Notify.Admin) → notify.viewer, notify.operator, notify.admin.

• role/observability-viewer(Authority role: Observability.Viewer) → obs:read, timeline:read, evidence:read, attest:read.

• role/observability-investigator(Authority role: Observability.Investigator) → obs:read, timeline:read, timeline:write, evidence:read, evidence:create, attest:read.

• role/observability-legal(Authority role: Observability.Legal) → evidence:read, evidence:hold.

• role/observability-incident-commander(Authority role: Observability.IncidentCommander) → obs:read, obs:incident, timeline:read, timeline:write, evidence:create, evidence:read, attest:read.

• role/airgap-viewer→ airgap:status:read.

• role/airgap-operator→ airgap:status:read, airgap:import.

• role/airgap-admin→ airgap:status:read, airgap:import, airgap:seal.

• role/exceptions-service→ exceptions:read, exceptions:write.

• role/exceptions-approver→ exceptions:read, exceptions:approve.

• role/release-developer-> release:read, release:write, orch:read, scanner:read, scanner:scan, sbom:read, policy:read, findings:read, evidence:read. Must be ABAC-constrained to owned services and allowed environments; it does not include release:publish, release:bypass, policy:approve, ui.admin, or broad orch:operate. In the interactive console authorization-code flow, Authority intersects requested scopes for developer principals with the self-service allow-list, so a broadly configured UI client still mints a developer token without admin, publisher, or approval scopes. Release Orchestrator enforces these developer ABAC attributes again on direct deployment creation and developer-originated approval request creation, so UI visibility is not the authorization boundary.

Developer self-service ABAC attributes:

Full module role bundle catalog (Console, Scanner, Scheduler, Policy, Graph, Observability, etc.) is maintained in docs/technical/architecture/console-admin-rbac.md and is the reference for Console admin UI and Authority seeding.

Roles are declared per tenant in authority.yaml:

Runtime note (verified 2026-07-18): YAML role entries document/operator-configure intended bundles, but the current tenant catalog does not seed these definitions into the durable RoleRepository or token-issuance role catalog. In particular, the five pack-* bundles below are not yet a canonical runtime RBAC feature. The four packs.* scope constants and tenant checks are implemented independently.

tenants:
  - name: default
    roles:
      concelier-ingest:
        scopes: [advisory:ingest, advisory:read]
      signals-uploader:
        scopes: [signals:write, signals:read, aoc:verify]
      aoc-operator:
        scopes: [aoc:verify, advisory:read, vex:read]
      orch-viewer:
        scopes: [orch:read]
      orch-operator:
        scopes: [orch:read, orch:operate]
      policy-author:
        scopes: [policy:author, policy:read, policy:simulate, findings:read]
      policy-reviewer:
        scopes: [policy:review, policy:read, policy:simulate, findings:read]
      policy-approver:
        scopes: [policy:approve, policy:review, policy:read, policy:simulate, findings:read]
      policy-operator:
        scopes: [policy:operate, policy:run, policy:activate, policy:publish, policy:promote, policy:read, policy:simulate, findings:read]
      policy-auditor:
        scopes: [policy:audit, policy:read, policy:simulate, findings:read]
      release-developer:
        scopes: [release:read, release:write, orch:read, scanner:read, scanner:scan, sbom:read, policy:read, findings:read, evidence:read]
        claims:
          serviceIds: ["payments-api", "billing-worker"]
          environmentIds: ["dev", "qa"]
          maxEnvironmentType: "nonprod"
          directUpdateAllowed: true
      pack-viewer:
        scopes: [packs.read]
      pack-operator:
        scopes: [packs.read, packs.run]
      pack-publisher:
        scopes: [packs.read, packs.write]
      pack-approver:
        scopes: [packs.read, packs.approve]
      pack-admin:
        scopes: [packs.read, packs.write, packs.run, packs.approve]
      policy-engine:
        scopes: [effective:write, findings:read]
      exceptions-service:
        scopes: [exceptions:read, exceptions:write]
      exceptions-approver:
        scopes: [exceptions:read, exceptions:approve]
      notify-viewer:
        scopes: [notify.viewer]
      notify-operator:
        scopes: [notify.viewer, notify.operator]
      notify-admin:
        scopes: [notify.viewer, notify.operator, notify.admin]
      observability-viewer:
        scopes: [obs:read, timeline:read, evidence:read, attest:read]
      observability-investigator:
        scopes: [obs:read, timeline:read, timeline:write, evidence:read, evidence:create, attest:read]
      observability-legal:
        scopes: [evidence:read, evidence:hold]
      observability-incident-commander:
        scopes: [obs:read, obs:incident, timeline:read, timeline:write, evidence:create, evidence:read, attest:read]

MFA requirement: When any exceptions.routingTemplates entry sets requireMfa: true, Authority refuses to mint tokens containing exceptions:approve unless the authenticating identity provider advertises MFA support. Password/OIDC flows produce authority.password.grant audit events with reason="Exception approval scope requires an MFA-capable identity provider." when the requirement is violated.

2 · Tenancy enforcement

2.1 Token claims

Tokens now include:

• tenant claim (string) — required for all ingestion and verification scopes.
• service_identity (optional) — e.g., policy-engine, cartographer. Required when requesting effective:write or graph:write.
• delegation_allowed (boolean) — defaults false. Prevents console tokens from delegating ingest scopes.

Authority rejects requests when:

• tenant is missing while requesting advisory:ingest, advisory:read, vex:ingest, vex:read, or aoc:verify scopes.
• aoc:verify is absent while tokens request advisory:read, vex:read, or any signals:* scope (invalid_scope with deterministic message).
• service_identity != policy-engine but effective:write is present (ERR_AOC_006 enforcement).
• service_identity != cartographer but graph:write is present (graph pipeline enforcement).
• Tokens attempt to combine advisory:ingest with effective:write (separation of duties).
• exceptions:approve is requested by a client without a tenant assignment or via an identity provider lacking MFA when RequireMfaForApprovals=true.

2.2 Propagation

• API Gateway forwards tenant claim as header (X-StellaOps-TenantId). Services refuse requests lacking the header.
• Concelier/Excititor stamp tenant into raw documents and structured logs.
• Policy Engine copies tenant from tokens into effective_finding_* collections.
• Exception lifecycle services persist tenant and the selected routing template identifier alongside approval decisions. Authority audit events (authority.password.grant, authority.client_credentials.grant) surface audit.scopes and, on denials, a scope.invalid metadata entry so operators can trace exception approval attempts without inspecting downstream services.

2.3 Cross-tenant scenarios

• Platform operators with tenant:admin can assume other tenants via /authority/tenant/switch if explicitly permitted.
• CLI commands accept --tenant <id> to override environment default; Authority logs tenant switch events (authority.tenant.switch).
• Console tenant picker uses delegated token exchange (/token/exchange) to obtain scoped tenant tokens without exposing raw credentials.

3 · Configuration changes

3.1 Authority configuration (authority.yaml)

Add new scopes and optional claims transformations:

security:
  scopes:
    - name: advisory:ingest
      description: Concelier raw ingestion (append-only)
    - name: advisory:read
      description: Read Concelier advisories and guard verdicts
    - name: vex:ingest
      description: Excititor raw ingestion
    - name: vex:read
      description: Read Excititor VEX records
    - name: vex.admin
      description: Administer Excititor VEX providers
    - name: aoc:verify
      description: Run AOC verification
    - name: airgap:status:read
      description: Read air-gap sealing status and staleness indicators
    - name: airgap:import
      description: Import offline bundles into the air-gapped catalog
    - name: airgap:seal
      description: Seal or unseal the installation during change control
    - name: effective:write
      description: Policy Engine materialisation
    - name: findings:read
      description: Read derived findings
    - name: graph:write
      description: Cartographer build submissions
    - name: graph:read
      description: Read graph overlays
    - name: graph:export
      description: Export graph artefacts
    - name: graph:simulate
      description: Run graph what-if simulations
    - name: vuln:view
      description: Read Vuln Explorer data, list findings, issue permalinks
    - name: vuln:investigate
      description: Perform triage actions (assign, comment, remediation notes)
    - name: vuln:operate
      description: Execute state changes and remediation workflows
    - name: vuln:audit
      description: Access Vuln Explorer audit ledgers and offline exports
  claimTransforms:
    - match: { scope: "effective:write" }
      require:
        serviceIdentity: policy-engine
    - match: { scope: "graph:write" }
      require:
        serviceIdentity: cartographer

3.2 Client registration

Update service clients:

• Concelier.WebService → request advisory:ingest, advisory:read.
• Excititor.WebService → request vex:ingest, vex:read.
• Policy.Engine → request effective:write, findings:read; set properties.serviceIdentity=policy-engine.
• Cartographer.Service → request graph:write, graph:read; set properties.serviceIdentity=cartographer.
• Graph API Gateway → request graph:read, graph:export, graph:simulate; tenant hint required.
• Console → request advisory:read, vex:read, aoc:verify, findings:read, replay:read, vuln:view, vuln:investigate, vuln:operate, vuln:audit plus existing UI scopes. Role issuance still narrows each interactive token to its professional bundle; Executive Assurance Viewer receives replay:read but not replay or vulnerability mutation scopes.
• CLI automation → request aoc:verify, advisory:read, vex:read, and vex.admin for VEX provider administration and forced ingestion runs as needed.

Client definition snippet:

clients:
  - clientId: concelier-web
    grantTypes: [client_credentials]
    scopes: [advisory:ingest, advisory:read]
    tenants: [default]
  - clientId: policy-engine
    grantTypes: [client_credentials]
    scopes: [effective:write, findings:read]
    properties:
      serviceIdentity: policy-engine
  - clientId: cartographer-service
    grantTypes: [client_credentials]
    scopes: [graph:write, graph:read]
    properties:
      serviceIdentity: cartographer

3.3 Delegated service accounts

Add delegated service accounts when automation needs scoped tokens with shorter lifetimes:

delegation:
  quotas:
    maxActiveTokens: 50
  serviceAccounts:
    - accountId: "svc-observer"
      tenant: "tenant-default"
      allowedScopes: [ "jobs:read", "findings:read" ]
      authorizedClients: [ "export-center-worker" ]

tenants:
  - name: "tenant-default"
    delegation:
      maxActiveTokens: 25

• Clients request delegated tokens by supplying service_account=<accountId> (and optional delegation_actor) alongside the usual client-credentials payload.
• Authority enforces both tenant and service-account quotas. Exceeding either returns invalid_request and records delegation.quota.exceeded in audit events.
• Only scopes listed in allowedScopes are granted; authorizedClients restricts which OAuth clients may impersonate the delegate.
• Delegated tokens include stellaops:service_account and an act claim. The token store persists tokenKind = "service_account", serviceAccountId, and the normalized actor chain for offline auditing.

4 · Operational safeguards

• Audit events: Authority emits authority.scope.granted and authority.scope.revoked events with scope and tenant. Monitor for unexpected grants.
• Rate limiting: Apply stricter limits on /token endpoints for clients requesting advisory:ingest or vex:ingest to mitigate brute-force ingestion attempts.
• Incident response: Link AOC alerts to Authority audit logs to confirm whether violations come from expected identities.
• Rotation: Rotate ingest client secrets alongside guard deployments; add rotation steps to ops/authority-key-rotation.md.
• Testing: Integration tests must fail if tokens lacking tenant attempt ingestion; add coverage in Concelier/Excititor smoke suites (see CONCELIER-CORE-AOC-19-013).

5 · Offline & air-gap notes

• Offline Kit bundles include tenant-scoped service credentials. Ensure ingest bundles ship without advisory:ingest scopes unless strictly required.
• CLI verification in offline environments uses pre-issued aoc:verify tokens; document expiration and renewal processes.
• Authority replicas in air-gapped environments should restrict scope issuance to known tenants and log all /token interactions for later replay.

6 · References

• Aggregation-Only Contract reference
• Architecture overview
• Concelier architecture
• Excititor architecture
• Policy governance
• Authority key rotation playbook
• Authority threat model
• Authority audit events
• Console security posture

7 · Compliance checklist

• [ ] Scope catalogue updated in Authority configuration templates.
• [ ] Role mappings documented for each tenant profile.
• [ ] Claim transforms enforce serviceIdentity for effective:write.
• [ ] Claim transforms enforce serviceIdentity for graph:write.
• [ ] Concelier/Excititor smoke tests cover missing tenant rejection.
• [ ] Delegation quotas configured (delegation.quotas.maxActiveTokens, tenants[].delegation.maxActiveTokens where required).
• [ ] Service account seeds (delegation.serviceAccounts) reviewed for allowed scopes and authorized clients; audit dashboards show delegation.service_account usage.
• [ ] Offline kit credentials reviewed for least privilege.
• [ ] Audit/monitoring guidance validated with Observability Guild.
• [ ] Authority Core sign-off recorded (owner: @authority-core, due 2025-10-28).

Last updated: 2025-11-02 (Sprint 19).