Before
Formbricks v5.2 migrates authentication from NextAuth to Better Auth. For most self-hosted instances this is a drop-in upgrade, but if you use SSO (Azure AD / Entra ID, generic OIDC, or SAML) you must re-register the OAuth callback URL at your identity provider before the first v5.2 restart, or SSO sign-in will fail with a redirect-URI mismatch.SSO callback URL change (action required for SSO users)
Better Auth serves the OAuth2/OIDC callback at a new path:- old (NextAuth):
/api/auth/callback/{provider} - new (Better Auth):
/api/auth/oauth2/callback/{providerId}
https://your-domain.com
with your instance URL:
Google and GitHub sign-in do not change. They use Better Auth’s built-in social providers, whose
callback path (
/api/auth/callback/{provider}) is unchanged — nothing to do there.For SAML, only the Jackson connection’s redirect_uri changes. The IdP-side ACS endpoint
(/api/auth/saml/callback) is unchanged, so you do not need to reconfigure your IdP’s SAML app.Leave the old /api/auth/callback/* redirect URIs registered through the transition. Keeping them in
place is harmless and makes a rollback to v5.1 clean.OIDC: missing issuer response
A changed callback andissuer_missing are different failures. The older generic OIDC provider requires
an RFC 9207 iss response parameter that some identity providers do not send. Setting OIDC_EMAIL_CLAIM
does not fix this; it is not a supported configuration option in these releases.
- For Microsoft Entra, use the dedicated Azure AD provider. Changing providers also requires testing existing-account linking; do not switch a production provider without rehearsal.
- For generic OIDC, the 5.4 authentication update
removes the unconditional missing-
issrequirement. Verify sign-in against your actual provider. This does not disable issuer validation whenissis returned. - Keep a working administrator sign-in available during rehearsal. Capture redacted callback errors if it fails.
Authentication environment variables
Better Auth introduces two optional variables. Neither is required for a standard upgrade — both fall back to your existing NextAuth configuration:BETTER_AUTH_SECRET— cookie/session signing secret. Falls back toNEXTAUTH_SECRETwhen unset. On these releases it must be at least 32 characters when set explicitly. Use the valueNEXTAUTH_SECRETalready holds: a different one invalidates every session and every outstanding invite and verification link.BETTER_AUTH_URL— the auth base URL. Falls back toNEXTAUTH_URL(and thenWEBAPP_URL) when unset.
If your instance already sets
NEXTAUTH_SECRET and NEXTAUTH_URL (all v5.1 instances do), you can
upgrade without adding any new auth variables.DISABLE_ACCOUNT_DELETION_SSO_CONFIRMATION no longer exists. Remove it from your environment
if you set it; it now has no effect.
Optional new configuration
None of the following is required to run v5.2. Add them only if you want the associated feature.Hub enrichment (sentiment, emotion, translation)
Hub>= 0.8.0 can classify sentiment and emotion and translate feedback. These are off unless you set
a provider and model, and they run in both the Hub API and the hub-worker, so set the variables on both
services. Bump your Hub image to >= 0.8.0 (via HUB_IMAGE_REF) to pick up these features.
SENTIMENT_PROVIDER,SENTIMENT_MODEL,SENTIMENT_PROVIDER_API_KEYEMOTIONS_PROVIDER,EMOTIONS_MODEL,EMOTIONS_PROVIDER_API_KEYTRANSLATION_PROVIDER,TRANSLATION_MODEL,TRANSLATION_PROVIDER_API_KEY,TRANSLATION_DEFAULT_LANGUAGE
openai, google (AI Studio, needs *_PROVIDER_API_KEY), and google-gemini
(Vertex, needs *_GOOGLE_CLOUD_PROJECT / *_LOCATION plus Application Default Credentials).
AI taxonomy (beta)
An optional standalone taxonomy service, enabled in Docker Compose withCOMPOSE_PROFILES=taxonomy. It
shares an internal token with Hub:
TAXONOMY_SERVICE_URL(the internal URL to the taxonomy service)HUB_INTERNAL_API_TOKEN,TAXONOMY_SERVICE_TOKEN(strong random secrets)TAXONOMY_LLM_PROVIDER/TAXONOMY_LLM_MODEL/TAXONOMY_LLM_BASE_URL/TAXONOMY_LLM_API_KEY(openai-compatibleby default;bedrockandvertex-geminialso supported)TAXONOMY_IMAGE_REFto pin a released image (e.g.:v0.1.0)
openssl rand -hex 32, then store it in the protected environment file or Secret consumed by those services.
Use COMPOSE_PROFILES=qwen,taxonomy to back it with the bundled Qwen/vLLM service.
Bundled Qwen / vLLM runtime
Docker Compose can now run a bundled OpenAI-compatible LLM for self-hosted AI features withCOMPOSE_PROFILES=qwen. Tunable via QWEN_VLLM_IMAGE, QWEN_MODEL_ID, QWEN_SERVED_MODEL_NAME,
QWEN_MAX_MODEL_LEN, QWEN_MAX_NUM_SEQS, QWEN_GPU_MEMORY_UTILIZATION, QWEN_VLLM_HOST, and
QWEN_VLLM_PORT.
OpenTelemetry log export
OTEL_LOGS_ENABLED=1— export Pino application logs via OTLP (off by default; also needsOTEL_EXPORTER_OTLP_ENDPOINT).
During
The credential-account backfill runs in the normal application migration runner; no separate SQL step is needed. On Compose, runformbricks-migrate before Hub migrations and app startup, as shown below.
Use the 4.x/5.x maintenance procedure with the selected release’s assets.
Add the new SSO callbacks before restart and keep the old ones registered for recovery. Run the target’s
application and Hub migrations before starting services; stop on errors.
After
- Sign in with an existing user through every configured SSO provider, plus password/2FA where enabled.
- Verify API keys, MCP OAuth and feedback-source connections. Language codes are canonicalized by a data migration; check integrations that compare stored locale values.
- Run the shared acceptance checks, including old uploads.