stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
7e7be4d2fd30491b9fba6a9236af08fe1e9fd143
git.stella-ops.org/docs/product-advisories/29-Nov-2025 - Authentication and Authorization Architecture.md
StellaOps Bot b34f13dc03 up
2025-11-29 02:19:50 +02:00

12 KiB
Raw Blame History

Authentication and Authorization Architecture

Version: 1.0 Date: 2025-11-29 Status: Canonical

This advisory defines the product rationale, token model, scope taxonomy, and implementation strategy for the Authority module, consolidating authentication and authorization patterns across all Stella Ops services.

1. Executive Summary

Authority is the on-premises OIDC/OAuth2 issuing service that provides secure identity for all Stella Ops operations. Key capabilities:

  • Short-Lived Tokens (OpTok) - 2-5 minute TTL operational tokens
  • Sender Constraints - DPoP or mTLS binding prevents token theft
  • Fine-Grained Scopes - 65+ scopes with role bundles
  • Multi-Tenant Isolation - Tenant claims enforced throughout
  • Delegated Service Accounts - Automation without credential exposure
  • Sovereign Crypto Support - Configurable signing algorithms per profile

2. Market Drivers

2.1 Target Segments

Segment Authentication Requirements Use Case
Enterprise SSO/SAML integration, MFA Corporate security policies
Government CAC/PIV, FIPS validation Federal compliance
Financial Services Strong auth, audit trails SOC 2, PCI-DSS
Healthcare HIPAA access controls PHI protection

2.2 Competitive Positioning

Most vulnerability scanning tools rely on basic API keys. Stella Ops differentiates with:

  • Zero-trust token model with sender constraints
  • Fine-grained RBAC with 65+ scopes
  • Cryptographic binding (DPoP/mTLS) prevents token theft
  • Deterministic revocation bundles for offline verification
  • Plugin extensibility for custom identity providers

3. Token Model

3.1 Three-Token System

Token Lifetime Purpose Binding
License Token (LT) Long-lived Cloud licensing enrollment Installation
Proof-of-Entitlement (PoE) Medium License validation Installation key
Operational Token (OpTok) 2-5 min Runtime authentication DPoP/mTLS

3.2 Operational Token Structure

Registered Claims:

{
  "iss": "https://authority.example.com",
  "sub": "client-id-or-user-id",
  "aud": "signer|scanner|attestor|concelier|...",
  "exp": 1732881600,
  "iat": 1732881300,
  "nbf": 1732881270,
  "jti": "uuid",
  "scope": "scanner.scan scanner.export signer.sign"
}

Sender Constraint Claims:

{
  "cnf": {
    "jkt": "base64url(SHA-256(JWK))",     // DPoP binding
    "x5t#S256": "base64url(SHA-256(cert))" // mTLS binding
  }
}

Tenant & Context Claims:

{
  "tid": "tenant-id",
  "inst": "installation-id",
  "roles": ["svc.scanner", "svc.signer"],
  "plan": "enterprise"
}

3.3 Sender Constraints

DPoP (Demonstration of Proof-of-Possession):

  1. Client generates ephemeral JWK keypair
  2. Client sends DPoP proof header with htm, htu, iat, jti
  3. Authority validates and stamps token with cnf.jkt
  4. Resource servers verify same key on each request
  5. Nonce challenges available for high-value audiences

mTLS (Mutual TLS):

  1. Client presents certificate at TLS handshake
  2. Authority validates and binds to cnf.x5t#S256
  3. Resource servers verify same cert on each request
  4. Required for high-value audiences (signer, attestor)

4. Scope Taxonomy

4.1 Scope Categories (65+ scopes)

Ingestion Scopes (tenant-required):

  • advisory:ingest - Concelier advisory ingestion
  • vex:ingest - Excititor VEX ingestion
  • signals:write - Reachability signal ingestion

Verification Scopes (require aoc:verify pairing):

  • advisory:read - Advisory queries
  • vex:read - VEX queries
  • signals:read - Signal queries

