feat(oauth2): tenant-aware IdP-initiated restart (context + cross-host)

[pinetops]

Draft. Rebased directly onto upstream/main (2026-09-01) — the mechanism this builds on (idp_initiated_login?'s request-phase restart) landed as #1205, the merged form of what team-alembic#1184 (closed without merging) proposed. Also picks up team-alembic#1205's not state_param?(conn) fail-closed hardening, added upstream after this branch's commits were originally written — preserved and combined with the context/cross-host mechanism below. Full suite green (771 tests), format/credo clean. Design proposal; the open questions below are genuine.

The problem

idp_initiated_login? (from team-alembic#1184) restarts the request phase from a stateless callback to mint a verifiable state (OIDC Core §4). Enough for a single-tenant provider. A multi-tenant one needs to know which tenant to restart for — and on an IdP-initiated launch the tenant is only knowable from the launch itself (the profile behind the code), which the plain restart never reads. So the restart can't route, and lands on a generic picker/login screen.

Two flavours of this, depending on where the tenant lives:

1. Same host, per-tenant config — one host, but authorize_url/redirect_uri vary by tenant.
2. Per-tenant host — each tenant on its own host/subdomain. Here the restart must run on that host: the CSRF state is stored by the host that will receive the callback (host-scoped cookies), so restarting on the wrong host loses it. (This is the Ed.link district-SSO case: a global Clever launch on the bare host must end up authenticating on the district's subdomain.)

Both are solvable today only with a bespoke app plug that session-lessly pre-exchanges the code, resolves the tenant, and redirects. Every consumer reinvents it. It should be the strategy's job.

The change (five commits)

1. Surface the launch profile to context (4ce8025)
On the restart, read-only and best-effort, exchange the launch's code, fetch the profile, and put it in the secret-resolution context as :idp_initiated_user_info — the same map your register/sign_in action already receives. A tenant-aware secret reads it:

def secret_for([_, _, _, :authorize_url], _resource, _opts, context) do
  case context do
    %{idp_initiated_user_info: %{"id" => id}} -> {:ok, tenant_authorize_url(id)}
    _ -> {:ok, @default_authorize_url}
  end
end

2. Route the restart to a resolved host (23fec10)
New optional idp_initiated_request_url secret. When present, the plug resolves the tenant's request-phase URL from the launch context and redirects the browser there instead of restarting inline — so the target host runs the request phase and stores state where the callback will read it. Absent → inline restart (unchanged).

3. Gate the pre-exchange behind opt-in (de0a523)
The pre-exchange now only runs when resolve_idp_initiated_launch? is truthy — a wasted round-trip on providers that never configure a tenant-aware secret is avoided by default.

4. Allow a conn-aware gate (3b79191)
resolve_idp_initiated_launch? can also be a Secret module, resolved with %{conn: conn} before the exchange — e.g. "only pre-exchange when the request's host carries no tenant." A plain boolean still works unchanged; idp_initiated_request_url still implies the gate.

5. Docs wording (067e35b)

Properties

• Read-only. The pre-exchange mints no session/token/user; the only thing derived from the untrusted code is where to restart. The real, state-verified auth is unchanged.
• Fail-open. Any failure (spent code, provider error, unresolvable launch) → plain inline restart. Single-tenant and existing behaviour untouched — full OAuth2/OIDC suite green, plus new tests for the cross-host handoff and the fall-throughs.
• Single-use-code safe. The restart triggers a fresh authorize → fresh code.
• Context needs a module secret. Only a Secret module (secret_for/4) receives context; an inline function secret is called with just (name, resource). Documented on AshAuthentication.Secret.

Open questions for the maintainer

1. Gating the pre-exchange. Resolved (see de0a523/3b79191): opt-in via resolve_idp_initiated_launch?, which can also be a conn-aware Secret module (e.g. "only pre-exchange when the host carries no tenant") — not just a plain boolean. idp_initiated_request_url still implies the gate.
2. Two knobs or one? :idp_initiated_user_info in context (same-host) and idp_initiated_request_url (cross-host) are separate mechanisms. Is that the right split, or should cross-host also be expressed through the existing secrets?
3. Context key names — :idp_initiated_user_info, idp_initiated_request_url.
4. How much of the launch to expose — profile only today; tokens / raw params too?
5. Public config_for. The pre-exchange reuses the plug's private config_for/2; making it public would let apps share one config builder.

Downstream payoff

The Ed.link district-SSO stack collapses: the consuming app deletes its entire bespoke IdP-subdomain plug (bare-host detection, session-less exchange, redirect, router wiring). It configures idp_initiated_request_url as a Secret module that maps the launch's person id → the district's subdomain request URL — the app keeps only that genuinely app-specific mapping, and the framework owns the mechanism (including the host-scoped state correctness that a naive app plug can get wrong).

🤖 Generated with Claude Code