Eve library

OSHUN Studio Authentication Architecture Runbook

Runbook

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + Platform Identity
Last Updated: 2026-02-23
Related:

  • docs/adr/ADR-0025-oshun-studio-authentication-architecture.md
  • docs/releases/v1/specs/studio-authentication-architecture-dependency-and-data-contract-map.md
  • docs/releases/v1/specs/studio-authentication-architecture-user-journeys-and-edge-cases.md
  • apps/oshun/web/src/components/studio/StudioAuthenticationArchitectureWorkspace.tsx
  • apps/oshun/web/src/analytics/studioAuthenticationArchitectureTelemetry.ts

Purpose#

Define operational ownership, SLOs, incident playbooks, and escalation paths for Studio authentication architecture governance workflows.

This document is the execution artifact for OST-00104.

1. Ownership Model#

Surface Primary Owner Backup Owner Dependencies
Authentication architecture route OSHUN Web Platform Web route + analytics contracts
Session/auth context envelope contracts Platform Identity + Studio Architecture BFF session + entitlement schemas
Step-up challenge orchestration Platform Identity Security Engineering challenge providers + risk engine
Privileged action policy controls Security + Platform Identity Program Ops policy engine + entitlement service
Telemetry and audit evidence Data Platform SRE event sinks + ingestion pipelines

2. Core SLOs#

Metric Target Alert Threshold
Authentication flow success rate >= 99.0% < 98.0% over 15 min
Auth context validation integrity 100% deterministic any false pass
Privileged policy decision correctness 100% policy-consistent any false allow
Authentication flow p95 latency <= 2200ms > 3200ms over 15 min
Authentication audit completeness >= 99.5% < 99.0% over 15 min

3. Operational Playbooks#

3.1 Auth Context Validation Failures#

Trigger: repeated AUTH_CONTEXT_VALIDATION_FAILED outcomes.

Actions:

  1. Inspect identity/session/action envelope diagnostics.
  2. Verify entitlement payload freshness and assurance metadata validity.
  3. Re-run validation in preview with expanded diagnostics.
  4. Roll back to last certified auth-context contract if needed.

3.2 Step-Up Challenge Failures#

Trigger: repeated AUTH_STEP_UP_CHALLENGE_FAILED outcomes.

Actions:

  1. Validate risk signal inputs and selected challenge strategy.
  2. Check provider timeout/error telemetry and response signatures.
  3. Re-run challenge flow in controlled mode with tracing enabled.
  4. Block privileged promotion until assurance elevation is deterministic.

3.3 Privileged Action Grant Failures#

Trigger: repeated AUTH_PRIVILEGED_ACTION_GRANT_FAILED outcomes.

Actions:

  1. Inspect policy decision logs and entitlement claims.
  2. Verify assurance level satisfies required action threshold.
  3. Reconcile policy versions and rollback conflicting policy rollout.
  4. Re-attempt grant only after policy and assurance checks pass.

3.4 Policy Denial Spike#

Trigger: unexpected increase in ROLE_POLICY_DENIED outcomes.

Actions:

  1. Compare flow policy map against active role entitlements.
  2. Validate identity payload version and role-claim mappings.
  3. Apply policy hotfix or rollback entitlement drift.
  4. Confirm deny-rate normalization after mitigation.

3.5 Telemetry and Audit Degradation#

Trigger: missing or delayed authentication telemetry/audit events.

Actions:

  1. Validate analytics sink health and ingestion queue depth.
  2. Enable degraded-observability warning in authentication workspace.
  3. Reconcile missed events from buffered traces.
  4. Confirm event completeness and SLO recovery.

4. Release Checklist#

  • Validate /studio/authentication-architecture renders and executes required flows.
  • Validate optimistic, error, and retry behavior for each flow.
  • Validate role-policy allow/deny behavior.
  • Validate telemetry/audit emissions and SLO panel updates.
  • Validate integration/e2e/accessibility evidence artifacts.

5. Incident Communication Templates#

Incident Start#

text
[P{severity}] Studio Authentication Architecture Incident
Detected: {timestamp}
Impact: {context validation | step-up challenge | privileged grant impact}
Suspected cause: {contract drift | challenge provider issue | policy drift}
Owner: {on-call}

Incident Update#

text
[P{severity}] Studio Authentication Architecture Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {authContextValidation | stepUpChallengeExecution | privilegedActionGrant}
ETA: {time}

Incident Resolved#

text
[P{severity}] Studio Authentication Architecture Incident Resolved
Resolved: {timestamp}
Root cause: {description}
Fix: {release/hotfix id}
Validation: {tests + telemetry checks}
Postmortem: {link}

6. Escalation Paths#

Area Primary Channel Escalate To
Web runtime and workspace #oshun-web Platform on-call
Identity/session architecture #oshun-identity Identity architecture lead
Challenge orchestration and providers #oshun-security Security engineering lead
Policy and entitlement decisions #oshun-security Security lead
Telemetry pipeline and reliability #oshun-data-platform SRE lead

7. Acceptance Criteria (OST-00104)#

OST-00104 is complete only when:

  1. Ownership and decision authority are documented.
  2. Authentication architecture SLOs and alert thresholds are documented.
  3. At least five playbooks are documented for major failure modes.
  4. Release checklist, communication templates, and escalation paths exist.