# ToolHost — Enterprise SSO / Identity Federation (E-IDP-1)

*Anchor: project-docs/03-engineering-design/01-identity-auth.md §6.3, §8 (L4 row); §5 of
00-FINAL-GOAL.md licenses no SSO claim — this artifact is a design-and-mechanism statement, not a
governance guarantee.*

## Status: design-locked, live verification pending a customer IdP tenant

The ID-JAG federation seam is locked in the corpus (03/01 §6.3, "L4" row of §8). It is **not yet
verified against a real enterprise identity provider** — the `jwt-bearer` grant on `/token`
honestly returns `unsupported_grant_type` until a customer's IdP tenant exercises it. E-IDP-1 is
blocked on exactly that; a prospective enterprise customer's own evaluation is the unblocking
event, not a claim we make in advance of it.

## The mechanism, when enabled

```
employee → Okta/Entra/Keycloak SSO → ID-JAG assertion
  → POST /token (grant_type=jwt-bearer, assertion)
  → verify assertion against the IdP's JWKS (cached, SSRF-safe fetch)
  → aud must be the gateway's authorization-server facade
  → map claims: idp sub → principal (create-on-first-login per org policy),
    idp groups → teams via declarative idp_mappings (exact-string match, no glob/regex in v1)
  → mint a standard gateway token → the resource server verifies it exactly as any other token
```

The property this diagram exists to prove: **humans authenticate at the customer's IdP; the
authorization-server facade remains the sole mint for agent tokens; the IdP never mints gateway
tokens** (NG-6, locked). The resource server is unchanged by federation — there is no second
verification path to audit.

## Group → team mapping

Mapping is exact-match on `(org, idp_issuer, idp_group)`, config-declared, fail-closed: an
unmatched group contributes no membership (and the unmatched-group count is itself evidenced on
the login record — drift is visible, not silent). Conflicting mappings resolve by priority, then
by least-privileged-role-wins. Mapping mode is `additive` by default (union with manually granted
roles); `authoritative` mode — IdP-sourced memberships replace manually granted ones on each
login — is available per-org as the dedicated enterprise-SSO posture.

## What we are not claiming today

- Not "SSO is live" — it is designed, locked, and unverified against a real IdP.
- Not a claim that our federation seam has been battle-tested at a customer; it has not.
- The console-side Settings screen for configuring an IdP (metadata upload, mapping table,
  test-login) is scoped but not yet built — it is a deferred, backlog-tracked screen, not
  vaporware; the wire seam it will drive is what's described above.

If your evaluation includes a real IdP tenant, that evaluation is the verification event this
artifact is waiting on.