Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to wire up TrueFoundry SSO against any Identity Provider (IdP) that speaks OpenID Connect — useful when there isn’t a dedicated guide for your IdP yet. If your IdP is Microsoft Entra ID, Okta, Google, or another provider that already has a TrueFoundry guide, prefer that guide instead. After you finish, members of your IdP can sign in to TrueFoundry through a customisable Login with SSO button.

​
Prerequisites

  • A TrueFoundry tenant with Admin access to Platform → Settings → SSO.
  • Administrator access to your Identity Provider, with permission to register applications / clients.
  • An IdP that implements OpenID Connect with the Authorization Code grant.
  • Network access from TrueFoundry to your IdP’s discovery document (/.well-known/openid-configuration) is strongly recommended — it lets TrueFoundry auto-discover the OIDC endpoints. If discovery isn’t reachable you can still configure the endpoints manually (see Step 4).
Keep the IdP admin console and TrueFoundry’s Platform → Settings → SSO page open in side-by-side tabs. You’ll copy the Client ID, Client Secret, and Issuer URL from one into the other.

​
Configuration overview

1

Register a client application in your IdP

Create a web application / OIDC client and configure the TrueFoundry callback URL.
2

Configure claims

Make sure the ID token carries email and a stable unique identifier such as sub.
3

Configure TrueFoundry

Enter the Client ID, Client Secret, and Issuer URL in TrueFoundry’s SSO settings.
4

(Fallback) Manual endpoint configuration

Required only if your IdP does not expose a standard discovery document.
5

Assign users and test sign-in

Grant users access in your IdP and verify the end-to-end flow.

​
Step 1 — Register a client application in your IdP

The exact wording varies by IdP, but every OIDC-compliant Identity Provider asks for the same set of inputs.
1

Create a new OIDC client

In your IdP admin console, create a new application (sometimes labelled OIDC client, App registration, Relying Party, or Web app). Choose Web as the application type.
2

Set the redirect / callback URL

Add the TrueFoundry callback URL as the only allowed redirect URI:
https://login.truefoundry.com/oauth2/callback
The URL must match exactly — no trailing slash, no extra path segments. A mismatch produces a redirect_uri_mismatch error during sign-in.
3

Enable the Authorization Code grant

Confirm that your IdP allows the Authorization Code grant type for this client. TrueFoundry does not use the implicit or password grants.
4

Capture the client credentials

After saving, your IdP will display:
  • Client ID (sometimes called Application ID)
  • Client Secret (sometimes called Application secret or Key)
  • Issuer URL — usually of the form https://<idp-host>/... and used to build the discovery URL <issuer>/.well-known/openid-configuration.
Copy all three. Treat the Client Secret as sensitive — store it in your password manager and never commit it to source control.

​
Step 2 — (Optional) Configure claims

TrueFoundry needs at least two claims in the ID token: the user’s email and a stable unique identifier. Most IdPs include these by default — this step is only needed if yours doesn’t.
1

Confirm the ID token claims

Make sure the ID token (or the response from the UserInfo endpoint) carries the following claims:
ClaimPurposeRequired?
subA stable, unique identifier for the userRequired
emailThe user’s primary email addressRequired
given_nameThe user’s first nameRecommended
family_nameThe user’s last nameRecommended
groupsA list of group membershipsOptional — needed for group-based authorization or SCIM
If your IdP doesn’t emit a sub claim by default, map any stable unique attribute (for example the user’s directory ID) to sub. Avoid mapping mutable values like email to sub because users may change them over time.
2

Decide on scopes

TrueFoundry requests openid email by default. Add profile if you want first/last name, and groups if you configured a groups claim. You’ll enter the final scope list in Step 3.

​
Step 3 — Configure TrueFoundry

1

Open the SSO settings

In TrueFoundry, go to Platform → Settings → SSO and click Configure.
2

Fill in the SSO form

  • Enabled: turn this on.
  • Name: a label such as Company SSO.
  • SSO Provider: choose Custom.
  • Authentication Configuration: select OIDC.
  • Client ID: the Client ID from Step 1.
  • Client Secret: the Client Secret from Step 1.
  • Discover endpoints: leave this on so TrueFoundry pulls the OIDC endpoints from the discovery document.
  • Issuer URL: the issuer string from your IdP — for example https://idp.example.com/realms/main. TrueFoundry will fetch https://idp.example.com/realms/main/.well-known/openid-configuration to discover the rest of the endpoints.
  • Scopes (optional): leave blank to use the default openid email. Add profile, groups, or any other scopes your IdP requires to emit the claims you configured in Step 2.
