diff --git a/references/workspace/scim-integration.mdx b/references/workspace/scim-integration.mdx
index 9451c757..0dea63fd 100644
--- a/references/workspace/scim-integration.mdx
+++ b/references/workspace/scim-integration.mdx
@@ -27,11 +27,16 @@ SCIM_ENABLED=true
```
- **Important:** When using SCIM with SSO, you should also enable the `AUTH_ENABLE_OIDC_TO_EMAIL_LINKING` environment variable. This allows linking OIDC identity to an existing user by email. Without this setting, Lightdash will attempt to create a new user when they sign in via SSO, which will fail if the user was already provisioned via SCIM.
+ **Important:** When using SCIM with SSO, you must also enable **Link SSO logins to existing accounts by email**. Without it, Lightdash will try to create a new user when a SCIM-provisioned user first signs in via SSO, and the login will fail.
- ```bash
- AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true
- ```
+ Enable it in one of two ways:
+
+ - **Admin panel** (recommended, available on Cloud and self-hosted): organization admins can toggle it under **Settings** → **Organization settings** → **Single sign-on** → **Account linking**. See [SSO account linking](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#sso-account-linking).
+ - **Environment variable** (self-hosted only) — sets the instance-wide default:
+
+ ```bash
+ AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true
+ ```
## SCIM Setup within Lightdash
diff --git a/self-host/customize-deployment/environment-variables.mdx b/self-host/customize-deployment/environment-variables.mdx
index 117d144c..26cdbb6d 100644
--- a/self-host/customize-deployment/environment-variables.mdx
+++ b/self-host/customize-deployment/environment-variables.mdx
@@ -109,8 +109,8 @@ These variables enable you to control Single Sign On (SSO) functionality.
| :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AUTH_DISABLE_PASSWORD_AUTHENTICATION` | If "true" disables signing in with plain passwords (default=false) |
| `AUTH_ENABLE_GROUP_SYNC` | If "true" enables assigning SSO groups to Lightdash groups (default=false) |
-| `AUTH_ENABLE_OIDC_LINKING` | Enables linking a new OIDC identity to an existing user if they already have another OIDC with the same email (default=false) |
-| `AUTH_ENABLE_OIDC_TO_EMAIL_LINKING` | Enables linking OIDC identity to an existing user by email. Required when using [SCIM](/references/workspace/scim-integration) with SSO (default=false) |
+| `AUTH_ENABLE_OIDC_LINKING` | Instance-wide default for linking a new OIDC identity to an existing user if they already have another OIDC with the same email. Organization admins can override this per-org from [SSO account linking](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#sso-account-linking) (default=false) |
+| `AUTH_ENABLE_OIDC_TO_EMAIL_LINKING` | Instance-wide default for linking OIDC identity to an existing user by email. Required when using [SCIM](/references/workspace/scim-integration) with SSO. Organization admins can override this per-org from [SSO account linking](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#sso-account-linking) (default=false) |
| `AUTH_GOOGLE_OAUTH2_CLIENT_ID` | Required for Google SSO |
| `AUTH_GOOGLE_OAUTH2_CLIENT_SECRET` | Required for Google SSO |
| `AUTH_OKTA_OAUTH_CLIENT_ID` | Required for Okta SSO |
diff --git a/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash.mdx b/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash.mdx
index c816741c..4a9cb316 100644
--- a/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash.mdx
+++ b/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash.mdx
@@ -40,6 +40,36 @@ To enforce SSO, it's recommended to disable password authentication. This can be
| :-------------------------------------- | :---------------------------------------------------- | :---------: | :-------: |
| `AUTH_DISABLE_PASSWORD_AUTHENTICATION` | If `"true"` disables signing in with plain passwords | | false |
+## SSO account linking
+
+Account linking controls what happens when a user signs in via SSO and their identity isn't already attached to a Lightdash account. There are two independent toggles:
+
+- **Link SSO identities across providers** — when a user signs in with a new OIDC provider, link the new identity to an existing user that already has another OIDC identity with the same email.
+- **Link SSO logins to existing accounts by email** — when a user signs in via OIDC with an email that matches an existing Lightdash user, attach the SSO identity to that user instead of failing the login. Required when using [SCIM](/references/workspace/scim-integration) with SSO so SCIM-provisioned users can sign in.
+
+
+ Only enable account linking with identity providers whose emails you trust. Anyone able to authenticate with a verified email through a linked provider will gain access to the matching Lightdash account.
+
+
+### Configure linking from the admin panel
+
+Organization admins can toggle account linking per organization from the SSO settings page:
+
+1. Sign in as an organization admin.
+2. Go to **Settings** → **Organization settings** → **Single sign-on**.
+3. Under **Account linking**, toggle **Link SSO identities across providers** or **Link SSO logins to existing accounts by email**.
+
+Changes take effect on the next sign-in. On Lightdash Cloud, the admin panel is the only way to configure these settings.
+
+### Configure linking via environment variables (self-hosted)
+
+Self-hosted instances can set instance-wide defaults with environment variables. The per-org toggle wins when set — if either the env var **or** the org setting enables linking, it is enabled for that org.
+
+| Variable | Description | Default |
+| :---------------------------------- | :----------------------------------------------------------------------------------- | :-----: |
+| `AUTH_ENABLE_OIDC_LINKING` | Instance-wide default for linking SSO identities across providers | false |
+| `AUTH_ENABLE_OIDC_TO_EMAIL_LINKING` | Instance-wide default for linking SSO logins to existing accounts by matching email | false |
+
## Okta
Lightdash supports Okta as an authentication provider. The integration uses OpenID Connect (OIDC) to authenticate users and JIT provisioning to create users in Lightdash when they first log in.