SAML SSO
Configure SAML Single Sign-On (SSO) for secure enterprise authentication with your Formbricks instance.
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.
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:
-
Login Initiation:
The user clicksContinue with SAML SSO
on Formbricks. -
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. -
Redirection:
With the configuration details from BoxyHQ, Formbricks redirects the user to the IdP’s login page (e.g., Okta). -
Authentication:
The user authenticates directly with the IdP. -
SAML Response:
Upon successful authentication, the IdP sends a signed SAML response back to Formbricks via the user’s browser. -
Validation via BoxyHQ:
BoxyHQ Jackson validates the SAML assertion—verifying the signature and extracting user details—before sending the validated data back to Formbricks. -
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:
Setting Up SAML SSO
To configure SAML SSO in Formbricks, follow these steps:
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.
IdP Application
Create a SAML application in your IdP by following your provider’s instructions(SAML Setup)
User Provisioning
Provision users in your IdP and configure access to the IdP SAML app for all your users (who need access to Formbricks).
Metadata
Keep the XML metadata from your IdP handy for the next step.
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.
Restart Formbricks
Restart Formbricks to apply the changes. You can do this by running docker compose down
and then docker compose up -d
.
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.
Was this page helpful?