Skip to main content
External Identity allows you to bring your own Auth. It authenticate and authorize external, third-party identity providers (Okta, Azure AD) to securely access a TrueFoundry’s APIs (e.g., AI Gateway, MCP Gateway) instead of using TrueFoundry’s built-in authentication. Users/Applications authenticate with corporate credentials without TrueFoundry user accounts.

​
Overview

External Identity enables you to:
  • Authenticate using existing identity provider (Okta, Azure AD)
  • Control RBAC access to TrueFoundry resources (e.g., Models, MCP Servers, Agents, etc.)
  • No need to create TrueFoundry user accounts
External Identity requires an identity provider to be configured.

​
When to Use External Identity

Organizations with existing identity providers (Okta, Azure AD) can use External Identity. Common scenarios:
  • B2B applications: Your customers authenticate through their own Identity Provider (IdP)
  • No TrueFoundry accounts: Users who aren’t in TrueFoundry need Model, MCP, Agent access

​
How External Identity Works

  1. User/application authenticate and get a JWT token from the identity provider.
  2. User/application adds the JWT token as Bearer authorization header in TrueFoundry API’s
  3. TrueFoundry validates the token against the configured identity provider.
  4. TrueFoundry extracts claims from the token and maps it to external identity based on the claims configured.
  5. The selected external identity is used for RBAC when accessing TrueFoundry resources
  6. TrueFoundry uses the sub claim to uniquely identify each user and manage their authentication for MCP Servers for personalization.
TrueFoundry never handles user credentials. Your identity provider remains the source of truth for identity.

​
Prerequisites

Before creating an external identity, you must configure Identity Provider.

​
Creating an Identity Provider

1

Navigate to Identity Provider tab

Navigate to Access > External Auth > Identity Provider.
2

Add a new External Identity Provider

Click on New Identity Provider button on the top right.
3

Fill the form

Configure the identity provider with config for JWT token validation. The form contains following fields:
​
Name
string
required
A unique name to identify this external identity provider. Should follow the format as Alphanumeric characters and hyphens.
The name should be descriptive and help you identify the purpose of this external identity.
​
Config
object
required
Contains JWKS URI that exposed the JWKS for fetching the public key to validate the JWT token.
(Optional) You can also validate the token against the issuer and audience.
​
Advanced Options
You can configure claim keys for unique id and email. Defaults are sub and email respectively.
sub claim is mandatory for the token to be validated. You can change the claim key under Advanced Settings.
(Optional) You can also configure email claim to allow tracking of the user’s requests in traces.
4

Save the configuration

Click Submit to create the external identity provider. You’ll see it listed in the Identities providers tab.

​
Examples

​
Okta

Note <okta-organization> is the organization name of the Okta. 
config:
  jwks_uri: https://<okta-organization>.okta.com/oauth2/v1/keys
  issuer: https://<okta-organization>.okta.com

​
Azure AD

Note <tenant-id> and <client-id> are the tenant ID and client ID of the Azure AD application. 
config:
  jwks_uri: https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys
  issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
  audience: <client-id>

​
Creating an External Identity

1

Navigate to External Identities

Go to Access > External Auth > Idenities.
Navigate to External Auth > Identities
2

Add an external identity

Click the Add External Identity button to open the configuration form.
3

Fill in the form

The form contains the following fields:
​
Name
string
required
A unique name to identify this external identity. Should follow the format as alphanumeric characters and hyphens. Examples: api-service, external-app, partner-integration
The name should be descriptive and help you identify the purpose of this external identity.
​
Identity Provider
string
required
Select the identity provider from the list of configured identity providers.
You can create multiple external identities using the same identity provider. When Truefoundry gets a token from the external identity, it will validate the token against the identity provider and assign it to all the matching external identity.
4

Submit the configuration

Click Submit to create the external identity. You’ll see it listed in the External Identities section.
Best Practice: Create more specific external identities with detailed claims for precise access control, and use general external identities (with fewer or no claims) as fallbacks.

​
Using External Identity as Collaborator

Once created, external identities can be added as collaborators to TrueFoundry resources, granting them access based on the assigned role, similar to how you add users and teams as collaborators.

​
Adding External Identity as Collaborator

1

Navigate to the Resource

Navigate to the resource you want to grant access to (e.g., Model, MCP Server, Workspace, Cluster, etc.)
2

Edit the resource

Edit the resource you want to grant access to
3

Add Collaborator

Click Add Collaborator in the collaborator selection and search for your *External Identity. Choose the appropriate Role (e.g., Viewer, Editor, Manager).
Adding external identity as collaborator showing the selection interface
4

Save the Configuration

Click Submit to save the collaborators in your resource. Your External Identity can now access the selected resource.

​
Troubleshooting

​
External Identity Not Matching

Problem: Token authentication fails or wrong external identity is selected. Solutions:
  • verify the JWKS URI is correct and the JWKS is accessible by TrueFoundry.
  • verify the token issuer and audience in the token are correct if configured.
  • verify the sub claim is present in the token and is correct.
  • verify the identity provider is correct and matches your identity provider configuration name