Skip to main content
This guide walks you through setting up SAML 2.0 single sign-on between TrueFoundry and Okta. Once finished, members of your Okta tenant can sign in to TrueFoundry through a Login with Okta button.

​
Prerequisites

  • A TrueFoundry tenant with Admin access to Settings → Security & Access → SSO.
  • An Okta Workforce Identity Cloud tenant with permission to create new Applications (Super Admin or App Admin).
You’ll bounce between the Okta admin console and the TrueFoundry SSO settings. Keep both open in adjacent tabs to copy-paste values quickly.

​
Configuration overview

1

Create the SSO configuration in TrueFoundry

Save a SAML SSO configuration in TrueFoundry to surface the Single sign-on URL, Audience URI (SP Entity ID), and Relay URL.
2

Create a SAML 2.0 app integration in Okta

Register a custom SAML application in Okta that TrueFoundry will federate with.
3

Configure the SAML connection on both sides

Paste TrueFoundry’s values into Okta, then paste Okta’s IdP values back into TrueFoundry.
4

Assign users and test

Assign people or groups to the Okta application and sign in to verify.

​
Step 1 — Create the SSO configuration in TrueFoundry

1

Open SSO settings

Go to Settings → Security & Access → SSO.Click the + icon labeled Add New SSO Config.
TrueFoundry SSO settings page with the Add New SSO Config plus button highlighted

SSO page in TrueFoundry — click the + icon to add a new SSO configuration

2

Fill in the basic fields

  • Enabled: turn this on.
  • Name: a lowercase alphanumeric label — for example, oktasaml.
  • SSO Provider: choose Okta.
  • Authentication Configuration: select SAML v2.
Leave Identity Provider Endpoint and X.509 Certificate blank for now — you’ll fill them in once Okta surfaces those values.
3

Save to reveal the Single sign-on URL, Audience URI (SP Entity ID), and Relay URL

Click Save. TrueFoundry displays the values you need for Okta on the SSO configuration card:
  • Single sign-on URL in Okta — Single Sign On URL in TrueFoundry.
  • Audience URI (SP Entity ID) in Okta — Audience URI (SP Entity ID) in TrueFoundry.
  • Default RelayState in Okta (optional) — Relay URL in TrueFoundry.
TrueFoundry SSO configuration card displaying Audience URI, Single Sign On URL, Metadata URL, and Relay URL for SAML setup

TrueFoundry SSO configuration card showing the SAML values to copy into Okta

​
Step 2 — Create a SAML 2.0 application in Okta

1

Open the Okta admin console

