​
Passwords

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:
  1. Open the bash terminal for the docker Lightdash container
  2. Override user password with this command:
cd ./packages/backend && node ./dist/overrideUserPassword.js <user email> <new password>

​
SSO setup

To enforce SSO, it’s recommended to disable password authentication. This can be done by setting the following environment variable:
VariableDescriptionRequired?Default
AUTH_DISABLE_PASSWORD_AUTHENTICATIONIf "true" disables signing in with plain passwordsfalse

​
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 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.

​
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

You’ll need to set the following environment variables in your Lightdash deployment:
VariableDescriptionRequired?
AUTH_OKTA_DOMAINThe {{ okta_domain }}. Should not include https://
AUTH_OKTA_OAUTH_CLIENT_IDThe Client ID copied from the application settings in okta
AUTH_OKTA_OAUTH_CLIENT_SECRETThe Client secret copied from the application settings in okta
AUTH_OKTA_OAUTH_ISSUERThe Issuer URI copied from the authorization server. Should include https://
AUTH_OKTA_AUTHORIZATION_SERVER_IDOptional. The Name of a custom authorization server if not using the org authorization server.
AUTH_OKTA_EXTRA_SCOPESOptional. 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:
VariableDescriptionRequired?
AUTH_ENABLE_GROUP_SYNCIf "true" enables group sync from Okta.
read more about 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. 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
VariableDescriptionRequired?Default
AUTH_GOOGLE_ENABLEDRequired to be set to true for Google SSO
AUTH_GOOGLE_OAUTH2_CLIENT_IDRequired see instructions above
AUTH_GOOGLE_OAUTH2_CLIENT_SECRETRequired see instructions above

​
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 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.
These variables enable you to control Single Sign On (SSO) functionality for One Login
VariableDescriptionRequired?Default
AUTH_ONE_LOGIN_OAUTH_CLIENT_IDRequired for One Login SSO
AUTH_ONE_LOGIN_OAUTH_CLIENT_SECRETRequired for One Login SSO
AUTH_ONE_LOGIN_OAUTH_ISSUERRequired 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

These variables enable you to control Single Sign On (SSO) functionality for Azure Active Directory.
VariableDescriptionRequired?Default
AUTH_AZURE_AD_OAUTH_CLIENT_IDRequired for Azure AD
AUTH_AZURE_AD_OAUTH_CLIENT_SECRETRequired for Azure AD
AUTH_AZURE_AD_OAUTH_TENANT_IDRequired for Azure AD
AUTH_AZURE_AD_OIDC_METADATA_ENDPOINTOptional for Azure AD
AUTH_AZURE_AD_X509_CERT_PATHOptional for Azure AD
AUTH_AZURE_AD_X509_CERTOptional for Azure AD
AUTH_AZURE_AD_PRIVATE_KEY_PATHOptional for Azure AD
AUTH_AZURE_AD_PRIVATE_KEYOptional for Azure AD

​
OpenID Connect

Lightdash supports OpenID Connect-compliant SSO providers, via our configurable OIDC connector.

​
Configuring Lightdash for OpenID Connect

These variables enable you to control Single Sign On (SSO) functionality for a generic OpenID Connect provider.
VariableDescriptionRequired?Default
AUTH_OIDC_CLIENT_ID
AUTH_OIDC_CLIENT_SECRETRequired unless AUTH_METHOD is private_key_jwt
AUTH_OIDC_METADATA_DOCUMENT_URLURL to OIDC metadata discovery endpoint
AUTH_OIDC_AUTH_METHODclient_secret_basic or private_key_jwtclient_secret_basic
AUTH_OIDC_X509_CERTPEM-encoded content of a public key certificate for private_key_jwt
AUTH_OIDC_PRIVATE_KEYPEM-encoded content of a private key file for private_key_jwt
AUTH_OIDC_X509_CERT_PATHPath to a PEM-encoded public key certificate for private_key_jwt
AUTH_OIDC_PRIVATE_KEY_PATHPath to a PEM-encoded private key for private_key_jwt
AUTH_OIDC_SCOPESList of space-delimited OIDC scopes