Configuring Superset

Configuration

To configure your application, you need to create a file superset_config.py and add it to your PYTHONPATH. If your application was installed using docker-compose an alternative configuration is required. See https://github.com/apache/superset/tree/master/docker#readme for details.

Here are some of the parameters you can set in that file:

# Superset specific config
ROW_LIMIT = 5000
SUPERSET_WEBSERVER_PORT = 8088
# Flask App Builder configuration
# Your App secret key will be used for securely signing the session cookie
# and encrypting sensitive information on the database
# Make sure you are changing this key for your deployment with a strong key.
# You can generate a strong key using `openssl rand -base64 42`
SECRET_KEY = 'YOUR_OWN_RANDOM_GENERATED_SECRET_KEY'
# The SQLAlchemy connection string to your database backend
# This connection defines the path to the database that stores your
# superset metadata (slices, connections, tables, dashboards, ...).
# Note that the connection information to connect to the datasources
# you want to explore are managed directly in the web UI
SQLALCHEMY_DATABASE_URI = 'sqlite:////path/to/superset.db'
# Flask-WTF flag for CSRF
WTF_CSRF_ENABLED = True
# Add endpoints that need to be exempt from CSRF protection
WTF_CSRF_EXEMPT_LIST = []
# A CSRF token that expires in 1 year
WTF_CSRF_TIME_LIMIT = 60 * 60 * 24 * 365
# Set this API key to enable Mapbox visualizations
MAPBOX_API_KEY = ''

All the parameters and default values defined in https://github.com/apache/superset/blob/master/superset/config.py can be altered in your local superset_config.py. Administrators will want to read through the file to understand what can be configured locally as well as the default values in place.

Since superset_config.py acts as a Flask configuration module, it can be used to alter the settings Flask itself, as well as Flask extensions like flask-wtf, flask-caching, flask-migrate, and flask-appbuilder. Flask App Builder, the web framework used by Superset, offers many configuration settings. Please consult the Flask App Builder Documentation for more information on how to configure it.

Make sure to change:

• SQLALCHEMY_DATABASE_URI: by default it is stored at ~/.superset/superset.db
• SECRET_KEY: to a long random string

If you need to exempt endpoints from CSRF (e.g. if you are running a custom auth postback endpoint), you can add the endpoints to WTF_CSRF_EXEMPT_LIST:

WTF_CSRF_EXEMPT_LIST = [‘’]

Using a production metastore

By default Superset is configured to use SQLite, it’s a simple and fast way to get you started (no installation needed). But for production environments you should use a different database engine on a separate host or container.

Superset supports the following database engines/versions:

Use the following database drivers and connection strings:

To configure Superset metastore set SQLALCHEMY_DATABASE_URI config key on superset_config to the appropriate connection string.

Running on a WSGI HTTP Server

While you can run Superset on NGINX or Apache, we recommend using Gunicorn in async mode. This enables impressive concurrency even and is fairly easy to install and configure. Please refer to the documentation of your preferred technology to set up this Flask WSGI application in a way that works well in your environment. Here’s an async setup known to work well in production:

      -w 10 \
      -k gevent \
      --worker-connections 1000 \
      --timeout 120 \
      -b  0.0.0.0:6666 \
      --limit-request-line 0 \
      --limit-request-field_size 0 \
      --statsd-host localhost:8125 \
      "superset.app:create_app()"

Refer to the Gunicorn documentation for more information. Note that the development web server (superset run or flask run) is not intended for production use.

If you’re not using Gunicorn, you may want to disable the use of flask-compress by setting COMPRESS_REGISTER = False in your superset_config.py.

Configuration Behind a Load Balancer

If you are running superset behind a load balancer or reverse proxy (e.g. NGINX or ELB on AWS), you may need to utilize a healthcheck endpoint so that your load balancer knows if your superset instance is running. This is provided at /health which will return a 200 response containing “OK” if the webserver is running.

If the load balancer is inserting X-Forwarded-For/X-Forwarded-Proto headers, you should set ENABLE_PROXY_FIX = True in the superset config file (superset_config.py) to extract and use the headers.

In case the reverse proxy is used for providing SSL encryption, an explicit definition of the X-Forwarded-Proto may be required. For the Apache webserver this can be set as follows:

RequestHeader set X-Forwarded-Proto "https"

Custom OAuth2 Configuration

Beyond FAB supported providers (GitHub, Twitter, LinkedIn, Google, Azure, etc), its easy to connect Superset with other OAuth2 Authorization Server implementations that support “code” authorization.

Make sure the pip package Authlib is installed on the webserver.

First, configure authorization in Superset superset_config.py.

