​
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:
  1. Client sends Authorization: Bearer <token>.
  2. The LLM Gateway attempts validation against all configured OIDC providers.
  3. On success, TrueFoundry RBAC evaluates and authorizes the request. [user needs to link OIDC groups to Truefoundry teams to work as intended]
  4. Authorized requests are forwarded to the model provider (e.g., OpenAI), and the response is returned.
  5. If no provider validates the token, the gateway returns 401 Unauthorized.
This design keeps authentication external (your IdP) while authorization remains internal (via TrueFoundry RBAC).

​
How to configure OIDC

1

Add configuration to your control plane values.yaml

To enable OIDC, add the following to your control plane values.yaml:
oidc:
  enabled: true
  configs:
  - id: keycloak-config
    jwt_public_key_urls:
    - https://keycloak.example.com/auth/realms/dev/protocol/openid-connect/certs
    - https://keycloak.example.com/auth/realms/staging/protocol/openid-connect/certs
    claim_mapping:
      user_email: email
  - id: google-config
    jwt_public_key_urls:
    - https://www.googleapis.com/oauth2/v3/certs
    claim_mapping:
      user_email: email
You can also mount a config_map and add it to the environment variable 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:
  1. Go to Platform -> Settings -> Teams and click Add Team.
  2. Add the team name and the OIDC groups to map to the team.
Once configured, users in those OIDC groups will be authorized per team policies.
Please read below for exact fields and their descriptions.

​
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 in oidc.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.