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

# 5.2: Upgrade guide

> Update SSO callbacks and verify existing accounts after the authentication change.

**Applies to:** installations crossing 5.2, both editions; SSO-specific actions apply to Enterprise.
Also read [5.0](https://formbricks.com/docs/self-hosting/upgrade/versions/5.0.md) and [5.1](https://formbricks.com/docs/self-hosting/upgrade/versions/5.1.md) when coming from v4.
Use the [upgrade-path table](https://formbricks.com/docs/self-hosting/upgrade/paths.md) to choose a target patch.

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

> [!WARNING]
>
> All users are signed out once when you upgrade to v5.2. Better Auth takes over session handling and
> there is no dual-read from the old NextAuth sessions, so the cutover is a one-time forced re-login.
> Passwords are preserved — existing credential hashes are migrated automatically, so no password reset
> is needed.

### 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}`

Update the redirect / callback URIs at your identity provider to the new path. Replace `https://your-domain.com`
with your instance URL:

| Provider | Where to update | New callback URL |
| - | - | - |
| Azure AD / Entra ID | Azure portal -> App registration -> Authentication -> Redirect URIs | `https://your-domain.com/api/auth/oauth2/callback/azuread` |
| Generic OIDC | At your OIDC provider | `https://your-domain.com/api/auth/oauth2/callback/openid` |
| SAML (BoxyHQ / Jackson) | The Jackson connection's `redirect_uri` | `https://your-domain.com/api/auth/oauth2/callback/saml` |

> [!NOTE]
>
> **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 and `issuer_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](https://formbricks.com/docs/self-hosting/configuration/auth-sso/azure-ad-oauth.md).
  Changing providers also requires testing existing-account linking; do not switch a production provider without rehearsal.
* For generic OIDC, the [5.4 authentication update](https://formbricks.com/docs/self-hosting/upgrade/versions/5.4-authentication.md)
  removes the unconditional missing-`iss` requirement. Verify
  sign-in against your actual provider. This does not disable issuer validation when `iss` is 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 to `NEXTAUTH_SECRET` when unset. On
  these releases it must be at least 32 characters when set explicitly. Use the value `NEXTAUTH_SECRET`
  already holds: a *different* one invalidates every session and every outstanding invite and
  verification link.
* `BETTER_AUTH_URL` — the auth base URL. Falls back to `NEXTAUTH_URL` (and then `WEBAPP_URL`) when unset.

> [!NOTE]
>
> If your instance already sets `NEXTAUTH_SECRET` and `NEXTAUTH_URL` (all v5.1 instances do), you can
> upgrade without adding any new auth variables.

**Removed:** `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_KEY`
* `EMOTIONS_PROVIDER`, `EMOTIONS_MODEL`, `EMOTIONS_PROVIDER_API_KEY`
* `TRANSLATION_PROVIDER`, `TRANSLATION_MODEL`, `TRANSLATION_PROVIDER_API_KEY`, `TRANSLATION_DEFAULT_LANGUAGE`

Supported providers: `openai`, `google` (AI Studio, needs `*_PROVIDER_API_KEY`), and `google-gemini`
(Vertex, needs `*_GOOGLE_CLOUD_PROJECT` / `*_LOCATION` plus Application Default Credentials).

> [!WARNING]
>
> A provider set **without** its required credentials crash-loops both Hub containers on startup — it does
> not degrade gracefully. Set the credentials, or leave the provider unset.

#### AI taxonomy (beta)

An optional standalone taxonomy service, enabled in Docker Compose with `COMPOSE_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-compatible` by default; `bedrock` and `vertex-gemini` also supported)
* `TAXONOMY_IMAGE_REF` to pin a released image (e.g. `:v0.1.0`)

Use the target release’s [taxonomy setup](https://formbricks.com/docs/self-hosting/configuration/ai-deployment.md) for the service and
secret bindings; do not enable the profile with empty tokens. Generate each missing token with
`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 with
`COMPOSE_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 needs
  `OTEL_EXPORTER_OTLP_ENDPOINT`).

## During

The credential-account backfill runs in the normal application migration runner; no separate SQL step is
needed. On Compose, run `formbricks-migrate` before Hub migrations and app startup, as shown below.

Use the [4.x/5.x maintenance procedure](https://formbricks.com/docs/self-hosting/upgrade/legacy.md) 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](https://formbricks.com/docs/self-hosting/upgrade/rehearse.md#acceptance-at-every-stop), including old uploads.

## Recovery

Keeping the old callback registered allows the identity provider to redirect to an older deployment,
but does not undo the authentication database migration. Restore coordinated data and matching images
when needed; do not describe a callback change alone as proof that an image-only rollback is safe.
See [backup and restore](https://formbricks.com/docs/self-hosting/operate/backup-restore.md).

Source: [5.1.5 → 5.2.0](https://github.com/formbricks/formbricks/compare/5.1.5...5.2.0).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.