ADR-028: Service Identity + On-Behalf-Of (craig-identity contract)

Worker auth: published JWT contract, OIDC discovery, IdP-neutral identity hydration (lazy from JWT claims)

Service auth: per-service client_credentials + actor JWT on-behalf-of header

Per-jurisdiction, not multi-tenant SaaS. Each jurisdiction runs its own craig stack. Architectural simplicity per stack is what matters.

Operators choose any IAM backend. Keycloak / Okta / Auth0 / Azure AD-Entra / Authentik / ForgeRock / on-prem AD with ADFS or LDAP. craig must not lock anyone into a specific backend (ADR-026).

craig is not in the ops business. xtask is dev/CI tooling. Production identity-backend lifecycle (provisioning, secret rotation, access-review) is the deployer’s responsibility via their existing IaC. craig supplies contract, conformance test, and reference templates — nothing that mutates production infrastructure.

Single integration point per service. Every craig-* service depends on one URL (CRAIG_IDENTITY_ISSUER). No per-service operator-IdP integration. No per-service per-IdP claim-mapper hand-coding.

Genuine backend pluggability. Services don’t know the backend type because they only consume OIDC discovery + JWKS + standard JWT claims. Keycloak, Dex, Authentik, Okta, Entra, ForgeRock, or a custom Rust binary all work as long as xtask identity verify passes.

No new service container. Zero net deployment-surface increase. craig-auth (existing crate) gains client-side helpers; everything else is reference templates and a verifier.

Audit log gains caller-service. audit_log.actor_service = claims.service_id() (always present on service tokens). actor_user_sub = claims.actor.as_ref().map(|a| &a.sub) (when X-Craig-Actor is present).

Service token lifetime decoupled from worker session. Service tokens refresh on the service’s schedule. Long-running flows don’t fail mid-flight on session expiry.

KeycloakServiceToken retired. The IdP-coupled type name + ROPC grant goes away. Replaced by OidcServiceToken in crates/craig-auth.

Two JWKS to validate per request when X-Craig-Actor is present. Bearer validates against craig-identity JWKS; actor validates against craig-signing JWKS. Mitigated by caching: craig-auth caches verified JWTs for 30 s, with separate cache hits for bearer and actor tokens.

Operators must configure 9 service-account clients in their IAM backend. This is real work, but it’s a one-time per-stack cost (craig is per-jurisdiction, not multi-tenant SaaS) and xtask identity render provides templates for the supported backends.

Reference templates can drift from craig’s expectations. Mitigated by xtask identity verify — operators run it post-provisioning to confirm their backend matches craig’s contract.

Secrets rotation is the deployer’s job. craig-side caching survives a rotation event up to the cached service-token TTL (1h default); after that, services need a fresh client_credentials grant. Operators document their rotation procedure; craig doesn’t ship rotation tooling.

JWKS staleness: OIDC discovery + JWKS endpoints publish with sensible cache headers; craig-auth refreshes on kid cache miss.

Per-stack trust isolation: Each craig stack uses its own craig-identity issuer URL. Tokens from stack A don’t validate against stack B because the JWKS keys differ.

Soft-cutover continues to accept worker JWTs at internal endpoints — direct CLI/integration test callers don’t break. Future hardening (rejecting worker JWTs at internal-only endpoints) is a follow-up beyond Plan E.

Phase A — Foundations (Steps 2–7): Claims API extensions; OidcServiceToken (replaces KeycloakServiceToken); ActorTokenIssuer; auth middleware actor extraction; outbound helpers; bootstrap wiring; xtask identity verify. Worker JWTs still accepted at every endpoint.

Phase B — Outbound flip (Steps 8–9): craig-web’s 6 client call sites + craig-intake’s flip from JWT pass-through to with_service_identity + with_actor. End-to-end Playwright validates the BFF flow.

Phase C — Audit + tooling (Steps 10–13): audit-log enrichment with actor_service + actor_user_sub columns; xtask identity render for keycloak/authentik/dex; devstack realm.json + secrets updates.

Verbatim forward, not re-mint. A relaying service forwards the inbound Authorization bearer AND X-Craig-Actor header UNCHANGED, because it is relaying someone else’s on-behalf-of context, not asserting its own. The actor JWT’s fleet-wide aud: craig-internal-actor (no per-service audience — see "Out of scope" above) is what makes the extra hop valid: the receiver verifies the actor JWT against the deployment-wide peer-JWKS registry keyed by the JWT’s OWN (iss, kid), independent of which service’s bearer carried it.

Attribution semantics at hop N. audit_log.actor_service names the FIRST hop’s bearer service (the relay forwards that bearer too) and rule_evaluations.evaluated_by names the acting worker (claims.acting_worker().sub — the unit-pinned evaluation_attribution helper in craig-rules). The relay chain itself is not recorded; chain visibility (RFC 8693-style act_for chains) is a deliberate non-goal today, tracked under the #1481 enforcement tracker (see the #1377 amendment below).

