> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta OIDC

> Configure Okta as an OpenID Connect (OIDC) provider for secure Single Sign-On with your self-hosted Formbricks instance.

<Note>Okta OIDC is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license)</Note>

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.

<Note>
  Prefer SAML? Okta works either way — follow [SAML with Identity Providers](/docs/self-hosting/configuration/auth-sso/setup-saml-with-identity-providers#saml-with-okta) instead. OIDC is the simpler of the two: it needs no XML metadata file on the Formbricks side.
</Note>

### Requirements

* An Okta org with administrator access to the Admin Console.
* A self-hosted Formbricks instance with a valid [Enterprise license](/docs/self-hosting/advanced/license).
* The Formbricks callback URI: `{WEBAPP_URL}/api/auth/oauth2/callback/openid`

<Warning>
  **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](/docs/self-hosting/advanced/migration).
</Warning>

## Setting up Okta OIDC

<Steps>
  <Step title="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**.

    <img src="https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/create-app-integration.webp?fit=max&auto=format&n=AluoV1JcINmbRAK1&q=85&s=7fb1ad7cad43a945f1914a67370d61e5" width="3236" height="1928" data-path="images/self-hosting/configuration/auth-sso/okta/create-app-integration.webp" />
  </Step>

  <Step title="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**.

    <Note>
      **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.
    </Note>
  </Step>

  <Step title="Configure the app integration">
    | Field | Value |
    | - | - |
    | **App integration name** | Anything recognisable, e.g. `Formbricks`. |
    | **Grant type** | Leave **Authorization Code** selected (the default). Nothing else is required. |
    | **Sign-in redirect URIs** | `https://your-formbricks-domain.com/api/auth/oauth2/callback/openid` |
    | **Sign-out redirect URIs** | Leave empty — Formbricks does not use RP-initiated logout. |
    | **Assignments** | Choose who may sign in: a specific group, or *Allow everyone in your organization to access*. |

    Replace `your-formbricks-domain.com` with your actual Formbricks URL, then click **Save**.

    <Warning>
      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"*.
    </Warning>

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Copy the client credentials">
    On the app's **General** tab, find the **Client Credentials** section and copy:

    * **Client ID**
    * **Client secret** (under *Client Secrets*)

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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"*.
  </Step>

  <Step title="Determine the issuer URL">
    Okta can mint tokens from two kinds of authorization server, and the issuer URL differs:

    | Authorization server | Issuer URL |
    | - | - |
    | **Org** | `https://your-org.okta.com` |
    | **Custom** | `https://your-org.okta.com/oauth2/your-auth-server-id` |

    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.

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

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Configure Formbricks environment variables">
    Add the following to your Formbricks `.env` file or `docker-compose.yml`:

    ```yml Formbricks Env for Okta OIDC theme={null}
    OIDC_CLIENT_ID=0oa1b2c3d4EXAMPLE5
    OIDC_CLIENT_SECRET=your-client-secret-here
    OIDC_ISSUER=https://your-org.okta.com
    OIDC_DISPLAY_NAME="Okta"
    OIDC_SIGNING_ALGORITHM=RS256
    ```

    | Variable | Description |
    | - | - |
    | `OIDC_CLIENT_ID` | The **Client ID** from the app's General tab. |
    | `OIDC_CLIENT_SECRET` | The **Client secret** from the app's General tab. |
    | `OIDC_ISSUER` | Your Okta issuer URL (see the step above). |
    | `OIDC_DISPLAY_NAME` | The label shown on the Formbricks login button. |
    | `OIDC_SIGNING_ALGORITHM` | Optional. Okta signs with `RS256`, which is also the Formbricks default. |
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

## 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:

```yml Automatic User Provisioning theme={null}
AUTH_SKIP_INVITE_FOR_SSO=1
AUTH_SSO_DEFAULT_TEAM_ID=your-team-id-here
```

| Variable | Description |
| - | - |
| `AUTH_SKIP_INVITE_FOR_SSO` | Set to `1` to let SSO users create an account without a manual invite. |
| `AUTH_SSO_DEFAULT_TEAM_ID` | The ID of the team new SSO users are added to. The organization is derived from this team. |

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

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

<Note>
  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](mailto:support@formbricks.com) to enable it.
</Note>

## Full configuration example

```yml Complete Okta OIDC Configuration theme={null}
OIDC_CLIENT_ID=0oa1b2c3d4EXAMPLE5
OIDC_CLIENT_SECRET=your-client-secret-here
OIDC_ISSUER=https://your-org.okta.com
OIDC_DISPLAY_NAME="Okta"
OIDC_SIGNING_ALGORITHM=RS256
AUTH_SKIP_INVITE_FOR_SSO=1
AUTH_SSO_DEFAULT_TEAM_ID=your-team-id-here
# Optional: disable email/password login to force Okta-only authentication
# EMAIL_AUTH_DISABLED=1
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Okta shows 'The redirect_uri parameter must be a Login redirect URI'">
    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.
  </Accordion>

  <Accordion title="Okta shows 'User is not assigned to the client application'">
    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.
  </Accordion>

  <Accordion title="Sign-in fails and the logs mention discovery or the issuer">
    Formbricks reads `{OIDC_ISSUER}/.well-known/openid-configuration`, so that URL must be reachable from the Formbricks server:

    ```bash theme={null}
    curl https://your-org.okta.com/.well-known/openid-configuration
    ```

    * 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.
  </Accordion>

  <Accordion title="Sign-in fails only on a custom authorization server">
    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.
  </Accordion>

  <Accordion title="OIDC login button does not appear">
    * 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.
  </Accordion>

  <Accordion title="Users see 'No access to Workspaces' after login">
    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.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.