IdP federation

Federating an identity provider (IdP) lets your organization's users invoke Catalyst agents under their own identity. Catalyst trusts tokens issued by the providers you federate, verifies them, and passes the user's identity on to agents and downstream tools. This is the operator-side setup behind enterprise identity for agents. For more details on the trust model, see Identities and Security.

🌐Per-org federation

Federate Auth0, Microsoft Entra ID, Google, or any OpenID Connect provider once for your whole organization.

Configure a federation →

🗺️Scope to your regions only

Your self-managed BYOC and Enterprise Server regions all trust the same IdP federations. Catalyst Cloud regions trust only Diagrid's identity provider.

Understand scoping →

Scoping: which regions trust a federation

A federation belongs to your organization, and works in the regions you run yourself: your self-managed BYOC and Enterprise Server regions, once you turn federation on in each one. Catalyst Cloud, Dedicated Cloud and managed BYOC regions don't support it yet. Create a federation once per organization and all your regions trust the same set.

This is about trust, not routing. It does not enable cross-region or cross-organization invocation: a user invokes agents in the project, and the region, that those agents belong to.

Which identity provider a region trusts

• Catalyst Cloud regions trust only Diagrid's identity provider, the one behind diagrid login. Your federations aren't delivered to them, so they reject tokens from your own provider.
• Self-managed BYOC and Enterprise Server regions trust only your organization's federations, not Diagrid's identity provider. A diagrid login token is rejected there, so users send a token from your provider instead. See Custom identity provider tokens.

A region picks the federation that validates a token by the token's issuer (iss) claim.

No cross-org visibility

Federations never cross organization boundaries. A region holds only the federations of the organization that owns it. Two organizations can federate the same issuer, and each gets its own federation.

You can't limit a federation to some of your regions

Every federation applies to all your self-managed BYOC and Enterprise Server regions. You can't, for example, trust your Okta tenant only in your US regions. If you need per-region scoping, raise it with your Diagrid contact.

Supported identity providers

You can federate several providers at once, in any combination. Each issuer can be federated once in an organization.

Type	Provider	Typical issuer
auth0	Auth0. The default when you don't set a type.	https://<tenant>.us.auth0.com/
entra	Microsoft Entra ID	https://login.microsoftonline.com/<tenant-id>/v2.0
google	Google	https://accounts.google.com
oidc	Any other OpenID Connect provider, such as Okta	https://<your-org>.okta.com/oauth2/default

Claim mappings

Claim mappings tell Catalyst which claims on your provider's tokens carry the user's identity, so tokens from different providers look the same to your agents. The subject and scopes are the identity your agent receives on VerifiedUser.

Mapping	CLI flag	Default	Notes
Subject	--claim-subject	sub	The claim that identifies the user. If you map another claim, tokens without it are rejected.
Scopes	--claim-scopes	scope	The claim that carries the granted scopes. Entra and Okta use scp.
Scope format	--scope-format	space_delimited	Set array when the scopes claim is a JSON array, as on Okta.
Tenant	--claim-tenant	None	The claim that identifies the user's tenant, such as tid on Entra or hd on Google. If you map it, tokens without it are rejected.
Attributes	--attribute name=claim	None	Up to 16 other claims to pass on, such as the user's team or groups.

Catalyst copies each attribute, with its original JSON type, onto the token it issues for the user, under the https://diagrid.io/attributes claim. For example, --attribute team=roles on Entra produces {"https://diagrid.io/attributes": {"team": ["platform"]}}. Attribute names start with a letter and contain only letters, digits, _ and -, up to 64 characters.

A token that lacks a mapped attribute is accepted, and the attribute is left out. So when you make an access decision on an attribute, allow a value ("allow when team is platform") rather than deny one ("deny when team is contractor"): a token with no team at all passes a deny rule.

Configure a federation

Manage federations with the diagrid idp CLI commands or the Control Plane API. You need a global Operator or Admin role to create, change or delete a federation. Any role can list and view them.

The Catalyst console lists your federations under Identity and access › Identity providers. The console Diagrid hosts only lists them, so use the CLI or the API to make changes. On Enterprise Server, you can also add, edit and delete federations in the console.

Before you begin

Read two values off a token your provider issues:

• Issuer: the exact value of the token's iss claim, including any trailing slash. Catalyst compares it with each token's iss character for character, so a missing slash rejects every token. It must be an https URL with no user info, query or fragment.
• Audience: the token's aud claim. This is the identifier of the API the token is issued for, not the client ID of the app users sign in to. Google is the exception: a Google ID token's aud is your OAuth client ID.

