Skip to main content
TrueFoundry allows your team to enable SSO with your Identity Provider (IdP) by leveraging OpenID Connect (OIDC) or Security Assertion Markup Language (SAML). TrueFoundry SSO integration provides a seamless way to sign in with your own IdPs and also eliminates the need for employees to maintain/enter credentials. TrueFoundry can integrate with the following IdP providers: GSuite, AzureAD, Okta, Keycloak
If you don’t see the name of your IdP provider above, there is a high chance your IdP is also supported as long as it support OpenID Connect (OIDC) or SAML protocol.

​
How does TrueFoundry SSO work?

Truefoundry maintains a centralized Authentication Server that handles the authentication flow to the platform (as described here). The SSO integration of your IDP is done by configuring the Authentication Server to use your IdP as the Identity Provider. This helps us control the licensing and track the number of users accessing the platform. When a user logs into the control plane, the control-plane redirects to login.truefoundry.com, which is the Authentication Server. The Authentication Server then redirects to the IdP’s login page, which then redirects back to the Authentication Server with an authorization code. The Authentication Server then uses this authorization code to fetch user information from the IdP and create a new user in the platform if they don’t exist. The user is then redirected to the control plane with the authentication tokens. The flow of the request is described as follows:
1

Request Login Page

Browser initiates the OAuth flow by requesting the login page from TrueFoundry Control Plane, with the redirect URL being the TrueFoundry Control Plane URL.
Request
GET /api/svc/v1/oauth2/authorize?tenantName={tenant_name}
    &controlPlaneURL=https%3A%2F%2Fyour.example.com
    &redirectURL=https%3A%2F%2Fyour.example.com%2Fauth%2Fcallback
HTTP/1.1 
Host: your.example.com
Response
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 100
Connection: keep-alive
Date: Fri, 27 Jun 2025 07:00:00 GMT
  {
    "authorizationEndpoint":"https://login.truefoundry.com/oauth2/authorize?client_id={application_id}&response_type=code&scope=openid+email+profile+offline_access&redirect_uri=https%3A%2F%2Fyour.example.com%2Fauth%2Fcallback"
  }
2

Send Login Page

Browser redirects to the Login Page URL powered by . The login page provides an interactive form for the user to choose the type of authentication, such as password-based or SSO.
3

Redirect to SSO Identity Provider page

On selecting SSO, the browser is redirected to the SSO Identity Provider’s login page with the redirect URL as the
Request
POST /oauth2/<client_id>/v1/authorize 
HTTP/1.1 
Host: example.sso.com 
Content-Type: application/x-www-form-urlencoded 
Origin: https://login.truefoundry.com 
Body: login_hint=
      &scope=openid+groups+email
      &response_type=code
      &code_challenge_method=S256
      &redirect_uri=https%3A%2F%2Flogin.truefoundry.com%2Foauth2%2Fcallback
      &state={encoded_state}
      &client_id={client_id}
      &code_challenge={code_challenge}
Response
HTTP/1.1 302 Found
Cache-Control: no-cache, no-store
Pragma: no-cache
Server: nginx
Date: Fri, 27 Jun 2025 07:00:00 GMT
Location: https://login.truefoundry.com/oauth2/callback?code={authorization_code}&state={encoded_state}
All requests to the Identity Provider are signed using a RS256 key pair. In case of SAML, destination assertion is enabled ensuring secure transfer of user authentication information between the SAML identity provider (IdP) and TrueFoundry Auth Server (SP).
4

Redirect to the TrueFoundry Auth Server with code

On successful authentication by SSO Identity Provider, the browser redirects to the configured redirect URL, i.e. , with an authorisation code. The Auth server then uses this authorisation code to fetch user information using a POST HTTP request to the SSO Identity Provider.
Request
GET /oauth2/callback?code={authorization_code}&state={encoded_state} 
HTTP/1.1 
Host: login.truefoundry.com
Response
HTTP/1.1 302 Found
Cache-Control: no-cache, no-store
Pragma: no-cache
Server: nginx
Date: Fri, 27 Jun 2025 07:00:00 GMT
Location: https://your.example.com/auth/callback?code={authorization_code}&userState=Authenticated
To protect data integrity and privacy, all data in transit to and from TrueFoundry Control Plane or Auth Server is encrypted using TLS 1.2 or higher.
5

Validate & Create User if it doesn't exist

validates the response from the SSO Identity provider and maps the user based on the email claim with the user’s email in the database, and creates a new entry if not present already.
This step is performed by the and is not visible to the user.Get Token from SSO Identity Provider:
Request
POST /oauth2/{client_id}/v1/token
HTTP/1.1
Host: example.sso.com
Content-Type: application/x-www-form-urlencoded
Origin: https://login.truefoundry.com
Body: code={authorization_code}
      &grant_type=authorization_code
      &redirect_uri=https://login.truefoundry.com/oauth2/callback
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: Fri, 27 Jun 2025 07:00:00 GMT
  {
    "token_type" : "Bearer",
    "expires_in" : 3600,
    "access_token" : "{access_token}",
    "scope" : "groups openid email",
    "id_token" : "{id_token}"
  }
