External SSO (OIDC/SAML)

Deploy the TrueFoundry Control Plane without TrueFoundry Auth Server using any external OIDC or SAML identity providers for authentication.

This is a TrueFoundry High-tier Enterprise plan feature.

By default, the control plane uses the TrueFoundry Auth Server to authenticate users. However, you can deploy the control plane using your own external OIDC or SAML compliant identity provider instead.

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

OIDC

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")
    # AUTH_DEFAULT_OAUTH_SCOPES: string (default: "openid email profile offline_access")

Example: If your Okta setup returns user ID in a field called 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:

1. OpenID configuration is available at <ISSUER_URL>/.well-known/openid-configuration.
2. Scopes configured should include openid, email, profile and offline_access.
3. Allowed Redirect URI should be set to <CONTROL_PLANE_URL>/auth/callback.
4. 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.

SAML

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:

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)

Here we are assuming the identity provider is SAML compliant and satisfies the following:

1. Single Sign On URL/ACS URL is set as <CONTROL_PLANE_URL>/api/svc/v1/saml/acs.
2. Default Relay State is set as <CONTROL_PLANE_URL>.

Logout

By default, logging out of TrueFoundry only clears the local TrueFoundry session — the user stays signed in at your identity provider, so clicking Login again signs them straight back in without a prompt. To also end the session at your IdP (so the next login asks for credentials), configure Single Logout as shown below.

OIDC

With OIDC, TrueFoundry uses RP-Initiated Logout: on logout it clears the local session and redirects the user’s browser to your IdP’s logout endpoint (end_session_endpoint) to end the IdP session too.

Step 1 — (Recommended) enable ID-token-based logout

servicefoundryServer:
  env:
    USE_ID_TOKEN_AS_ACCESS_TOKEN: "true"

This lets TrueFoundry send the ID token to your IdP as id_token_hint, which is the most reliable way to identify and end the exact session. If it is not set, TrueFoundry falls back to sending client_id (still works, but less precise).

Step 2 — Register the post-logout redirect URI in your IdP

In your IdP application settings, add <CONTROL_PLANE_URL> as an allowed Sign-out redirect URI (also called post-logout redirect URI).

Your IdP will reject logout with an HTTP 400 error if this URI is not registered. It must exactly match <CONTROL_PLANE_URL>.

TrueFoundry automatically discovers the logout endpoint from your IdP’s <ISSUER_URL>/.well-known/openid-configuration (the end_session_endpoint field) — no extra environment variable is needed. If your IdP does not expose an end_session_endpoint, logout will clear only the local TrueFoundry session.

SAML

With SAML, TrueFoundry uses Single Logout (SLO): on logout it clears the local session, builds a signed <LogoutRequest> (containing the user’s NameID and SessionIndex captured at login), and redirects the browser to your IdP’s SLO endpoint. The IdP ends its session and redirects back to TrueFoundry.

Step 1 — Generate an SP signing key pair

The <LogoutRequest> must be signed, so you need a key pair. Run this once:

openssl req -x509 -newkey rsa:2048 -keyout sp-private-key.pem -out sp-certificate.pem -days 3650 -nodes -subj "/CN=truefoundry-saml-sp"

This produces two files:

• sp-private-key.pem — the private key TrueFoundry signs with (keep secret).
• sp-certificate.pem — the matching public certificate you upload to your IdP.

Step 2 — Add the logout environment variables

servicefoundryServer:
  env:
    EXTERNAL_SAML_LOGOUT_ENDPOINT: "<SAML IdP Single Logout URL>" # (eg: https://example.idp.com/app/my-app/slo/saml)
    EXTERNAL_SAML_SP_PRIVATE_KEY: "<Base64 encoded contents of sp-private-key.pem>"

Base64-encode the private key with:

base64 -w 0 sp-private-key.pem   # Linux
base64 -i sp-private-key.pem     # macOS

Step 3 — Configure your IdP application

• Single Logout URL (SLS): set it to <CONTROL_PLANE_URL>/api/svc/v1/saml/slo
• Signature Certificate: upload sp-certificate.pem (it must be the public pair of EXTERNAL_SAML_SP_PRIVATE_KEY).
• SP Entity ID / Audience URI: set it to <CONTROL_PLANE_URL> (it must match TrueFoundry’s issuer).

Store EXTERNAL_SAML_SP_PRIVATE_KEY securely using Kubernetes secrets rather than plain text in values.yaml.

Two common mistakes cause the IdP to reject logout:

• The uploaded certificate is not the public pair of EXTERNAL_SAML_SP_PRIVATE_KEY → error “Invalid Signature”.
• The SP Entity ID / Audience URI in the IdP does not match <CONTROL_PLANE_URL> → error “Issuer does not match”.

If EXTERNAL_SAML_LOGOUT_ENDPOINT or EXTERNAL_SAML_SP_PRIVATE_KEY is not set, logout will clear only the local TrueFoundry session (the IdP session is left intact).

SCIM Provisioning

You can now enable SCIM provisioning by adding following env:

servicefoundryServer:
  env:
    SCIM_ENABLED: bool (default: false)

Once SCIM is enabled, you can find the SCIM endpoint and bearer token in the TrueFoundry UI under Settings > Provisioning after the initial deployment completes.