Service Scopes:

Service Scopes
Signer signer.sign (mTLS enforced)
Scanner scanner.scan, scanner.export, scanner.read
Attestor attestor.write
Policy Studio policy:author, policy:review, policy:approve, policy:operate, policy:publish, policy:promote, policy:audit, policy:simulate
Vuln Explorer vuln:view, vuln:investigate, vuln:operate, vuln:audit
Orchestrator orch:read, orch:operate, orch:quota, orch:backfill
Export Center export.viewer, export.operator, export.admin
Task Packs packs.read, packs.write, packs.run, packs.approve
Evidence evidence:create, evidence:read, evidence:hold
Timeline timeline:read, timeline:write

Special Scopes:

  • obs:incident - Incident mode activation (fresh auth required)
  • tenant:admin - Cross-tenant operations

4.2 Role Bundles

Authority provides 40+ predefined roles that bundle related scopes:

Role Scopes Requirements
role/concelier-ingest advisory:ingest, advisory:read Tenant claim
role/signals-uploader signals:write, signals:read, aoc:verify Tenant claim
role/policy-engine effective:write, findings:read serviceIdentity: policy-engine
role/policy-author policy:author, policy:read, policy:simulate, findings:read -
role/policy-approver policy:approve, policy:review, policy:read, policy:simulate, findings:read -
role/orch-operator orch:read, orch:operate -
role/export-admin export.viewer, export.operator, export.admin -

5. Multi-Tenant Isolation

5.1 Tenant Claim Enforcement

Token Issuance:

  • Authority normalizes tenant: trim().ToLowerInvariant()
  • Tokens include tid (tenant ID) and inst (installation ID)
  • Cross-tenant isolation enforced at issuance

Propagation:

  • API Gateway forwards tid as X-Stella-Tenant header
  • Downstream services reject requests without header
  • All data stamped with tenant identifier

Scope Enforcement:

  • Ingestion scopes require tenant claim
  • aoc:verify pairing required for verification scopes
  • Cross-tenant replay rejected

5.2 Cross-Tenant Operations

For platform operators with tenant:admin:

  • Switch tenants via /authority/tenant/switch
  • CLI --tenant <id> override
  • Delegated token exchange for automation
  • Full audit trail of tenant switches

6. Advanced Token Features

6.1 Delegated Service Accounts

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

Token Shape:

  • Includes stellaops:service_account claim
  • act claim describes caller hierarchy
  • Quota enforcement per tenant/account

6.2 Fresh Auth Window (5 Minutes)

Required for high-privilege operations:

  • Policy publish/promote
  • Pack approvals
  • Incident mode activation
  • Operator actions

Token must include:

  • auth_time within 5 minutes of request
  • Interactive authentication (password/device-code)

6.3 ABAC Attributes (Vuln Explorer)

Tokens can carry attribute-based filters:

  • stellaops:vuln_env - Environment filter
  • stellaops:vuln_owner - Team/owner filter
  • stellaops:vuln_business_tier - Criticality tier

7. Implementation Strategy

7.1 Phase 1: Core Token Infrastructure (Complete)

  • DPoP validation on all /token grants
  • mTLS binding for refresh grants
  • Sealed-mode CI gating
  • Pack signing policies and RBAC
  • LDAP plugin with claims enricher

7.2 Phase 2: Sovereign Crypto (In Progress)

  • Crypto provider registry wiring (AUTH-CRYPTO-90-001)
  • GOST signing support
  • FIPS validation
  • Post-quantum preparation

7.3 Phase 3: Advanced Features (Planned)

  • DSSE predicate types for SBOM/Graph/VEX (AUTH-REACH-401-005)
  • PostgreSQL storage migration
  • Enhanced delegation quotas

8. API Surface

8.1 Token Endpoints

