Skip to main content
External Identity allows you to authenticate and authorize external users or systems to access TrueFoundry resources without requiring them to be registered as platform users. This feature is particularly useful for integrating with external systems, APIs, or services that need programmatic access to TrueFoundry resources.

​
Overview

External Identity enables you to:
  • Authenticate external systems using OIDC tokens from your Identity Provider (IdP)
  • Grant access to specific resources without creating user accounts
  • Use claim-based matching to automatically select the appropriate external identity
  • Manage access control by adding external identities as collaborators to resources
External Identity requires an OIDC SSO integration to be configured first. The SSO integration must have login enabled as false, meaning it won’t be used for user login but only for external identity authentication.

​
How External Identity Works

When an external system authenticates with TrueFoundry using an OIDC token:
  1. TrueFoundry validates the token against the configured SSO integration
  2. The system extracts claims from the token
  3. If multiple external identities share the same SSO FQN, TrueFoundry selects the one with the most matching claims
  4. The selected external identity is used for authorization checks when accessing resources
The claim matching algorithm prioritizes external identities with the highest number of matching claims. This allows you to create more specific external identities that take precedence over general ones.

​
Prerequisites

Before creating an external identity, you must:
  1. Configure an OIDC SSO Integration: Navigate to Settings > SSO and create a new SSO configuration, you can refer to SSO Overview on how to configure SSO in TrueFoundry.
  2. Disable Login: Ensure the SSO integration has login enabled as false (this prevents it from being used for user authentication)
  3. Note the SSO FQN: The SSO FQN is the name you assigned to your SSO configuration
The SSO integration used for external identity should not be used for user login. Keep login disabled to maintain security boundaries.

​
Creating an External Identity

​
Step 1: Navigate to External Identities

Go to Access > External Identities.
Navigate to External Identities

Navigate to External Identities

​
Step 2: Add External Identity

Click the Add External Identity button to open the configuration form.
Add External Identity form showing Name, SSO FQN, and Claims fields

Add External Identity Form

​
Step 3: Fill in the Form

Add External Identity form showing Name, SSO FQN, and Claims fields

Add External Identity Form

The form contains the following fields:

​
Name (Required)

  • Description: A unique name to identify this external identity
  • Format: Alphanumeric characters and hyphens
  • Example: api-service, external-app, partner-integration
The name should be descriptive and help you identify the purpose of this external identity.

​
SSO FQN (Required)

  • Description: The Fully Qualified Name (FQN) of the SSO configuration to use for authentication
  • Format: This is the name you assigned when creating the SSO integration
  • How to find: Go to Platform > Settings > SSO and check the name of your OIDC SSO configuration
The SSO FQN must reference an existing OIDC SSO integration with login disabled. You can create multiple external identities using the same SSO FQN, and TrueFoundry will automatically select the best match based on claims.

​
Claims (Optional)

  • Description: Key-values pairs that define the conditions for this external identity to be selected
  • Format: JSON object with claim names and expected values
  • Purpose: Used to match tokens and select the appropriate external identity when multiple identities share the same SSO FQN
Claims are optional. If you don’t specify claims, the external identity will match any token from the specified SSO FQN. However, if multiple external identities exist with the same SSO FQN, the one with the most matching claims will be selected.

​
Step 4: Save the Configuration

Click Save to create the external identity. You’ll see it listed in the External Identities section.
List of external identities showing available identities

External Identities List

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 you want to grant access to (e.g., Model, MCP Server, Workspace, Cluster, etc.)
  2. Open the Collaborators section
  3. Click Add Collaborator
  4. In the collaborator selection, you’ll see external identities listed under External Identities
Adding external identity as collaborator showing the selection interface

Adding External Identity as Collaborator

  1. Select the external identity from the list
  2. Choose the appropriate Role (e.g., Viewer, Editor, Manager)
  3. Save the changes

​
Editing External Identity

  1. Click on an external identity or use the Edit action
  2. you can only modify the claims for an identity
  3. Save the changes
Changing the SSO FQN or claims may affect which tokens match this identity. Ensure you understand the impact before making changes.

​
Deleting External Identity

  1. Select the external identity you want to delete
  2. Click Delete or use the delete action
  3. Confirm the deletion
Deleting an external identity will remove all access granted to it. Make sure to update resource collaborators before deletion if needed.

​
Troubleshooting

​
External Identity Not Matching

Problem: Token authentication fails or wrong external identity is selected. Solutions:
  • verify the token issuer and audience in the token are correct
  • verify the SSO FQN is correct and matches your SSO configuration name
  • verify the SSO integration has login disabled