From 90b82f5d8ad27febda446a40d62b5517d68f1558 Mon Sep 17 00:00:00 2001 From: Superset Dev Date: Fri, 17 Apr 2026 08:41:14 -0700 Subject: [PATCH 1/5] docs: add 6.1 catchup documentation for security, alerts, theming, and config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - security.mdx: document API key authentication (PR #37973) — creation via Security → API Keys, Bearer token usage, use cases, and security caution - alerts-reports.mdx: document webhook notifications (PR #36127) — enable via ALERT_REPORT_WEBHOOK feature flag, JSON payload format, multipart attachments, HTTPS enforcement, and retry behavior - theming.mdx: update default fonts note (IBM Plex Mono replaces Fira Code as default monospace in 6.1); add Theme Validation and Fallback section explaining the three-level fallback order and warning log behavior - configuring-superset.mdx: document HASH_ALGORITHM config key (md5/sha256 for FedRAMP compliance) and SQLLAB_HISTORY_RETENTION_DAYS (default 30 days, None to disable pruning) Co-Authored-By: Claude Sonnet 4.6 --- .../configuration/alerts-reports.mdx | 55 +++++++++++++++++++ .../configuration/configuring-superset.mdx | 26 +++++++++ docs/admin_docs/configuration/theming.mdx | 17 +++++- docs/admin_docs/security/security.mdx | 34 ++++++++++++ 4 files changed, 131 insertions(+), 1 deletion(-) diff --git a/docs/admin_docs/configuration/alerts-reports.mdx b/docs/admin_docs/configuration/alerts-reports.mdx index b66f641e290b..4007fa3bf228 100644 --- a/docs/admin_docs/configuration/alerts-reports.mdx +++ b/docs/admin_docs/configuration/alerts-reports.mdx @@ -81,6 +81,61 @@ SLACK_CACHE_TIMEOUT = int(timedelta(days=2).total_seconds()) SLACK_API_RATE_LIMIT_RETRY_COUNT = 5 ``` +### Webhook integration + +Superset can send alert and report notifications to any HTTP endpoint — useful for chat platforms, incident management tools, or custom automation. + +#### Enabling Webhooks + +Enable the feature flag in `superset_config.py`: + +```python +FEATURE_FLAGS = { + "ALERT_REPORTS": True, + "ALERT_REPORT_WEBHOOK": True, +} +``` + +#### Configuring a Webhook Recipient + +When creating or editing an alert or report, select **Webhook** as the notification method and enter your endpoint URL. + +#### Payload Format + +Superset sends an HTTP POST with `Content-Type: application/json`: + +```json +{ + "name": "My Alert", + "header": { + "notification_format": "JSON", + "notification_type": "Alert", + "notification_source": "Alert", + "chart_id": 42, + "dashboard_id": null + }, + "text": "Alert condition met: value exceeded threshold", + "description": "Monthly revenue dropped below target", + "url": "https://your-superset-host/superset/dashboard/1/" +} +``` + +When a report includes file attachments (CSV, PDF, or PNG screenshots), they are sent as a `multipart/form-data` request with the JSON payload in the `data` field and files attached separately. + +#### HTTPS Enforcement + +To require HTTPS webhook URLs (recommended for production), set: + +```python +ALERT_REPORTS_WEBHOOK_HTTPS_ONLY = True +``` + +When enabled, Superset rejects webhook configurations that use `http://` URLs. + +#### Retry Behavior + +Superset automatically retries webhook deliveries on `429 Too Many Requests` and `5xx` server errors using exponential backoff. + ### Kubernetes-specific - You must have a `celery beat` pod running. If you're using the chart included in the GitHub repository under [helm/superset](https://github.com/apache/superset/tree/master/helm/superset), you need to put `supersetCeleryBeat.enabled = true` in your values override. diff --git a/docs/admin_docs/configuration/configuring-superset.mdx b/docs/admin_docs/configuration/configuring-superset.mdx index 657d5d4dc75e..3b9d2a5cf919 100644 --- a/docs/admin_docs/configuration/configuring-superset.mdx +++ b/docs/admin_docs/configuration/configuring-superset.mdx @@ -444,6 +444,32 @@ FEATURE_FLAGS = { A current list of feature flags can be found in the [Feature Flags](/admin-docs/configuration/feature-flags) documentation. +## Security Configuration + +### HASH_ALGORITHM + +Controls the hashing algorithm used for internal checksums and cache keys. The default is `md5` for performance, but `sha256` is available for environments with stricter compliance requirements (e.g., FedRAMP): + +```python +HASH_ALGORITHM = "sha256" # default: "md5" +``` + +:::note +This setting affects internal Superset operations only, not user passwords or authentication tokens. Changing it in an existing deployment may invalidate cached values but does not require a database migration. +::: + +## SQL Lab Configuration + +### SQLLAB_HISTORY_RETENTION_DAYS + +Controls how long SQL Lab query history is retained in the metadata database. The default is 30 days: + +```python +SQLLAB_HISTORY_RETENTION_DAYS = 30 # set to None to retain history indefinitely +``` + +Old queries are pruned by the `celery beat` scheduler. Set to `None` to disable automatic cleanup, though this may cause the metadata database to grow unbounded over time. + :::resources - [Blog: Feature Flags in Apache Superset](https://preset.io/blog/feature-flags-in-apache-superset-and-preset/) ::: diff --git a/docs/admin_docs/configuration/theming.mdx b/docs/admin_docs/configuration/theming.mdx index 8f88ec8fda36..9795cf8d8f95 100644 --- a/docs/admin_docs/configuration/theming.mdx +++ b/docs/admin_docs/configuration/theming.mdx @@ -93,6 +93,17 @@ When `ENABLE_UI_THEME_ADMINISTRATION = True`: 3. Administrators can change system themes without restarting Superset 4. Configuration file themes serve as fallbacks when no UI themes are set +### Theme Validation and Fallback + +Superset validates theme JSON when it is saved, either through the UI or via configuration. If a theme contains invalid tokens or an unrecognized structure, Superset logs a warning and falls back to the built-in default theme rather than applying a broken configuration. This prevents a bad theme from rendering the application unusable. + +The fallback order is: +1. **UI-configured system theme** (highest priority, if `ENABLE_UI_THEME_ADMINISTRATION = True`) +2. **`THEME_DEFAULT` / `THEME_DARK`** from `superset_config.py` +3. **Built-in Superset default theme** (always present as a safety net) + +If you see unexpected styling after a config change, check the Superset server logs for theme validation warnings. + ### Copying Themes Between Systems To export a theme for use in configuration files or another instance: @@ -114,7 +125,11 @@ Superset supports custom fonts through the theme configuration, allowing you to ### Default Fonts -By default, Superset uses Inter and Fira Code fonts which are bundled with the application via `@fontsource` packages. These fonts work offline and require no external network calls. +By default, Superset uses **Inter** for UI text and **IBM Plex Mono** for code (SQL editors, JSON fields, and other monospace contexts). Both fonts are bundled with the application via `@fontsource` packages and work offline without any external network calls. + +:::note +IBM Plex Mono replaced Fira Code as the default code font in Superset 6.1. If you have an existing theme that explicitly sets `fontFamilyCode: "Fira Code, ..."`, you may want to update it. +::: ### Configuring Custom Fonts diff --git a/docs/admin_docs/security/security.mdx b/docs/admin_docs/security/security.mdx index 867e3f87986a..52de1d650adc 100644 --- a/docs/admin_docs/security/security.mdx +++ b/docs/admin_docs/security/security.mdx @@ -194,6 +194,40 @@ FAB_ADD_SECURITY_API = True Once configured, the documentation for additional "Security" endpoints will be visible in Swagger for you to explore. +### API Key Authentication + +Superset supports long-lived API keys for service accounts, CI/CD pipelines, and programmatic integrations (including MCP clients). API keys are managed through **Security → API Keys** in the admin menu. + +#### Creating an API Key + +1. Navigate to **Security → API Keys** +2. Click **+ API Key** +3. Enter a name and (optionally) an expiration date +4. Copy the generated token — it is shown only once + +Only users with the `can_read` and `can_write` permissions on `ApiKey` (granted by default to Admins) can manage API keys. + +#### Using an API Key + +Pass the key as a Bearer token in the `Authorization` header: + +``` +Authorization: Bearer +``` + +This works for all REST API endpoints and the MCP server. The request is executed with the permissions of the user who created the key. + +#### Use Cases + +- **CI/CD pipelines** — automated chart/dashboard exports and imports +- **MCP integrations** — connect AI assistants without interactive login +- **External services** — dashboards embedded in other applications +- **Service accounts** — long-lived credentials that don't expire with session cookies + +:::caution +Store API keys securely. Anyone with a valid key can make requests on behalf of the creating user. Revoke keys promptly if they are compromised by deleting them from **Security → API Keys**. +::: + ### Customizing Permissions The permissions exposed by FAB are very granular and allow for a great level of From df194a28e1c5ab892a7be293402921f345291bc5 Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Wed, 22 Apr 2026 12:35:32 -0700 Subject: [PATCH 2/5] address review: correct HASH_ALGORITHM default in docs Default is sha256 (per superset/config.py), not md5. Also mentions the HASH_ALGORITHM_FALLBACKS companion setting. --- docs/admin_docs/configuration/configuring-superset.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/admin_docs/configuration/configuring-superset.mdx b/docs/admin_docs/configuration/configuring-superset.mdx index 3b9d2a5cf919..0f7a8b4c978c 100644 --- a/docs/admin_docs/configuration/configuring-superset.mdx +++ b/docs/admin_docs/configuration/configuring-superset.mdx @@ -448,12 +448,14 @@ A current list of feature flags can be found in the [Feature Flags](/admin-docs/ ### HASH_ALGORITHM -Controls the hashing algorithm used for internal checksums and cache keys. The default is `md5` for performance, but `sha256` is available for environments with stricter compliance requirements (e.g., FedRAMP): +Controls the hashing algorithm used for internal checksums and cache keys (thumbnails, cache keys, etc.). The default is `sha256`, which satisfies environments with stricter compliance requirements (e.g., FedRAMP). Set it to `md5` to retain the legacy behavior from older Superset deployments: ```python -HASH_ALGORITHM = "sha256" # default: "md5" +HASH_ALGORITHM = "sha256" # default; set to "md5" for legacy behavior ``` +A companion `HASH_ALGORITHM_FALLBACKS` list (default: `["md5"]`) lets UUID lookups fall back to older algorithms, which enables gradual migration without breaking existing entries. Set it to `[]` for strict mode (use only `HASH_ALGORITHM`). + :::note This setting affects internal Superset operations only, not user passwords or authentication tokens. Changing it in an existing deployment may invalidate cached values but does not require a database migration. ::: From eadd14713f603e1337a6e7bf4ef4cb035213e316 Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Wed, 22 Apr 2026 12:36:42 -0700 Subject: [PATCH 3/5] address review: document SQL Lab query pruning accurately There is no SQLLAB_HISTORY_RETENTION_DAYS config. Pruning is opt-in via the prune_query Celery beat task, which is commented out in the default CELERY_BEAT_SCHEDULE. Rewrite the section to reflect how the feature actually works. --- .../configuration/configuring-superset.mdx | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/admin_docs/configuration/configuring-superset.mdx b/docs/admin_docs/configuration/configuring-superset.mdx index 0f7a8b4c978c..24120573ceab 100644 --- a/docs/admin_docs/configuration/configuring-superset.mdx +++ b/docs/admin_docs/configuration/configuring-superset.mdx @@ -460,17 +460,21 @@ A companion `HASH_ALGORITHM_FALLBACKS` list (default: `["md5"]`) lets UUID looku This setting affects internal Superset operations only, not user passwords or authentication tokens. Changing it in an existing deployment may invalidate cached values but does not require a database migration. ::: -## SQL Lab Configuration +## SQL Lab Query History Pruning -### SQLLAB_HISTORY_RETENTION_DAYS - -Controls how long SQL Lab query history is retained in the metadata database. The default is 30 days: +SQL Lab query history is stored in the metadata database and is **not** pruned by default. To trim older rows, enable the `prune_query` Celery beat task by uncommenting it in `CELERY_BEAT_SCHEDULE` and choosing a retention window: ```python -SQLLAB_HISTORY_RETENTION_DAYS = 30 # set to None to retain history indefinitely +CELERY_BEAT_SCHEDULE = { + "prune_query": { + "task": "prune_query", + "schedule": crontab(minute=0, hour=0, day_of_month=1), + "kwargs": {"retention_period_days": 180}, + }, +} ``` -Old queries are pruned by the `celery beat` scheduler. Set to `None` to disable automatic cleanup, though this may cause the metadata database to grow unbounded over time. +Adjust `retention_period_days` to control how long query rows are kept. Companion opt-in tasks (`prune_logs`, `prune_tasks`) exist for pruning the logs and tasks tables; see the commented-out examples in `superset/config.py`. Without enabling these tasks, the metadata database will grow unbounded over time. :::resources - [Blog: Feature Flags in Apache Superset](https://preset.io/blog/feature-flags-in-apache-superset-and-preset/) From 61dbcc955b81faeeba2f59cc319852582e639291 Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Wed, 22 Apr 2026 23:56:23 -0700 Subject: [PATCH 4/5] address review: correct webhook multipart payload description Clarify that multipart/form-data webhook deliveries send each top-level payload field (name, text, description, url) as its own form field, with nested values like `header` JSON-encoded. Files are attached as repeated `files` form fields. This matches what `WebhookNotification.send()` actually does in superset/reports/notifications/webhook.py. --- .../configuration/alerts-reports.mdx | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/admin_docs/configuration/alerts-reports.mdx b/docs/admin_docs/configuration/alerts-reports.mdx index 4007fa3bf228..f5c4efc42eda 100644 --- a/docs/admin_docs/configuration/alerts-reports.mdx +++ b/docs/admin_docs/configuration/alerts-reports.mdx @@ -120,7 +120,33 @@ Superset sends an HTTP POST with `Content-Type: application/json`: } ``` -When a report includes file attachments (CSV, PDF, or PNG screenshots), they are sent as a `multipart/form-data` request with the JSON payload in the `data` field and files attached separately. +When a report includes file attachments (CSV, PDF, or PNG screenshots), the request is sent as `multipart/form-data` instead. In that case, each top-level payload field (`name`, `text`, `description`, `url`) becomes its own form field, and nested structures like `header` are serialized as a JSON-encoded string in their own field. Every attachment is added as a repeated form field named `files`: + +``` +POST /webhook HTTP/1.1 +Content-Type: multipart/form-data; boundary=... + +--... +Content-Disposition: form-data; name="name" + +My Alert +--... +Content-Disposition: form-data; name="header" + +{"notification_format": "JSON", "notification_type": "Alert", ...} +--... +Content-Disposition: form-data; name="text" + +Alert condition met: value exceeded threshold +--... +Content-Disposition: form-data; name="files"; filename="report.csv" +Content-Type: text/csv + + +--... +``` + +Webhook consumers should branch on `Content-Type`: parse the body as JSON when `application/json`, or read the individual form fields (decoding `header` as JSON) when `multipart/form-data`. #### HTTPS Enforcement From a08219eaf816f866d61fd8e7a521ee4c13e7522f Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Wed, 22 Apr 2026 23:56:59 -0700 Subject: [PATCH 5/5] address review: correct API key enablement and UI location in docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous docs said API keys are managed via Security → API Keys in the admin menu, but that page does not exist. In reality: - API key authentication is disabled by default. Admins must both set FAB_API_KEY_ENABLED=True (Flask-AppBuilder config) and enable the FAB_API_KEY_ENABLED feature flag to expose the UI. - Keys are managed on the User Info page, under the "API Keys" collapse panel (see superset-frontend/src/pages/UserInfo/index.tsx). Update the section to describe both the enablement steps and the correct UI path. --- docs/admin_docs/security/security.mdx | 29 +++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/docs/admin_docs/security/security.mdx b/docs/admin_docs/security/security.mdx index 52de1d650adc..11b8a0651b0e 100644 --- a/docs/admin_docs/security/security.mdx +++ b/docs/admin_docs/security/security.mdx @@ -196,14 +196,31 @@ Once configured, the documentation for additional "Security" endpoints will be v ### API Key Authentication -Superset supports long-lived API keys for service accounts, CI/CD pipelines, and programmatic integrations (including MCP clients). API keys are managed through **Security → API Keys** in the admin menu. +Superset supports long-lived API keys for service accounts, CI/CD pipelines, and programmatic integrations (including MCP clients). + +#### Enabling API Key Authentication + +API key authentication is **disabled by default**. To turn it on, set the Flask-AppBuilder config value in `superset_config.py` and also enable the matching feature flag so the management UI is exposed: + +```python +FAB_API_KEY_ENABLED = True + +FEATURE_FLAGS = { + "FAB_API_KEY_ENABLED": True, +} +``` + +The config value registers the `ApiKeyApi` blueprint on the backend; the feature flag controls whether the UI for managing keys appears for the user. See the [Feature Flags](/admin-docs/configuration/feature-flags) documentation for more on feature flag configuration. #### Creating an API Key -1. Navigate to **Security → API Keys** -2. Click **+ API Key** -3. Enter a name and (optionally) an expiration date -4. Copy the generated token — it is shown only once +Once enabled, each user manages their own keys from their profile page: + +1. Open the user menu (top-right) and click **Info** to navigate to the User Info page +2. Expand the **API Keys** section +3. Click **+ API Key** +4. Enter a name and (optionally) an expiration date +5. Copy the generated token — it is shown only once Only users with the `can_read` and `can_write` permissions on `ApiKey` (granted by default to Admins) can manage API keys. @@ -225,7 +242,7 @@ This works for all REST API endpoints and the MCP server. The request is execute - **Service accounts** — long-lived credentials that don't expire with session cookies :::caution -Store API keys securely. Anyone with a valid key can make requests on behalf of the creating user. Revoke keys promptly if they are compromised by deleting them from **Security → API Keys**. +Store API keys securely. Anyone with a valid key can make requests on behalf of the creating user. Revoke keys promptly if they are compromised by deleting them from the **API Keys** section of your User Info page. ::: ### Customizing Permissions