Get User information from SSO Identity Provider:
Request
GET /oauth2/{client_id}/v1/userinfo
HTTP/1.1
Host: example.sso.com
Authorization: Bearer {access_token}
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: Fri, 27 Jun 2025 07:00:00 GMT
  {
    "sub" : "{sso_user_id}",
    "email" : "example@example.com",
    "email_verified" : true,
    "groups" : ["{group_1}", "{group_2}"]
  }
Link user via email example@example.com to user in TrueFoundry Auth Server and redirects to TrueFoundry Control Plane.
Any user deactivated from the platform is rejected at this step.
6

Redirect to TrueFoundry Control Plane with the OAuth authorisation code

On user validation, the redirects the control to TrueFoundry Control Plane via browser with an authorisation code
Request
GET /auth/callback?code={authorization_code}&userState=Authenticated
HTTP/1.1 
Host: your.example.com
Response
HTTP/1.1 200 OK
Date: Fri, 27 Jun 2025 07:00:00 GMT
7

Request tokens using OAuth authorisation code

TrueFoundry Control Plane uses the code to request tokens using a POST HTTP request to the .
Request
POST /api/svc/v1/oauth2/token
HTTP/1.1 
Host: your.example.com
Content-Type: application/json
Origin: https://your.example.com
Body: {
        "tenantName":"{tenant_name}",
        "code":"{authorization_code}",
        "grantType":"authorization_code",
        "redirectURI":"https://your.example.com/auth/callback"
      }
Response
HTTP/1.1 201 Created
Date: Fri, 27 Jun 2025 07:00:00 GMT
Set-Cookie: accessToken=<access_token>; HttpOnly; Path=/; Max-Age=86400; Expires=Sat, 28 Jun 2025 07:00:00 GMT
Set-Cookie: refreshToken=<refresh_token>; HttpOnly; Path=/; Max-Age=604800; Expires=Thu, 03 Jul 2025 07:00:00 GMT
8

Return authentication tokens

On successful code validation, responds with authentication tokens that include an access token and a refresh token, signed by .
By default, the access token is valid for 1 day and the refresh token is valid for 7 days. You can change the token expiry by contacting support.
9

Set tokens as an HttpOnly Cookie

TrueFoundry Control Plane sets these authentication tokens as HTTP-only cookies in the Browser. All further requests to TrueFoundry Control Plane contain the same cookies and are used for authentication and authorisation at the API server layer

​
Configure SSO in TrueFoundry

Go to Platform -> Settings -> SSO, toggle Enabled, pick your SSO Provider (Okta, Google, Azure AD, or Custom), then choose OIDC or SAML v2 under Authentication Configuration. SSO Settings You can enable the SSO settings and fill up the form with the fields as described below: SSO configuration in TrueFoundry You can choose any of the SSO providers: Google, AzureAD, Okta, or custom (KeyCloak can be integrated using Custom). In case you are using any of the above, you can read our specialized documentation for each of them:
  1. OIDC with AzureAD
  2. OIDC with Okta
  3. OIDC with Keycloak
  4. SAML v2 with AzureAD
In case you don’t find the guide above, you can follow the steps below for OIDC and SAML v2:
  • OpenID Connect (OIDC)
  • SAML v2
1

Create a client application in your IdP

Set the redirect/callback URL to https://login.truefoundry.com/oauth2/callback
2

Fill up the TrueFoundry SSO settings form

Fill up the TrueFoundry SSO settings form with the fields as described below: - Client ID - Client Secret - Discover endpoints — If you enable this as True, we will automatically discover the endpoints from the issuer URL. If you mark this as disabled, you will need to manually set the Authorization Endpoint, Token Endpoint and UserInfo Endpoint - Issuer URL - your IdP’s issuer - used with discovery to auto‑populate endpoints. - Scopes - Space separated list of scopes. Defaults to openid email

​
Advanced Customizations (apply to both OIDC and SAML)

You can customize the login button that will be shown to the user while logging into Truefoundry and token settings.
  • Button Text / Button Image URL - customize the login button.
  • Email Claim - claim/attribute carrying the user’s email (default: email).
  • Unique ID Claim - claim/attribute carrying a unique user ID (default: sub).

​
Automated User Management and RBAC

TrueFoundry supports automated user management using groups in your SSO claims. You can also configure RBAC automatically using SSO group backed teams. Features:
  1. Automatically register users to the platform using SSO.
  2. Automatically assign Tenant Admin roles to users using groups claim in your SSO.
  3. Automatically assign users to a SSO backed team based on groups claim in your SSO.
  4. Use the SSO backed team to configure RBAC at Model and MCP Server.
Steps to configure:
  1. Navigate to Platform > Settings > SSO
  2. Edit your configured SSO and add Group claim under advanced fields. SSO Group claim
  3. You can also configure what groups should map to Tenant Admin.
    If once a user’s role is updated manually to tenant admin, it will take the precedence and will not be converted to tenant member even in absence of the SSO groups.
  4. Once this is configured, you can create SSO backed teams under Access > SSO backed teams. Users will automatically get assigned to these teams based on the groups. SSO Group claim
  5. Further, these teams can be assigned as collaborators to Models, MCP Servers, Clusters, Workspaces, etc.