How to Configure OAuth2/SSO Authentication in Apache Superset: Google, Okta, and Auth0 Guide

To enable OAuth2/SSO in Apache Superset, install Authlib, set AUTH_TYPE = AUTH_OAUTH in superset_config.py, and populate the OAUTH_PROVIDERS list with your identity provider's endpoints.

Apache Superset delegates authentication to Flask-AppBuilder, allowing seamless integration with any OAuth 2.0 or OpenID Connect provider. By configuring a few Python variables in your superset_config.py file, you can redirect users through enterprise SSO flows while controlling automatic provisioning and role mapping.

Prerequisites for OAuth2 Authentication

Superset requires the Authlib library to handle token exchanges and HTTP client operations. Install the OAuth extra before modifying configuration files.

pip install "apache-superset[oauth]"

Configure OAuth2 Authentication in Superset

All SSO settings reside in superset_config.py (or any Python module imported at startup). You must change the authentication type and declare provider metadata.

Enable OAuth Mode

Import the authentication constant and switch from database authentication to OAuth. The application logic in superset/views/base.py checks auth_type == AUTH_OAUTH at line 39 to determine whether to render OAuth login buttons.

from flask_appbuilder.security.manager import AUTH_OAUTH

AUTH_TYPE = AUTH_OAUTH

Define OAuth Providers

Populate the OAUTH_PROVIDERS list with dictionaries containing name, token_key, icon, and remote_app keys. The remote_app dictionary passes directly to Authlib's client configuration.

Google Configuration Example:

OAUTH_PROVIDERS = [
    {
        "name": "google",
        "icon": "fa-google",
        "token_key": "access_token",
        "remote_app": {
            "client_id": "YOUR_GOOGLE_CLIENT_ID",
            "client_secret": "YOUR_GOOGLE_CLIENT_SECRET",
            "api_base_url": "https://www.googleapis.com/oauth2/v2/",
            "client_kwargs": {"scope": "openid email profile"},
            "authorize_url": "https://accounts.google.com/o/oauth2/auth",
            "access_token_url": "https://oauth2.googleapis.com/token",
        },
    },
]

Okta Configuration Example:

Replace YOUR_OKTA_DOMAIN with your organization's tenant domain.

OAUTH_PROVIDERS = [
    {
        "name": "okta",
        "icon": "fa-lock",
        "token_key": "access_token",
        "remote_app": {
            "client_id": "YOUR_OKTA_CLIENT_ID",
            "client_secret": "YOUR_OKTA_CLIENT_SECRET",
            "api_base_url": "https://YOUR_OKTA_DOMAIN.okta.com/oauth2/v1/",
            "client_kwargs": {"scope": "openid email profile"},
            "authorize_url": "https://YOUR_OKTA_DOMAIN.okta.com/oauth2/v1/authorize",
            "access_token_url": "https://YOUR_OKTA_DOMAIN.okta.com/oauth2/v1/token",
            "jwks_uri": "https://YOUR_OKTA_DOMAIN.okta.com/oauth2/v1/keys",
        },
    },
]

Auth0 Configuration Example:

OAUTH_PROVIDERS = [
    {
        "name": "auth0",
        "icon": "fa-key",
        "token_key": "access_token",
        "remote_app": {
            "client_id": "YOUR_AUTH0_CLIENT_ID",
            "client_secret": "YOUR_AUTH0_CLIENT_SECRET",
            "api_base_url": "https://YOUR_DOMAIN.auth0.com/",
            "client_kwargs": {"scope": "openid email profile"},
            "authorize_url": "https://YOUR_DOMAIN.auth0.com/authorize",
            "access_token_url": "https://YOUR_DOMAIN.auth0.com/oauth/token",
            "jwks_uri": "https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json",
        },
    },
]

The canonical reference for these structures appears in docs/versioned_docs/version-6.0.0/configuration/configuring-superset.mdx at lines 57-73.

Advanced Configuration

Beyond basic connectivity, you can automate user creation and map custom identity claims to Superset user attributes.

Enable Automatic User Registration

To create local Flask-AppBuilder accounts automatically upon first login, enable registration flags. According to the documentation at lines 98-102 of configuring-superset.mdx, add:

AUTH_USER_REGISTRATION = True
AUTH_USER_REGISTRATION_ROLE = "Public"  # Alternative: "Admin" or "Gamma"

Map Provider Claims with Custom Security Manager

When providers return non-standard claims or require additional API calls, subclass SupersetSecurityManager and override the oauth_user_info method. This function receives the provider name and token response, allowing you to fetch supplemental user data.

Create a custom security manager (e.g., custom_sso_security_manager.py):

from superset.security import SupersetSecurityManager
import logging

class CustomSsoSecurityManager(SupersetSecurityManager):
    def oauth_user_info(self, provider, response=None):
        logging.debug("OAuth2 provider: %s", provider)
        if provider == "okta":
            me = self.appbuilder.sm.oauth_remotes[provider].get('userinfo').data
            return {
                "name": me["name"],
                "email": me["email"],
                "id": me["sub"],
                "username": me["preferred_username"],
            }

Then reference the custom class in superset_config.py:

from custom_sso_security_manager import CustomSsoSecurityManager
CUSTOM_SECURITY_MANAGER = CustomSsoSecurityManager

This pattern appears in the official documentation at lines 14-32 and enables normalization of Okta, Auth0, or Azure AD profiles into Superset's internal user model.

Key Files and Implementation Details

Understanding the source code helps troubleshoot SSO issues:

• superset/views/base.py: Contains the AUTH_OAUTH constant check at line 39 that determines which login template to render.
• superset/config.py: Stores global defaults including the DATABASE_OAUTH2_CLIENTS dictionary (lines 72-103) used for database-level OAuth (e.g., Google Sheets).
• docs/versioned_docs/version-6.0.0/configuration/configuring-superset.mdx: Official reference documentation for SSO setup.

Summary

• Install the OAuth dependency with pip install "apache-superset[oauth]" before configuring providers.
• Set AUTH_TYPE = AUTH_OAUTH in superset_config.py to enable OAuth2 authentication.
• Configure identity providers in the OAUTH_PROVIDERS list using remote_app dictionaries for Google, Okta, Auth0, or any OIDC-compliant service.
• Enable AUTH_USER_REGISTRATION to automatically provision users on first login.
• Subclass SupersetSecurityManager and override oauth_user_info to handle custom claims or additional API calls.

Frequently Asked Questions

Does Apache Superset support SAML authentication?

Yes, Superset supports SAML through Flask-AppBuilder's AUTH_SAML type, though it requires different configuration keys than OAuth2. You must install python3-saml and configure SAML_CONFIG instead of OAUTH_PROVIDERS. OAuth2 remains the preferred method for cloud providers like Google and Auth0.

How do I troubleshoot "Invalid client" errors during OAuth login?

This error typically indicates a mismatch between your client_id or client_secret and the values registered in your provider's console. Verify that redirect URIs in your provider configuration exactly match your Superset base URL (e.g., https://superset.example.com/oauth-authorized/google). Check superset_config.py for typos in the remote_app dictionary.

Can I configure multiple OAuth providers simultaneously?

Yes, the OAUTH_PROVIDERS list accepts multiple dictionaries. Superset renders each provider as an icon on the login screen. Users click their preferred provider, and Superset routes them to /oauth-authorized/<name> where <name> matches the provider's identifier.

Where is the AUTH_OAUTH constant defined?

The constant is imported from flask_appbuilder.security.manager. In superset/views/base.py, the application checks this constant at line 39 to determine whether to display the OAuth login buttons or the standard database login form.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}