diff --git a/docs/admin_docs/configuration/alerts-reports.mdx b/docs/admin_docs/configuration/alerts-reports.mdx index b66f641e290..f5c4efc42ed 100644 --- a/docs/admin_docs/configuration/alerts-reports.mdx +++ b/docs/admin_docs/configuration/alerts-reports.mdx @@ -81,6 +81,87 @@ 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), 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 + +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 becdf70888b..daf92b1c943 100644 --- a/docs/admin_docs/configuration/configuring-superset.mdx +++ b/docs/admin_docs/configuration/configuring-superset.mdx @@ -472,6 +472,38 @@ 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 (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; 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. +::: + +## SQL Lab Query History Pruning + +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 +CELERY_BEAT_SCHEDULE = { + "prune_query": { + "task": "prune_query", + "schedule": crontab(minute=0, hour=0, day_of_month=1), + "kwargs": {"retention_period_days": 180}, + }, +} +``` + +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/) ::: diff --git a/docs/admin_docs/configuration/theming.mdx b/docs/admin_docs/configuration/theming.mdx index c13e42617a0..92e4fcd8e59 100644 --- a/docs/admin_docs/configuration/theming.mdx +++ b/docs/admin_docs/configuration/theming.mdx @@ -122,6 +122,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: @@ -143,7 +154,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 b4261c60bf5..6190925d8ab 100644 --- a/docs/admin_docs/security/security.mdx +++ b/docs/admin_docs/security/security.mdx @@ -205,6 +205,57 @@ 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). + +#### 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 + +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. + +#### 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 the **API Keys** section of your User Info page. +::: + ### Customizing Permissions The permissions exposed by FAB are very granular and allow for a great level of