Skip to main content

IdP federation

Federating an identity provider (IdP) lets your organization's users invoke Diagrid agents under their own identity. Diagrid 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.

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. Diagrid 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​

  • Diagrid 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.

TypeProviderTypical issuer
auth0Auth0. The default when you don't set a type.https://<tenant>.us.auth0.com/
entraMicrosoft Entra IDhttps://login.microsoftonline.com/<tenant-id>/v2.0
googleGooglehttps://accounts.google.com
oidcAny other OpenID Connect provider, such as Oktahttps://<your-org>.okta.com/oauth2/default

Claim mappings​

Claim mappings tell Diagrid 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.

MappingCLI flagDefaultNotes
Subject--claim-subjectsubThe claim that identifies the user. If you map another claim, tokens without it are rejected.
Scopes--claim-scopesscopeThe claim that carries the granted scopes. Entra and Okta use scp.
Scope format--scope-formatspace_delimitedSet array when the scopes claim is a JSON array, as on Okta.
Tenant--claim-tenantNoneThe 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=claimNoneUp to 16 other claims to pass on, such as the user's team or groups.

Diagrid 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 federated user calls an agentRegion picks the federation by issRegion applies the claim mappingsAgent gets VerifiedUser: sub, scopes1sign intoken (iss, sub, scopes)2invoke agent with token3Diagrid token + attributesUserYour IdPEntra, Okta, …Diagrid regionAgentUserYour IdPEntra, Okta, …Diagrid regionAgent
A federated user calls an agentThe region finds the federation by the token's issuer, maps its claims, and passes the user's identity on in a token it issues. Only self-managed BYOC and Enterprise Server regions trust your federations.

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.

The Diagrid Web 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.

Prerequisites​

  • A global Operator or Admin role, to create, change or delete a federation. Any role can list and view them.
  • An application in your identity provider that issues tokens to your users. For Microsoft Entra ID, see Create an enterprise application in Microsoft Entra ID.
  • The issuer and the audience, read off a token that application issues:
    • Issuer: the exact value of the token's iss claim, including any trailing slash. Diagrid compares it with each token's iss character for character, so a missing slash rejects every token. It must be an https URL.
    • 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.
  • Network access from your regions to the provider's signing keys over HTTPS. By default, Diagrid finds them through the jwks_uri in the provider's discovery document, <issuer>/.well-known/openid-configuration.

Create an enterprise application in Microsoft Entra ID​

Entra needs an application that represents the API your agents sit behind. That application fixes the audience and decides the format of the tokens your users send. Registering one creates both objects you work with, the app registration where you define the API, and the enterprise application, where you assign the users allowed to get a token for it.

Register the application and collect the federation values
  1. In the Microsoft Entra admin center, open App registrations β€Ί New registration. Name it, for example diagrid-agents, leave Supported account types on Accounts in this organizational directory only, and select Register.
  2. On Overview, copy the Directory (tenant) ID and the Application (client) ID.
  3. Open Expose an API, select Add next to Application ID URI, and accept the default, api://<client-id>. This is the value the federation's audience must match.
  4. Still on Expose an API, select Add a scope, name it, for example agents.invoke, set Who can consent as your organization requires, fill in the consent text, and select Add scope. Entra lists the scopes a token is granted in its scp claim.
  5. Open Manifest, set requestedAccessTokenVersion to 2, and save. Left at null or 1, Entra issues v1.0 tokens whose issuer is https://sts.windows.net/<tenant-id>/ which never matches the https://login.microsoftonline.com/<tenant-id>/v2.0 federated issuer, so the regions reject every token.
  6. Register the client application your users sign in with, if it isn't registered already. In its API permissions, select Add a permission β€Ί My APIs, pick the API you registered, choose the scope, and grant admin consent. To skip the consent prompt, add the client under Expose an API β€Ί Add a client application on the API registration.
  7. Optionally, open App roles β€Ί Create app role to define roles such as platform, with Allowed member types set to Users/Groups. Entra puts a user's roles in the roles claim, which you pass on to agents with --attribute team=roles.
  8. Open Enterprise applications, select the same application, then Users and groups β€Ί Add user/group, and assign your users, with an app role if you defined any. To stop anyone else getting a token, set Properties β€Ί Assignment required? to Yes.

This gives you every value the federation needs:

Federation valueWhere it comes fromExample
IssuerThe Directory (tenant) IDhttps://login.microsoftonline.com/<tenant-id>/v2.0
AudienceThe Application ID URI, or the API's client IDapi://<api-app-client-id>
Scopes claimEntra always uses scp--claim-scopes scp
Tenant claimEntra always uses tid--claim-tenant tid
AttributesApp roles arrive in roles--attribute team=roles

Before you create the federation, sign in as a test user, get a token for the scope you exposed, and read its claims. Paste the token into jwt.ms, or decode it locally:

python3 -c 'import base64, json, sys; p = sys.argv[1].split(".")[1]; print(json.dumps(json.loads(base64.urlsafe_b64decode(p + "=" * (-len(p) % 4))), indent=2))' "<token>"

ver must be 2.0, iss must equal the issuer in the table character for character, and aud must be the audience you are about to federate.

Create a federation​

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.

Check the federation​

List your federations, or show one in full:

diagrid idp list
diagrid idp get corp-entra

Then check that Diagrid can use your provider's discovery document. diagrid idp discovery prints the discovery URL that Diagrid 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 Diagrid 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 Diagrid 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​