diff --git a/self-host/customize-deployment/enterprise-license-keys.mdx b/self-host/customize-deployment/enterprise-license-keys.mdx index 29124307..7f843b69 100644 --- a/self-host/customize-deployment/enterprise-license-keys.mdx +++ b/self-host/customize-deployment/enterprise-license-keys.mdx @@ -1,107 +1,140 @@ --- -title: "Enterprise License Keys" +title: "Enterprise license keys" description: "Access enterprise features on self-hosted Lightdash instances" -boost: 0.001 --- -๐Ÿ›  This page is for engineering teams self-hosting their own Lightdash instance. If you want to learn about enterprise features and pricing, go to [lightdash.com/pricing](https://lightdash.com/pricing). + ๐Ÿ›  This page is for engineering teams self-hosting their own Lightdash instance. If you want to learn about enterprise features and pricing, go to [lightdash.com/pricing](https://lightdash.com/pricing). -Enterprise License Keys enable access to advanced Lightdash Enterprise Edition features on self-hosted instances. These features include enhanced security, performance optimizations, and advanced collaboration tools designed for large organizations. +Enterprise license keys unlock advanced Lightdash Enterprise Edition features on self-hosted instances โ€” SSO, SCIM, AI agents, embedding, custom roles, service accounts, results caching, pre-aggregates, and more. -## Getting an Enterprise License Key +## Getting an enterprise license key -To obtain an Enterprise License Key for your self-hosted Lightdash instance: +To obtain an enterprise license key for your self-hosted Lightdash instance: -1. **Contact our team** - [Schedule a call with our enterprise team](https://calendly.com/lightdash-cloud/enterprise?utm_source=docs&utm_medium=referral&utm_campaign=enterprise_licensing&utm_content=license_key_page) to discuss your requirements and get your license key. +1. **Contact our team** โ€” [schedule a call with our enterprise team](https://calendly.com/lightdash-cloud/enterprise?utm_source=docs\&utm_medium=referral\&utm_campaign=enterprise_licensing\&utm_content=license_key_page) to discuss your requirements. +2. **Receive your license key** โ€” the Lightdash team will share a unique license key with you (typically via 1Password). -2. **Receive your license key** - Our team will provide you with a unique license key tailored to your organization's needs. +## Configuring your license key -## Configuring Your License Key +Set the license key on every Lightdash container (backend, scheduler, and workers) via the `LIGHTDASH_LICENSE_KEY` environment variable. -Once you have received your Enterprise License Key, you need to configure it in your Lightdash deployment. + + + ```bash theme={null} + LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here + ``` + -### Using Environment Variables + + ```yaml theme={null} + secrets: + LIGHTDASH_LICENSE_KEY: your-enterprise-license-key-here + ``` -Add the following environment variable to your Lightdash configuration: + Then update your deployment: -```bash -LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here -``` + ```bash theme={null} + helm upgrade lightdash lightdash/lightdash -n lightdash -f values.yaml + ``` + -### Using Helm (Kubernetes) + + ```yaml theme={null} + services: + lightdash: + environment: + - LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here + ``` + + -If you're deploying Lightdash on Kubernetes using Helm, add the license key to your `values.yaml` file: +## License validation and network requirements -```yaml -secrets: - LIGHTDASH_LICENSE_KEY: your-enterprise-license-key-here -``` +On server start, Lightdash validates your enterprise license key by making an outbound HTTPS request to the [Keygen](https://keygen.sh) license validation API: -Then update your Helm deployment: +* **Endpoint:** `https://api.keygen.sh` +* **Purpose:** validates the license key provided via the `LIGHTDASH_LICENSE_KEY` environment variable +* **When:** on every Lightdash server start -```bash -helm upgrade lightdash lightdash/lightdash -n lightdash -f values.yaml -``` + + Your Lightdash instance must be able to reach `https://api.keygen.sh` on server start. This is the only external network request **required** to run Lightdash with enterprise features. If your environment restricts outbound traffic, allowlist this endpoint in your firewall or proxy. -### Using Docker Compose + If you enable the optional [organization roadmap](/self-host/customize-deployment/enable-organization-roadmap), your backend also makes outbound requests to `https://roadmap.lightdash.com` โ€” allowlist that domain too. + -For Docker Compose deployments, add the license key to your `docker-compose.yml` file: +No external code is pulled during this process โ€” the request solely validates your license key and returns the validation result. -```yaml -services: - lightdash: - environment: - - LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here -``` +## Verifying your license -## License validation and network requirements +After configuring your license key and restarting Lightdash, you can verify that enterprise features are enabled by: -On server start, Lightdash validates your Enterprise License Key by making an outbound HTTPS request to the [Keygen](https://keygen.sh) license validation API: +1. Logging in as an admin user. +2. Navigating to **Settings โ†’ Organization**. +3. Checking for the **Enterprise Edition** badge. -- **Endpoint:** `https://api.keygen.sh` -- **Purpose:** Validates the license key provided via the `LIGHTDASH_LICENSE_KEY` environment variable -- **When:** On every Lightdash server start +## Enterprise features - -Your Lightdash instance must be able to reach `https://api.keygen.sh` on server start. This is the only external network request **required** to run Lightdash with enterprise features. If your environment restricts outbound traffic, ensure this endpoint is allowlisted in your firewall or proxy configuration. +A valid enterprise license key unlocks the features below. Most features are gated behind an additional environment variable that you must set to `true` before the feature becomes active. Follow each feature's documentation link for the full list of configuration options. -If you enable the optional [organization roadmap](/self-host/customize-deployment/enable-organization-roadmap), your backend also makes outbound requests to `https://roadmap.lightdash.com` โ€” allowlist that domain too. - +### Feature flags -No external code is pulled during this process โ€” the request solely validates your license key and returns the validation result. +Set these on your Lightdash instance in addition to `LIGHTDASH_LICENSE_KEY`: -## Verifying your license +| Feature | Environment variable | What it enables | Documentation | +| --------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | +| Custom roles | `CUSTOM_ROLES_ENABLED=true` | Define custom organization and project roles with granular permissions | [Custom roles](/references/workspace/custom-roles#custom-roles) | +| Service accounts | `SERVICE_ACCOUNT_ENABLED=true` | Machine-to-machine tokens (prefixed `ldsvc_`) with org- or project-scoped roles | [Service accounts](/references/workspace/service-accounts) | +| SCIM provisioning | `SCIM_ENABLED=true` | Provision and deprovision users and groups from your IdP (Okta, Azure AD, OneLogin, etc.) | [SCIM integration](/references/workspace/scim-integration) | +| AI Analyst / AI agents | `AI_COPILOT_ENABLED=true` | Natural-language querying, AI-generated charts, and AI agents | [AI Analyst](/guides/ai-agents) ยท [env vars](/self-host/customize-deployment/environment-variables#ai-analyst) | +| Multi-agent Slack channels (Beta) | `SLACK_MULTI_AGENT_CHANNEL_ENABLED=true` | Run multiple AI agents in a single Slack channel | [Multi-agent Slack channels](/guides/ai-agents/getting-started#setting-up-a-multi-agent-slack-channel) | +| MCP server | `MCP_ENABLED=true` | Expose Lightdash as an MCP server at `/api/v1/mcp` for AI clients | [MCP integration](/self-host/customize-deployment/configure-mcp-for-lightdash) | +| Results caching | `RESULTS_CACHE_ENABLED=true` | Cache chart and dashboard query results in S3 to skip repeat warehouse queries | [Caching](/guides/developer/caching) ยท [env vars](/self-host/customize-deployment/environment-variables#cache) | +| Embedding | `EMBEDDING_ENABLED=true` | Embed dashboards, charts, data apps, and AI agents into your own product | [Embedding](/references/embedding) ยท [env vars](/self-host/customize-deployment/environment-variables#embedding) | +| Pre-aggregates | `preAggregateNatsWorker.enabled: true` | Materialize aggregated tables via a dedicated NATS worker and S3 bucket for faster dashboards | [Pre-aggregate workers](/self-host/nats-workers/pre-aggregate-workers) | +| Data apps | See [self-hosting data apps](/guides/data-apps/self-hosting) | AI-generated React apps built in an E2B sandbox and served from an S3 bucket | [Data apps self-hosting](/guides/data-apps/self-hosting) | +| AI writeback | `ai-writeback` feature flag | Let the AI agent open pull requests against your dbt repo to add or edit metrics | [AI writeback self-hosting](/guides/developer/ai-writeback-self-hosting) | -After configuring your license key and restarting Lightdash, you can verify that enterprise features are enabled by: +### Enterprise SSO providers -1. Logging in as an admin user -2. Navigating to Settings โ†’ Organization -3. Checking for the "Enterprise Edition" badge +SSO providers such as Google Workspace are available on all plans. The following SSO providers require an enterprise license key on self-hosted instances. Configure them via environment variables โ€” see [Configure SSO for self-hosted Lightdash](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash) for the full setup guide, and the [SSO env var reference](/self-host/customize-deployment/environment-variables#sso) for all options. -## Enterprise Features +| Provider | Required environment variables | Documentation | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | +| Okta | `AUTH_OKTA_OAUTH_CLIENT_ID`, `AUTH_OKTA_OAUTH_CLIENT_SECRET`, `AUTH_OKTA_OAUTH_ISSUER`, `AUTH_OKTA_DOMAIN` | [Okta SSO](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#okta) | +| Azure AD | `AUTH_AZURE_AD_OAUTH_CLIENT_ID`, `AUTH_AZURE_AD_OAUTH_CLIENT_SECRET`, `AUTH_AZURE_AD_OAUTH_TENANT_ID` | [Azure AD SSO](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#azure-ad) | +| OneLogin | `AUTH_ONE_LOGIN_OAUTH_CLIENT_ID`, `AUTH_ONE_LOGIN_OAUTH_CLIENT_SECRET`, `AUTH_ONE_LOGIN_OAUTH_ISSUER` | [OneLogin SSO](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#one-login) | +| Generic OpenID Connect | `AUTH_OIDC_CLIENT_ID`, `AUTH_OIDC_CLIENT_SECRET`, `AUTH_OIDC_METADATA_DOCUMENT_URL` | [OpenID Connect](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#openid-connect) | +| Snowflake OAuth (warehouse sign-in) | `SNOWFLAKE_OAUTH_CLIENT_ID`, `SNOWFLAKE_OAUTH_CLIENT_SECRET`, `SNOWFLAKE_OAUTH_AUTHORIZATION_ENDPOINT`, `SNOWFLAKE_OAUTH_TOKEN_ENDPOINT` | [Snowflake OAuth](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash) | +| Databricks OAuth (warehouse sign-in) | `DATABRICKS_OAUTH_CLIENT_ID`, `DATABRICKS_OAUTH_CLIENT_SECRET`, `DATABRICKS_OAUTH_AUTHORIZATION_ENDPOINT`, `DATABRICKS_OAUTH_TOKEN_ENDPOINT` | [Databricks OAuth](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash) | -With a valid Enterprise License Key, you'll have access to: +Additional SSO-related options: -- **Advanced authentication** - Enhanced SSO options and security controls -- **Extended analytics** - Additional usage analytics and monitoring capabilities -- **Priority support** - Direct access to our enterprise support team -- **Advanced customization** - Additional configuration options for large deployments -- **Performance optimizations** - Features designed for high-scale deployments +* `AUTH_DISABLE_PASSWORD_AUTHENTICATION=true` โ€” recommended for enterprise deployments to force SSO-only sign-in. +* `AUTH_ENABLE_GROUP_SYNC=true` โ€” sync groups from the IdP to Lightdash groups. +* `AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true` โ€” **required when using SCIM alongside SSO** so SSO sign-ins link to SCIM-provisioned users. + + + You can [search "enterprise" on the environment variables reference](/self-host/customize-deployment/environment-variables) to see every variable that requires an enterprise license key. + ## Troubleshooting If enterprise features are not available after configuring your license key: -1. Verify the license key is correctly set in your environment variables -2. Ensure Lightdash has been restarted after adding the license key -3. Confirm your server can reach `https://api.keygen.sh` (required for license validation) -4. Check the Lightdash logs for any license-related error messages -5. Contact our [enterprise support team](https://calendly.com/lightdash-cloud/enterprise) for assistance - -## Related Documentation - -- [Environment Variables Reference](/self-host/customize-deployment/environment-variables) -- [Self-Host Lightdash](/self-host/self-host-lightdash) -- [Lightdash Cloud vs Self-Hosted](/self-host/lightdash-cloud-vs-self-hosted) +1. Verify `LIGHTDASH_LICENSE_KEY` is set on **every** Lightdash container (backend, scheduler, workers). +2. Ensure Lightdash has been restarted after adding the license key. +3. Confirm the corresponding feature flag environment variable is set (for example, `AI_COPILOT_ENABLED=true` for the AI Analyst). +4. Confirm your server can reach `https://api.keygen.sh` (required for license validation). +5. Check the Lightdash logs for any license-related error messages. +6. Contact our [enterprise support team](https://calendly.com/lightdash-cloud/enterprise) for assistance. + +## Related documentation + +* [Enterprise on-prem setup](/self-host/enterprise-on-prem) +* [Production deployment checklist](/self-host/production-deployment-checklist) +* [Environment variables reference](/self-host/customize-deployment/environment-variables) +* [Configure SSO for self-hosted Lightdash](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash) +* [Self-host Lightdash](/self-host/self-host-lightdash) +* [Lightdash Cloud vs. self-hosted](/self-host/lightdash-cloud-vs-self-hosted)