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

# Keycloak OIDC

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

> [!NOTE]
>
> Keycloak OIDC is part of the Formbricks [Enterprise Edition](https://formbricks.com/docs/self-hosting/advanced/license.md)

Integrating Keycloak with your Formbricks instance allows users to log in using their existing Keycloak credentials via OpenID Connect. This guide walks you through setting up a Keycloak OIDC client and configuring Formbricks to use it, including automatic user provisioning into a default team.

### Requirements

* A running Keycloak instance with a configured realm and users.
* A self-hosted Formbricks instance with a valid [Enterprise license](https://formbricks.com/docs/self-hosting/advanced/license.md).
* 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](https://formbricks.com/docs/self-hosting/advanced/migration.md).

## Setting up Keycloak OIDC

**1. Create a new client in Keycloak**

* Log in to your Keycloak admin console.
* Select the realm you want to use (e.g., `production`).
* Navigate to **Clients** in the left menu and click **Create client**.
* Set **Client type** to `OpenID Connect`.
* Choose a **Client ID** (e.g., `formbricks`) and click **Next**.

**2. Configure client authentication**

* Enable **Client authentication** (this makes the client "confidential" and generates a client secret).
* Under **Authentication flow**, ensure **Standard flow** is enabled.
* Click **Next**.

> [!NOTE]
>
> Formbricks uses PKCE (Proof Key for Code Exchange) for added security. Modern Keycloak versions (21+) support PKCE automatically for confidential clients. No additional PKCE configuration is needed.

**3. Set the redirect URI**

* Under **Valid redirect URIs**, add your Formbricks callback URI:

```
https://your-formbricks-domain.com/api/auth/oauth2/callback/openid
```

Replace `your-formbricks-domain.com` with your actual Formbricks URL.

* Click **Save**.

**4. Copy the client secret**

* After saving, go to the **Credentials** tab of your newly created client.
* Copy the **Client secret** value — you will need this for the Formbricks configuration.

**5. Determine the issuer URL**

The OIDC issuer URL follows this pattern:

```
https://your-keycloak-domain.com/realms/your-realm-name
```

For example, if your Keycloak runs at `login.example.com` and your realm is called `production`:

```
https://login.example.com/realms/production
```

> [!NOTE]
>
> You can verify the issuer URL by navigating to `https://your-keycloak-domain.com/realms/your-realm-name/.well-known/openid-configuration` in your browser. It should return a JSON document with the OIDC discovery endpoints.

**6. Configure Formbricks environment variables**

Add the following environment variables to your Formbricks `.env` file or `docker-compose.yml`:

```yml Formbricks Env for Keycloak OIDC theme={null}
OIDC_CLIENT_ID=formbricks
OIDC_CLIENT_SECRET=your-client-secret-here
OIDC_ISSUER=https://your-keycloak-domain.com/realms/your-realm-name
OIDC_DISPLAY_NAME="Keycloak Login"
OIDC_SIGNING_ALGORITHM=RS256
```

| Variable | Description |
| - | - |
| `OIDC_CLIENT_ID` | The Client ID you chose in Keycloak (e.g., `formbricks`). |
| `OIDC_CLIENT_SECRET` | The client secret from the **Credentials** tab. |
| `OIDC_ISSUER` | Your Keycloak realm URL (see step above). |
| `OIDC_DISPLAY_NAME` | The label shown on the Formbricks login button. |
| `OIDC_SIGNING_ALGORITHM` | Optional. Keycloak and Formbricks both default to `RS256`. Only set this if your realm uses a different algorithm. |

**7. Restart and test**

* Restart your Formbricks instance.
* The login page should now display a button with your chosen `OIDC_DISPLAY_NAME`.
* Click it to authenticate through Keycloak.

> [!NOTE]
>
> To disable email/password login entirely and force all users through Keycloak, 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 allow Keycloak users to join automatically and be assigned to a team, configure the following additional environment variables:

```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 that new SSO users are automatically added to. The organization is determined from this team. |

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

### How It Works

When `AUTH_SKIP_INVITE_FOR_SSO=1` and `AUTH_SSO_DEFAULT_TEAM_ID` are both set:

1. A user authenticates through Keycloak for the first time.
2. Formbricks creates a new user account.
3. The user is automatically added as a **member** of the organization that owns the specified team.
4. The user is assigned to the default team, granting them access to all Workspaces associated with that team.

No manual invitation or admin action is required.

## Full Configuration Example

A complete `.env` configuration for Keycloak OIDC with automatic user provisioning:

```yml Complete Keycloak OIDC Configuration theme={null}
OIDC_CLIENT_ID=formbricks
OIDC_CLIENT_SECRET=your-client-secret-here
OIDC_ISSUER=https://login.example.com/realms/production
OIDC_DISPLAY_NAME="Company Login"
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 Keycloak-only authentication
# EMAIL_AUTH_DISABLED=1
```

## Troubleshooting

> [accordion] Users see 'No access to Workspaces' after login
>
> This means 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.
>
> You can verify the team exists by checking your database:
>
> ```sql theme={null}
> SELECT id, name, "organizationId" FROM "Team" WHERE id = 'your-team-id';
> ```

> [accordion] Users see 'No membership found' after login
>
> Formbricks determines the organization automatically from the `AUTH_SSO_DEFAULT_TEAM_ID` — you do not need to set a separate organization ID. If this error appears:
>
> * Verify the team specified in `AUTH_SSO_DEFAULT_TEAM_ID` exists and belongs to the correct organization.
> * Confirm your Enterprise license includes the RBAC feature (required for Teams).
> * Ensure the organization has an active billing plan that supports access control.

> [accordion] 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] Authentication fails with a redirect error
>
> * Verify the **Valid redirect URI** in your Keycloak client matches exactly: `{WEBAPP_URL}/api/auth/oauth2/callback/openid`
> * If you're on v5.1 or earlier, the path is `{WEBAPP_URL}/api/auth/callback/openid` (without `/oauth2`) instead.
> * Check that the OIDC issuer URL is reachable from your Formbricks server. You can test with:
>
> ```bash theme={null}
> curl https://your-keycloak-domain.com/realms/your-realm-name/.well-known/openid-configuration
> ```


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