docs: saml-sso (#4772)

Co-authored-by: Matthias Nannt <mail@matthiasnannt.com>

docs/development/guides/auth-and-provision/setup-saml-with-identity-providers.mdx

@@ -0,0 +1,76 @@
+---
+title: "How to setup SAML with Identity Providers"
+---
+
+### SAML Registration with Identity Providers
+
+This guide explains the settings you need to use to configure SAML with your Identity Provider. Once configured, obtain an XML metadata file and upload it on your Formbricks instance.
+
+> **Note:** Please do not add a trailing slash at the end of the URLs. Create them exactly as shown below.
+
+**Assertion consumer service URL / Single Sign-On URL / Destination URL:** https://app.formbricks.com/api/auth/saml/callback
+
+**Entity ID / Identifier / Audience URI / Audience Restriction:** [https://saml.formbricks.com](https://saml.formbricks.com)
+
+**Response:** Signed
+
+**Assertion Signature:** Signed
+
+**Signature Algorithm:** RSA-SHA256
+
+**Assertion Encryption:** Unencrypted
+
+**Mapping Attributes / Attribute Statements:**
+
+- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier -> id
+- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress -> email
+- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname -> firstName
+- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname -> lastName
+
+### SAML With Okta
+
+<Steps>
+  <Step title="Create an application with your OIDC provider">
+    For example, in Okta, once you create an account, you can click on Applications on the sidebar menu:
+    <img src="/images/development/guides/auth-and-provision/okta/okta-applications.webp" />
+  </Step>
+  <Step title="Click on Create App Integration">
+    <img src="/images/development/guides/auth-and-provision/okta/create-app-integration.webp" />
+  </Step>
+  <Step title="Select SAML 2.0 in the modal form, and click Next">
+    <img src="/images/development/guides/auth-and-provision/okta/select-saml-2.0.webp" />
+  </Step>
+  <Step title="Fill the general settings as shown and click Next">
+    <img src="/images/development/guides/auth-and-provision/okta/general-settings.webp" />
+  </Step>
+  <Step title="Fill the fields mapping as shown and click Next">
+    <img src="/images/development/guides/auth-and-provision/okta/fields-mapping.webp" />
+  </Step>
+  <Step title="Enter the SAML Integration Settings as shown and click Next">
+    <img src="/images/development/guides/auth-and-provision/okta/saml-integration-settings.webp" />
+  </Step>
+  <Step title="Check the internal app checkbox and click Finish">
+    <img src="/images/development/guides/auth-and-provision/okta/internal-app.webp" />
+  </Step>
+  <Step title="Check that the app is created successfully">
+    <img src="/images/development/guides/auth-and-provision/okta/app-created.webp" />
+  </Step>
+  <Step title="Click on the app and head over to the Assignments tab">
+    <img src="/images/development/guides/auth-and-provision/okta/assignments-tab.webp" />
+  </Step>
+  <Step title="Click on Assign button and select Assign to People">
+    <img src="/images/development/guides/auth-and-provision/okta/assign-to-people.webp" />
+  </Step>
+  <Step title="Select the users you want to assign the app to and click Assign">
+    <img src="/images/development/guides/auth-and-provision/okta/select-users.webp" />
+  </Step>
+  <Step title="Head over to the Sign On tab and scroll to the bottom to get the metadata, click on the Actions button">
+    <img src="/images/development/guides/auth-and-provision/okta/actions-button.webp" />
+  </Step>
+  <Step title="Click on View IdP metadata">
+    <img src="/images/development/guides/auth-and-provision/okta/view-idp-metadata.webp" />
+  </Step>
+  <Step title="Copy the metadata and paste it in the Formbricks SAML configuration"></Step>
+</Steps>
+
+      That's it. Now when you try to login with SSO, your application on Okta will handle the authentication.

docs/mint.json

@@ -92,7 +92,6 @@
         }
       ]
     },
-
     {
       "group": "Core Features",
       "pages": [
@@ -139,6 +138,10 @@
         "xm-and-surveys/core-features/email-customization"
       ]
     },
