diff --git a/references/workspace/sso-providers.mdx b/references/workspace/sso-providers.mdx index 3876f358..9b7e6a31 100644 --- a/references/workspace/sso-providers.mdx +++ b/references/workspace/sso-providers.mdx @@ -45,7 +45,73 @@ Lightdash supports multiple SSO providers for secure authentication. This page p OAuth 2.0-based authentication using Google accounts. Ideal for organizations using Google Workspace. - **Included in**: Cloud Pro, Enterprise, Self-hosted -- **Setup guide**: [Google SSO configuration](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#google) + +#### Setting up Google SSO + + + + Lightdash Cloud (including the shared `app.lightdash.cloud` instance) ships with a shared Google OAuth app, so there are **no client IDs, client secrets, or environment variables to configure**. Organization admins can turn Google SSO on or off themselves from the Lightdash UI — you do not need to contact the Lightdash team. + + To enable Google SSO for your organization: + + 1. In Lightdash, open **Settings → Organization → Authentication**. + 2. Find the **Google** panel in the **Single Sign-On** section. + 3. Click **Set up Google**. + 4. (Optional) Under **Discovery**, restrict which email domains see the **Sign in with Google** button: + - **Unchecked** (default): users whose email matches your organization's [allowed email domains](/references/workspace/roles#allowed-email-domains-to-join-organization-automatically) see Google as a login option. + - **Override organization's allowed email domains**: provide a custom list of domains (e.g. `acme.com`, `acme.io`) that should see Google. Public domains like `gmail.com`, `outlook.com`, `yahoo.com`, etc. are not allowed. + 5. Choose whether to **Allow password sign-in** for users matched by this method. Uncheck to force Google SSO for those users. + 6. Click **Save**. Use the **Enabled** toggle at the top of the panel to turn the method on or off later without losing your configuration. + + + Google SSO is enabled by default on Lightdash Cloud. The panel above only exists so you can either **disable Google** for your organization or **restrict which domains** see the Google button. If you never visit this panel, Google sign-in works out of the box for all users in your allowed email domains. + + + To **fully enforce SSO** (block password sign-in entirely for everyone in the org, not just users matched by Google), contact the Lightdash team. See [Migrating users from password to Google SSO](#migrating-users-from-password-to-google-sso) below before you do this. + + + Self-hosted instances need their own Google OAuth credentials. Follow the [Google SSO configuration guide](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#google) to create a Google OAuth client and set the `AUTH_GOOGLE_ENABLED`, `AUTH_GOOGLE_OAUTH2_CLIENT_ID`, and `AUTH_GOOGLE_OAUTH2_CLIENT_SECRET` environment variables. + + Once Google is enabled at the instance level, organization admins can use the same in-app **Settings → Organization → Authentication** panel described in the Cloud tab to scope it to specific email domains or disable it per organization. + + + +## 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). + + + 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). + + +### 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. + - **Lightdash Cloud**: in **Settings → Organization → Authentication**, open the **Google** panel and uncheck **Allow password sign-in** to block passwords for users matched by Google. To block password sign-in across the whole organization (including users not matched by any per-org SSO method), contact the Lightdash team. + - **Self-hosted**: set `AUTH_DISABLE_PASSWORD_AUTHENTICATION=true`. + +### 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. + + + 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. + ### Okta