Superset OAuth2 Integration

This document explains how to implement Monosign with Apache Superset, the open-source data exploration and dashboard platform. It covers Single Sign-On. Superset calls its external login OAuth2 (AUTH_OAUTH in Flask-AppBuilder). It works with any OpenID Connect compatible identity provider by using the OIDC discovery document, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to start with the Superset configuration documentation (section “Custom OAuth2 Configuration”).

This configuration is done with Apache Superset 6.1.0 running on Docker Compose (image apache/superset:6.1.0, official docker-compose-image-tag.yml of Superset). If your Superset version or deployment type is different, please check the Superset documentation.

Superset uses one authentication type at a time. When OAuth2 is enabled, the local user name and password form is replaced by the “Sign in with Monosign” button.

Monofor has no responsibility to do Superset configurations. If you need support please contact the Apache Superset community or your Superset support provider.

📑 Instructions

This documentation contains 5 main steps for integration.

Creating an application on Monosign
Configuring the OIDC/OpenID settings on Monosign
Assign a user to the Superset application
Configuration Single Sign-On for Superset
Sign In Test

1- Creating an Application on Monosign

Create your application on Monosign first. Open the Applications page from the left menu and click Add New.

Applications page in Monosign (1: Applications menu, 2: Add New)

Superset is not in the application catalog, so click Create from scratch.

Creating a new application from scratch (1: Create from scratch)

Fill in the application details on the Application tab and click Next.

New Application - Application tab (1: Name, 2: Logo, 3: Next)

Property	Value	Description
Name	`Superset`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Superset is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the Superset address (for example `https://superset.example.com`).
Logo	Optional	Browse and upload a logo; it is also shown on the Monosign sign-in page.
Users can see this application on their list	`Enabled`	Displays the application on the user portal.

On the Access tab define who can reach the application and click Create Application.

New Application - Access tab (1: Profile Access Type, 2: Create Application)

Property	Value	Description
User Access Type	`System Default`	Defines which users can access this application. Options: Only Assigned Users, All Users, System Default.
User Group Access Type	`System Default`	Defines the application’s user group access.
Source Using Type	`System Default`	Defines which user sources the application can use.
Profile Access Type	`All`	Defines which user profile attributes are available to the application. Superset reads the first name and the last name of the user from the profile (Options: Restricted, All).

After the application is created, click Keys and add a new Access Key for OIDC/OpenID access.

Keys tab of the Superset application (1: Keys, 2: Add New Access Key)

Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically.

Creating the OIDC/OpenID Access Key (1: Type OIDC/OpenID, 2: Create)

Property	Value	Options
Type	`OIDC/OpenID`	Rest API, OAuth 2.0, JWT, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server
Client Id / Client Secret	Generated automatically	Use the eye icon next to the secret to reveal it. Both values are required in step 4.
Session	`System Default`	System Default, On-demand, Permanent
State	`Enabled`	Enabled, Disabled
Never Expires	`Yes`	Turn off to define a specific expiration date for the key.

The details of the key that Superset needs are:

Monosign value	Example	Used in Superset as
Client Id	`<client-id>`	`client_id`
Client Secret	`<client-secret>`	`client_secret`
Configuration Url	`https://<monosign-host>/.well-known/openid-configuration`	`server_metadata_url`. Superset reads the Auth, Token, UserInfo and JWKS addresses from this document.

2- Configuring the OIDC/OpenID Settings on Monosign

Open the key with the Configure button, go to OIDC/OpenID Settings and add the callback address of Superset to Allowed Redirect URIs.

OIDC/OpenID Settings - Allowed Redirect URIs

Property	Value	Description
Allowed Redirect URIs	`https://superset.example.com/oauth-authorized/monosign`	Superset uses `https://<superset-address>/oauth-authorized/<provider-name>`. `monosign` is the provider name that is defined in the Superset configuration (step 4); both must be the same.
Scope	Empty	Superset sends the scope itself (`openid`).
Use ‘state’ parameter as ‘nonce’	`Disabled` (default)	No change is required for Superset.
Token lifetimes, CORS	Empty	Default values are used.

Open the Claim Mapping tab and add the user claims that Superset reads. Click Update to save.

Claim Name	Value	Used in Superset as
preferred_username	`{{UserName}}`	User name of the Superset account.
given_name	`{{Profile.FirstName}}`	First name.
family_name	`{{Profile.LastName}}`	Last name.

The email, name and sub claims are already returned by the Monosign UserInfo endpoint, so they do not need to be added. Superset uses email as the e-mail address of the user.

3- Assign a User to the Superset Application

Please follow the below instructions on how to assign a user to the Superset application. Open the application, click the Assignments tab and click Assign a User.

Assignments tab of the Superset application (1: Assignments, 2: Assign a User)

Search and select the users who can sign in to Superset, check the Expiration Date and save. You can select more than one user.

