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: you don’t set these environment variables yourself. Complete the provider-side setup steps on this page (creating an OAuth app, configuring redirect URIs, etc.), then securely share the resulting values (client ID, client secret, issuer URL, etc.) with the Lightdash team — we’ll configure everything on your behalf. See the SSO providers guide for more details.
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.
We recommend adding the SMTP environment variables 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:
Open the bash terminal for the docker Lightdash container
Override user password with this command:
cd ./packages/backend && node ./dist/overrideUserPassword.js <user email> <new password>
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.
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 }}.
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)
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 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 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.
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 .*
Lightdash Cloud users: instead of setting these environment variables, securely share the client ID, client secret, Okta domain, and issuer URI with the Lightdash team.
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 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. To enable this functionality, ensure the following environment variable is set:
To enable Google Single Sign On (SSO) you’ll need to follow these instructions to Create the OAuth web client ID. Once you reach Step 13 to configure the client you’ll need to enter the following details:
Where {{ lightdash_domain }} is the domain you use to sign in to Lightdash such as mycompany.lightdash.com
Lightdash Cloud users: instead of setting these environment variables, securely share the Google OAuth client ID and client secret with the Lightdash team.
These environment variables must be provided to Lightdash to enable you to control Single Sign On (SSO) functionality for Google
From the SSO page copy the client id, client secret, and issuer URL.
Lightdash Cloud users: instead of setting these environment variables, securely share the client ID, client secret, and issuer URL with the Lightdash team.
These variables enable you to control Single Sign On (SSO) functionality for One Login
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.
Lightdash Cloud users: instead of setting these environment variables, securely share the client ID, client secret, and tenant ID with the Lightdash team.
These variables enable you to control Single Sign On (SSO) functionality for Azure Active Directory.
Lightdash Cloud users: instead of setting these environment variables, securely share the client ID, client secret, and metadata document URL with the Lightdash team.
These variables enable you to control Single Sign On (SSO) functionality for a generic OpenID Connect provider.
