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

# SAML SSO

> Configure SAML Single Sign-On (SSO) for secure enterprise authentication with your Formbricks instance.

<Note>SAML SSO is part of the Formbricks [Enterprise Edition](/self-hosting/advanced/license)</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 `Continue with SAML SSO` 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 Auth Flow Sequence Diagram

Below is a sequence diagram illustrating the complete SAML authentication flow with BoxyHQ Jackson integrated:

```mermaid theme={null}
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 “Continue with SAML SSO"
    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:

<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` (use `formbricks/apps/web/saml-connection` for development) 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
  change the `connection.xml` file, your existing SAML connection will be overwritten.
</Note>