Assign a User dialog (select the users and set the Expiration Date)

Property	Value	Description
User(s)	Selected users	Users who can sign in to Superset with Monosign.
Expiration Date	Default one year	The assignment expires on this date.

4- Configuration Single Sign-On for Superset

As we mentioned at the start, please check out the Superset documentation first. Superset has no single sign-on screen in its Settings menu. The OAuth2 login is configured in the Python configuration file of Superset (superset_config.py). In the Docker Compose deployment the file docker/pythonpath_dev/superset_config_docker.py is loaded by the default configuration, so the settings are added there. The configuration contains these steps:

Install the Authlib package
Keep the client id and the client secret in an environment file
Add the OAuth2 settings and the custom security manager
Restart the Superset services

a. Install the Authlib Package

The OAuth2 login of Superset needs the Authlib package. It is not included in the Superset image. In the Docker Compose deployment, the startup script installs every package that is listed in docker/requirements-local.txt each time a Superset container starts. Create the file with this line:

Bash

Authlib>=1.3.0,<2

For other deployments install it in the Python environment of Superset: pip install Authlib.

b. Keep the Client Id and the Client Secret in an Environment File

The compose file reads the optional file docker/.env-local for every Superset service. Put the values from step 1 there and restrict the permissions of the file (chmod 600 docker/.env-local). This way the secret is not written in the configuration code.

Bash

OAUTH_CLIENT_ID=<client-id>
OAUTH_CLIENT_SECRET=<client-secret>

c. Add the OAuth2 Settings and the Custom Security Manager

Add the following to docker/pythonpath_dev/superset_config_docker.py:

Python

import os

from flask_appbuilder.security.manager import AUTH_OAUTH

from custom_sso_security_manager import CustomSsoSecurityManager

# Behind a reverse proxy that terminates HTTPS: trust the X-Forwarded-* headers
ENABLE_PROXY_FIX = True

# --- Single Sign-On with Monosign (OAuth2 / OpenID Connect discovery) ---
AUTH_TYPE = AUTH_OAUTH

OAUTH_PROVIDERS = [
    {
        "name": "monosign",
        "icon": "fa-key",
        "token_key": "access_token",
        "remote_app": {
            "client_id": os.getenv("OAUTH_CLIENT_ID"),
            "client_secret": os.getenv("OAUTH_CLIENT_SECRET"),
            "server_metadata_url": "https://<monosign-host>/.well-known/openid-configuration",
            "client_kwargs": {"scope": "openid"},
        },
    }
]

# Create the Superset user automatically on the first Monosign sign-in
AUTH_USER_REGISTRATION = True
AUTH_USER_REGISTRATION_ROLE = "Gamma"
AUTH_ROLES_SYNC_AT_LOGIN = False

CUSTOM_SECURITY_MANAGER = CustomSsoSecurityManager

Superset does not know where the user name and the e-mail address are in the response of a generic provider, so a custom security manager reads them from the Monosign UserInfo endpoint. Create the file custom_sso_security_manager.py in the same folder as the configuration file (docker/pythonpath_dev/):

Python

import logging

from superset.security import SupersetSecurityManager

logger = logging.getLogger(__name__)

USERINFO_URL = "https://<monosign-host>/openid/userinfo"


class CustomSsoSecurityManager(SupersetSecurityManager):
    def oauth_user_info(self, provider, response=None):
        if provider != "monosign":
            return {}

        remote = self.appbuilder.sm.oauth_remotes[provider]
        try:
            me = remote.userinfo()
        except Exception:  # fall back to calling the UserInfo endpoint directly
            logger.warning("userinfo() failed, calling the UserInfo URL", exc_info=True)
            me = remote.get(USERINFO_URL).json()
        me = dict(me)
        logger.info("Monosign userinfo claims: %s", sorted(me.keys()))

        username = me.get("preferred_username") or me.get("username") or me.get("sub")
        email = me.get("email")
        if not email:
            logger.warning("Monosign userinfo has no email, using a placeholder for %s", username)
            email = f"{username}@monosign.invalid"
        return {
            "id": me.get("sub") or username,
            "username": username,
            "email": email,
            "first_name": me.get("given_name") or me.get("name") or username,
            "last_name": me.get("family_name") or "",
        }

Setting	Value	Description
AUTH_TYPE	`AUTH_OAUTH`	Enables the OAuth2 login. The local user name and password form is not shown anymore.
name	`monosign`	Provider name. It is a part of the redirect URI `/oauth-authorized/monosign` and it is checked in the custom security manager.
client_id / client_secret	From the environment	Client Id and Client Secret of the Monosign key.
server_metadata_url	Configuration Url	OIDC discovery document of Monosign. Superset reads all the other addresses from here.
client_kwargs → scope	`openid`	The scope that Superset requests.
AUTH_USER_REGISTRATION	`True`	Creates the Superset account on the first sign-in.
AUTH_USER_REGISTRATION_ROLE	`Gamma`	Role of a new user. Monosign does not send a group claim, so a role cannot be mapped from groups; every new user gets this role.
ENABLE_PROXY_FIX	`True`	Needed when Superset is behind a reverse proxy that terminates HTTPS, so that Superset builds the `https` redirect address.

