# IdP federation

Federating an identity provider (IdP) lets your organization's end users invoke Catalyst agents under their **own** identity. Catalyst trusts tokens issued by the providers you federate, verifies them, and propagates the resulting user identity to agents and downstream tools. This is the operator-side setup behind [enterprise identity for agents](https://docs.diagrid.io/develop/agents/enterprise-identity); for the trust model, see [Identities](https://docs.diagrid.io/concepts/identities) and [Security](https://docs.diagrid.io/concepts/security).

- [Per-org federation](#configure-a-federation) — Configure Auth0, Entra ID, Okta, Google Workspace, or generic OIDC providers once at the organization level.
- [Uniform delivery](#scoping) — Every region your org uses trusts the exact same set of federations — there is no per-region subset at this point in time.

## Scoping: per-org, delivered to every region

Federation in Catalyst is **scoped per organization and delivered uniformly to every region**. Understand this before you configure a federation.

Each federation lives under your organization. Catalyst delivers your org's federations to **every region that serves any of your org's projects**, so you configure a federation once and never per region. This makes the **trust set** uniform — the same providers are validated in every region your org runs in, with no per-region setup.

This is about trust, not routing. It does **not** enable cross-region or cross-organization invocation: a user invokes agents within the project — and the region — those agents belong to. Uniform trust simply means a token from a federated provider is validated the same way wherever your org's projects run.

### Two sources of trust

A region's trust set is the **union** of two sources:

- **The Diagrid identity provider (the SaaS default).** Every region trusts Diagrid's managed identity provider out of the box. This is what backs `diagrid login` on the SaaS path and requires no configuration.
- **Federations you configure.** Each federation you create at the org level is delivered to every region serving your org and added to that region's trust set.

A region validates an incoming token against the union of both sources, keyed by the token's issuer (`iss`) claim.

### No cross-org visibility

Federations never cross organization boundaries. Two organizations using the same region get different trust sets — each region holds only the federations of the orgs whose projects it serves, plus the shared Diagrid identity provider default.

:::warning Per-region subsetting is not supported at this time

You **cannot** restrict a federation to a subset of your regions — for example, "trust our Okta only for our US customers." Every federation you configure applies to **every** region your org uses, uniformly.

If your organization needs per-region scoping, raise it with your Diagrid contact.

:::

## What you can configure

- **Multiple upstream IdPs** at the organization level — Auth0, Entra ID, Okta, Google Workspace, or any generic OIDC provider, in any combination.
- **Routing by issuer.** Catalyst selects the federation to validate a token by its `iss` claim, so multiple providers coexist without ambiguity.

## Supported identity providers

| Provider | Notes |
|---|---|
| Diagrid | SaaS default, trusted in every region with no configuration. |
| Auth0 | Your own Auth0 tenant. |
| Microsoft Entra ID | |
| Okta | |
| Google Workspace | |
| Generic OIDC | Any standards-compliant OIDC provider. |

## Claim mappings

Each federation tells Catalyst which claims on the provider's token carry the user's identity, so identities from different providers normalize onto one model. The **subject** and **scopes** are the identity your agents receive on the [`VerifiedUser`](https://docs.diagrid.io/develop/agents/enterprise-identity/oauth-helper#what-verifieduser-gives-you); if you omit either mapping, Catalyst reads the standard claim name (`sub` and `scope`).

| Mapping | What it identifies | Typical source claim |
|---|---|---|
| Subject | The individual user | `sub` |
| Scopes | The permissions granted to the token | `scope` / `scp` |

For providers that carry them under non-standard names, you can also map a **tenant** claim (`tid` on Entra, `org_id` on Auth0, `hd` on Google Workspace) and a **groups** claim (`groups`).

## Configure a federation

Federations are managed through the **Control Plane API**, which exposes org-scoped IdP federation resources with full CRUD plus a discovery check:

| Operation | Method and path |
|---|---|
| Create a federation | `POST /idp-federations` |
| List federations | `GET /idp-federations` |
| Get a federation | `GET /idp-federations/{idpFederationId}` |
| Update a federation | `PATCH /idp-federations/{idpFederationId}` |
| Delete a federation | `DELETE /idp-federations/{idpFederationId}` |
| Run a trust test | `GET /idp-federations/{idpFederationId}/discovery` |

See the [Control Plane API reference](https://docs.diagrid.io/api/control-plane/catalyst) for request and response schemas.

:::info Console and CLI support are not yet available

A console experience under the organization's identity settings and a `diagrid` CLI command group are both planned. Neither has shipped — the [Diagrid CLI reference](https://docs.diagrid.io/references/catalyst/catalyst-cli-intro) has no federation commands today. Use the Control Plane API until they land.

:::

### Validate trust

After configuring a federation, call the `discovery` endpoint to confirm Catalyst can reach the provider and validate its tokens. The test checks that the provider's discovery document is reachable and its signing keys resolve — enough to catch typos and connectivity issues before a user's first login fails.

## Next steps

- [Enterprise identity for agents](https://docs.diagrid.io/develop/agents/enterprise-identity) — the developer-side story this federation enables.
- [Custom identity provider tokens](https://docs.diagrid.io/develop/agents/enterprise-identity/custom-idp-tokens) — how users pass a token from a federated provider today.