Skip to main content
Okta OIDC is part of the Formbricks Enterprise Edition
Integrating Okta with your Formbricks instance lets your users sign in with their existing Okta accounts over OpenID Connect. This guide walks you through creating an Okta app integration, finding the right issuer URL, and configuring Formbricks — including automatic user provisioning into a default team.
Prefer SAML? Okta works either way — follow SAML with Identity Providers instead. OIDC is the simpler of the two: it needs no XML metadata file on the Formbricks side.

​
Requirements

  • An Okta org with administrator access to the Admin Console.
  • A self-hosted Formbricks instance with a valid Enterprise license.
  • The Formbricks callback URI: {WEBAPP_URL}/api/auth/oauth2/callback/openid
Upgrading from v5.1 or earlier? This path changed once, at v5.2:
  • v5.1 and earlier: {WEBAPP_URL}/api/auth/callback/openid
  • v5.2 and later (current): {WEBAPP_URL}/api/auth/oauth2/callback/openid
Upgrading from v5.2 or later needs no change — the callback URL is pinned and does not move with Formbricks’ authentication library. See the migration guide.

​
Setting up Okta OIDC

1

Create a new app integration in Okta

  • Sign in to the Okta Admin Console.
  • Go to Applications → Applications in the sidebar.
  • Click Create App Integration.
2

Choose OIDC and Web Application

In the Create a new app integration dialog:
  • Sign-in method: OIDC - OpenID Connect
  • Application type: Web Application
Click Next.
Web Application, not Single-Page Application. Formbricks completes the authorization code exchange on the server with a client secret, so it needs a confidential client. A SPA integration issues no secret and sign-in will fail.
3

Configure the app integration

Replace your-formbricks-domain.com with your actual Formbricks URL, then click Save.
The redirect URI must match exactly, including the scheme and with no trailing slash. A mismatch surfaces in Okta as “The ‘redirect_uri’ parameter must be a Login redirect URI in the client app settings”.
Formbricks sends PKCE on every authorization request. Okta accepts PKCE on confidential web apps, so the Require PKCE as additional verification checkbox can be left either way.
4

Copy the client credentials

On the app’s General tab, find the Client Credentials section and copy:
  • Client ID
  • Client secret (under Client Secrets)
If Client authentication shows Public client / PKCE only rather than Client secret, the app was created as a SPA or native integration. Create a Web Application integration instead — Formbricks needs the secret.
5

Assign users or groups

  • Open the app’s Assignments tab.
  • Click Assign → Assign to People or Assign to Groups, and assign everyone who should be able to sign in to Formbricks.
Okta rejects sign-in for anyone not assigned to the app, so skipping this step makes every login fail with “User is not assigned to the client application”.
6

Determine the issuer URL

Okta can mint tokens from two kinds of authorization server, and the issuer URL differs:The org authorization server works on every Okta plan and is the simpler choice. Custom authorization servers require API Access Management (integrator and developer orgs ship a default one); find their exact issuer under Security → API → Authorization Servers, in the Issuer URI column.
Use your Okta org domain (your-org.okta.com, or your custom domain such as login.example.com) — never the Admin Console domain your-org-admin.okta.com. The latter hosts no OIDC discovery document.
Verify the issuer by opening {OIDC_ISSUER}/.well-known/openid-configuration in your browser. It returns a JSON document with the OIDC endpoints. Formbricks builds that URL by appending to OIDC_ISSUER, so do not add a trailing slash.
7

Configure Formbricks environment variables

Add the following to your Formbricks .env file or docker-compose.yml:
Formbricks Env for Okta OIDC
8

Restart and test

  • Restart your Formbricks instance.
  • The login page now shows a button labelled with your OIDC_DISPLAY_NAME.
  • Click it to authenticate through Okta.
To disable email/password login entirely and force all users through Okta, set EMAIL_AUTH_DISABLED=1. This hides the email/password form on the login page.

​
Automatic user provisioning

By default, new SSO users must be invited by an organization admin before they can access Formbricks. To let Okta users join automatically and land in a team, add:
Automatic User Provisioning
With AUTH_SKIP_INVITE_FOR_SSO=1, anyone Okta lets through the app integration gets a Formbricks account. Keep the app’s Assignments scoped to the group that should have access.

​
Finding your team ID

  1. Log in to Formbricks as an admin.
  2. Go to Settings → Organization → Teams.
  3. Click Manage Team on the team you want to use as the default.
  4. The Team ID is displayed in the modal.
The Teams feature requires the Role-Based Access Control (RBAC) add-on on your Enterprise license. If you don’t see the Teams section under Settings → Organization, contact Formbricks support to enable it.

​
Full configuration example

Complete Okta OIDC Configuration

​
Troubleshooting

The Sign-in redirect URIs entry on the Okta app does not match what Formbricks sends. It must be exactly {WEBAPP_URL}/api/auth/oauth2/callback/openid — same scheme and host, no trailing slash.If you’re on v5.1 or earlier, the path is {WEBAPP_URL}/api/auth/callback/openid (without /oauth2) instead.
The signed-in Okta user is not assigned to the app integration. Open the app’s Assignments tab and assign the user, or the group they belong to.
Formbricks reads {OIDC_ISSUER}/.well-known/openid-configuration, so that URL must be reachable from the Formbricks server:
  • Check that OIDC_ISSUER has no trailing slash.
  • Check that you used the org domain, not your-org-admin.okta.com.
  • On a custom authorization server, the issuer includes the /oauth2/... path.
A custom authorization server applies its own access policies and scopes; the org authorization server does not.
  • Under Security → API → your server → Access Policies, make sure a policy and rule cover the Formbricks app (or all clients).
  • Under the Scopes tab, make sure openid, profile and email are present — Formbricks requests all three.
If you don’t need custom claims, pointing OIDC_ISSUER at the org authorization server (https://your-org.okta.com) avoids both.
  • Confirm that OIDC_CLIENT_ID, OIDC_CLIENT_SECRET and OIDC_ISSUER are all set.
  • Ensure your Formbricks instance has a valid Enterprise license.
  • Restart the Formbricks container after adding the environment variables.
The user was added to the organization but not assigned to a team. Verify that:
  • AUTH_SSO_DEFAULT_TEAM_ID is set correctly (the env variable name is AUTH_SSO_DEFAULT_TEAM_ID, not DEFAULT_TEAM_ID).
  • The Team ID is a valid cuid that exists in your database.
  • The team is linked to a Workspace via Workspace Teams settings.