The Superset configuration is imported when the application starts, so a change needs a restart of the Superset services. The docker/.env-local file contains the client secret; restrict its permissions and do not store it in a shared repository.

The Superset roles are managed inside Superset (Settings → List Users). AUTH_USER_REGISTRATION_ROLE sets the role of the users that are created by the sign-in. To start with an administrator, you can temporarily set it to "Admin" before the administrator signs in for the first time and change it back to "Gamma" afterwards. The local administrator account that the Superset installation creates cannot be used while the OAuth2 login is active, because the local sign-in form is not shown.

d. Restart the Superset Services

Recreate the Superset application, the worker and the scheduler (beat) so that they load the new files and install Authlib. Do not start the one-time superset-init service again; it creates the administrator account and it stops with an error when the account exists.

Bash

cd /opt/superset
docker compose up -d --no-deps --force-recreate superset superset-worker superset-worker-beat

Wait until the application answers OK on the health address, then check that the sign-in starts at Monosign:

Bash

curl -s http://localhost:8088/health
curl -s -o /dev/null -D - http://localhost:8088/login/monosign | grep -i ^location

The Location header must be the Monosign authorization address with redirect_uri=…/oauth-authorized/monosign and scope=openid.

Now try to log in to Superset using Monosign SSO.

Open a new browser window (or a private window) and type the Superset address, for example https://superset.example.com.
Click Sign in with Monosign on the Superset sign-in page.

Superset sign-in page with the “Sign in with Monosign” button

Superset redirects the browser to the Monosign sign-in page of the Superset application. You can log in passwordless with your QR code (Monofor Identity), with a Passkey or with your user name and password (Sign in with Password).

Monosign sign-in page of the Superset application

After the sign-in Monosign redirects the browser back to Superset. Superset creates the account of the user on the first sign-in and opens the home page. You can see the signed-in user from Settings → User → Info.

User logged in to Superset through Monosign SSO (Settings menu: Info and Logout)

Troubleshooting

Symptom	Cause	Solution
The “Sign in with Monosign” button is not shown, or Superset reports that the `authlib` module is missing	The Authlib package is not installed, or the containers were not recreated.	Create `docker/requirements-local.txt` and recreate the Superset services (step 4-a and 4-d).
Monosign shows a redirect URI error	The redirect URI that Superset sends does not exactly match the Allowed Redirect URIs.	Add `https://superset.example.com/oauth-authorized/monosign` in Monosign. The last part must be the provider `name` of the Superset configuration. Check `ENABLE_PROXY_FIX = True` if the address starts with `http://`.
The sign-in succeeds on Monosign but Superset does not log the user in	The custom security manager does not return the user, for example because the provider name is different.	Check that the `name` in `OAUTH_PROVIDERS` is the same as the name in `custom_sso_security_manager.py` and look at the log: `docker logs superset_app \| grep Monosign` shows the claims that Monosign sends.
The user is created with an address that ends with `@monosign.invalid`	The UserInfo response of Monosign has no `email` claim.	Add the `email` claim with the value `{{Email}}` in the Claim Mapping tab (step 2).
A new user sees only a few Superset pages	New users get the `Gamma` role.	Change the role of the user in Superset (Settings → List Users) with an administrator account, or use `AUTH_USER_REGISTRATION_ROLE` as described in step 4-c.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
The local administrator cannot sign in	With `AUTH_OAUTH` the local user name and password form is not shown.	Sign in with Monosign as a user that has the `Admin` role (see the note in step 4-c).
The Superset services do not start after running `docker compose up`	The `superset-init` service ran again and tried to create the administrator account that exists.	Restart only the application, worker and beat services: `docker compose up -d --no-deps --force-recreate superset superset-worker superset-worker-beat`.
SAML sign-in is required	Superset uses one authentication type at a time and its documentation describes the OAuth2 and LDAP logins.	Use the OAuth2 integration in this document.

After completing the configuration on Superset and Monosign, it is better to test in a new private browser window if the OAuth2 SSO doesn’t work, because old session cookies of the Superset address may cause errors.

📑 Instructions

1- Creating an Application on Monosign

2- Configuring the OIDC/OpenID Settings on Monosign

3- Assign a User to the Superset Application

4- Configuration Single Sign-On for Superset

a. Install the Authlib Package

b. Keep the Client Id and the Client Secret in an Environment File

c. Add the OAuth2 Settings and the Custom Security Manager

d. Restart the Superset Services

5- Sign In Test

Troubleshooting