Your regions must also reach the provider's signing keys over HTTPS. By default, Catalyst finds them through the jwks_uri in the provider's discovery document, <issuer>/.well-known/openid-configuration.

Create a federation

CLI

This federates Microsoft Entra ID, maps Entra's tid and scp claims, and passes the user's app roles on as a team attribute:

diagrid idp create corp-entra \
  --type entra \
  --issuer https://login.microsoftonline.com/<tenant-id>/v2.0 \
  --audience <api-app-client-id> \
  --claim-tenant tid \
  --claim-scopes scp \
  --attribute team=roles

For Okta and other OpenID Connect providers, use --type oidc:

diagrid idp create acme-okta \
  --type oidc \
  --issuer https://acme.okta.com/oauth2/default \
  --audience api://default \
  --claim-scopes scp \
  --scope-format array

Run diagrid idp create with no arguments to be prompted for each value instead. Other optional flags:

• --required-scope: scopes every token must carry, all of them, to be accepted.
• --accept-algorithm: the signing algorithms to accept. Defaults to RS256. Only asymmetric algorithms are allowed: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512 and EdDSA.
• --jwks-uri: where to fetch the signing keys, when the address in the discovery document isn't one your regions can reach. It must be an https URL.

See the diagrid idp create reference for every flag.

API

Send the federation to the Control Plane API with an API key:

curl -X POST "https://api.r1.diagrid.io/apis/cra.diagrid.io/v1beta1/idp-federations" \
  -H "x-diagrid-api-key: ${DIAGRID_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "cra.diagrid.io/v1beta1",
    "kind": "IDPFederation",
    "metadata": { "name": "corp-entra" },
    "spec": {
      "name": "corp-entra",
      "type": "entra",
      "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0",
      "audience": ["<api-app-client-id>"],
      "claimMappings": {
        "tenant": "tid",
        "scopes": "scp",
        "attributes": { "team": "roles" }
      }
    }
  }'

The API answers 202 Accepted and delivers the federation to your regions in the background. The other operations:

Operation	Method and path, under /apis/cra.diagrid.io/v1beta1
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}
Get the discovery URL	GET /idp-federations/{idpFederationId}/discovery

A PATCH takes the whole resource, as a GET returns it, with your changes made. Its metadata.name must match the path.

Check the federation

List your federations, or show one in full:

diagrid idp list
diagrid idp get corp-entra

Then check that Catalyst can use your provider's discovery document. diagrid idp discovery prints the discovery URL that Catalyst derives from the issuer. It doesn't contact the provider, so fetch the document yourself:

curl -s "$(diagrid idp discovery corp-entra)" | jq '{issuer, jwks_uri}'

The issuer in the document must equal the federation's issuer exactly, and your regions must be able to reach the jwks_uri. Finally, invoke an agent with a token from the provider, as shown in Custom identity provider tokens. If Catalyst rejects it, see Troubleshooting.

Change or delete a federation

Change a federation with diagrid idp update, passing only the flags you want to change:

diagrid idp update corp-entra --audience <api-app-client-id>,api://corp-agents

• Flags you leave out keep their value. A list flag, such as --audience, --required-scope, --accept-algorithm or --attribute, replaces the whole list.
• A federation's name can't change.
• A new issuer takes effect straight away: your regions stop accepting tokens from the previous issuer.
• Once set, the JWKS URI, required scopes, accepted algorithms and the subject, tenant and scopes mappings can't be emptied. An update that clears one reports success and keeps the old value. To remove one, delete the federation and create it again. Tokens from that issuer are rejected in between.

Delete a federation with diagrid idp delete. Every region stops accepting tokens from its issuer straight away.

diagrid idp delete corp-entra

Turn on federation in your regions

Federation is off by default in the Catalyst Helm chart. A self-managed BYOC or Enterprise Server region validates federated tokens only when both of these values are true:

• agent.config.internal_dapr.sentry.oidc.idp_federation_enabled
• agent.config.internal_dapr.sentry.oidc.mtls.enabled

Set them together after you create your first federation. helm install and helm upgrade reject one without the other. To have the region fetch your provider's signing keys at startup instead of on the first request, list your issuers, exactly as federated, in agent.config.internal_dapr.sentry.oidc.bootstrap_issuers. See the Helm chart reference.

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.
• diagrid idp CLI reference: every federation command and flag.