Endpoint Method Purpose
/token POST Token issuance (all grant types)
/introspect POST Token introspection
/revoke POST Token/refresh revocation
/.well-known/openid-configuration GET OIDC discovery
/jwks GET JSON Web Key Set

8.2 Supported Grant Types

  • Client Credentials - Service-to-service (mTLS or private_key_jwt)
  • Device Code - CLI on headless agents
  • Authorization Code + PKCE - Browser UI login
  • Refresh Token - With DPoP/mTLS re-validation

8.3 Admin APIs

All under /admin (mTLS + authority.admin scope):

Endpoint Method Purpose
/admin/clients POST Create/update client
/admin/audiences POST Register audience URIs
/admin/roles POST Define role→scope mappings
/admin/tenants POST Create tenant entries
/admin/keys/rotate POST Rotate signing key

9. Revocation & JWKS

9.1 Revocation Bundles

Deterministic bundles for offline verification:

revocation-bundle.json
├── revokedTokens[]      # List of revoked jti values
├── revokedClients[]     # Revoked client IDs
├── generatedAt          # UTC timestamp
├── validUntil           # Expiry for offline cache
└── signature            # Detached JWS (RFC 7797)

9.2 JWKS Management

  • At least 2 active keys during rotation
  • Old keys retained for max TTL + 5 minutes
  • Key status: active, retired, revoked

9.3 CLI Verification

# Export revocation bundle
stella auth revoke export --output revocation.json

# Verify bundle signature
stella auth revoke verify --bundle revocation.json --key pubkey.pem

10. Security Considerations

10.1 Threat Model Coverage

Threat Mitigation
Token theft DPoP/mTLS sender constraints
Replay attacks DPoP nonce challenges, short TTL
Token injection Audience validation
Privilege escalation Scope enforcement, role bundles
Cross-tenant access Tenant claim isolation

10.2 Operational Security

  • Bootstrap API key protection
  • Key rotation before expiration
  • Rate limiting on /token endpoint
  • Audit logging for all token operations

11. Observability

11.1 Metrics

  • authority_token_issued_total{grant_type,audience}
  • authority_token_rejected_total{reason}
  • authority_dpop_nonce_miss_total
  • authority_mtls_mismatch_total

11.2 Audit Events

  • authority.token.issued - Token issuance
  • authority.token.rejected - Rejection with reason
  • authority.tenant.switch - Cross-tenant operation
  • authority.key.rotated - Key rotation
  • authority.plugin.*.password_verification - Plugin events

12. Related Documentation

Resource Location
Authority architecture docs/modules/authority/architecture.md
Authority overview docs/11_AUTHORITY.md
Scope reference docs/security/authority-scopes.md
DPoP/mTLS rollout docs/security/dpop-mtls-rollout.md
Threat model docs/security/authority-threat-model.md
Revocation bundles docs/security/revocation-bundle.md
Key rotation docs/modules/authority/operations/key-rotation.md
Plugin guide docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md

13. Sprint Mapping

  • Historical: SPRINT_100_identity_signing.md (CLOSED)
  • Documentation: SPRINT_314_docs_modules_authority.md
  • PostgreSQL: SPRINT_3401_0001_0001_postgres_authority.md
  • Crypto: SPRINT_0514_0001_0001_sovereign_crypto_enablement.md

Key Task IDs:

  • AUTH-DPOP-11-001 - DPoP validation (DONE)
  • AUTH-MTLS-11-002 - mTLS binding (DONE)
  • AUTH-AIRGAP-57-001 - Sealed-mode CI gating (DONE)
  • AUTH-CRYPTO-90-001 - Sovereign crypto wiring (IN PROGRESS)
  • AUTH-REACH-401-005 - DSSE predicates (TODO)

14. Success Metrics

Metric Target
Token issuance latency < 50ms p99
DPoP validation rate 100% on /token
Sender constraint coverage 100% for high-value audiences
Key rotation downtime Zero
Revocation bundle freshness < 5 minutes

Last updated: 2025-11-29