No bearer↔actor issuer binding — accepted boundary. The middleware verifies the pair as two independent checks; nothing requires the actor JWT’s iss to equal the bearer’s service_id(). Verbatim forwarding keeps pairs coherent in practice (the relay forwards both halves of the SAME inbound pair), and production services hold only their own signing key. Decided 2026-08-16: this is an ACCEPTED boundary, per the #1377 amendment below; the enforcement question (enforce iss == service_id, or add chain visibility instead) is tracked as #1481.

TTL bounds the chain. The 10-minute actor-JWT TTL means verbatim forwarding only suits SYNCHRONOUS relay chains. Deferred work (outbox / inbox consumers) uses RelayAuth::service — the service’s own bearer, NO actor by construction — and its audit rows correctly name the machine (the conversion auto-link consumer is the reference case).

Caching boundaries stay service-context. A relay whose response feeds a CROSS-REQUEST cache must NOT forward per-worker credentials (one worker’s authz outcome would be served to another): craig-cases' screening-policy ruleset fetch (a rule_set READ writing no rule_evaluations row) deliberately sends only the service bearer, per the hazard note in relay_auth.rs. Converting such a site requires keying the cache by acting identity first.

Fixture posture. The rule_evaluation authz fixtures (GA/TX 1.2.0) narrow the bare-service create row to claims.service_id == 'craig-cases' — the relay’s system leg is the only legitimate bare-service evaluator (#1107 per-principal precedent). The rule_set read/list service rows stay UN-narrowed: they serve the fleet-wide authz cache-warm every service performs with its own bare token, and a principal IN-list there would need editing on every new service — a maintenance hazard with no attribution stake (reads write no audit evaluation rows).

The gap, precisely. The middleware verifies the bearer and the actor JWT as two INDEPENDENT checks. The actor path is gated only on the bearer being a service principal (!claims.is_service() skips it — crates/craig-auth/src/middleware.rs:215); verify_actor_token never receives the bearer’s claims (middleware.rs:218); the verified actor is lifted unconditionally (middleware.rs:225). Verification resolves the key by the actor JWT’s OWN (iss, kid) against the peer registry (crates/craig-auth/src/actor_verifier.rs:239-244), and the issuer check is self-referential — set_issuer receives the same iss just extracted from the token (actor_verifier.rs:250-251; the audience is the fleet-wide craig-internal-actor). Nothing binds the actor JWT’s iss to the bearer’s service_id(): a (craig-cases bearer, craig-web actor) pair verifies today. The characterization test cross_issuer_actor_pair_verifies_today_the_adr_028_accepted_boundary (in middleware.rs) pins this so the behavior stays visible, never accidental.

Threat accepted, explicitly. An attacker holding a compromised low-privilege service’s bearer credential plus ANY registered peer’s actor JWT — captured in transit or coaxed, usable for its ≤10-minute TTL — evaluates downstream as the asserted worker. And because audit_log.actor_service names the first-hop bearer service only (the #1329 attribution contract above), the relay chain such a pair claims to represent is invisible in audit: forensics cannot distinguish the legitimate relay from the mixed pair.

Compensating controls (why this is tolerable today). (1) Production services hold ONLY their own ES256 signing key (CRAIG_<SVC>__SIGNING_JWK) — minting another service’s actor JWT requires that service’s private key, so the mixed pair needs a CAPTURED token, not a minted one; the devstack’s everyone-has-everything key layout is dev-only. (2) The actor-JWT TTL ceiling is enforced server-side at 600 s + 30 s clock skew (actor_verifier.rs:271-275), bounding the replay window. (3) The RelayAuth verbatim-forward practice (services/craig-cases/src/relay_auth.rs:27-34) forwards both halves of the SAME inbound pair, so legitimate traffic keeps pairs coherent — a mixed pair is anomalous, never routine.

Revisit trigger. #1481 is the standing enforcement tracker (bind iss == service_id(), or add chain visibility instead — alternatives, not a bundle). It is BLOCKED until the first multi-tenant or partner-adjacent deployment: today every service inside a stack’s trust boundary is first-party (one jurisdiction, one operator), and the binding would add a fail-closed coupling with no present attacker it defeats.

act_for, honestly. The minted claim "act_for": service_name (crates/craig-auth/src/actor_token.rs:143) is a SCALAR duplicate of iss: it is not present on Claims, is silently dropped at decode (actor_verifier.rs:255), and has ZERO consumers repo-wide. It is NOT an RFC 8693 act chain and must not be read as chain evidence; an actual chain (each relay hop appending itself) is future design under #1481.