Skip to main content
This guide walks you through setting up OpenID Connect (OIDC) 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. For SAML 2.0 instead of OIDC, see SAML with Okta.

​
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).
  • Your Okta tenant domain — the hostname you use to reach the admin console, for example https://acme.okta.com or https://acme.okta-emea.com.
The TrueFoundry OIDC callback URL is always https://login.truefoundry.com/oauth2/callback. Keep that value handy — you’ll paste it into Okta during application setup.

​
Configuration overview

1

Create an OIDC Web Application in Okta

Register a new OIDC – OpenID Connect application of type Web Application.
2

Collect the Client ID, Client Secret, and Issuer

Copy the credentials Okta generates and your Okta tenant domain.
3

Configure TrueFoundry

Paste the values into the TrueFoundry SSO form and save.
4

Assign users and test

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

​
Step 1 — Create an OIDC 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 OIDC – Web Application

In the Create a new app integration dialog:
  • Sign-in method: choose OIDC – OpenID Connect.
  • Application type: choose Web Application.
Click Next.
Okta Create a new app integration dialog with OIDC – OpenID Connect and Web Application selected

Select OIDC – OpenID Connect and Web Application in the Create a new app integration dialog.

3

Configure the integration

On the New Web App Integration page:
  • App integration name: a label such as TrueFoundry.
  • Grant type: ensure Authorization Code is checked. Leave the other grant types unchecked unless you have a specific reason.
  • Sign-in redirect URIs: click Add URI and enter:
  • Sign-out redirect URIs: leave blank (or set it to your TrueFoundry login URL if you want a custom post-logout redirect).
  • Assignments: choose Skip group assignment for now — you’ll assign users in Step 4.
Click Save.
Okta New Web App Integration page with the App integration name field highlighted

Set the app integration name and confirm Authorization Code is the only checked grant type.

Okta New Web App Integration page with the Sign-in redirect URIs section highlighted

Click Add URI under Sign-in redirect URIs and paste the TrueFoundry callback URL.

​
Step 2 — Collect the credentials

After saving, Okta opens the application’s General tab.
1

Copy the Client ID and Client Secret

Under Client Credentials, copy:
  • Client ID
  • Client secret — click Show if it isn’t already visible.
Store both values somewhere safe; you’ll paste them into TrueFoundry in Step 3.
Okta OIDC application General tab showing the Client ID, Client Secrets section, and the Okta tenant domain in the user dropdown

Copy the Client ID and Client secret from the General tab. Your Okta tenant domain appears in the user dropdown at the top right.

2

Confirm the Issuer URL

Open the Sign On tab and find the OpenID Connect ID Token card. Make sure Issuer is set to Okta URL, which produces an issuer of the form:
If the dropdown is currently set to Dynamic, change it to Okta URL and click Save.
Your tenant domain is the hostname you use to sign in to the Okta dashboard. For European tenants this is usually https://<your-tenant>.okta-emea.com; for preview tenants it’s https://<your-tenant>.oktapreview.com. Use whichever matches your environment.

​
Step 3 — Configure TrueFoundry

1

Open SSO settings

In TrueFoundry, 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 SSO form

  • Enabled: turn this on.
  • Name: a lowercase alphanumeric label — for example, oktaoidc.
  • SSO Provider: select Okta.
  • Authentication Configuration: choose OIDC.
  • Client ID: the Client ID from Okta.
  • Client Secret: the Client secret from Okta.
  • Discover endpoints: leave enabled.
  • Issuer URL: your Okta tenant URL — for example:
  • Scopes (optional): leave blank to use the default openid email. Add profile if you want first and last name in the token.
3

Save

Click Save. TrueFoundry validates the issuer URL by fetching /.well-known/openid-configuration from it and stores the credentials.

​
Step 4 — Assign users 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.
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.
You can also assign from Directory → People: click a user, open Assign Applications, and pick the TrueFoundry app.
Users who are not assigned to the Okta application will see an “app not assigned to user” error when they click Login with Okta in TrueFoundry.

​
Step 5 — Test single sign-on

  1. Open a private/incognito window and visit your TrueFoundry login page.
  2. Click Login with Okta.
  3. Authenticate with an assigned Okta user.
You should land in the TrueFoundry dashboard. New users are created automatically if JIT provisioning is enabled.

​
Optional next steps

​
Troubleshooting

The Issuer URL doesn’t host an OpenID discovery document. Confirm the value is exactly your Okta tenant URL (for example https://acme.okta.com) with no trailing slash and no /oauth2/default suffix. You can test it directly by visiting <issuer>/.well-known/openid-configuration in your browser.
The client secret in TrueFoundry doesn’t match Okta. Regenerate the secret on the Okta application’s General → Client Credentials card, copy the new value, and paste it into TrueFoundry’s Client Secret field.
Make sure your TrueFoundry Scopes include email, and (if you want first/last name) profile. If you renamed claims on the Okta side, expand Show advanced fields in TrueFoundry and set the Email Claim to the claim name Okta is emitting.
The Okta user isn’t assigned to your application. Go back to Step 4 and assign them under the Assignments tab — either directly as a person or by adding them to an assigned group.