from flask_appbuilder.security.manager import AUTH_OAUTH
# Set the authentication type to OAuth
AUTH_TYPE = AUTH_OAUTH
OAUTH_PROVIDERS = [
    {   'name':'egaSSO',
        'token_key':'access_token', # Name of the token in the response of access_token_url
        'icon':'fa-address-card',   # Icon for the provider
        'remote_app': {
            'client_id':'myClientId',  # Client Id (Identify Superset application)
            'client_secret':'MySecret', # Secret for this Client Id (Identify Superset application)
            'client_kwargs':{
                'scope': 'read'               # Scope for the Authorization
            },
            'access_token_method':'POST',    # HTTP Method to call access_token_url
            'access_token_params':{        # Additional parameters for calls to access_token_url
                'client_id':'myClientId'
            },
            'access_token_headers':{    # Additional headers for calls to access_token_url
                'Authorization': 'Basic Base64EncodedClientIdAndSecret'
            },
            'api_base_url':'https://myAuthorizationServer/oauth2AuthorizationServer/',
            'access_token_url':'https://myAuthorizationServer/oauth2AuthorizationServer/token',
            'authorize_url':'https://myAuthorizationServer/oauth2AuthorizationServer/authorize'
        }
    }
]
# Will allow user self registration, allowing to create Flask users from Authorized User
AUTH_USER_REGISTRATION = True
# The default user self registration role
AUTH_USER_REGISTRATION_ROLE = "Public"

Then, create a CustomSsoSecurityManager that extends SupersetSecurityManager and overrides oauth_user_info:

import logging
from superset.security import SupersetSecurityManager
class CustomSsoSecurityManager(SupersetSecurityManager):
    def oauth_user_info(self, provider, response=None):
        logging.debug("Oauth2 provider: {0}.".format(provider))
        if provider == 'egaSSO':
            # As example, this line request a GET to base_url + '/' + userDetails with Bearer  Authentication,
    # and expects that authorization server checks the token, and response with user details
            me = self.appbuilder.sm.oauth_remotes[provider].get('userDetails').data
            logging.debug("user_data: {0}".format(me))
            return { 'name' : me['name'], 'email' : me['email'], 'id' : me['user_name'], 'username' : me['user_name'], 'first_name':'', 'last_name':''}
    ...

This file must be located at the same directory than superset_config.py with the name custom_sso_security_manager.py. Finally, add the following 2 lines to superset_config.py:

from custom_sso_security_manager import CustomSsoSecurityManager
CUSTOM_SECURITY_MANAGER = CustomSsoSecurityManager

Notes

• The redirect URL will be https://<superset-webserver>/oauth-authorized/<provider-name> When configuring an OAuth2 authorization provider if needed. For instance, the redirect URL will be https://<superset-webserver>/oauth-authorized/egaSSO for the above configuration.

• If an OAuth2 authorization server supports OpenID Connect 1.0, you could configure its configuration document URL only without providing api_base_url, access_token_url, authorize_url and other required options like user info endpoint, jwks uri etc. For instance:

  OAUTH_PROVIDERS = [
    {   'name':'egaSSO',
        'token_key':'access_token', # Name of the token in the response of access_token_url
        'icon':'fa-address-card',   # Icon for the provider
        'remote_app': {
            'client_id':'myClientId',  # Client Id (Identify Superset application)
            'client_secret':'MySecret', # Secret for this Client Id (Identify Superset application)
            'server_metadata_url': 'https://myAuthorizationServer/.well-known/openid-configuration'
        }
    }
  ]

Flask app Configuration Hook

FLASK_APP_MUTATOR is a configuration function that can be provided in your environment, receives the app object and can alter it in any way. For example, add FLASK_APP_MUTATOR into your superset_config.py to setup session cookie expiration time to 24 hours:

from flask import session
from flask import Flask
def make_session_permanent():
    '''
    Enable maxAge for the cookie 'session'
    '''
    session.permanent = True
# Set up max age of session to 24 hours
PERMANENT_SESSION_LIFETIME = timedelta(hours=24)
def FLASK_APP_MUTATOR(app: Flask) -> None:
    app.before_request_funcs.setdefault(None, []).append(make_session_permanent)

Feature Flags

To support a diverse set of users, Superset has some features that are not enabled by default. For example, some users have stronger security restrictions, while some others may not. So Superset allow users to enable or disable some features by config. For feature owners, you can add optional functionalities in Superset, but will be only affected by a subset of users.

You can enable or disable features with flag from superset_config.py:

FEATURE_FLAGS = {
    'CLIENT_CACHE': False,
    'ENABLE_EXPLORE_JSON_CSRF_PROTECTION': False,
    'PRESTO_EXPAND_DATA': False,
}

A current list of feature flags can be found in RESOURCES/FEATURE_FLAGS.md.

SECRET_KEY Rotation

If you want to rotate the SECRET_KEY(change the existing secret key), follow the below steps.

Add the new SECRET_KEY and PREVIOUS_SECRET_KEY to superset_config.py:

PREVIOUS_SECRET_KEY = 'CURRENT_SECRET_KEY' # The default SECRET_KEY for deployment is '21thisismyscretkey12eyyh'
SECRET_KEY = 'YOUR_OWN_RANDOM_GENERATED_SECRET_KEY'

Then run superset re-encrypt-secrets