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; for the trust model, see Identities and Security.
🌐Per-org federation
Configure Auth0, Entra ID, Okta, Google Workspace, or generic OIDC providers once at the organization level.
Configure a federation →🗺️Uniform delivery
Every region your org uses trusts the exact same set of federations — there is no per-region subset at this point in time.
Understand scoping →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 loginon 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.
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
issclaim, 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; 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 for request and response schemas.
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 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 — the developer-side story this federation enables.
- Custom identity provider tokens — how users pass a token from a federated provider today.
