SSO Overview - TrueFoundry Docs

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:

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.

Example Request/Response

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"
  }

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.

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

Example Request/Response

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).

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.

Example Request/Response

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.

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.

Example Request/Response

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.

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

Example Request/Response

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

Request tokens using OAuth authorisation code

TrueFoundry Control Plane uses the code to request tokens using a POST HTTP request to the .

Example Request/Response

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

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.

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.

You can enable the SSO settings and fill up the form with the fields as described below:

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:

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

Create a client application in your IdP

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

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

Create a service provider in your IdP

When adding ACS / Single sign‑on URL or Audience / SP Entity ID you can use placeholder values for now and update it once you save the configuration in TrueFoundry.

Simplify claim configuration with attribute mapping(Optional)SAML identity providers often use complex, vendor-specific attribute names for user information. For example, attributes like http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier require you to configure custom claim names in TrueFoundry’s advanced settings.Recommended approach: Configure attribute mapping in your IdP to use standard, simple names that match TrueFoundry’s defaults:

Attribute Name	Map to	Purpose
`sub`	Your IdP’s user ID field	User’s unique identifier
`email`	Your IdP’s email field	User’s email address
`groups`	Your IdP’s groups field (if supported)	User’s group memberships for RBAC

This allows TrueFoundry’s default settings to work automatically without needing to specify custom claim names in the advanced settings.

Fill up the TrueFoundry SSO settings form

Fill up the TrueFoundry SSO settings form with the fields as described below:

Identity Provider Endpoint (IdP SSO URL) — your IdP’s SAML login URL.
X.509 Certificate (PEM) — the IdP signing certificate used to verify SAML responses.

Update the IdP configuration

After you save your SAML configuration:

Replace the placeholder ACS / Single sign‑on URL with the actual Callback URL shown in TrueFoundry.
Replace the placeholder Audience / SP Entity ID with the actual Issuer shown in TrueFoundry portal.

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).

Enable SCIM Provisioning

TrueFoundry supports SCIM (System for Cross-domain Identity Management) to automatically create and update users and groups from your identity provider. SCIM provisioning is available for SAML v2 SSO configurations.

SCIM enables automatic user lifecycle management — when you add or remove users in your identity provider, TrueFoundry will automatically sync those changes.

Steps to configure SCIM:

Group name format: Only alphanumeric characters and ”-” are allowed. Group names can be up to 36 characters in length.

Enable SCIM when creating SAML SSO

When configuring a new SAML v2 SSO provider, check the Enable SCIM checkbox at the bottom of the authentication configuration form.

Enable SCIM checkbox in SAML SSO configuration

Save the SSO configuration

Complete the SAML configuration with your Identity Provider Endpoint and X.509 Certificate, then save the configuration.

Get the SCIM URL

After saving, expand your SSO configuration to view the SCIM URL along with other metadata. Copy this URL — you’ll need it for your identity provider’s SCIM settings.

Get the SCIM Token

Click the key icon (Get SCIM Token) next to your SSO configuration to generate and copy the SCIM authentication token.

Store this token securely. You’ll need it to authenticate SCIM requests from your identity provider.

Configure your Identity Provider

In your identity provider’s SCIM provisioning settings:

Set the SCIM Base URL to the SCIM URL from TrueFoundry
Set the Authentication method to Bearer Token
Use the SCIM Token as the Bearer token value

Platform

​How does TrueFoundry SSO work?

​Configure SSO in TrueFoundry

​Advanced Customizations (apply to both OIDC and SAML)

​Enable SCIM Provisioning

How does TrueFoundry SSO work?

Configure SSO in TrueFoundry

Advanced Customizations (apply to both OIDC and SAML)

Enable SCIM Provisioning