Overview
TrueFoundry’s AI Gateway already works with TrueFoundry Auth, where users authenticate using Personal Access Tokens (PATs) or Virtual Access Tokens (VATs) to call APIs. If your organization relies on an OpenID Connect (OIDC) identity provider (e.g., Keycloak, Auth0, Okta, Google), you can integrate it directly with the gateway. Users can continue using the JWTs issued by your IdP, removing the need to create and manage separate TrueFoundry tokens.What is OIDC?
OIDC (OpenID Connect) is an authentication layer built on OAuth 2.0. When a user authenticates, your IdP issues a signed JWT. The LLM Gateway verifies this token using the IdP’s public keys (JWKS) and maps claims (such as user email or client ID) to user identities in TrueFoundry. Supporting Multiple OIDC Providers In many enterprises, you may have multiple IdPs or realms—for example, separate Keycloak realms per team, or distinct setups for internal and external users. TrueFoundry supports configuring multiple OIDC providers concurrently. For each request, the LLM Gateway attempts validation against all configured providers and accepts the first successful result. This enables federation across trust boundaries without requiring changes in client applications.Architecture of OIDC
The per-request flow is:- Client sends Authorization: Bearer <token>.
- The LLM Gateway attempts validation against all configured OIDC providers.
- On success, TrueFoundry RBAC evaluates and authorizes the request. [user needs to link OIDC groups to Truefoundry teams to work as intended]
- Authorized requests are forwarded to the model provider (e.g., OpenAI), and the response is returned.
- If no provider validates the token, the gateway returns 401 Unauthorized.
How to configure OIDC
1
Add configuration to your control plane values.yaml
To enable OIDC, add the following to your control plane You can also mount a config_map and add it to the environment variable
values.yaml
:env.OIDC_CONFIG_FILE_PATH
. Check the reference below.Either set
env.OIDC_CONFIG_FILE_PATH
or oidc.configs
(not both).2
Configure Truefoundry Teams and OIDC Groups
Map your OIDC groups to teams so RBAC works as intended:
- Go to Platform -> Settings -> Teams and click Add Team.
- Add the team name and the OIDC groups to map to the team.
Required Fields
oidc.enabled
(boolean)
- Turns on OIDC authentication
-
Must be set to
true
to activate -
env.OIDC_CONFIG_FILE_PATH
(string): Filesystem path to the OIDC config inside the container; set to/etc/oidc/config.json
.
oidc.configs
(array)
- Array of OIDC provider configurations
Either one of
env.OIDC_CONFIG_FILE_PATH
or oidc.configs
must be set, but not both.OIDC Provider Configuration
Each entry inoidc.configs
must include:
id
(string, required)
- Unique identifier for the OIDC configuration
- Used for logging and debugging
jwt_public_key_urls
(array of strings, required)
- List of JWKS URLs (JSON Web Key Set) from your IdP
- Used to validate JWT signatures
- Use multiple URLs if they share the same claim mapping; otherwise, create separate configs
- This corresponds to the OpenID provider public keys endpoint
- Typically
{openid-provider-base-url}/.well-known/openid-configuration/jwks
. For Keycloak:{keycloak_base_url}/realms/{your-realm}/protocol/openid-connect/certs
claim_mapping
(object, required)
user_email
(string, required): Claim containing the user’s email. Must map to an existing TrueFoundry user.