Skip to main content
Keycloak OIDC is part of the Formbricks Enterprise Edition
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.
  • The Formbricks callback URI: {WEBAPP_URL}/api/auth/callback/openid

​
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.
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/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
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:
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
VariableDescription
OIDC_CLIENT_IDThe Client ID you chose in Keycloak (e.g., formbricks).
OIDC_CLIENT_SECRETThe client secret from the Credentials tab.
OIDC_ISSUERYour Keycloak realm URL (see step above).
OIDC_DISPLAY_NAMEThe label shown on the Formbricks login button.
OIDC_SIGNING_ALGORITHMOptional. 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.
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:
Automatic User Provisioning
AUTH_SKIP_INVITE_FOR_SSO=1
AUTH_SSO_DEFAULT_TEAM_ID=your-team-id-here
VariableDescription
AUTH_SKIP_INVITE_FOR_SSOSet to 1 to let SSO users create an account without a manual invite.
AUTH_SSO_DEFAULT_TEAM_IDThe 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.
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 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 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:
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

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:
SELECT id, name, "organizationId" FROM "Team" WHERE id = 'your-team-id';
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.
  • 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.
  • 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:
curl https://your-keycloak-domain.com/realms/your-realm-name/.well-known/openid-configuration