> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-mintlify-9f84ba80.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure Lightdash to use passwords or SSO for authentication
🛠This page is for engineering teams **self-hosting** their own Lightdash instance. The environment variables listed below are set directly in your self-hosted deployment.
**Lightdash Cloud users**: configure SSO yourself from **Organization settings → Single Sign-On** — see [Configure SSO](/references/workspace/configure-sso). Use the provider-side steps on this page (creating an OAuth app, configuring redirect URIs, etc.) to obtain the values, then enter them in the organization settings UI instead of setting environment variables.
Cloud SSO also requires a [verified domain](/references/workspace/verified-domains). Saving provider credentials without a verified domain will not route users to that provider during sign-in.
## Multiple authentication methods
Lightdash supports configuring multiple authentication methods simultaneously on a single instance. You can enable any combination of sign-in options, including:
* Password + Okta
* Password + Google + Okta
* Multiple SSO providers (e.g., Google + Azure AD + One Login)
Simply configure the environment variables for each authentication method you want to enable, and all configured options will appear on your login page.
## Passwords
We recommend [adding the SMTP environment variables](/self-host/customize-deployment/environment-variables#smtp) so Lightdash can display a `Forgot your password?` button in the login page and send emails to reset passwords.
You can override a user password in just a few steps:
1. Open the bash terminal for the docker Lightdash container
2. Override user password with this command:
```bash theme={null}
cd ./packages/backend && node ./dist/overrideUserPassword.js
```
## Email-only signup and OTP login
Lightdash can offer a passwordless email-first sign-in flow: new users sign up with just their email address, and returning users on those passwordless accounts sign in with a 6-digit code emailed to them instead of a password. Signup is gated by an instance-wide feature flag and is **off by default**. OTP login for existing passwordless accounts is always available, even if the flag is later turned off — see [Security notes](#security-notes) below.
This flow currently has **no built-in rate limiting** on the OTP request or verify endpoints. Put rate limiting in front of Lightdash (e.g. at your ingress or WAF) before enabling this feature on a production instance.
### Enable the feature flag
Set the `new-onboarding` [feature flag](/self-host/customize-deployment/environment-variables#feature-flags) on your instance:
```bash theme={null}
LIGHTDASH_ENABLE_FEATURE_FLAGS=new-onboarding
```
Because [SMTP](/self-host/customize-deployment/environment-variables#smtp) is used to deliver the one-time codes, you must also have SMTP configured.
The `new-onboarding` flag is a single umbrella toggle that also enables the full-page organization setup experience shown after registration and the dbt-less "connect to your warehouse" onboarding path.
### What changes when the flag is on
**Register page (`/register`)**
* The signup form asks only for an email address — no name, no password.
* Lightdash creates the account with no password, sends a 6-digit code to that address, and — once the user enters the code — takes them through the standard join-or-create-organization flow.
* Passwordless users can add a password later by clicking **Forgot your password?** on the login page: the reset link now upserts a password row for accounts that didn't previously have one.
**Login page (`/login`)**
* When a user enters an email that belongs to a passwordless account (no password set, no SSO identity), the password field is hidden and Lightdash emails a 6-digit code instead.
* Entering the code signs the user in and marks the email as verified.
* The same 5-attempt limit and expiry window used elsewhere for one-time passcodes applies.
For example, a new user visits `/register` and types `alex@ecom-store.com`. They receive a code by email, enter something like `123456`, and land in the standard "create or join an organization" step. The next time they visit `/login` and type `alex@ecom-store.com`, the password field is hidden and they receive a fresh 6-digit code to sign in — no password ever set.
### What stays the same
* **Accounts with a password** — the password field is still shown, and the OTP login path is refused regardless of the flag.
* **SSO users** — accounts with any linked SSO identity continue to sign in via SSO. OTP login is refused for them regardless of the flag.
* **Invite flow** (`/invite/`) — unchanged; invited users still complete the full signup form (name + password).
### Security notes
* OTP login only applies to accounts that have **no password and no SSO identity**. Any account with either is excluded from this flow.
* All failure modes (unknown email, non-passwordless account, wrong code, expired code, too many attempts) return the **same generic 401** so the endpoint can't be used to probe whether an email is registered.
* OTP login is intentionally **not** gated on the `new-onboarding` flag. Turning the flag off stops new email-only signups, but existing passwordless accounts can still sign in with a one-time code — otherwise a flag rollback would strand them with no way to authenticate. If you want to end passwordless sign-in for those users, have them reset their password via **Forgot your password?** first.
## SSO setup
To enforce SSO, it's recommended to disable password authentication. This can be done by setting the following environment variable:
| Variable | Description | Required? | Default |
| :------------------------------------- | :--------------------------------------------------- | :-------: | :-----: |
| `AUTH_DISABLE_PASSWORD_AUTHENTICATION` | If `"true"` disables signing in with plain passwords | | 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.
### Creating an Okta application
In the Okta admin panel, navigate to **Applications** and click **Create App Integration**, choose the following settings:
* **Sign-in method**: OIDC - OpenID Connect
* **Application type**: Web application
On the following page you'll need to use the following settings, replace `{{ lightdash_url }}` with the URL of your Lightdash instance. For example if you normally access Lightdash at `https://lightdash.example.com/login` then you should use `https://lightdash.example.com` as your `{{ lightdash_url }}`.
* **Grant type**: Authorization Code
* **Sign-in redirect URIs**: `{{ lightdash_url }}/api/v1/oauth/redirect/okta`
* **Sign-out redirect URIs**: `{{ lightdash_url }}`
* **Controlled access**: Select who can access this application
Hit **Save** and you'll be taken to the application settings page. For the optimal user experience, we recommend allowing Okta to initiate the login flow. To do this, click **Edit** next to **General Settings** and set:
* **Login initiated by**: App and Okta Sign-in Page
* **Application visibility**: Display application icon to users
* **Login flow**: Redirect to app to initiate login (OIDC Compliant)
* **Initiate login URI**: `{{ lightdash_url }}/api/v1/login/okta`
Hit **Save** to finish.
### Okta configuration variables
From the application settings page, you'll need to copy the following values:
* **Client ID**
* **Client secret**
You'll also need your **Okta domain**, which is the first part of your okta URL. For example if your Okta URL is [https://dev-123456.okta.com](https://dev-123456.okta.com) then your Okta domain is `dev-123456.okta.com`.
Finally, you need the **Issuer URI**. This is the URL of your Okta authorization server. You can use your [Org authorization server](https://developer.okta.com/docs/concepts/auth-servers/#org-authorization-server) which uses `https://dev-123456.okta.com` as your issuer or select a custom authorization server. To find the issuer URI for a custom authorization server navigate to **API** > **Authorization Servers** and click on the authorization server and note the **Issuer URI** and **Name** of the authorization server. For example the `default` authorization server has an issuer URI of `https://dev-123456.okta.com/oauth2/default`.
#### Groups & Okta
If you want to use groups to control access to Lightdash, you'll need to configure Okta and Lightdash to support this.
If you're **not** using a custom authorization server ID:
* on `OpenID Connect ID Token` section in the Okta application settings, add `groups` to the `Groups claim` field, by setting a Groups claims type to `Filter` and a Filter to match expression to `.*`
If you're using a custom authorization server ID:
* you don't need to set the `AUTH_OKTA_EXTRA_SCOPES` environment variable
* on the Authorization Server settings, add claim `groups`, value type `Groups`, matches regex `.*`
### Configuring Lightdash for Okta
**Lightdash Cloud users**: instead of setting these environment variables, enter the client ID, client secret, Okta domain, and issuer URI in **Organization settings → Single Sign-On → Okta**. See [Configure SSO](/references/workspace/configure-sso#okta).
Make sure your organization has a [verified domain](/references/workspace/verified-domains), otherwise Okta will not appear for users during sign-in.
You'll need to set the following environment variables in your Lightdash deployment:
| Variable | Description | Required? |
| :---------------------------------- | :------------------------------------------------------------------------------------------------- | :-------------------------------------------: |
| `AUTH_OKTA_DOMAIN` | The `{{ okta_domain }}`. Should not include `https://` | |
| `AUTH_OKTA_OAUTH_CLIENT_ID` | The **Client ID** copied from the application settings in okta | |
| `AUTH_OKTA_OAUTH_CLIENT_SECRET` | The **Client secret** copied from the application settings in okta | |
| `AUTH_OKTA_OAUTH_ISSUER` | The **Issuer URI** copied from the authorization server. Should include `https://` | |
| `AUTH_OKTA_AUTHORIZATION_SERVER_ID` | Optional. The **Name** of a custom authorization server if not using the org authorization server. | |
| `AUTH_OKTA_EXTRA_SCOPES` | Optional. The extra **scopes** (e.g. "groups") when not using a custom authorization server | |
### Enable Automatic Assignment of Okta Users to Groups in Lightdash
**This feature is deprecated and will be removed in a future release.**
For more information on how to provision users and groups in Lightdash, see the [SCIM integration](/references/workspace/scim-integration) documentation.
Okta users will automatically be assigned to the same groups in Lightdash as they are in Okta if you have [configured Okta to share groups with Lightdash](/references/workspace/groups#using-okta-to-manage-groups-in-lightdash). To enable this functionality, ensure the following environment variable is set:
| Variable | Description | Required? |
| :----------------------- | :---------------------------------------- | :-------: |
| `AUTH_ENABLE_GROUP_SYNC` | If `"true"` enables group sync from Okta. | |
read more about [Using OKTA to manage groups in Lightdash](/references/workspace/groups#using-okta-to-manage-groups-in-lightdash)
## Google
To enable Google Single Sign On (SSO) you'll need to follow these instructions to [Create the OAuth web client ID](https://support.google.com/workspacemigrate/answer/9222992?hl=en). Once you reach **Step 13** to configure the client you'll need to enter the following details:
* Authorized JavaScript Origins: `https://{{ lightdash_domain }}`
* Authorized redirect URIs: `https://{{ lightdash_domain }}/api/v1/oauth/redirect/google`
Where `{{ lightdash_domain }}` is the domain you use to sign in to Lightdash such as `mycompany.lightdash.com`
These environment variables must be provided to Lightdash to enable you to control Single Sign On (SSO) functionality for Google
| Variable | Description | Required? | Default |
| :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-----: |
| `AUTH_GOOGLE_ENABLED` | Required to be set to `true` for Google SSO | | |
| `AUTH_GOOGLE_OAUTH2_CLIENT_ID` | Required see instructions above | | |
| `AUTH_GOOGLE_OAUTH2_CLIENT_SECRET` | Required see instructions above | | |
| `AUTH_GOOGLE_INCLUDE_BIGQUERY_SCOPE` | When `true`, bundles the BigQuery scope into the Google login flow so BigQuery SSO users see a single consent screen instead of two | | `false` |
### Combine BigQuery SSO consent with Google login
If you use [BigQuery SSO](/references/workspace/sso-providers#warehouse-sso-enterprise-only) to give users per-user warehouse credentials, set `AUTH_GOOGLE_INCLUDE_BIGQUERY_SCOPE=true` to request the BigQuery scope during the initial Google login. Users will complete one consent screen that covers both Lightdash login and BigQuery warehouse access instead of two separate OAuth flows.
When enabled, Lightdash also requests offline access with a forced consent prompt so Google returns a refresh token for the BigQuery connection. Leave this unset (or `false`) if you do not use BigQuery SSO.
Before enabling this option:
* Confirm Google SSO is configured and working (`AUTH_GOOGLE_ENABLED=true`).
* Add the `https://www.googleapis.com/auth/bigquery` scope to your OAuth consent screen in Google Cloud.
* Enable BigQuery SSO at the project level for the warehouse connections that should use it.
## One Login
To create a One Login integration:
* Head to the **Administration** portal
* In the navigation bar at the top select **Applications** > **Applications**
* Hit the **Add App** button
* Under **Find Applications** search for **OpenID Connect (OIDC)** and select it
* Set the **Display Name** and for the **Icon** you can use our [Lightdash Media Kit](https://lightdash.notion.site/Media-kit-957921de51c7453f90ca7dcec11ef52b) to get a Lightdash Bolt logo and press **Save**
* Set the following values for the application
* **Configuration** > **Login URL** `{{site_url}}/api/v1/login/oneLogin`
* **Configuration** > **Redirect URL** `{{site_url}}/api/v1/oauth/redirect/oneLogin`
* **SSO** > **Application Type** `web`
* **SSO** > **Token endpoint** `post`
* **SSO** > **Enable login hint** `true`
* From the **SSO** page copy the client id, client secret, and issuer URL.
**Lightdash Cloud users**: instead of setting these environment variables, enter the client ID, client secret, and issuer URL in **Organization settings → Single Sign-On → OneLogin**. See [Configure SSO](/references/workspace/configure-sso#onelogin).
Make sure your organization has a [verified domain](/references/workspace/verified-domains), otherwise OneLogin will not appear for users during sign-in.
These variables enable you to control Single Sign On (SSO) functionality for One Login
| Variable | Description | Required? | Default |
| :----------------------------------- | :------------------------- | :-------------------------------------------: | :-----: |
| `AUTH_ONE_LOGIN_OAUTH_CLIENT_ID` | Required for One Login SSO | | |
| `AUTH_ONE_LOGIN_OAUTH_CLIENT_SECRET` | Required for One Login SSO | | |
| `AUTH_ONE_LOGIN_OAUTH_ISSUER` | Required for One Login SSO | | |
## Azure Active Directory
### Creating an Azure AD application
In the admin panel, navigate to **App Registrations** and click **New registration**, choose the following settings for the redirect URI:
* **Type**: Web
* **URI**: `{{ lightdash_url }}/api/v1/oauth/redirect/azuread`
On the following page you'll need to use the following settings, replace `{{ lightdash_url }}` with the URL of your Lightdash instance. For example if you normally access Lightdash at `https://lightdash.example.com/login` then you should use `https://lightdash.example.com` as your `{{ lightdash_url }}`.
Hit **Register** and you'll be taken to the application settings page. Copy the "Application (client) ID" and "Directory (tenant) ID" values as you'll need them later.
In the left hand menu, navigate to **Certificates & secrets** and click **New client secret**. Give the secret a description and choose an expiry time. Hit **Add** and you'll be shown the secret value. Copy this value as you'll need it later.
### Configuring Lightdash for Azure AD
**Lightdash Cloud users**: instead of setting these environment variables, enter the client ID, client secret, and tenant ID in **Organization settings → Single Sign-On → Azure AD**. See [Configure SSO](/references/workspace/configure-sso#azure-active-directory).
Make sure your organization has a [verified domain](/references/workspace/verified-domains), otherwise Azure AD will not appear for users during sign-in.
These variables enable you to control Single Sign On (SSO) functionality for Azure Active Directory.
| Variable | Description | Required? | Default |
| :------------------------------------- | :-------------------- | :-------------------------------------------: | :-----: |
| `AUTH_AZURE_AD_OAUTH_CLIENT_ID` | Required for Azure AD | | |
| `AUTH_AZURE_AD_OAUTH_CLIENT_SECRET` | Required for Azure AD | | |
| `AUTH_AZURE_AD_OAUTH_TENANT_ID` | Required for Azure AD | | |
| `AUTH_AZURE_AD_OIDC_METADATA_ENDPOINT` | Optional for Azure AD | | |
| `AUTH_AZURE_AD_X509_CERT_PATH` | Optional for Azure AD | | |
| `AUTH_AZURE_AD_X509_CERT` | Optional for Azure AD | | |
| `AUTH_AZURE_AD_PRIVATE_KEY_PATH` | Optional for Azure AD | | |
| `AUTH_AZURE_AD_PRIVATE_KEY` | Optional for Azure AD | | |
## OpenID Connect
Lightdash supports OpenID Connect-compliant SSO providers, via our configurable OIDC connector.
### Configuring Lightdash for OpenID Connect
**Lightdash Cloud users**: instead of setting these environment variables, enter the client ID, client secret, and metadata document URL in **Organization settings → Single Sign-On → OpenID Connect**. See [Configure SSO](/references/workspace/configure-sso#openid-connect).
Make sure your organization has a [verified domain](/references/workspace/verified-domains), otherwise OpenID Connect will not appear for users during sign-in.
These variables enable you to control Single Sign On (SSO) functionality for a generic OpenID Connect provider.
| Variable | Description | Required? | Default |
| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-------------------: |
| `AUTH_OIDC_CLIENT_ID` | | | |
| `AUTH_OIDC_CLIENT_SECRET` | Required unless AUTH\_METHOD is `private_key_jwt` | | |
| `AUTH_OIDC_METADATA_DOCUMENT_URL` | [URL to OIDC metadata discovery endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest) | | |
| `AUTH_OIDC_AUTH_METHOD` | `client_secret_basic` or `private_key_jwt` | | `client_secret_basic` |
| `AUTH_OIDC_X509_CERT` | PEM-encoded content of a public key certificate for `private_key_jwt` | | |
| `AUTH_OIDC_PRIVATE_KEY` | PEM-encoded content of a private key file for `private_key_jwt` | | |
| `AUTH_OIDC_X509_CERT_PATH` | Path to a PEM-encoded public key certificate for `private_key_jwt` | | |
| `AUTH_OIDC_PRIVATE_KEY_PATH` | Path to a PEM-encoded private key for `private_key_jwt` | | |
| `AUTH_OIDC_SCOPES` | List of space-delimited OIDC scopes | | |