How does TrueFoundry SSO work?

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

Request tokens using OAuth authorisation code

TrueFoundry Control Plane uses the code to request tokens using a POST HTTP request to the .
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

Integrate SSO with TrueFoundry

TrueFoundry allows your team to utilize an 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 enter credentials to prove their identities repeatedly. 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.

Requirements

  • An Identity Provider (IdP) such Okta, OneLogin, Google Workplace, etc to facilitate SSO that supports either OpenID Connect (OIDC) or SAML protocol such as GSuite, AzureAD, Okta, Keycloak, etc.
  • TrueFoundry would need the following SSO configuration information from your IdP:
    • For OIDC configurations:
      • A customer’s Client ID and Client Secret
      • A customer’s OIDC issuer URL where the /.well-known/openid-configuration endpoint is hosted
    • For SAML configurations:
      • Identity Provider Single Sign-On URL
      • X.509 Certificate

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.

SAML v2 Configuration

Fill these fields:
  • 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. It is recommended to use a TrueFoundry secret instead of using the value directly.

SSO SAML configuration in TrueFoundry


OpenID Connect (OIDC) Configuration

Fill these fields:
  • Client ID
  • Client Secret - It is recommended to use a TrueFoundry secret instead of using the value directly.
  • Discover endpoints — Discover the endpoints from the issuer URL. Enabled by default (recommended).
  • Issuer URL - your IdP’s issuer; used with discovery to auto‑populate endpoints.
  • Scopes - Space separated list of scopes. Defaults to openid email
You can also manually set the following endpoints:
  • Authorization Endpoint
  • Token Endpoint
  • UserInfo Endpoint

SSO OIDC configuration in TrueFoundry


Common Options (apply to both OIDC and SAML)

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

Complete Setup in Your IdP

SAML v2

After you save your SAML configuration:
  1. Set ACS / Single sign‑on URL to the Callback URL (ACS) shown in TrueFoundry.
  2. Set Audience / SP Entity ID to the Issuer shown in TrueFoundry.

SSO SAML metadata in TrueFoundry

OIDC

After you save your OIDC configuration:
  1. Add the Redirect URI shown in TrueFoundry to your IdP.