IdP Integration

Worker-attributed writes fail closed without a configured exchanger (exchanger_not_configured — there is no service-token fallback), so the worker review surfaces (document accept/reject/scan-override), the user-only reporting surfaces, and every S-slice user-context arm are inoperable.

There is no header-based substitute: the transitional X-Canopy-Actor channel is retired and rejected outright.

Dedicated confidential exchanger clients — canopy-web-exchanger (canopy-web’s BFF, access.token.lifespan=300) and canopy-eligibility-exchanger (the orchestrator fan-out, access.token.lifespan=240 — the hop-2 chaining margin, #1563 below). Each carries standard.token.exchange.enabled=true (exchanged tokens are ≤ 300s per ADR-043) and holds no service:* role — it mints on behalf of a human.

Per-target audience scopes (aud-canopy-<target>) as OPTIONAL client scopes on the exchangers, each an oidc-audience-mapper with included.client.audience=canopy-<target>. The exchange request passes scope=aud-canopy-<target> so the exchanged token’s aud is EXACTLY the one target (the receiver contract’s exact-audience rule; the F3 broker rejects anything broader). The broad canopy / canopy-internal-service audiences are deliberately not emittable by any exchanger scope — requesting them is denied at the IdP.

Requester-audience mappers on the worker clients — canopy-api (and canopy-ui) carry an oidc-audience-mapper with included.client.audience=canopy-web-exchanger, because V2 requires the subject token to name the requesting exchanger in aud.

canopy-conformance-exchanger is devstack-only — do NOT provision it in production. It exists solely so the F4 conformance matrix (#1425) can mint adversarial shapes (rogue-azp, multi-audience) and prove receivers reject them; no service allowlists it in AUTHORIZED_EXCHANGER_AZPS. An operator replicating the realm shape provisions ONLY the two real exchangers above.

Chained exchange (hop-2) works: an exchanged token whose aud includes canopy-eligibility-exchanger can itself be the subject of a second exchange (the orchestrator fan-out). Proven in the devstack on R1 — see the #1423 hop-2 note. Wire mechanics (#1430, verified live on KC 26.5): the hop-1 mint must send two audience params (canopy-eligibility + canopy-eligibility-exchanger) alongside both aud-* scopes — a single audience param down-filters the exchanger entry away and the resulting token cannot hop; omitting the param yields the pair too, but the explicit two-param form is what the broker sends (deterministic against future granted-scope drift). Receivers accept the pair only via ReceiverContract::with_hop2_exchanger (canopy-eligibility only). Chained-lifespan requirement (#1563, verified live on KC 26.5): KC V2 mints the chained output with a FRESH client lifespan, never capped to the subject’s remaining life — so the F3 broker’s exp ≤ subject.exp bound trips (lifetime_exceeds_cap) the moment the chain takes >0s at equal lifespans. Sizing rule: hop2_lifespan ≤ hop1_lifespan − worst-case hop1-mint→hop2-exchange gap. The devstack realm mints canopy-eligibility-exchanger tokens at 240s vs the 300s hop-1 lifespan (60s margin — the real gap is bounded by the web dispatch window, seconds); cargo xtask identity render emits the same 300/240 split, and any production realm replicating the hop-2 topology must preserve the inequality.

Realm builtin scopes must stay explicit: adding a top-level clientScopes section suppresses Keycloak’s auto-creation of the builtin default scopes, so roles/basic/profile/email/ web-origins/acr are defined explicitly and named in defaultDefaultClientScopes; without this, realm_access.roles vanishes from every token fleet-wide. Exchanger clients declare defaultClientScopes explicitly (they don’t inherit the realm defaults once they declare optionalClientScopes) — and their list is the MINIMAL ["roles", "basic", "web-origins", "acr"], deliberately without profile/email (#1424): those two land in the exchanged token’s scope claim, which the F3 broker’s granted-scope ⊆ requested rule refuses, and a per-target user-context token has no business carrying name/email claims anyway. An IdP whose exchanger client adds any scope-string-visible default breaks every exchange loudly with scope_exceeds_requested — trim the client, don’t widen the request.

Every exchange audits (#1424, OIDC A1): the broker’s production ChainAuditSink posts each outcome — grants fail-closed (audit-commit-before-release), denials best-effort — as an auth.token_exchange event to canopy-security’s ingest under the exchanging service’s own ADR-019 identity. The exchanging services therefore need CANOPY_<SVC>OIDC_EXCHANGER_CLIENT_ID
OIDC_EXCHANGER_CLIENT_SECRET (half-configured pairs are a boot error) and a reachable canopy-security URL; without the exchanger credentials the exchange path stays inert.

Per-target acquisition: the portal holds one token source per backend target, each minting with the aud-canopy-<target> scope — the realm’s optional client scope stamps exactly that audience, so a stolen applications-scoped token is a 401 at every other service.

Operation scopes (P2, #1441): each source additionally mints its target’s portal:* operation scopes (12 mapperless optional client scopes with include.in.token.scope = true, so the granted names land in the scope claim). Receivers enforce them per route family — and refuse the portal credential outright on every route outside its classified surface (403 portal_on_non_portal_route), so inside an allowed target the token is good for exactly its classified operations and nothing else.

No broad audience: the canopy-portal client carries NO canopy-internal-service audience mapper (the CONTRACT shape). A scope-less mint by this client yields a token no receiver accepts.

Short exp: access.token.lifespan = 600 on the client (the ADR-043 A1 short-exp dimension; comfortably above the token source’s 300s refresh lead).

Exact self-validation: each source revalidates (ADR-037) against its OWN target audience — the process-wide canopy-internal-service validation pin is gone.

crates/canopy-auth/src/discovery.rs — OidcDiscovery::fetch + per-issuer-URL cache (300s default TTL; honours Cache-Control: max-age).

crates/canopy-auth/src/jwks.rs::JwksProvider::from_discovery — JWKS provider constructor that uses discovery.jwks_uri directly.

crates/canopy-api/src/bootstrap.rs — every service’s startup path fetches discovery before binding the auth middleware.

services/canopy-web/src/auth.rs::OidcConfig::from_web_config — fetches both external and internal discovery docs at startup.

oidc-pluggability-refactor.adoc — the plan that landed this design (#422).