docs: document password to Google SSO migration behavior

Author: mintlify[bot]

references/workspace/sso-providers.mdx

@@ -47,6 +47,41 @@ OAuth 2.0-based authentication using Google accounts. Ideal for organizations us
 - **Included in**: Cloud Pro, Enterprise, Self-hosted
 - **Setup guide**: [Google SSO configuration](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#google)
 
+## Migrating users from password to Google SSO
+
+Lightdash identifies users by their **primary email address**, not by how they sign in. A user account is the same account whether the user authenticates with a password or with a linked Google identity, so all dashboards, charts, spaces, group memberships, project access, and personal settings are preserved across the switch.
+
+### How linking works
+
+When a user clicks **Sign in with Google** for the first time:
+
+1. Lightdash receives the verified email from Google's OAuth response.
+2. If that email matches an existing Lightdash user **and** the user's email is already verified, the Google identity is linked to the existing account automatically. The user keeps the same `userUuid` and all associated content and permissions.
+3. From then on, the user can sign in with either Google or their password (until password sign-in is disabled).
+
+<Note>
+  Linking by primary email requires the user's Lightdash email to be **verified**. Users who signed up with a password are normally verified on first login. If a user has an unverified email, the Google login attempt will create a new, separate account instead of linking — so make sure users verify their email before they try Google SSO for the first time. Self-hosted instances must also set `AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true` for this linking to happen (it is enabled by default on Lightdash Cloud).
+</Note>
+
+### Recommended rollout
+
+1. **Enable Google SSO** alongside password authentication, so both options appear on the login page.
+2. **Ask users to sign in with Google at least once.** This is what links their Google identity to their existing account. Their email must already be verified.
+3. **Confirm the migration is complete** — for example, by checking that everyone has logged in with Google recently — before turning off password sign-in.
+4. **Disable password authentication** to enforce SSO. On self-hosted, set `AUTH_DISABLE_PASSWORD_AUTHENTICATION=true`. On Lightdash Cloud, ask the Lightdash team to disable it for your workspace.
+
+### What happens if you enforce SSO before everyone has linked their account?
+
+Disabling password authentication only blocks the password login flow — it does **not** delete users or their content. Users who never signed in with Google before the cutover will see their password rejected on the next login, but:
+
+- Their account, dashboards, charts, spaces, group memberships, and permissions all still exist.
+- The next time they sign in with Google using the same email address, Lightdash will link the Google identity to their existing account (as long as their email is verified), and they will regain full access to everything they had before.
+- No admin action is required to "reclaim" the account — the user just needs to complete the Google login flow once.
+
+<Warning>
+  If a user's primary email in Lightdash differs from the email on their Google account, Google login will create a new account rather than link to the existing one. Update the user's primary email in Lightdash to match their Google identity before they switch.
+</Warning>
+
 ### Okta
 
 OpenID Connect (OIDC) integration with Okta. Supports group synchronization and SCIM provisioning.