Skip to main content
This feature is in beta. Reach out to your account manager to have it enabled for your Cube Cloud deployment.

Use case

You want each user’s queries to run under their own database identity using OAuth tokens managed by Cube Cloud. When a user’s token is unavailable or expired, Cube falls back to a service account so that connectivity checks and background operations still work. This pattern applies to any data source that supports OAuth, including Databricks and Snowflake. The examples below use Databricks; switch the userCredentials key and driver options for any other OAuth-capable data source. Because every user connects with different credentials, you also need per-user query orchestrator state. Without this, one user’s cached connection could leak to another.
Cube caches one database connection per context_to_orchestrator_id for the lifetime of the process. Every input your driver_factory reads must therefore also appear in the orchestrator ID. OAuth access tokens rotate (typically hourly), so an ID built from the username alone leaves the cached connection pinned to the token it was first built with — new database sessions then fail to authenticate until the next deploy. The configuration below derives both from one helper so they cannot drift.

Prerequisites

  • A Cube Cloud deployment connected to an OAuth-capable data source
  • OAuth configured in your data source so that Cube Cloud can obtain per-user tokens (via the User Credentials feature)
  • A service account credential (token or password) stored as an environment variable for fallback connectivity
The service account credential is used only as a fallback for Cube’s internal liveness checks and background operations. Grant it the minimum permissions necessary — ideally read-only access to the required schemas — to limit exposure if the credential is compromised.

Set up the OAuth app

Before configuring Cube to use per-user OAuth, register your data source as an OAuth app in Cube Cloud:
1

Open the OAuth apps settings

In Cube Cloud, go to Admin → Integrations → OAuth apps and click Add.
Admin Integrations page showing the OAuth apps section with the Add button
2

Fill out the OAuth app details

Provide the OAuth app metadata from your data source: Name, Auth URL, Token URL, Client ID, Client Secret, and any required Scopes. Copy the Redirect URI shown in this form and register it with your data source’s OAuth provider, then click Create.
New OAuth app form with fields for Name, Auth URL, Token URL, Client ID, Client Secret, Scopes, and Redirect URI
3

Authorize the app

Open the sidebar and go to Connected apps. Find your OAuth app and click Authorize to generate an access token.You’ll need to repeat this step whenever the token expires.
Connected apps page showing the OAuth integration with an Authorize action

Configuration

The configuration uses two options from the configuration file reference:
  • driver_factory — dynamically selects the authentication credential per request
  • context_to_orchestrator_id — gives each user their own query orchestrator instance (database connections, execution queues, pre-aggregation table caches)

Environment variables

Set the environment variables for your data source. The examples below show Databricks and Snowflake; adapt them to your specific setup.

Configuration file

The examples below use Databricks. To target a different data source, swap userCredentials.databricks for the matching key (for example, userCredentials.snowflake) and update the driver_factory return value with the correct type and driver-specific options. See the data sources reference for available drivers.
cube.py

How it works

  1. User makes a request — Cube Cloud attaches the user’s OAuth credentials to securityContext.cubeCloud.userCredentials.<data_source> (for example, .databricks or .snowflake).
  2. driver_factory resolves the credential — If the user has a token that has not expired, it is used. Otherwise, Cube falls back to the service account credential stored in environment variables.
  3. Per-user, per-credential orchestratorcontext_to_orchestrator_id returns a key derived from both the username and the credential in use, so each user gets their own database connection pool, execution queues, and pre-aggregation table cache — and a rotated token produces a fresh connection instead of reusing one built from the previous token. Keying on the username alone would share a single cached connection across token rotations; omitting the username would share one across users.

Operational notes

  • Expect one orchestrator per token rotation. Each distinct orchestrator ID holds its own connection pool, queues and pre-aggregation table cache, and tokens typically rotate hourly. Watch memory on deployments with many concurrent users, and note that the first query after a rotation runs against a cold pre-aggregation cache.
  • Don’t make context_to_app_id per-user. The data model is identical for every user — only the connection differs — so a per-user app ID forces a full data-model recompile per user on every replica for no benefit. Leave it unset, or return a constant if your deployment already sets one.
  • Give the service account the minimum it needs to pass a connection check. If it has no access at all, liveness checks and any query that falls back to it fail with an opaque authorization error from the driver rather than something diagnosable.