This is a TrueFoundry High-tier Enterprise plan feature.
Prerequisites
Before deploying the control plane with external OAuth/SAML:
- Ensure you have an OIDC or SAML-compliant identity provider configured
- Obtain the necessary credentials (Client ID, Client Secret, Issuer URL, etc.)
- Contact TrueFoundry team to obtain the
INTERNAL_JWT_JWKS value required for secure token signing
- Verify network connectivity between your identity provider, user browsers, control plane, and AI Gateway servers
You need to add your OIDC application details under servicefoundryServer.env in the values.yaml file of truefoundry helm installation.servicefoundryServer:
env:
OAUTH_PROVIDER_TYPE: "EXTERNAL"
EXTERNAL_OAUTH_ISSUER: "<OIDC_ISSUER_URL>"
EXTERNAL_OAUTH_CLIENT_ID: "<OIDC_CLIENT_ID>"
EXTERNAL_OAUTH_CLIENT_SECRET: "<OIDC_CLIENT_SECRET>"
INCLUDE_TRUEFOUNDRY_MANAGED_JWKS: "false"
INTERNAL_JWT_SERVICE_ENABLED: "true"
INTERNAL_JWT_JWKS: "<INTERNAL_JWT_JWKS>" # Contact TrueFoundry support to obtain this value - required for secure token signing
tfy-llm-gateway:
env:
ENABLE_EXTERNAL_OAUTH: "true"
Store sensitive values like EXTERNAL_OAUTH_CLIENT_SECRET and
INTERNAL_JWT_JWKS securely using Kubernetes secrets rather than plain text
in values.yaml. Consider using a secrets management solution like HashiCorp
Vault or sealed-secrets.
Optional Configuration Fields
Use these fields only if your identity provider returns user information with non-standard claim names:servicefoundryServer:
env:
## Optional: Customize if your IdP uses non-standard claim names
# USE_ID_TOKEN_AS_ACCESS_TOKEN: boolean (default: false) - Set to true if your IdP doesn't provide separate access tokens
# EXTERNAL_OAUTH_USER_INFO_EMAIL_KEY_NAME: string (default: "email") - Customize if email is not in the "email" field
# EXTERNAL_OAUTH_USER_INFO_ID_KEY_NAME: string (default: "id")
# EXTERNAL_OAUTH_USER_INFO_NAME_KEY_NAME: string (default: "name")
# EXTERNAL_OAUTH_USER_INFO_FIRST_NAME_KEY_NAME: string (default: "firstName")
# EXTERNAL_OAUTH_USER_INFO_LAST_NAME_KEY_NAME: string (default: "lastName")
# EXTERNAL_OAUTH_USER_INFO_IMAGE_URI_KEY_NAME: string (default: "picture")
# EXTERNAL_OAUTH_TOKEN_EMAIL_CLAIM_KEY_NAME: string (default: "email")
# EXTERNAL_OAUTH_TOKEN_USERNAME_CLAIM_KEY_NAME: string (default: "username")
# EXTERNAL_OAUTH_TOKEN_ID_CLAIM_KEY_NAME: string (default: "sub") - Customize if user ID is not in the "sub" claim
# EXTERNAL_OAUTH_USER_INFO_USERNAME_KEY_NAME: string (default: "username")
userId instead of sub, set:EXTERNAL_OAUTH_TOKEN_ID_CLAIM_KEY_NAME: "userId"
Here we are assuming the identity provider is OIDC compliant and satisfies the following:
- OpenID configuration is available at
<ISSUER_URL>/.well-known/openid-configuration.
- Scopes configured should include
openid, email, profile and offline_access.
- Allowed Redirect URI should be set to
<CONTROL_PLANE_URL>/auth/callback.
- OIDC issuer servers must be accessible (network connectivity with no firewall blocks) from user’s browser, TrueFoundry control plane servers, and all multi-zone AI Gateway servers.
You need to add your SAML application details under servicefoundryServer.env in the values.yaml file of truefoundry helm installation.servicefoundryServer:
env:
OAUTH_PROVIDER_TYPE: "EXTERNAL_SAML"
EXTERNAL_SAML_IDP_ENDPOINT: "<SAML IDP URL>" # (eg: https://example.idp.com/app/my-app/sso/saml)
EXTERNAL_SAML_CERTIFICATE: "<Base64 encoded X.509 Certificate>"
INCLUDE_TRUEFOUNDRY_MANAGED_JWKS: "false"
INTERNAL_JWT_SERVICE_ENABLED: "true"
INTERNAL_JWT_JWKS: "<INTERNAL_JWT_JWKS>" # Contact TrueFoundry support to obtain this value - required for secure token signing
tfy-llm-gateway:
env:
ENABLE_EXTERNAL_OAUTH: "true"
Store sensitive values like EXTERNAL_SAML_CERTIFICATE and
INTERNAL_JWT_JWKS securely using Kubernetes secrets rather than plain text
in values.yaml. Consider using a secrets management solution like HashiCorp
Vault or sealed-secrets.
Optional Configuration Fields
Use these fields to customize SAML claim mappings or enable SCIM provisioning:servicefoundryServer:
env:
## Optional: Customize SAML claim mappings if your IdP uses non-standard attributes
# EXTERNAL_SAML_EMAIL_CLAIM: string (default: "email") - Customize if email is not in the "email" attribute
# EXTERNAL_SAML_UNIQUE_ID_CLAIM: string (default: "sub") - Customize if user ID is not in the "sub" attribute
# EXTERNAL_SAML_LOGOUT_ENDPOINT: string (optional) - Single Logout URL for your IdP
# EXTERNAL_SAML_ACCESS_TOKEN_EXPIRY_SECONDS: string (default: "3600")
# EXTERNAL_SAML_GROUPS_CLAIM: string (default: not set) - Attribute name for group memberships
# EXTERNAL_SAML_ROLE_MAPPING_TENANT_ADMIN_GROUPS: string (default: not set) - Comma-separated list of groups for tenant admin role
# EXTERNAL_SAML_NAME_ID_FORMAT: string (default: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
## Enable SCIM for automatic user and team provisioning using groups
# SCIM_ENABLED: bool (default: false)
memberOf and you want to map the “Admins” group to tenant admin role:EXTERNAL_SAML_GROUPS_CLAIM: "memberOf"
EXTERNAL_SAML_ROLE_MAPPING_TENANT_ADMIN_GROUPS: "Admins"
Here we are assuming the identity provider is SAML compliant and satisfies the following:
- Single Sign On URL/ACS URL is set as
<CONTROL_PLANE_URL>/api/svc/v1/saml/acs.
- Default Relay State is set as
<CONTROL_PLANE_URL>.
- If SCIM is enabled, you can find the SCIM endpoint and bearer token in the TrueFoundry UI under
Settings > SSO after the initial deployment completes.
