Phase 2 hardening

Author: rcholic

docs/authorityd-operations.md

@@ -81,12 +81,98 @@ PYTHONPATH=. predicate-authorityd \
   --mandate-signing-key-env PREDICATE_AUTHORITY_SIGNING_KEY
 ```
 
+## 2b) Okta production hardening checklist + staging matrix
+
+Use this section when validating enterprise IdP readiness for Phase 2.
+
+### Checklist
+
+- [ ] Configure dedicated Okta OIDC app integration per environment (staging/prod split).
+- [ ] Verify configured `issuer` and `audience` are exact matches to the target environment.
+- [ ] Verify required claims/scopes/groups mapping used by authority role/tenant checks.
+- [ ] Enforce strict JWT checks (`iss`, `aud`, `exp`, `nbf`, `iat`, required claims, alg allowlist).
+- [ ] Validate JWKS retrieval and cache behavior for normal operation.
+- [ ] Validate key rotation behavior (`kid` rollover) without service restart.
+- [ ] Validate fail-closed behavior for cold-start JWKS failure and stale key scenarios.
+- [ ] Validate redaction: no token/secret leakage in logs on failures/retries.
+- [x] Validate startup diagnostics for missing/invalid auth configuration.
+- [ ] Validate revocation path behavior under Okta-backed principals.
+
+### Staging test matrix
+
+| Test ID | Scenario | Expected Result |
+| --- | --- | --- |
+| OKTA-01 | Valid token (correct issuer/audience/scope) | Request authorized and audit emitted |
+| OKTA-02 | Wrong issuer | Denied with issuer mismatch reason |
+| OKTA-03 | Wrong audience | Denied with audience mismatch reason |
+| OKTA-04 | Missing required scope | Denied fail-closed before action |
+| OKTA-05 | Expired token | Denied with expiration reason |
+| OKTA-06 | Future `nbf` beyond leeway | Denied with temporal validation reason |
+| OKTA-07 | Unsupported signing algorithm | Denied before trust decision |
+| OKTA-08 | JWKS rotation (`kid` changes) | Validation recovers without restart |
+| OKTA-09 | JWKS outage with warm cache | Existing key path continues until cache boundary |
+| OKTA-10 | JWKS outage with cold cache | Startup/auth fails closed with actionable diagnostics |
+| OKTA-11 | Tenant outside allow-list | Denied with tenant policy reason |
+| OKTA-12 | Principal/intent revocation during run | Subsequent action denied promptly |
+| OKTA-13 | Log redaction check | No raw tokens/secrets in logs |
+
+### Signoff evidence commands (deterministic integration tests)
+
+Run these from `AgentIdentity` repo root and attach output to signoff evidence.
+
+1) Network partition fail-closed behavior:
+
+```bash
+python3 -m pytest tests/test_daemon_phase2.py -k "network_partition_fail_closed_raises_and_tracks_failure"
+```
+
+Checkpoints:
+
+- pass result proves fail-closed error path is enforced when control-plane is partitioned and `fail_open=False`,
+- `/status` payload includes incremented control-plane failure counters.
+
+2) Restart recovery with persisted queue:
+
+```bash
+python3 -m pytest tests/test_daemon_phase2.py -k "restart_recovers_queue_after_partition"
+```
+
+Checkpoints:
+
+- pre-restart flush queue has pending event(s),
+- post-restart `POST /ledger/flush-now` reports `sent_count >= 1`,
+- post-flush queue is empty (`GET /ledger/flush-queue` returns no items).
+
 When enabled, daemon bootstrap auto-attaches `ControlPlaneTraceEmitter` so each
 authority decision pushes:
 
 - audit events -> `/v1/audit/events:batch`
 - usage credits -> `/v1/metering/usage:batch`
 
+### Optional: use Okta identity mode
+
+Provide Okta OIDC values via env vars:
+
+```bash
+export OKTA_ISSUER="https://<org>.okta.com/oauth2/default"
+export OKTA_CLIENT_ID="<okta-client-id>"
+export OKTA_AUDIENCE="api://predicate-authority"
+```
+
+Start daemon in Okta mode:
+
+```bash
+PYTHONPATH=. predicate-authorityd \
+  --host 127.0.0.1 \
+  --port 8787 \
+  --mode cloud_connected \
+  --identity-mode okta \
+  --okta-issuer "$OKTA_ISSUER" \
+  --okta-client-id "$OKTA_CLIENT_ID" \
+  --okta-audience "$OKTA_AUDIENCE" \
+  --policy-file examples/authorityd/policy.json
+```
+
 ## 3b) Optional local identity registry (ephemeral task identities)
 
 Enable local identity support:

predicate_authority/__init__.py

@@ -7,6 +7,8 @@
     LocalIdPBridgeConfig,
     OIDCBridgeConfig,
     OIDCIdentityBridge,
+    OktaBridgeConfig,
+    OktaIdentityBridge,
     TokenExchangeResult,
 )
 from predicate_authority.client import AuthorityClient, LocalAuthorizationContext
@@ -71,6 +73,8 @@
     "LocalRevocationCache",
     "OIDCBridgeConfig",
     "OIDCIdentityBridge",
+    "OktaBridgeConfig",
+    "OktaIdentityBridge",
     "OpenTelemetryTraceEmitter",
     "PolicyEngine",
     "PolicyFileSource",

predicate_authority/bridge.py

@@ -44,6 +44,14 @@ class EntraBridgeConfig:
     token_ttl_seconds: int = 300
 
 
+@dataclass(frozen=True)
+class OktaBridgeConfig:
+    issuer: str
+    client_id: str
+    audience: str
+    token_ttl_seconds: int = 300
+
+
 @dataclass(frozen=True)
 class LocalIdPBridgeConfig:
     issuer: str = "http://localhost/predicate-local-idp"
@@ -138,6 +146,33 @@ def exchange_token(
         )
 
 
+class OktaIdentityBridge(OIDCIdentityBridge):
+    """Okta adapter built on generic OIDC behavior.
+
+    Phase 2 keeps this as a deterministic local stand-in for real IdP token exchange.
+    """
+
+    def __init__(self, config: OktaBridgeConfig) -> None:
+        oidc_config = OIDCBridgeConfig(
+            issuer=config.issuer,
+            client_id=config.client_id,
+            audience=config.audience,
+            token_ttl_seconds=config.token_ttl_seconds,
+        )
+        super().__init__(oidc_config)
+
+    def exchange_token(
+        self, subject: PrincipalRef, state_evidence: StateEvidence
+    ) -> TokenExchangeResult:
+        result = super().exchange_token(subject, state_evidence)
+        return TokenExchangeResult(
+            access_token=result.access_token,
+            expires_at_epoch_s=result.expires_at_epoch_s,
+            token_type=result.token_type,
+            provider=IdentityProviderType.OKTA,
+        )
+
+
 class LocalIdPBridge:
     """Local IdP emulator for dev/offline/air-gapped workflows."""
 

predicate_authority/daemon.py

@@ -20,6 +20,8 @@
     LocalIdPBridgeConfig,
     OIDCBridgeConfig,
     OIDCIdentityBridge,
+    OktaBridgeConfig,
+    OktaIdentityBridge,
 )
 from predicate_authority.control_plane import (
     ControlPlaneClient,
@@ -727,6 +729,19 @@ def _build_identity_bridge_from_args(args: argparse.Namespace) -> ExchangeTokenB
                 token_ttl_seconds=int(args.idp_token_ttl_s),
             )
         )
+    if mode == "okta":
+        if args.okta_issuer is None or args.okta_client_id is None or args.okta_audience is None:
+            raise SystemExit(
+                "identity-mode=okta requires --okta-issuer, --okta-client-id, and --okta-audience."
+            )
+        return OktaIdentityBridge(
+            OktaBridgeConfig(
+                issuer=str(args.okta_issuer),
+                client_id=str(args.okta_client_id),
+                audience=str(args.okta_audience),
+                token_ttl_seconds=int(args.idp_token_ttl_s),
+            )
+        )
     raise SystemExit(f"Unsupported identity mode: {mode}")
 
 
@@ -773,9 +788,9 @@ def main() -> None:
     parser.add_argument("--local-identity-default-ttl-s", type=int, default=900)
     parser.add_argument(
         "--identity-mode",
-        choices=["local", "local-idp", "oidc", "entra"],
+        choices=["local", "local-idp", "oidc", "entra", "okta"],
         default="local",
-        help="Identity source for token exchange: local, local-idp, oidc, or entra.",
+        help="Identity source for token exchange: local, local-idp, oidc, entra, or okta.",
     )
     parser.add_argument("--idp-token-ttl-s", type=int, default=300)
     parser.add_argument(
@@ -797,6 +812,9 @@ def main() -> None:
     parser.add_argument("--entra-tenant-id", default=os.getenv("ENTRA_TENANT_ID"))
     parser.add_argument("--entra-client-id", default=os.getenv("ENTRA_CLIENT_ID"))
     parser.add_argument("--entra-audience", default=os.getenv("ENTRA_AUDIENCE"))
+    parser.add_argument("--okta-issuer", default=os.getenv("OKTA_ISSUER"))
+    parser.add_argument("--okta-client-id", default=os.getenv("OKTA_CLIENT_ID"))
+    parser.add_argument("--okta-audience", default=os.getenv("OKTA_AUDIENCE"))
     parser.add_argument(
         "--control-plane-enabled",
         action="store_true",