mirror/formbricks-formbricks
1
0
Fork 0
mirror of https://github.com/formbricks/formbricks.git synced 2025-12-21 13:40:31 -06:00
Code Issues Packages Projects Releases 100 Wiki Activity

docs: tweak docs for sso (#4974)

Browse Source
This commit is contained in:
Johannes
2025-03-17 06:46:54 -07:00
committed by GitHub
parent e5ce6532f5
commit 3dea241d7a
6 changed files with 266 additions and 218 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/mint.json
View File

@@ -262,7 +262,9 @@
"group": "Auth & SSO",
"icon": "lock",
"pages": [
"self-hosting/configuration/auth-sso/oauth",
"self-hosting/configuration/auth-sso/open-id-connect",
"self-hosting/configuration/auth-sso/azure-ad-oauth",
"self-hosting/configuration/auth-sso/google-oauth",
"self-hosting/configuration/auth-sso/saml-sso"
]
},

109
docs/self-hosting/configuration/auth-sso/azure-ad-oauth.mdx Normal file
View File

@@ -0,0 +1,109 @@
---
title: Azure AD OAuth
description: "Configure Microsoft Entra ID (Azure AD) OAuth for secure Single Sign-On with your Formbricks instance. Use enterprise-grade authentication for your survey platform."
icon: "microsoft"
---
<Note>
Single Sign-On (SSO) functionality, including OAuth integrations with Google, Microsoft Azure AD, and OpenID Connect, requires is part of the [Enterprise Edition](/self-hosting/advanced/license).
</Note>
### Microsoft Entra ID
Do you have a Microsoft Entra ID Tenant? Integrate it with your Formbricks instance to allow users to log in using their existing Microsoft credentials. This guide will walk you through the process of setting up an Application Registration for your Formbricks instance.
### Requirements
- A Microsoft Entra ID Tenant populated with users. [Create a tenant as per Microsoft's documentation](https://learn.microsoft.com/en-us/entra/fundamentals/create-new-tenant).
- A Formbricks instance running and accessible.
- The callback URI for your Formbricks instance: `{WEBAPP_URL}/api/auth/callback/azure-ad`
## How to connect your Formbricks instance to Microsoft Entra
<Steps>
<Step title="Access the Microsoft Entra admin center">
- Login to the [Microsoft Entra admin center](https://entra.microsoft.com/).
- Go to **Applications** > **App registrations** in the left menu.
![first](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250153/image_tobdth.jpg)
</Step>
<Step title="Create a new app registration">
- Click the **New registration** button at the top.
![second](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250228/image_dmz75t.jpg)
</Step>
<Step title="Configure the application">
- Name your application something descriptive, such as `Formbricks SSO`.
![third](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250292/image_rooa3w.jpg)
- If you have multiple tenants/organizations, choose the appropriate **Supported account types** option. Otherwise, leave the default option for _Single Tenant_.
![fourth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250542/image_nyndzo.jpg)
- Under **Redirect URI**, select **Web** for the platform and paste your Formbricks callback URI (see Requirements above).
![fifth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250776/image_s3pgb6.jpg)
- Click **Register** to create the App registration. You will be redirected to your new app's _Overview_ page after it is created.
</Step>
<Step title="Collect application credentials">
- On the _Overview_ page, under **Essentials**:
- Copy the entry for **Application (client) ID** to populate the `AZUREAD_CLIENT_ID` variable.
- Copy the entry for **Directory (tenant) ID** to populate the `AZUREAD_TENANT_ID` variable.
![sixth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250876/image_dj2vi5.jpg)
</Step>
<Step title="Create a client secret">
- From your App registration's _Overview_ page, go to **Manage** > **Certificates & secrets**.
![seventh](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250913/image_p4zknw.jpg)
- Make sure you have the **Client secrets** tab active, and click **New client secret**.
![eighth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250973/image_kyjray.jpg)
- Enter a **Description**, set an **Expires** period, then click **Add**.
<Note>
You will need to create a new client secret using these steps whenever your chosen expiry period ends.
</Note>
![ninth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738251467/image_bkirq4.jpg)
- Copy the entry under **Value** to populate the `AZUREAD_CLIENT_SECRET` variable.
<Note>
Microsoft will only show this value to you immediately after creation, and you will not be able to access it again. If you lose it, simply create a new secret.
</Note>
![tenth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738251234/image_jen6tp.jpg)
</Step>
<Step title="Update environment variables">
- Update these environment variables in your `docker-compose.yml` or pass it like your other environment variables to the Formbricks container.
<Note>
You must wrap the `AZUREAD_CLIENT_SECRET` value in double quotes (e.g., "THis~iS4faKe.53CreTvALu3"`) to prevent issues with special characters.
</Note>
An example `.env` for Microsoft Entra ID in Formbricks would look like this:
```yml Formbricks Env for Microsoft Entra ID SSO
AZUREAD_CLIENT_ID=a25cadbd-f049-4690-ada3-56a163a72f4c
AZUREAD_TENANT_ID=2746c29a-a3a6-4ea1-8762-37816d4b7885
AZUREAD_CLIENT_SECRET="THis~iS4faKe.53CreTvALu3"
```
</Step>
<Step title="Restart and test">
- Restart your Formbricks instance.
- You're all set! Users can now sign up & log in using their Microsoft credentials associated with your Entra ID Tenant.
</Step>
</Steps>

81
docs/self-hosting/configuration/auth-sso/google-oauth.mdx Normal file
View File

@@ -0,0 +1,81 @@
---
title: "Google OAuth"
description: "Configure Google OAuth for secure Single Sign-On with your Formbricks instance. Implement enterprise-grade authentication for your survey platform with Google credentials."
icon: "google"
---
<Note>
Single Sign-On (SSO) functionality, including OAuth integrations with Google, Microsoft Azure AD, and OpenID Connect, requires is part of the [Enterprise Edition](/self-hosting/advanced/license).
</Note>
### Google OAuth
Integrating Google OAuth with your Formbricks instance allows users to log in using their Google credentials, ensuring a secure and streamlined user experience. This guide will walk you through the process of setting up Google OAuth for your Formbricks instance.
### Requirements
- A Google Cloud Platform (GCP) account
- A Formbricks instance running
### How to connect your Formbricks instance to Google
<Steps>
<Step title="Create a GCP Project">
- Navigate to the [GCP Console](https://console.cloud.google.com/).
- From the projects list, select a project or create a new one.
</Step>
<Step title="Setting up OAuth 2.0">
- If the **APIs & services** page isn't already open, open the console left side menu and select **APIs & services**.
- On the left, click **Credentials**.
- Click **Create Credentials**, then select **OAuth client ID**.
</Step>
<Step title="Configure OAuth Consent Screen">
- If this is your first time creating a client ID, configure your consent screen by clicking **Consent Screen**.
- Fill in the necessary details and under **Authorized domains**, add the domain where your Formbricks instance is hosted.
</Step>
<Step title="Create OAuth 2.0 Client IDs">
- Select the application type **Web application** for your project and enter any additional information required.
- Ensure to specify authorized JavaScript origins and authorized redirect URIs.
```
Authorized JavaScript origins: {WEBAPP_URL}
Authorized redirect URIs: {WEBAPP_URL}/api/auth/callback/google
```
</Step>
<Step title="Update Environment Variables in Docker">
- To integrate the Google OAuth, you have two options: either update the environment variables in the docker-compose file or directly add them to the running container.
- In your Docker setup directory, open the `.env` file, and add or update the following lines with the `Client ID` and `Client Secret` obtained from Google Cloud Platform:
```sh
GOOGLE_CLIENT_ID=your-client-id-here
GOOGLE_CLIENT_SECRET=your-client-secret-here
```
- Alternatively, you can add the environment variables directly to the running container using the following commands (replace `container_id` with your actual Docker container ID):
```sh
docker exec -it container_id /bin/bash
export GOOGLE_CLIENT_ID=your-client-id-here
export GOOGLE_CLIENT_SECRET=your-client-secret-here
exit
```
</Step>
<Step title="Restart Your Formbricks Instance">
<Note>
Restarting your Docker containers may cause a brief period of downtime. Plan accordingly.
</Note>
- Once the environment variables have been updated, it's crucial to restart your Docker containers to apply the changes. This ensures that your Formbricks instance can utilize the new Google OAuth configuration for user authentication.
- Navigate to your Docker setup directory where your `docker-compose.yml` file is located.
- Run the following command to bring down your current Docker containers and then bring them back up with the updated environment configuration.
</Step>
</Steps>

208
docs/self-hosting/configuration/auth-sso/oauth.mdx
View File

@@ -1,208 +0,0 @@
---
title: OAuth
description: "OAuth for Formbricks"
icon: "key"
---
<Note>
Single Sign-On (SSO) functionality, including OAuth integrations with Google, Microsoft Entra ID, Github and OpenID Connect, requires a valid Formbricks Enterprise License.
</Note>
### Google OAuth
Integrating Google OAuth with your Formbricks instance allows users to log in using their Google credentials, ensuring a secure and streamlined user experience. This guide will walk you through the process of setting up Google OAuth for your Formbricks instance.
#### Requirements:
- A Google Cloud Platform (GCP) account.
- A Formbricks instance running and accessible.
#### Steps:
1. **Create a GCP Project**:
- Navigate to the [GCP Console](https://console.cloud.google.com/).
- From the projects list, select a project or create a new one.
2. **Setting up OAuth 2.0**:
- If the **APIs & services** page isn't already open, open the console left side menu and select **APIs & services**.
- On the left, click **Credentials**.
- Click **Create Credentials**, then select **OAuth client ID**.
3. **Configure OAuth Consent Screen**:
- If this is your first time creating a client ID, configure your consent screen by clicking **Consent Screen**.
- Fill in the necessary details and under **Authorized domains**, add the domain where your Formbricks instance is hosted.
4. **Create OAuth 2.0 Client IDs**:
- Select the application type **Web application** for your project and enter any additional information required.
- Ensure to specify authorized JavaScript origins and authorized redirect URIs.
```{{ Redirect & Origin URLs
Authorized JavaScript origins: {WEBAPP_URL}
Authorized redirect URIs: {WEBAPP_URL}/api/auth/callback/google
```
- **Update Environment Variables in Docker**:
- To integrate the Google OAuth, you have two options: either update the environment variables in the docker-compose file or directly add them to the running container.
- In your Docker setup directory, open the `.env` file, and add or update the following lines with the `Client ID` and `Client Secret` obtained from Google Cloud Platform:
- Alternatively, you can add the environment variables directly to the running container using the following commands (replace `container_id` with your actual Docker container ID):
```sh Shell commands
docker exec -it container_id /bin/bash
export GOOGLE_CLIENT_ID=your-client-id-here
export GOOGLE_CLIENT_SECRET=your-client-secret-here
exit
```
```sh env file
GOOGLE_CLIENT_ID=your-client-id-here
GOOGLE_CLIENT_SECRET=your-client-secret-here
```
1. **Restart Your Formbricks Instance**:
- **Note:** Restarting your Docker containers may cause a brief period of downtime. Plan accordingly.
- Once the environment variables have been updated, it's crucial to restart your Docker containers to apply the changes. This ensures that your Formbricks instance can utilize the new Google OAuth configuration for user authentication. Here's how you can do it:
- Navigate to your Docker setup directory where your `docker-compose.yml` file is located.
- Run the following command to bring down your current Docker containers and then bring them back up with the updated environment configuration:
### Microsoft Entra ID (Azure Active Directory) SSO OAuth
Do you have a Microsoft Entra ID Tenant? Integrate it with your Formbricks instance to allow users to log in using their existing Microsoft credentials. This guide will walk you through the process of setting up an Application Registration for your Formbricks instance.
#### Requirements
- A Microsoft Entra ID Tenant populated with users. [Create a tenant as per Microsoft's documentation](https://learn.microsoft.com/en-us/entra/fundamentals/create-new-tenant).
- A Formbricks instance running and accessible.
- The callback URI for your Formbricks instance: `{WEBAPP_URL}/api/auth/callback/azure-ad`
#### Creating an App Registration
- Login to the [Microsoft Entra admin center](https://entra.microsoft.com/).
- Go to **Applications** > **App registrations** in the left menu.
![first](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250153/image_tobdth.jpg)
- Click the **New registration** button at the top.
![second](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250228/image_dmz75t.jpg)
- Name your application something descriptive, such as `Formbricks SSO`.
![third](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250292/image_rooa3w.jpg)
- If you have multiple tenants/organizations, choose the appropriate **Supported account types** option. Otherwise, leave the default option for _Single Tenant_.
![fourth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250542/image_nyndzo.jpg)
- Under **Redirect URI**, select **Web** for the platform and paste your Formbricks callback URI (see Requirements above).
![fifth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250776/image_s3pgb6.jpg)
- Click **Register** to create the App registration. You will be redirected to your new app's _Overview_ page after it is created.
- On the _Overview_ page, under **Essentials**:
- Copy the entry for **Application (client) ID** to populate the `AZUREAD_CLIENT_ID` variable.
- Copy the entry for **Directory (tenant) ID** to populate the `AZUREAD_TENANT_ID` variable.
![sixth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250876/image_dj2vi5.jpg)
- From your App registration's _Overview_ page, go to **Manage** > **Certificates & secrets**.
![seventh](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250913/image_p4zknw.jpg)
- Make sure you have the **Client secrets** tab active, and click **New client secret**.
![eighth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250973/image_kyjray.jpg)
- Enter a **Description**, set an **Expires** period, then click **Add**.
<Note>
You will need to create a new client secret using these steps whenever your chosen expiry period ends.
</Note>
![ninth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738251467/image_bkirq4.jpg)
- Copy the entry under **Value** to populate the `AZUREAD_CLIENT_SECRET` variable.
<Note>
Microsoft will only show this value to you immediately after creation, and you will not be able to access it again. If you lose it, simply start from step 9 to create a new secret.
</Note>
![tenth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738251234/image_jen6tp.jpg)
- Update these environment variables in your `docker-compose.yml` or pass it like your other environment variables to the Formbricks container.
<Note>
You must wrap the `AZUREAD_CLIENT_SECRET` value in double quotes (e.g., "THis~iS4faKe.53CreTvALu3"`) to prevent issues with special characters.
</Note>
An example `.env` for Microsoft Entra ID in Formbricks would look like:
```yml Formbricks Env for Microsoft Entra ID SSO
AZUREAD_CLIENT_ID=a25cadbd-f049-4690-ada3-56a163a72f4c
AZUREAD_TENANT_ID=2746c29a-a3a6-4ea1-8762-37816d4b7885
AZUREAD_CLIENT_SECRET="THis~iS4faKe.53CreTvALu3"
```
- Restart your Formbricks instance.
- You're all set! Users can now sign up & log in using their Microsoft credentials associated with your Entra ID Tenant.
## OpenID Configuration
Integrating your own OIDC (OpenID Connect) instance with your Formbricks instance allows users to log in using their OIDC credentials, ensuring a secure and streamlined user experience. Please follow the steps below to set up OIDC for your Formbricks instance.
- Configure your OIDC provider & get the following variables:
- `OIDC_CLIENT_ID`
- `OIDC_CLIENT_SECRET`
- `OIDC_ISSUER`
- `OIDC_SIGNING_ALGORITHM`
<Note>
Make sure the Redirect URI for your OIDC Client is set to `{WEBAPP_URL}/api/auth/callback/openid`.
</Note>
- Update these environment variables in your `docker-compose.yml` or pass it directly to the running container.
An example configuration for a FusionAuth OpenID Connect in Formbricks would look like:
```yml Formbricks Env for FusionAuth OIDC
OIDC_CLIENT_ID=59cada54-56d4-4aa8-a5e7-5823bbe0e5b7
OIDC_CLIENT_SECRET=4f4dwP0ZoOAqMW8fM9290A7uIS3E8Xg29xe1umhlB_s
OIDC_ISSUER=http://localhost:9011
OIDC_DISPLAY_NAME=FusionAuth
OIDC_SIGNING_ALGORITHM=HS256
```
- Set an environment variable `OIDC_DISPLAY_NAME` to the display name of your OIDC provider.
- Restart your Formbricks instance.
- You're all set! Users can now sign up & log in using their OIDC credentials.

45
docs/self-hosting/configuration/auth-sso/open-id-connect.mdx Normal file
View File

@@ -0,0 +1,45 @@
---
title: "Open ID Connect"
description: "Configure Open ID Connect for secure Single Sign-On with your Formbricks instance. Implement enterprise-grade authentication for your survey platform with Open ID Connect."
icon: "key"
---
<Note>
Single Sign-On (SSO) functionality, including OAuth integrations with Google, Microsoft Azure AD, and OpenID Connect, requires is part of the [Enterprise Edition](/self-hosting/advanced/license).
</Note>
Integrating your own OIDC (OpenID Connect) instance with your Formbricks instance allows users to log in using their OIDC credentials, ensuring a secure and streamlined user experience. Please follow the steps below to set up OIDC for your Formbricks instance.
- Configure your OIDC provider & get the following variables:
- `OIDC_CLIENT_ID`
- `OIDC_CLIENT_SECRET`
- `OIDC_ISSUER`
- `OIDC_SIGNING_ALGORITHM`
<Note>
Make sure the Redirect URI for your OIDC Client is set to `{WEBAPP_URL}/api/auth/callback/openid`.
</Note>
- Update these environment variables in your `docker-compose.yml` or pass it directly to the running container.
An example configuration for a FusionAuth OpenID Connect in Formbricks would look like:
```yml Formbricks Env for FusionAuth OIDC
OIDC_CLIENT_ID=59cada54-56d4-4aa8-a5e7-5823bbe0e5b7
OIDC_CLIENT_SECRET=4f4dwP0ZoOAqMW8fM9290A7uIS3E8Xg29xe1umhlB_s
OIDC_ISSUER=http://localhost:9011
OIDC_DISPLAY_NAME=FusionAuth
OIDC_SIGNING_ALGORITHM=HS256
```
- Set an environment variable `OIDC_DISPLAY_NAME` to the display name of your OIDC provider.
- Restart your Formbricks instance.
- You're all set! Users can now sign up & log in using their OIDC credentials.

37
docs/self-hosting/configuration/auth-sso/saml-sso.mdx
View File

@@ -1,7 +1,7 @@
---
title: "SAML SSO"
icon: "user-shield"
description: "How to set up SAML SSO for Formbricks"
description: "Configure SAML Single Sign-On (SSO) for secure enterprise authentication with your Formbricks instance."
---
<Note>You require an Enterprise License along with a SAML SSO add-on to avail this feature.</Note>
@@ -12,7 +12,7 @@ Formbricks supports SAML Single Sign-On (SSO) to enable secure, centralized auth
To learn more about SAML Jackson, please refer to the [BoxyHQ SAML Jackson documentation](https://boxyhq.com/docs/jackson/deploy).
## How SAML Works in Formbricks
## How SAML works in Formbricks
SAML (Security Assertion Markup Language) is an XML-based standard for exchanging authentication and authorization data between an Identity Provider (IdP) and Formbricks. Here's how the integration works with BoxyHQ Jackson embedded into the flow:
@@ -37,7 +37,7 @@ SAML (Security Assertion Markup Language) is an XML-based standard for exchangin
7. **Access Granted:**
Formbricks logs the user in using the verified information.
## SAML Authentication Flow Sequence Diagram
## SAML Auth Flow Sequence Diagram
Below is a sequence diagram illustrating the complete SAML authentication flow with BoxyHQ Jackson integrated:
@@ -67,12 +67,31 @@ sequenceDiagram
To configure SAML SSO in Formbricks, follow these steps:
1. **Database Setup:** Configure a dedicated database for SAML by setting the `SAML_DATABASE_URL` environment variable in your `docker-compose.yml` file (e.g., `postgres://postgres:postgres@postgres:5432/formbricks-saml`). If you're using a self-signed certificate for Postgres, include the `sslmode=disable` parameter.
2. **IdP Application:** Create a SAML application in your IdP by following your provider's instructions([SAML Setup](/development/guides/auth-and-provision/setup-saml-with-identity-providers))
3. **User Provisioning:** Provision users in your IdP and configure access to the IdP SAML app for all your users (who need access to Formbricks).
4. **Metadata:** Keep the XML metadata from your IdP handy for the next step.
5. **Metadata Setup:** Create a file called `connection.xml` in your self-hosted Formbricks instance's `formbricks/saml-connection` directory and paste the XML metadata from your IdP into it. Please create the directory if it doesn't exist. Your metadata file should start with a tag like this: `<?xml version="1.0" encoding="UTF-8"?><...>` or `<md:EntityDescriptor entityID="...">`. Please remove any extra text from the metadata.
6. **Restart Formbricks:** Restart Formbricks to apply the changes. You can do this by running `docker compose down` and then `docker compose up -d`.
<Steps>
<Step title="Database Setup">
Configure a dedicated database for SAML by setting the `SAML_DATABASE_URL` environment variable in your `docker-compose.yml` file (e.g., `postgres://postgres:postgres@postgres:5432/formbricks-saml`). If you're using a self-signed certificate for Postgres, include the `sslmode=disable` parameter.
</Step>
<Step title="IdP Application">
Create a SAML application in your IdP by following your provider's instructions([SAML Setup](/development/guides/auth-and-provision/setup-saml-with-identity-providers))
</Step>
<Step title="User Provisioning">
Provision users in your IdP and configure access to the IdP SAML app for all your users (who need access to Formbricks).
</Step>
<Step title="Metadata">
Keep the XML metadata from your IdP handy for the next step.
</Step>
<Step title="Metadata Setup">
Create a file called `connection.xml` in your self-hosted Formbricks instance's `formbricks/saml-connection` directory and paste the XML metadata from your IdP into it. Please create the directory if it doesn't exist. Your metadata file should start with a tag like this: `<?xml version="1.0" encoding="UTF-8"?><...>` or `<md:EntityDescriptor entityID="...">`. Please remove any extra text from the metadata.
</Step>
<Step title="Restart Formbricks">
Restart Formbricks to apply the changes. You can do this by running `docker compose down` and then `docker compose up -d`.
</Step>
</Steps>
<Note>
We don't support multiple SAML connections yet. You can only have one SAML connection at a time. If you