3

Save

Click Save. TrueFoundry validates the discovery document and stores the credentials. If validation fails, see Step 4 or the troubleshooting section.

​
Step 4 — (Fallback) Manual endpoint configuration

Most modern IdPs expose /.well-known/openid-configuration at the issuer URL. Skip this step if discovery worked in Step 3. Use manual configuration when:
  • Your IdP does not publish a discovery document at the standard path.
  • The discovery document is reachable from a browser but not from TrueFoundry’s network (for example, the IdP is on a private network).
  • The discovery document returns non-standard or invalid JSON.
1

Locate the four OIDC endpoints

From your IdP’s documentation, collect:
FieldWhat it is
Authorization EndpointWhere TrueFoundry sends the user to authenticate (the authorization_endpoint from discovery).
Token EndpointWhere TrueFoundry exchanges the authorization code for tokens (token_endpoint).
UserInfo EndpointWhere TrueFoundry fetches profile claims using the access token (userinfo_endpoint).
JWKS EndpointWhere TrueFoundry fetches the public keys used to verify ID token signatures (jwks_uri).
2

Turn off discovery and paste the endpoints

In TrueFoundry’s SSO form, toggle Discover endpoints off. Paste each endpoint into the corresponding field, then click Save.
The Issuer URL is still required even in manual mode — TrueFoundry uses it as the expected iss value when validating ID tokens.

​
Step 5 — Assign users and test sign-in

1

Assign users in your IdP

Depending on your IdP, you’ll either grant users access by assigning them to the application directly, by adding them to a group that’s assigned to the application, or by making the application available to all users in the tenant. Follow your IdP’s documentation.
Users who haven’t been assigned to the application will see an “access denied” or “user not assigned” error when they try to sign in.
2

Test sign-in

  1. Open a private/incognito window and visit your TrueFoundry login page.
  2. Click Login with SSO (or whichever button label you chose under Show advanced fields → Button Text).
  3. Authenticate as an assigned user.
If the sign-in succeeds you’ll land in the TrueFoundry dashboard. The user is created automatically if JIT provisioning is on; otherwise the user must already exist in TrueFoundry or be invited.

​
Optional customizations

The fields below live under Show advanced fields on the SSO form and apply to both OIDC and SAML.
FieldWhat it doesDefault
Button TextLabel shown on the SSO login button.Login with SSO
Button Image URLIcon shown next to the button label.None
Email ClaimOIDC claim that carries the user’s email. Override if your IdP uses a non-standard name (for example mail or upn).email
Unique ID ClaimOIDC claim used as the stable user identifier. Override if your IdP doesn’t emit sub.sub
If you want to brand the login button per environment, set the Button Text and Button Image URL to match your company brand.

​
Troubleshooting

TrueFoundry could not load <issuer>/.well-known/openid-configuration. Verify the URL in a browser. If the document is unreachable or returns non-JSON content, follow Step 4 to enter the four endpoints manually.
Either the wrong secret was pasted, the secret was rotated/expired in your IdP, or only an identifier (not the secret value) was copied. Generate a fresh client secret in your IdP, copy the value immediately, and update TrueFoundry.
The ID token is missing the email claim.
  • Make sure the email claim is included in the ID token in your IdP.
  • Add email profile to Scopes on the TrueFoundry SSO form.
  • If your IdP uses a non-standard claim name (for example mail or upn), expand Show advanced fields and set Email Claim to that name.
The redirect URI registered in your IdP doesn’t match the one TrueFoundry sends. The IdP must have https://login.truefoundry.com/oauth2/callback listed exactly — no trailing slash, no extra query parameters, and the scheme must be https.
The iss value inside the ID token doesn’t equal the Issuer URL you entered in TrueFoundry. Some IdPs return an issuer with or without a trailing slash, or with a different host than the one used for discovery. Check the iss claim in a returned token (use jwt.io) and update the Issuer URL to match it exactly.
The TrueFoundry Auth Server validates the iat/nbf/exp timestamps on the ID token. If your IdP host clock drifts, NTP can fall behind by enough seconds to break validation. Sync the IdP host’s clock with an authoritative time source.
TrueFoundry requires https:// for the Issuer URL and all four endpoints. If your IdP is only reachable on http://, terminate TLS in front of it (for example, with a reverse proxy) and use the HTTPS URL. Self-signed certificates must be issued by a CA trusted by TrueFoundry’s Auth Server.

​
Optional next steps