How Google Workspace sign-in to Apache Superset works
Superset supports OAuth2 providers such as Google through Flask-AppBuilder, the framework it is built on, so letting staff sign in with their Google Workspace accounts is a bounded piece of work: create an OAuth client in Google Cloud, add a provider block to your Superset configuration, restrict sign-in to your domain, and decide which role a newly authenticated user receives. Each of these steps is small on its own, but the design choices behind them decide who can reach your dashboards and what they can do once they are inside.
The part that often surprises teams is group-based access. Superset's documented mapping, AUTH_ROLES_MAPPING, assigns roles from groups, but it only works when group data reaches Superset at login. A Google sign-in by itself returns the user's identity, not a list of Google Groups, so unless your configuration explicitly requests and reads group membership from Google, the mapping has nothing to act on. Confirm in your own Superset and Flask-AppBuilder versions how the Google OAuth provider is wired, what user information it returns, and whether group data is available at login before you design around it.
Treat the exact behavior as something to verify, not assume. Check the configuration reference for the version you run, test with a non-admin account in staging, and confirm which roles a self-registered user receives on first login. Keep a local admin account available for recovery and confirm it still works after the change. The sibling topic on mapping identity provider groups to Superset roles covers the role design in detail, so this page focuses on how the Google sign-in path itself is assembled.
What you need before configuring Google login
Google login touches your identity tenant, your Superset hosting and your recovery path, so each prerequisite should be confirmed before any configuration starts. The cards below cover what must exist and what must be verified in your environment.
Google Workspace admin access
Someone with admin rights in your Google Workspace tenant must be able to create OAuth credentials and confirm which domain users sign in with. Confirm that the account you plan to use can manage the Google Cloud project that will hold the client, and that your organization permits internal OAuth clients. If a Google Cloud organization policy blocks this, the work stops before Superset is touched, so check it first.
Supported Superset and metadata database
Confirm the Superset release you will run and the metadata database behind it. The configuration documentation lists PostgreSQL 10 to 17 and MySQL 5.7 and 8.x as supported metadata databases. The SQLite default used by quickstart and PyPI installs and the Docker Compose PostgreSQL container are not recommended for production, so a production login setup should not rely on them.
Required SECRET_KEY
Superset will not start without a user-specified SECRET_KEY, a requirement added in version 2.1.0. Generate a strong value, store it in your secrets manager and load it through your deployment configuration rather than a file in the repository. Record how you will rotate it, because PREVIOUS_SECRET_KEY exists for that purpose and rotation planned later is easier than rotation after an incident.
HTTPS on the public Superset URL
Google redirects users back to Superset at a fixed callback address, so the public Superset URL must be stable and served over HTTPS before you register the redirect URI. Confirm the exact hostname, the reverse proxy or load balancer that terminates TLS, and that the path Google will call reaches Superset unchanged. A mismatch between the registered URI and the URL users actually reach is one of the most common causes of failed sign-in.
Google Cloud project for the client
The OAuth client lives in a Google Cloud project, which should be owned by your organization and not by an individual. Decide which project, which consent screen owner and who can rotate the client secret. Ask who receives alerts if the secret expires or the consent configuration changes, because those events stop logins without changing anything in Superset.
Break-glass local admin account
Keep at least one local Superset administrator with a password that is not tied to Google. If the OAuth provider is misconfigured, unavailable or the domain restriction locks out every administrator, this account is how you repair the login setup. Store its credentials in a sealed location, test that it works before enabling SSO, and record who may use it and how each use is logged.
Configuring the Google OAuth client and the Superset provider
This sequence creates a Google OAuth client, wires it into Superset's OAuth provider settings with the secret kept out of source control, and confirms that an authorized Workspace user can sign in while outside accounts are refused. Confirm exact key names and provider fields against the Flask-AppBuilder version your Superset release uses before you start.
Create the OAuth client in Google Cloud
A Google Cloud administrator creates an OAuth client for a web application in the project that your organization controls. Register the authorized redirect URI as your Superset base address followed by the OAuth callback path that your Flask-AppBuilder version expects, and confirm the exact path in the Superset and Flask-AppBuilder documentation before saving. Use the production hostname only, with HTTPS. Done when the client appears in the credentials list with the redirect URI shown exactly as entered, and a browser request to the Superset login route reaches Google's consent screen without a redirect mismatch error.
Record the client ID and secret in your secrets store
Copy the client ID and client secret into the secrets manager your platform team already operates, such as a vault, a Kubernetes secret managed by your cluster tooling, or a parameter store in your cloud account. Assign access to the people and service accounts that deploy Superset, and do not paste the secret into tickets, chat or repository files. Done when the secret can be read by the deployment pipeline and by no one outside the approved group, and the local copy used during setup has been deleted.
Set the authentication type to OAuth
In superset_config.py, set AUTH_TYPE to the OAuth mode defined in the Superset configuration documentation, which is the Flask-AppBuilder constant for OAuth authentication. Keep the database login available only as a deliberate break-glass path that you plan separately. Confirm the constant name against your installed Flask-AppBuilder version, because the names are defined by that library. Done when the configuration file parses, the web server starts, and the login page shows a Google sign-in option instead of a username and password form.
Define the Google entry in OAUTH_PROVIDERS
Add a Google entry to OAUTH_PROVIDERS in superset_config.py with the provider name, the OAuth2 driver settings and the client ID and secret read from environment variables. Set the scopes to the minimum your login needs, typically the openid, email and profile scopes, and confirm the provider fields and token and user info endpoints against the Flask-AppBuilder documentation for your version. Done when the provider block loads without errors and the login page button starts the Google flow, with no secret value visible in the rendered page or logs.
Load the secret from environment configuration
Have the deployment read the client secret from an environment variable or mounted secret file, and have superset_config.py reference that variable rather than a literal string. Keep the configuration file itself in version control only without credential values. Also confirm that the SECRET_KEY used for sessions is supplied the same way, since Superset requires a user-specified value to start. Done when a search of the repository and the rendered configuration finds no client secret, and the running process reports that the variable is set without printing its value.
Restart the web server and workers
Restart the Superset web processes so they load the new authentication settings, and restart Celery workers and beat if your deployment runs them, so background tasks do not keep an old configuration. Use the same restart procedure your platform team applies to configuration changes. Done when every web and worker instance reports the new configuration version, the health endpoint returns success on each one, and no startup errors about OAuth providers appear in the logs.
Confirm sign-in with a test user
Sign in with a test account from your Workspace domain and confirm that Superset creates a user record with the expected email address in the Security section for users. Then attempt sign-in with an account from outside your domain, or a personal Google account, and confirm that Superset refuses it. Domain restriction and default roles are covered in the next steps of this page, so at this stage the refused outside account shows only that the provider is reachable. Done when the test user lands on the Superset home page and the user record exists, and the outside account does not gain a session.
Restricting sign-in to your Google Workspace domain
An OAuth client alone does not limit who can sign in. Creating a Google OAuth client for Superset tells Google which application is asking for identity, but it does not stop an account from another Google Workspace domain, or a personal Google account, from completing the sign-in flow. The domain restriction has to be enforced somewhere in the chain: on the authorization request sent to Google, in Superset's own login handling, or both. Treat the Google client configuration as one control among several, and record which layer your team relies on for each rule.
There are two main mechanisms to weigh. The first is the hosted domain parameter (hd) on the authorization request, which asks Google to prefer accounts from a named Workspace domain. It narrows what the user is offered, but it is a hint to the identity provider, so it should not be your only gate. The second is a server-side check of the email domain returned in the ID token after login, applied by Superset before it creates or updates a user record. This check is the one you can inspect and test in your own code and configuration, so most security owners want it in place even when hd is also set. Confirm with your security owner whether they also require the verified email claim and whether the allowed domain list is maintained in one place.
Test both paths before go-live. Sign in with a valid staff account and confirm access and the default role match your design. Then sign in with an account outside the domain, including a personal Google account, and confirm Superset refuses it and creates no user record. Repeat the outside test after any change to the OAuth client, the authorization parameters or the login code, and after Superset upgrades. Keep the results with your change records. Ask your security owner to sign off on the controls they expect to see, including who can change the allowed domains and how a rejected sign-in is logged.
Mapping Google profile fields and groups to Superset users and roles
This table compares each value Google Workspace can supply at sign-in with what Superset does with it and where the team must make a decision. Read the group row first, because group-based role mapping depends on data that a standard Google sign-in does not carry.
| Source | Superset field or role | How it is set | Caveat |
|---|---|---|---|
| Google account email | Username and login identifier | Taken from the verified email claim in the OAuth response when the provider is configured for Google | Confirm the claim your OAuth configuration requests and that Superset stores it as the username. Changing a user's email at Google can create a second Superset account. |
| Given name | First name on the Superset user record | Mapped from the given name claim in the profile response | Display only. It does not affect permissions, and it is not refreshed for existing users unless your configuration updates it at login. |
| Family name | Last name on the Superset user record | Mapped from the family name claim in the profile response | Display only. Confirm the field appears in audit and user lists as your team expects before relying on it. |
| Google account status (suspended or deleted) | Active or inactive Superset user | Not read from Google by default. A suspended Google account still receives no new tokens, but an existing Superset session or account stays active until it expires or is disabled | Plan a deprovisioning step. Confirm how long an existing Superset session remains valid after a Google suspension, and disable accounts for leavers in Superset if no sync exists. |
| Default role for self-registered users | AUTH_USER_REGISTRATION_ROLE | Set in the Superset configuration so that first-time Google sign-ins receive one role | Keep this role minimal. Users who register without a mapped group inherit it, so a broad default grants access to every new sign-in in the domain. |
| Google group membership | Superset roles through AUTH_ROLES_MAPPING (requires confirmation) | AUTH_ROLES_MAPPING needs group values in the login response. Standard Google sign-in does not include group membership, so the team must choose how groups reach Superset, such as a directory read at login or a managed user-to-role list | Confirm feasibility before committing. Verify that your Google Workspace tenant and admin permissions allow the chosen group read, and test with a sample group before rollout. |
Choosing default roles for self-registered and pre-created users
With self-registration, Superset creates an account the first time someone signs in with Google Workspace and passes the domain check. No administrator approves that account in advance. Access control therefore sits in two places: the Google Workspace domain restriction decides who may sign in, and the default role decides what a new account can do until someone changes it. The default role is the most important setting in this pattern, because every person in the permitted domain receives it.
- Who controls access: the domain restriction and the default role decide who gets an account. Anyone who signs in under the permitted domain receives the default role without a human review, so the domain list should be as narrow as your policy allows.
- How roles change: an administrator edits the user in the Superset interface, or group membership mapped through
AUTH_ROLES_MAPPINGchanges roles at login if role sync at login applies in your version. - Team moves: a self-registered user who changes teams keeps the default role plus any roles already assigned. Without group mapping, nothing removes old roles automatically, so schedule reviews of accounts whose team has changed.
- Audit consequence: the account exists from the first sign-in, and the record shows creation without an approval step. Auditors will ask who approved that access, so your evidence is the domain policy, the configured default role and the change history for both.
Confirm the registration default role setting and whether roles resync on every sign-in in your Superset version before you open registration to the domain.
With pre-created accounts, an administrator creates each Superset user and assigns roles before that person signs in for the first time. Approval happens before the account exists, so the access decision is recorded at creation. This pattern suits smaller user groups, sensitive dashboards or teams where every grant needs a ticket. Its costs are slower onboarding and the need to keep account records accurate, because the account is only useful if its identity matches what Google Workspace presents at sign-in.
- Who controls access: the administrator who creates the account decides who can sign in and what they can see. The person does not influence their own role.
- Lead time: each new user needs a request and a creation step. This slows onboarding for large groups but keeps the approval ahead of the access.
- Identity matching: the Superset username or email must match the Google Workspace primary address used at sign-in. A mismatch can lock the user out or create a second account, so test with one user before any bulk creation.
- Team moves: change the roles on the existing account, or change the group membership that drives them. Remove the old role in the same change so access does not accumulate across moves.
- Dormant accounts: accounts created but never used are a review item. Include them in periodic access reviews and disable those that no longer have an owner.
Before bulk creation, confirm with a test user in staging how a pre-created account is matched to the Google identity on first sign-in in your version.
Whichever pattern you choose, the default role for new accounts should grant the least access that still lets a person sign in and reach a landing page. Avoid giving self-registered users an elevated role, such as one that can administer users, edit shared dashboards or query broad data. Every person in the permitted domain would receive that access, including staff and contractors from unrelated departments, and the grant would be made silently. Put elevated access behind an explicit grant with a named owner.
- Restricted default: set the registration default to a role with no administrative rights and no broad data access.
- Group-based elevation: grant more access through groups mapped in
AUTH_ROLES_MAPPING, so each elevated role has a traceable source and an owner. - Break-glass administrator: keep a local administrator account for recovery when the identity provider or Google sign-in is unavailable. Store its credentials under your control and test the procedure.
- Behavior tests: place a test user in one group, sign in, change the group, sign in again and compare the roles shown in the admin interface. Run the same test for removal, since removal is where access most often lingers.
- Decision record: document the default role, the reason for it and the owner of the setting. Auditors test that the configured default matches the documented decision.
Confirm the registration role and sync-at-login settings for your version in Configuring Superset and in your staging test results before rollout.
Security settings that keep Google login from becoming a weak point
Google sign-in moves the trust decision to your Workspace tenant, but the Superset side still holds the client secret, the admin roles and the local fallback account. The cards below cover the controls that connect those pieces, and each one names what to check before go-live. PKCE and session settings are covered on separate pages.
Protect and rotate the client secret
The OAuth client secret lets Superset exchange authorization codes with Google, so anyone who holds it can impersonate the application. Store it in your secrets manager or an environment variable, never in a committed configuration file, and restrict who can read the deployment's runtime settings. Plan a rotation procedure before go-live: create a new secret in the Google Cloud console, deploy it, confirm sign-in works, then delete the old one. Record who owns the rotation.
Use HTTPS and exact redirect URIs
Google returns the authorization code to the redirect URI registered on the OAuth client, so every hostname, path and scheme must match what Superset sends. Serve Superset only over HTTPS behind your load balancer or proxy, and register only the production and approved staging callback URLs. Remove stale localhost entries once testing ends. Wildcards and broad domain entries widen the set of places a code can be delivered, so keep the list short and review it on every hostname change.
Keep the break-glass admin separate
A local database admin account lets you recover access if Google sign-in fails, the OAuth client is deleted or the Workspace tenant is unavailable. Create it before enabling SSO, give it a long unique password stored in a sealed location, and keep it out of daily use. Make sure it is not tied to any Google identity, and test that it can log in. Document who may open the sealed credential and log each use.
Limit who holds Superset admin roles
With Google login, a user's Superset role is usually set by a mapping from Google group claims or by a default role for new accounts. Keep Admin limited to a small named group, and avoid granting it through a broad group such as all staff. Check that the default role for self-registered users is the least-privileged role your model needs. Review the mapping whenever a team changes, since a stale mapping can keep access alive after a job change.
Review offboarding for suspended accounts
Suspending a Google Workspace account stops new sign-ins, but it does not end a Superset session that is already open or remove the local user record. Ask who disables the Superset user, who reviews accounts without a matching Google identity, and how often this happens. Confirm with your Superset version how existing sessions expire. Make offboarding a checklist item that covers both the Workspace suspension and the Superset account, so access ends in both places.
Log sign-in events for review
Sign-in records show who reached Superset, when and from where, and they are the first evidence you need when an account looks wrong. Decide where Superset and reverse-proxy logs are sent, who can read them and how long they are kept, and confirm the retention with your logging platform. Review failed sign-ins and logins by admin accounts on a set schedule. Identify which events Superset records by default and which need your proxy or SIEM to capture.
Common Google login failures and their causes
This table pairs each common symptom with its likely cause and a specific check the team can run. Work through it in order when a Google sign-in fails, since the redirect and client settings are the first things to verify. Most failures trace back to a mismatch between the Google Cloud client and the Superset configuration.
| Symptom | Likely cause | What to check |
|---|---|---|
| Google shows redirect_uri_mismatch | The redirect URI registered in the Google Cloud OAuth client does not match the callback URL Superset sends | Compare the authorized redirect URI in the Google client with the public Superset address plus the OAuth callback path, character for character, including scheme and trailing slash |
| Login fails after Google consent with a token or client error | Client secret is missing, copied incorrectly or belongs to a different OAuth client | Confirm the secret is loaded from the environment or secret store into the Superset configuration and matches the client ID shown in the Google Cloud console |
| Callback returns a 404 or Superset reports an unknown provider | The provider name in the OAuth configuration does not match the callback path Flask-AppBuilder builds | Check that the provider name in the configuration and the last segment of the callback URL are identical and that the path in Google matches it |
| Sign-in works but the user lands with the wrong role | Default role for self-registered users is broader or narrower than intended, or the role mapping has not been applied at login | Log in as a test user from each group, then inspect the user record in Superset's security list to confirm roles and the login timestamp |
| Group-based roles are not applied | Google group data did not reach Superset, because the OAuth scope or the group field was not requested or was not read | Review the scopes requested by the provider configuration and the attributes returned for a test user, and confirm the group names match the mapping keys exactly |
| Accounts outside your organization can sign in | The Google hosted domain restriction is missing or the allowed domain check is not enforced in the configuration | Attempt sign-in with a personal Google account and with an account from a second domain, then review the restriction settings in both Google and Superset |
| Local admin cannot sign in after the change | Database-backed login was disabled or the admin account was never tested against the new flow | Before switching, confirm a local admin account exists, test its password login in a separate browser session, and keep that session open during the change |
Questions teams ask before setting up Google login for Superset
How much effort does Google login for Superset take, and what drives it?
The core OAuth change is small, but the effort depends on how much policy sits around it. The main drivers are the domain restriction you need, whether access must follow Google groups, how many environments (development, staging, production) must be configured and tested, and how thoroughly you test self-registration and role assignment. A single production instance with one domain and default roles is a narrow job. Multiple environments, several allowed domains, and group rules that must be verified with real test accounts widen the scope. Ask any provider to break the quote into these items so you can see which ones you need.
Can our team set up Google login for Superset without outside help?
Yes, if you have an engineer comfortable with Superset's configuration file, Flask-AppBuilder authentication settings, and Google Cloud OAuth clients. The steps themselves are documented by the Superset project, so the work is more about careful testing than new engineering. Teams usually struggle with three things: getting the redirect URI and consent screen right, deciding who can self-register and with which role, and making sure a break-glass admin still works if the OAuth flow fails. An outside partner is most useful when those decisions must be documented for an audit or when several environments need the same settings.
What do we need from our Google Workspace and Superset administrators?
Your Google Workspace administrator needs to create or approve an OAuth client in a Google Cloud project, configure the consent screen for your organization, and confirm which domains and groups should be able to sign in. Your Superset administrator needs access to the deployment configuration, the ability to restart the web and worker services, and a way to test logins with accounts from each relevant group. Both should agree on who owns the client secret, where it is stored, and who approves changes to domain or role rules. Settle these owners before the work starts so the handover is clear.
How long does the setup take, and what sets the schedule?
The schedule depends on approvals and testing more than on configuration. The longest waits are usually Google Workspace administrators approving the OAuth client and consent settings, change windows for production restarts, and security review of the domain and role policy. Testing also takes time because each role path (self-registered user, group member, admin) needs a real account. Ask for a written schedule in the quote that lists these dependencies and the environments in scope, rather than a single overall date.
Is group-based access without directory sync realistic, and what are the alternatives?
It is realistic when you accept that roles are assigned at sign-in rather than kept in sync. Superset's documentation describes mapping OAuth groups to roles with AUTH_ROLES_MAPPING, so the group claim received at login decides the Superset role for that session. The trade-off is that a user removed from a Google group keeps their old role until their next login, and users who leave the organization still need their Superset account disabled. If that delay is unacceptable, the alternatives are directory sync through a tool such as an identity broker, or managing roles manually inside Superset. Confirm with your Google Workspace administrator which group data is available to the OAuth flow, since group visibility depends on your Workspace configuration.
What changes for users who already have local Superset accounts?
Existing local accounts keep working unless you disable local authentication, but they can end up as duplicates of the same person. Superset matches users by their username or email, so you should check how a Google sign-in will map to an existing record before you enable it. Decide whether local accounts remain for break-glass admins only, how users are notified of the new login path, and what happens to their ownership of dashboards and saved charts. Plan this migration with a list of current accounts, not an assumption that they will merge cleanly.
What should a written quote for this work include?
A useful quote lists the scope in plain terms: the Superset version and deployment type, the number of environments, the domains allowed to sign in, the group-to-role mapping rules, and the default role for self-registered users. It should name each deliverable, such as configuration changes, a test plan with the accounts used, and a short runbook for rotating the OAuth client secret and recovering access. Ask which items are one-time work and which recur, such as support for future Superset upgrades that touch authentication. Also ask what the provider needs from your team, what is excluded, and how changes after kickoff are priced.
How DeployOpen scopes and delivers Superset Google login
DeployOpen treats Google Workspace sign-in for Superset as a access design decision, not only a configuration change. We agree the domain rules, default roles and group mapping in writing, then build and test them in your own environment before any user signs in.
How we scope
- The written scope names your Google Workspace domain, the OAuth client ownership and the Superset version you run.
- It defines which Google groups map to which Superset roles, and who approves changes to that mapping.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts; ongoing support is available as a retainer.
How we build
- We configure the Google OAuth client, redirect URIs and domain restriction in your Superset deployment.
- We set default roles for self-registered users and test that unmapped accounts receive only the access you approve.
- We verify group-based role assignment, including a break-glass local administrator, in a staging environment first.
How we hand over
- You receive the configuration, role mapping table and test results documented against your agreed scope.
- The runbook explains how to add a Google group, change a default role and rotate the OAuth client secret.
- We walk your administrators through sign-in, sign-out and what to check when a user cannot log in.
How we support
- Retainer support can cover re-testing login after Superset upgrades, which the upgrade documentation says to test in staging first.
- We review role mappings when your Google groups or organizational structure change.
- Ask us to confirm how group membership is read at each login, since directory sync is outside this topic's design.
