mirror of
https://github.com/formbricks/formbricks.git
synced 2026-04-22 21:48:45 -05:00
docs: add keycloack docs (#7440)
This commit is contained in:
Harsh Bhat
@@ -240,6 +240,7 @@
|
||||
"pages": [
|
||||
"self-hosting/auth-behavior",
|
||||
"self-hosting/configuration/auth-sso/open-id-connect",
|
||||
"self-hosting/configuration/auth-sso/keycloak-oidc",
|
||||
"self-hosting/configuration/auth-sso/azure-ad-oauth",
|
||||
"self-hosting/configuration/auth-sso/google-oauth",
|
||||
"self-hosting/configuration/auth-sso/saml-sso"
|
||||
|
||||
@@ -61,6 +61,7 @@ For more information on SSO setup, see:
|
||||
- [Google OAuth](./configuration/auth-sso/google-oauth)
|
||||
- [Azure AD OAuth](./configuration/auth-sso/azure-ad-oauth)
|
||||
- [Open ID Connect](./configuration/auth-sso/open-id-connect)
|
||||
- [Keycloak OIDC](./configuration/auth-sso/keycloak-oidc)
|
||||
- [SAML SSO](./configuration/auth-sso/saml-sso)
|
||||
|
||||
<Note>
|
||||
|
||||
@@ -0,0 +1,191 @@
|
||||
---
|
||||
title: "Keycloak OIDC"
|
||||
description: "Configure Keycloak as an OpenID Connect (OIDC) provider for secure Single Sign-On with your self-hosted Formbricks instance."
|
||||
icon: "key-skeleton-left-right"
|
||||
---
|
||||
|
||||
<Note>Keycloak OIDC is part of the Formbricks [Enterprise Edition](/self-hosting/advanced/license)</Note>
|
||||
|
||||
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](/self-hosting/advanced/license).
|
||||
- The Formbricks callback URI: `{WEBAPP_URL}/api/auth/callback/openid`
|
||||
|
||||
## Setting up Keycloak OIDC
|
||||
|
||||
<Steps>
|
||||
<Step title="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**.
|
||||
</Step>
|
||||
|
||||
<Step title="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.
|
||||
</Note>
|
||||
</Step>
|
||||
|
||||
<Step title="Set the redirect URI">
|
||||
- Under **Valid redirect URIs**, add your Formbricks callback URI:
|
||||
|
||||
```
|
||||
https://your-formbricks-domain.com/api/auth/callback/openid
|
||||
```
|
||||
|
||||
Replace `your-formbricks-domain.com` with your actual Formbricks URL.
|
||||
|
||||
- Click **Save**.
|
||||
</Step>
|
||||
|
||||
<Step title="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.
|
||||
</Step>
|
||||
|
||||
<Step title="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.
|
||||
</Note>
|
||||
</Step>
|
||||
|
||||
<Step title="Configure Formbricks environment variables">
|
||||
Add the following environment variables to your Formbricks `.env` file or `docker-compose.yml`:
|
||||
|
||||
```yml Formbricks Env for Keycloak OIDC
|
||||
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. |
|
||||
</Step>
|
||||
|
||||
<Step title="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.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
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 **Organization Settings** → **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 in Organization Settings, contact [Formbricks support](mailto:support@formbricks.com) to enable it.
|
||||
</Note>
|
||||
|
||||
### 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 projects 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
|
||||
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
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="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 project via **Project Teams** settings.
|
||||
|
||||
You can verify the team exists by checking your database:
|
||||
```sql
|
||||
SELECT id, name, "organizationId" FROM "Team" WHERE id = 'your-team-id';
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="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>
|
||||
|
||||
<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="Authentication fails with a redirect error">
|
||||
- Verify the **Valid redirect URI** in your Keycloak client matches exactly: `{WEBAPP_URL}/api/auth/callback/openid`
|
||||
- Check that the OIDC issuer URL is reachable from your Formbricks server. You can test with:
|
||||
```bash
|
||||
curl https://your-keycloak-domain.com/realms/your-realm-name/.well-known/openid-configuration
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
Reference in New Issue
Block a user