Sign in to your Okta admin console (https://<your-tenant>-admin.okta.com) as an administrator.In the left navigation, expand Applications → Applications and click Create App Integration.
Okta admin console dashboard with the Applications section highlighted in the left navigation

Expand Applications in the left nav of the Okta admin console.

Okta Applications listing with the Create App Integration button highlighted

Click Create App Integration on the Applications page.

2

Pick SAML 2.0

In the Create a new app integration dialog, select SAML 2.0 and click Next.
Okta Create a new app integration dialog with SAML 2.0 selected

Select SAML 2.0 in the Create a new app integration dialog.

3

Name the application

On the General Settings step, give the application a name such as TrueFoundry. Optionally upload an app logo.Click Next to move on to the Configure SAML step.

​
Step 3 — Enter TrueFoundry’s details into Okta

On the Configure SAML step of the application you created in Step 2, fill in the SAML Settings card using the values from Step 1.
1

Configure SAML settings

On the Configure SAML step, fill in the SAML Settings section using the values from Step 1:Leave Use this for Recipient URL and Destination URL checked.Set Name ID format to EmailAddress and leave Application username at the default of Okta username.Click Next.
Okta Configure SAML step showing Single sign-on URL, Audience URI, Default RelayState, and Name ID format set to EmailAddress

Configure SAML — paste TrueFoundry values and set Name ID format to EmailAddress

2

Submit the feedback page

Okta requires a short feedback prompt. Select I’m an Okta customer adding an internal app, then scroll down and click Finish.
3

Add attribute statements

After the wizard completes, open your application and click the Sign On tab. Scroll to the Attribute statements section and click Add expression for each row below:
Okta Sign On tab Attribute statements section showing email mapped to user.profile.email and sub mapped to user.id

Sign On tab — Attribute statements with email and sub expressions

​
Step 4 — Copy Okta’s details back to TrueFoundry

Okta drops you on the application detail page once the wizard completes.
1

Open View SAML setup instructions

On the application page, click the Sign On tab. In the right sidebar under SAML Setup, click View SAML setup instructions.
Okta Sign On tab with View SAML setup instructions button highlighted in the SAML Setup section on the right sidebar

Sign On tab — click View SAML setup instructions in the SAML Setup sidebar

2

Copy the IdP URL and certificate

In the setup instructions panel, copy the values shown:
  • Identity Provider Single Sign-On URL — you’ll paste this into TrueFoundry as the Identity Provider Endpoint.
  • X.509 Certificate — copy the full certificate from the text box, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. You can also use Download certificate and open the file in a text editor.
Okta View SAML setup instructions panel showing Identity Provider Single Sign-On URL, Identity Provider Issuer, and X.509 Certificate

View SAML setup instructions — copy the SSO URL and X.509 certificate

3

Paste into TrueFoundry

Return to Settings → Security & Access → SSO in TrueFoundry and edit the SSO configuration you created in Step 1. Set:
  • Identity Provider Endpoint → Identity Provider Single Sign-On URL from Okta.
  • X.509 Certificate → the certificate you copied from the setup instructions.
Click Save.

​
Step 5 — Assign people in Okta

Okta only lets users sign in to applications they’ve been explicitly assigned to.
1

Open Assignments

Inside your Okta application, click the Assignments tab and open the Assign dropdown.
Okta application Assignments tab with the Assign dropdown expanded showing Assign to People and Assign to Groups

Open the Assignments tab and choose Assign to People or Assign to Groups.

2

Pick people or groups

Choose Assign to People or Assign to Groups, select the users or groups that should have TrueFoundry access, and click Assign for each. When you’re done, click Done.
Okta Assign to Groups dialog listing HR, Marketing, and Engineering with an Assign action next to each

Assign the relevant groups (or people) to the application and click Done.

Prefer assigning groups when you can — it pairs well with SCIM with Okta for automated user lifecycle management.
Users who are not assigned to the Okta application will see an “app not assigned” error when they click Login with Okta in TrueFoundry.

​
Step 6 — Test single sign-on

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

​
Optional next steps

  • Automate user lifecycle with SCIM — see SCIM with Okta to push users and groups from Okta into TrueFoundry automatically.
  • Use OIDC instead of SAML — see OIDC with Okta for the equivalent OpenID Connect flow.

​
Troubleshooting

The Okta user isn’t assigned to your application. Go back to Step 5 and assign them under Assignments.
The certificate copied into TrueFoundry doesn’t match Okta’s active signing certificate. Open Sign On → SAML Setup → View SAML setup instructions, copy the X.509 Certificate again (or use Download certificate), and paste the full PEM (including the BEGIN/END lines) into TrueFoundry.
Check the provisioning mode under Settings → Security & Access → Provisioning:
  • Invite-only — the user must be invited from Access → Users first.
  • JIT — the user is created on first login automatically.
  • SCIM — the user must be synced from your IdP first. See SCIM with Okta.
Confirm Name ID format is set to EmailAddress and that Attribute statements on the Sign On tab includes email → user.profile.email and sub → user.id as described in Step 3. If you renamed attributes, expand Show advanced fields in TrueFoundry and set:
  • Email Claim → the attribute name you used for email (defaults to email).
  • Unique ID Claim → defaults to sub; on Okta the Name ID is typically the unique identifier, so you can usually leave this at the default.
The Audience URI (SP Entity ID) in Okta doesn’t match TrueFoundry’s Audience URI (SP Entity ID). Re-copy the value from the TrueFoundry SSO configuration card and paste it verbatim into Okta (no trailing slashes, no extra whitespace).