+    {
+      "group": "Enterprise Features",
+      "pages": ["xm-and-surveys/enterprise-features/saml-sso"]
+    },
     {
       "group": "XM",
       "pages": [
@@ -182,6 +185,16 @@
       "group": "Contribution",
       "pages": ["development/contribution/contribution"]
     },
+    {
+      "group": "Guides",
+      "pages": [
+        {
+          "group": "Auth & Provision",
+          "icon": "user-shield",
+          "pages": ["development/guides/auth-and-provision/setup-saml-with-identity-providers"]
+        }
+      ]
+    },
     {
       "group": "Support",
       "pages": ["development/support/troubleshooting"]
@@ -203,7 +216,14 @@
       "pages": [
         "self-hosting/configuration/custom-ssl",
         "self-hosting/configuration/environment-variables",
-        "self-hosting/configuration/oauth",
+        {
+          "group": "Auth & SSO",
+          "icon": "lock",
+          "pages": [
+            "self-hosting/configuration/auth-sso/oauth",
+            "self-hosting/configuration/auth-sso/saml-sso"
+          ]
+        },
         {
           "group": "Integrations",
           "icon": "bridge",

docs/self-hosting/configuration/auth-sso/saml-sso.mdx

@@ -0,0 +1,76 @@
+---
+title: "SAML SSO"
+icon: "user-shield"
+description: "How to set up SAML SSO for Formbricks"
+---
+
+<Note>You require an Enterprise License along with a SAML SSO add-on to avail this feature.</Note>
+
+## Overview
+
+Formbricks supports SAML Single Sign-On (SSO) to enable secure, centralized authentication. With SAML, organizations can integrate their existing Identity Provider (IdP) infrastructure for streamlined access management. Formbricks internally uses BoxyHQ's SAML Jackson to manage SAML connections. SAML Jackson is a service provided by BoxyHQ that manages SAML connection details and validates assertions. It is part of the Formbricks server.
+
+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
+
+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:
+
+1. **Login Initiation:**  
+   The user clicks “Sign in with SAML” on Formbricks.
+
+2. **Configuration Retrieval via BoxyHQ:**  
+   Formbricks requests the SAML connection details from BoxyHQ Jackson. BoxyHQ securely stores and manages the IdP configuration, including endpoints, certificates, and other metadata.
+
+3. **Redirection:**  
+   With the configuration details from BoxyHQ, Formbricks redirects the user to the IdP’s login page (e.g., Okta).
+
+4. **Authentication:**  
+   The user authenticates directly with the IdP.
+
+5. **SAML Response:**  
+   Upon successful authentication, the IdP sends a signed SAML response back to Formbricks via the user’s browser.
+
+6. **Validation via BoxyHQ:**  
+   BoxyHQ Jackson validates the SAML assertion—verifying the signature and extracting user details—before sending the validated data back to Formbricks.
+
+7. **Access Granted:**  
+   Formbricks logs the user in using the verified information.
+
+## SAML Authentication Flow Sequence Diagram
+
+Below is a sequence diagram illustrating the complete SAML authentication flow with BoxyHQ Jackson integrated:
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant FB as Formbricks (SP)
+    participant BHQ as BoxyHQ Jackson
+    participant OK as Okta (IdP)
+
+    Note over FB,BHQ: (Setup phase, done beforehand)<br/>1. Admin configures SAML metadata in Formbricks<br/>2. BoxyHQ stores & manages SAML connection details
+
+    U->>FB: Clicks “Sign in with SAML”
+    FB->>BHQ: Request SAML connection details
+    BHQ->>FB: Returns SAML configuration (IdP info)
+    FB->>OK: Redirect user to Okta (SAML Auth Request)
+    OK->>U: Prompts user for credentials
+    U->>OK: Submits credentials
+    OK->>FB: Sends SAML Assertion (Callback URL)
+    FB->>BHQ: Validates assertion & extracts user info
+    BHQ->>FB: Returns validated user data
+    FB->>U: Logs user into Formbricks
+
+```
+
+## Setting Up SAML SSO
+
+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 (e.g., `postgresql://postgres:@localhost:5432/formbricks-saml`). If you're using a self-signed certificate for Postgres, include the `sslmode=no-verify` parameter.
+2. **Admin Configuration:** Define the SAML administrators by setting `SAML_ADMINS` as a comma-separated list of admin emails.
+3. **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))
+4. **User Provisioning:** Provision users in your IdP and configure access to the IdP SAML app for all your users (who need access to Formbricks).
+5. **Metadata:** Keep the XML metadata from your IdP handy for the next step.
+6. **Metadata Upload:** Log in with one of the SAML admin accounts and navigate to **Organization Settings -> Single Sign-On** in Formbricks. Paste the XML metadata from your IdP into the SAML configuration section.
+7. **Finalize Setup:** Save your configuration. Provisioned users can now use SAML SSO to access Formbricks.

docs/xm-and-surveys/enterprise-features/saml-sso.mdx

@@ -0,0 +1,42 @@
+---
+title: "SAML SSO"
+icon: "user-shield"
+description: "How to set up SAML SSO for Formbricks"
+---
+
+<Note>This feature is only available with the Formbricks Enterprise plan having a SAML SSO add-on.</Note>
+
+## Overview
+
+Formbricks supports Security Assertion Markup Language (SAML) SSO. We prioritize your ease of access and security by providing robust Single Sign-On (SSO) capabilities.
+
+### Setting up SAML login
+
+<Steps>
+  <Step title='Create a SAML application with your Identity Provider (IdP)'>
+    Follow the instructions here - [SAML Setup](/development/guides/auth-and-provision/setup-saml-with-identity-providers)
+  </Step>
+  <Step title='Configure access to the IdP SAML app'>
+    Ensure that all users who need access to Formbricks have access to the IdP SAML
+    app.
+  </Step>
+  <Step title='Retrieve XML metadata from your IdP'>
+    Keep the XML metadata from your IdP accessible, as you will need it later.
+  </Step>
+  <Step title='Log in to your Organization Admin account'>
+    Visit `environments/<ENVIRONMENT_ID>/settings/sso`.
+    <img src='/images/xm-and-surveys/core-features/saml-sso/sso-settings.webp' />
+  </Step>
+  <Step title='Configure SSO with SAML'>
+    Click on the `Configure` button for `SSO with SAML`.
+    <img src='/images/xm-and-surveys/core-features/saml-sso/sso-settings-configure.webp' />
+  </Step>
+  <Step title='Paste the XML metadata and Save'>
+    In the SAML configuration section, copy and paste the XML metadata from step
+    3 and click on Save.
+    <img src='/images/xm-and-surveys/core-features/saml-sso/sso-settings-modal.webp' />
+  </Step>
+  <Step title='Your users can now log into Formbricks using SAML'>
+    Once setup is complete, provisioned users can log into Formbricks using SAML.
+  </Step>
+</Steps>

packages/lib/messages/de-DE.json

@@ -123,7 +123,6 @@
     "are_you_sure": "Bist Du sicher?",
     "are_you_sure_this_action_cannot_be_undone": "Bist Du sicher? Diese Aktion kann nicht rückgängig gemacht werden.",
     "attributes": "Attribute",
-    "automatic": "Automatisch",
     "avatar": "Avatar",
     "back": "Zurück",
     "billing": "Abrechnung",
@@ -180,7 +179,6 @@
     "edit": "Bearbeiten",
     "email": "E-Mail",
     "embed": "Einbetten",
-    "enable": "Aktivieren",
     "enterprise_license": "Enterprise Lizenz",
     "environment_not_found": "Umgebung nicht gefunden",
     "environment_notice": "Du befindest dich derzeit in der {environment}-Umgebung.",
@@ -1835,8 +1833,7 @@
         "multiple_industries": "Mehrere Branchen",
         "use_this_template": "Vorlage verwenden",
         "uses_branching_logic": "Diese Umfrage verwendet Logik."
-      },
-      "this_is_a_new_key": "Das ist ein neuer Schlüssel "
+      }
     },
     "xm-templates": {
       "ces": "CES",

packages/lib/messages/en-US.json

@@ -123,7 +123,6 @@
     "are_you_sure": "Are you sure?",
     "are_you_sure_this_action_cannot_be_undone": "Are you sure? This action cannot be undone.",
     "attributes": "Attributes",
-    "automatic": "Automatic",
     "avatar": "Avatar",
     "back": "Back",
     "billing": "Billing",
@@ -180,7 +179,6 @@
     "edit": "Edit",
     "email": "Email",
     "embed": "Embed",
-    "enable": "Enable",
     "enterprise_license": "Enterprise License",
     "environment_not_found": "Environment not found",
     "environment_notice": "You're currently in the {environment} environment.",
@@ -1835,8 +1833,7 @@
         "multiple_industries": "Multiple industries",
         "use_this_template": "Use this template",
         "uses_branching_logic": "This survey uses branching logic."
-      },
-      "this_is_a_new_key": "This is a updated key"
+      }
     },
     "xm-templates": {
       "ces": "CES",

packages/lib/messages/fr-FR.json

@@ -123,7 +123,6 @@
     "are_you_sure": "Es-tu sûr ?",
     "are_you_sure_this_action_cannot_be_undone": "Êtes-vous sûr ? Cette action ne peut pas être annulée.",
     "attributes": "Attributs",
-    "automatic": "Automatique",
     "avatar": "Avatar",
     "back": "Retour",
     "billing": "Facturation",
@@ -180,7 +179,6 @@
     "edit": "Modifier",
     "email": "Email",
     "embed": "Intégrer",
-    "enable": "Activer",
     "enterprise_license": "Licence d'entreprise",
     "environment_not_found": "Environnement non trouvé",
     "environment_notice": "Vous êtes actuellement dans l'environnement {environment}.",
@@ -1835,8 +1833,7 @@
         "multiple_industries": "Plusieurs secteurs",
         "use_this_template": "Utilisez ce modèle",
         "uses_branching_logic": "Cette enquête utilise une logique de branchement."
-      },
-      "this_is_a_new_key": "Ceci est une clé mise à jour"
+      }
     },
     "xm-templates": {
       "ces": "CES",

packages/lib/messages/pt-BR.json

@@ -123,7 +123,6 @@
     "are_you_sure": "Certeza?",
     "are_you_sure_this_action_cannot_be_undone": "Tem certeza? Essa ação não pode ser desfeita.",
     "attributes": "atributos",
-    "automatic": "Automático",
     "avatar": "Avatar",
     "back": "Voltar",
     "billing": "Faturamento",
@@ -180,7 +179,6 @@
     "edit": "Editar",
     "email": "Email",
     "embed": "incorporar",
-    "enable": "habilitar",
     "enterprise_license": "Licença Empresarial",
     "environment_not_found": "Ambiente não encontrado",
     "environment_notice": "Você está atualmente no ambiente {environment}.",
@@ -1835,8 +1833,7 @@
         "multiple_industries": "várias indústrias",
         "use_this_template": "Use esse modelo",
         "uses_branching_logic": "Essa pesquisa usa lógica de ramificação."
-      },
-      "this_is_a_new_key": "Esta é uma chave atualizada"
+      }
     },
     "xm-templates": {
       "ces": "CES",

packages/lib/messages/zh-Hant-TW.json

@@ -123,7 +123,6 @@
     "are_you_sure": "您確定嗎？",
     "are_you_sure_this_action_cannot_be_undone": "您確定嗎？此操作無法復原。",
     "attributes": "屬性",
-    "automatic": "自動",
     "avatar": "頭像",
     "back": "返回",
     "billing": "帳單",
@@ -180,7 +179,6 @@
     "edit": "編輯",
     "email": "電子郵件",
     "embed": "嵌入",
-    "enable": "啟用",
     "enterprise_license": "企業授權",
     "environment_not_found": "找不到環境",
     "environment_notice": "您目前在 '{'environment'}' 環境中。",
@@ -1835,8 +1833,7 @@
         "multiple_industries": "多個產業",
         "use_this_template": "使用此範本",
         "uses_branching_logic": "此問卷使用分支邏輯。"
-      },
-      "this_is_a_new_key": "這是一個更新的 key"
+      }
     },
     "xm-templates": {
       "ces": "CES",