docs: document per-org SSO account linking toggles

references/workspace/scim-integration.mdx

@@ -27,11 +27,16 @@ SCIM_ENABLED=true
 ```
 
 <Warning>
-  **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
+    ```
 </Warning>
 
 ## SCIM Setup within Lightdash

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                                                                                                                                   |

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.
+
+<Warning>
+  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.
+</Warning>
+
+### 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.