<article class="blog-post">For a company on Google Workspace, &#8220;Sign in with Google&#8221; is the SSO users already expect, and Flask-AppBuilder has a Google handler built in, so the first version of this integration takes fifteen minutes. The reason it deserves a full guide is what the first version gets wrong.</p>
<p>Two things. First, Google&#8217;s OAuth flow will happily authenticate any Google account, including personal Gmail, unless you restrict it. Second, Google&#8217;s user info response contains a name and an email address and nothing about groups, so Superset&#8217;s <code>AUTH_ROLES_MAPPING</code> has nothing to map from and every user lands in the default role. Both are fixable in <code>superset_config.py</code>, and the second has three solutions of increasing power.</p>
<p>The general mechanics of Superset OAuth, proxy settings and the break-glass procedure are in our <a href="https://www.andolasoft.com/blog/okta-sso-apache-superset-setup-guide" target="_blank" rel="noopener">Okta guide</a> and are not repeated here. Written against Superset 4.x.</p>
<h2>Step 1: Create the Google OAuth client</h2>
<p>In the Google Cloud console, in a project owned by your organisation:</p>
<ul>
<li>Go to <strong>APIs &amp; Services, OAuth consent screen</strong>. Choose <strong>Internal</strong> as the user type. This alone restricts sign-in to accounts in your Workspace organisation and is the single most important setting in this guide. Fill in the app name (&#8220;Superset BI&#8221;), support email and developer contact. Add the scopes <code>openid</code>, <code>.../auth/userinfo.email</code> and <code>.../auth/userinfo.profile</code>. Save.</li>
<li>Go to <strong>Credentials, Create credentials, OAuth client ID</strong>. Application type <strong>Web application</strong>. Name it &#8220;Superset&#8221;.</li>
<li>Under <strong>Authorised JavaScript origins</strong>, add <code>https://superset.example.com</code>.</li>
<li>Under <strong>Authorised redirect URIs</strong>, add <code>https://superset.example.com/oauth-authorized/google</code>. The last segment must match the provider <code>name</code> in Superset&#8217;s config.</li>
<li>Create, and copy the <strong>Client ID</strong> and <strong>Client secret</strong>.</li>
</ul>
<p>If your consent screen must be <strong>External</strong> (for example, contractors on a different Workspace domain need access), you lose the automatic organisation restriction, and the domain enforcement in Step 2 becomes mandatory rather than belt-and-braces.</p>
<h2>Step 2: Configure Superset</h2>
<div class="code-block">
<div class="code-header">python</div>
<pre><code class="language-python">import os
from flask_appbuilder.security.manager import AUTH_OAUTH

AUTH_TYPE = AUTH_OAUTH

WORKSPACE_DOMAIN = "example.com"

OAUTH_PROVIDERS = [
    {
        "name": "google",
        "icon": "fa-google",
        "token_key": "access_token",
        "remote_app": {
            "client_id": os.environ["GOOGLE_CLIENT_ID"],
            "client_secret": os.environ["GOOGLE_CLIENT_SECRET"],
            "api_base_url": "https://www.googleapis.com/oauth2/v2/",
            "client_kwargs": {
                "scope": "openid email profile",
                # hd is a hint that pre-selects the Workspace account picker.
                # It is NOT enforcement; enforcement is in the security manager below.
                "hd": WORKSPACE_DOMAIN,
                "prompt": "select_account",
            },
            "server_metadata_url": "https://accounts.google.com/.well-known/openid-configuration",
            "request_token_url": None,
            "access_token_url": "https://accounts.google.com/o/oauth2/token",
            "authorize_url": "https://accounts.google.com/o/oauth2/auth",
        },
    }
]

AUTH_USER_REGISTRATION = True
AUTH_USER_REGISTRATION_ROLE = "Gamma"
AUTH_ROLES_SYNC_AT_LOGIN = True

ENABLE_PROXY_FIX = True
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_SAMESITE = "Lax"</code></pre>
</div>
<p>With only this, any user your consent screen allows can log in and will receive the Gamma role. The next section adds domain enforcement and role assignment in a custom security manager.</p>
<style>
.as-inline-cta{display:flex;align-items:stretch;border-radius:14px;overflow:hidden;<br />
background:#eaf4f6;border:1px solid #dee7ea;margin:32px 0}<br />
.as-inline-cta__icon{flex:0 0 128px;background-color:#1aa9ca;<br />
background-image:radial-gradient(rgba(255,255,255,.35) 1.4px,transparent 1.4px);<br />
background-size:11px 11px;display:flex;align-items:center;justify-content:center;padding:20px}<br />
.as-inline-cta__icon span{width:64px;height:64px;border-radius:50%;background:#fff;<br />
display:flex;align-items:center;justify-content:center;box-shadow:0 2px 6px rgba(0,0,0,.12)}<br />
.as-inline-cta__icon svg{width:28px;height:28px;stroke:#0f7f9c;fill:none;stroke-width:2;<br />
stroke-linecap:round;stroke-linejoin:round}<br />
.as-inline-cta__body{padding:22px 28px;display:flex;flex-direction:column;justify-content:center;gap:8px}<br />
.as-inline-cta__body h4{font-size:19px;font-weight:700;color:#1e2246;margin:0}<br />
.as-inline-cta__body p{font-size:14.5px;line-height:1.6;color:#45506b;margin:0;max-width:52ch}<br />
.as-inline-cta__link{display:inline-flex;align-items:center;gap:5px;font-size:14.5px;<br />
font-weight:700;color:#0f7f9c;text-decoration:none;width:max-content}<br />
.as-inline-cta__link svg{width:16px;height:16px;stroke:currentColor;fill:none;stroke-width:2.4;<br />
stroke-linecap:round;stroke-linejoin:round}<br />
.as-inline-cta__link:hover{text-decoration:underline}<br />
@media (max-width:560px){.as-inline-cta{flex-direction:column}<br />
.as-inline-cta__icon{flex:0 0 auto;width:100%;padding:16px 0}}<br />
</style>
<div class="as-inline-cta">
<div class="as-inline-cta__icon"></div>
<div class="as-inline-cta__body">
<h4>SSO is the easy half of access control</h4>
<p>Mapping Google Groups to Superset roles, keeping that sync from drifting, and layering row-level security on top is where most SSO setups quietly rot. A Superset Architecture Review covers all three.</p>
<p><a class="as-inline-cta__link" href="https://www.andolasoft.com/what-we-do/superset-architecture-review" target="_blank" rel="noopener">Book a Superset Architecture Review</a></p>
</div>
</div>
<h2>Step 3: Enforce the domain and assign roles</h2>
<p>FAB&#8217;s Google handler returns <code>username</code>, <code>first_name</code>, <code>last_name</code> and <code>email</code>, and no <code>role_keys</code>. Override <code>oauth_user_info</code> to add both checks. Three options follow; pick one.</p>
<h3>Option A: Roles by domain rule</h3>
<p>The simplest useful version. Everyone in the domain is a viewer; an explicit list of emails are analysts or admins.</p>
<div class="code-block">
<div class="code-header">python</div>
<pre><code class="language-python">from flask import flash, redirect, url_for
from superset.security import SupersetSecurityManager

ADMINS = {"data.lead@example.com", "platform@example.com"}
ANALYSTS = {"finance.analyst@example.com", "ops.analyst@example.com"}


class GoogleSecurityManager(SupersetSecurityManager):
    def oauth_user_info(self, provider, response=None):
        if provider != "google":
            return super().oauth_user_info(provider, response)

        me = self.appbuilder.sm.oauth_remotes[provider].get("userinfo").json()
        email = (me.get("email") or "").lower()

        # Enforcement: refuse anything outside the Workspace domain.
        if not email.endswith("@" + WORKSPACE_DOMAIN) or not me.get("verified_email", True):
            return {}

        if email in ADMINS:
            role_keys = ["admin"]
        elif email in ANALYSTS:
            role_keys = ["analyst"]
        else:
            role_keys = ["viewer"]

        return {
            "username": email,
            "first_name": me.get("given_name", ""),
            "last_name": me.get("family_name", ""),
            "email": email,
            "role_keys": role_keys,
        }


CUSTOM_SECURITY_MANAGER = GoogleSecurityManager

AUTH_ROLES_MAPPING = {
    "admin": ["Admin"],
    "analyst": ["Alpha", "sql_lab"],
    "viewer": ["Gamma"],
}</code></pre>
</div>
<p>Returning an empty dict makes FAB refuse the login. The allow-lists live in configuration, which is fine for a team of thirty and unpleasant for a company of three hundred. That is when you move to Option C.</p>
<h3>Option B: Roles by email pattern</h3>
<p>A middle step for organisations with structured addresses or aliases: a mapping from regex to role key.</p>
<div class="code-block">
<div class="code-header">python</div>
<pre><code class="language-python">import re

ROLE_PATTERNS = [
    (re.compile(r"^(data|bi)-admin@example\.com$"), "admin"),
    (re.compile(r"^.+\.analyst@example\.com$"), "analyst"),
]

def role_keys_for(email):
    for pattern, key in ROLE_PATTERNS:
        if pattern.match(email):
            return [key]
    return ["viewer"]</code></pre>
</div>
<p>Substitute <code>role_keys_for(email)</code> into Option A. It scales a little further and is still visible in config.</p>
<h3>Option C: Roles from Google Groups via the Directory API</h3>
<p>The correct long-term answer: Google Groups are the source of truth, and Superset looks up the user&#8217;s groups at login. This uses the Admin SDK Directory API with a service account that has domain-wide delegation.</p>
<p>Setup in Google Cloud and Workspace admin:</p>
<ul>
<li>Enable the <strong>Admin SDK API</strong> in the Cloud project.</li>
<li>Create a <strong>service account</strong>, create a JSON key for it, and note its <strong>client ID</strong> (the numeric one).</li>
<li>In the Workspace admin console, <strong>Security, Access and data control, API controls, Domain-wide delegation</strong>, add the service account&#8217;s client ID with the scope <code>https://www.googleapis.com/auth/admin.directory.group.readonly</code>.</li>
<li>Pick a Workspace admin account the service account will impersonate (a dedicated, low-privilege admin role that can read groups is enough).</li>
</ul>
<p>Then in Superset:</p>
<div class="code-block">
<div class="code-header">python</div>
<pre><code class="language-python">import os
from google.oauth2 import service_account
from googleapiclient.discovery import build
from superset.security import SupersetSecurityManager

DIRECTORY_SCOPES = ["https://www.googleapis.com/auth/admin.directory.group.readonly"]
IMPERSONATE = os.environ["GOOGLE_DIRECTORY_ADMIN"]          # e.g. directory-reader@example.com
SA_KEY_PATH = os.environ["GOOGLE_DIRECTORY_SA_KEY"]          # mounted JSON key

_directory = None

def directory():
    global _directory
    if _directory is None:
        creds = service_account.Credentials.from_service_account_file(SA_KEY_PATH, scopes=DIRECTORY_SCOPES)
        creds = creds.with_subject(IMPERSONATE)
        _directory = build("admin", "directory_v1", credentials=creds, cache_discovery=False)
    return _directory


def google_groups_for(email):
    groups = []
    page_token = None
    while True:
        resp = directory().groups().list(userKey=email, pageToken=page_token).execute()
        groups.extend(g["email"] for g in resp.get("groups", []))
        page_token = resp.get("nextPageToken")
        if not page_token:
            return groups


class GoogleGroupsSecurityManager(SupersetSecurityManager):
    def oauth_user_info(self, provider, response=None):
        if provider != "google":
            return super().oauth_user_info(provider, response)
        me = self.appbuilder.sm.oauth_remotes[provider].get("userinfo").json()
        email = (me.get("email") or "").lower()
        if not email.endswith("@" + WORKSPACE_DOMAIN):
            return {}
        try:
            role_keys = google_groups_for(email)
        except Exception as exc:  # directory outage should not lock everyone out
            self.appbuilder.get_app.logger.error("Directory lookup failed for %s: %s", email, exc)
            role_keys = []
        return {
            "username": email,
            "first_name": me.get("given_name", ""),
            "last_name": me.get("family_name", ""),
            "email": email,
            "role_keys": role_keys,
        }


CUSTOM_SECURITY_MANAGER = GoogleGroupsSecurityManager

# Google Group email -&gt; Superset roles
AUTH_ROLES_MAPPING = {
    "superset-admins@example.com": ["Admin"],
    "superset-analysts@example.com": ["Alpha", "sql_lab"],
    "superset-viewers@example.com": ["Gamma"],
}</code></pre>
</div>
<p>Install <code>google-api-python-client</code> and <code>google-auth</code> into the Superset image. The lookup adds a few hundred milliseconds to login, once per session, which nobody notices. Decide deliberately what happens when the Directory API is unreachable: the code above falls back to the registration role so people can still see public dashboards, which is usually the right trade-off. If you would rather fail closed, return <code>{}</code> in the exception handler.</p>
<h2>Step 4: Test</h2>
<ul>
<li>Restart Superset. The login page shows &#8220;Sign in with google&#8221;.</li>
<li>Sign in with an admin account. Check <strong>Settings, List Users</strong> for the expected role.</li>
<li>In a private window, attempt sign-in with a personal Gmail account. With an Internal consent screen, Google refuses before Superset is involved. With an External screen, the security manager refuses and you land back on the login page.</li>
<li>For Option C, add a user to <code>superset-analysts@example.com</code>, wait a minute for Google to propagate, sign out and in, and confirm SQL Lab appears.</li>
</ul>
<h2>Troubleshooting</h2>
<div class="table-responsive">
<table>
<thead>
<tr>
<th>Symptom</th>
<th>Cause</th>
<th>Fix</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Error 400: redirect_uri_mismatch</code></td>
<td>Redirect URI not registered exactly</td>
<td>Add <code>https://superset.example.com/oauth-authorized/google</code>; enable <code>ENABLE_PROXY_FIX</code></td>
</tr>
<tr>
<td><code>Error 403: org_internal</code></td>
<td>Consent screen is Internal and the account is outside the organisation</td>
<td>Expected for outsiders; for legitimate external users switch to External and rely on the security manager</td>
</tr>
<tr>
<td>Personal Gmail accounts can log in</td>
<td>Consent screen External and no domain check</td>
<td>Add the domain enforcement from Step 3</td>
</tr>
<tr>
<td>Everyone is Gamma</td>
<td>No <code>role_keys</code> returned</td>
<td>Implement Option A, B or C; the built-in handler returns none</td>
</tr>
<tr>
<td>Option C: <code>403 Not Authorized to access this resource/api</code></td>
<td>Domain-wide delegation missing or wrong scope</td>
<td>Add the service account client ID with the group read-only scope in Workspace admin</td>
</tr>
<tr>
<td>Option C: <code>400 Bad Request: Invalid Input: memberKey</code></td>
<td>Impersonated account lacks group read permission</td>
<td>Impersonate an account with a Groups Reader admin role</td>
</tr>
<tr>
<td><code>mismatching_state</code></td>
<td>Session cookie not returned on callback</td>
<td><code>SESSION_COOKIE_SAMESITE = "Lax"</code>, <code>SESSION_COOKIE_SECURE</code> matching the scheme</td>
</tr>
</tbody>
</table>
</div>
<h2>Operational notes</h2>
<ul>
<li><strong>Offboarding.</strong> Suspending a user in Workspace blocks new logins immediately. Existing Superset sessions last until <code>PERMANENT_SESSION_LIFETIME</code>; keep it short.</li>
<li><strong>Multiple domains.</strong> Workspace organisations with secondary domains should check membership of a set rather than a single suffix.</li>
<li><strong>Service account key hygiene</strong> (Option C). Mount it as a secret, never in the image, and rotate on the same schedule as other credentials.</li>
<li><strong>2-Step Verification</strong> and Google&#8217;s context-aware access policies apply to Superset automatically, which is a good part of the reason to do this.</li>
</ul>
<h2>Frequently Asked Questions</h2>
<h3>Can I restrict Apache Superset sign-in to my Google Workspace domain?</h3>
<p>Yes, and it is worth doing in two places. Setting the OAuth consent screen to <strong>Internal</strong> restricts sign-in to accounts in your Workspace organisation and is the single most important setting in the setup. Then check the email domain again server-side in <code>oauth_user_info</code>, returning an empty dict for anything outside it, so the restriction survives a consent screen that later has to change to External for contractors.</p>
<h3>Is the <code>hd</code> parameter enough to block personal Gmail accounts?</h3>
<p>No. <code>hd</code> is a hint that pre-selects the right account in Google&#8217;s account picker; it is not enforcement, and the flow can still be completed with a personal account. Enforcement is the Internal consent screen plus the explicit domain check in the security manager. Treat <code>hd</code> purely as a usability improvement.</p>
<h3>How do I map Google Groups to Superset roles?</h3>
<p>Google&#8217;s user info response carries a name and an email address and nothing about group membership, so <code>AUTH_ROLES_MAPPING</code> has nothing to match and every user lands in the default role. The long-term answer is to look the user&#8217;s groups up at login through the Admin SDK Directory API, using a service account with domain-wide delegation and the group read-only scope. For a team of thirty, allow-lists or email patterns in configuration are a reasonable interim step.</p>
<h3>Do I need a service account to use Google Workspace SSO with Superset?</h3>
<p>Only for group-based role assignment. Authentication itself needs nothing more than the OAuth client ID and secret. The service account, its JSON key and the domain-wide delegation grant exist solely so Superset can ask the Directory API which groups a user belongs to. If roles are assigned by allow-list or email pattern instead, skip it and avoid the key-rotation burden that comes with it.</p>
<h2>Build It With Andolasoft</h2>
<p>Getting the sign-in right is the first step; deciding what each role can see is the second. A <a href="https://www.andolasoft.com/what-we-do/superset-architecture-review" target="_blank" rel="noopener">Superset Architecture Review</a> covers authentication, role design and row-level security together with caching, async queries and upgrade readiness, in five working days with a written report. If you want the whole platform run for you, service-account key rotation included, that is <a href="https://www.andolasoft.com/what-we-do/superset-managed-support" target="_blank" rel="noopener">Managed Support</a>. For the broader set of controls, see <a href="https://www.andolasoft.com/blog/data-governance-and-security-best-practices-for-superset-deployments" target="_blank" rel="noopener">governance and security best practices for Superset</a>.</p>
<p>If your Workspace organisation is on Superset and everyone is still landing in the same role, <a href="https://www.andolasoft.com/contact-us" target="_blank" rel="noopener">talk to us</a>. We will map your Google Groups to a Superset role model that holds up, and give you a fixed-scope plan to get there.</p>
</article>


How to Set Up Google Workspace SSO for Apache Superset

Table of Contents

Related Articles

For Sales