Set up per-user OAuth

​

Use case

​

Prerequisites

• A Cube deployment connected to an OAuth-capable data source
• OAuth configured in your data source so that Cube can obtain per-user tokens (via the User Credentials feature)
• A service account credential (token or password) stored as an environment variable, used for background operations and for users without an active token

​

Set up the OAuth app

1

Open the OAuth apps settings

In Cube, go to Admin → Integrations → OAuth apps and click Create OAuth app.

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.Request a refresh token so users don’t have to authorize again each time the access token expires. For Databricks, add offline_access to Scopes and to the Databricks OAuth app, and set token_access_policy.refresh_token_ttl_in_minutes on the Databricks OAuth app to how long a user can go before authorizing again.

3

Authorize the app

Each user does this for their own account. An admin’s token is never used for other users.Open the sidebar and go to Connected apps. Find your OAuth app and click Authorize to generate an access token.Cube refreshes the access token automatically as long as the provider issues a refresh token. A user needs to authorize again only if the refresh token expires or is revoked; Connected apps shows the current status.

​

Configuration

• driver_factory — dynamically selects the authentication credential per request
• context_to_orchestrator_id — gives each user, and each of their tokens, a separate query orchestrator instance (database connections, execution queues, pre-aggregation table caches)

​

Environment variables

CUBEJS_DB_TYPE=databricks-jdbc
CUBEJS_DB_DATABRICKS_URL=jdbc:databricks://dbc-XXXXXXX-XXXX.cloud.databricks.com:443/default;transportMode=http;ssl=1;httpPath=sql/protocolv1/o/XXXXX/XXXXX;AuthMech=3;UID=token
CUBEJS_DB_DATABRICKS_TOKEN=dapi_service_account_token
CUBEJS_DB_DATABRICKS_ACCEPT_POLICY=true
# Optional: specify a catalog
CUBEJS_DB_DATABRICKS_CATALOG=my_catalog

CUBEJS_DB_TYPE=snowflake
CUBEJS_DB_SNOWFLAKE_ACCOUNT=XXXXXXXXX.us-east-1
CUBEJS_DB_SNOWFLAKE_WAREHOUSE=MY_SNOWFLAKE_WAREHOUSE
CUBEJS_DB_NAME=my_snowflake_database
CUBEJS_DB_USER=service_account_user
CUBEJS_DB_PASS=service_account_password
CUBEJS_DB_SNOWFLAKE_ROLE=MY_ROLE

​

Configuration file

from cube import config
import os


@config("driver_factory")
def driver_factory(ctx: dict) -> dict:
    # Extract the Cube security context, which contains
    # per-user OAuth credentials when available.
    # "databricks" is the Name of the OAuth app.
    databricks_creds = (
        ctx
        .get("securityContext", {})
        .get("cubeCloud", {})
        .get("userCredentials", {})
        .get("databricks", {})
    )

    # Only use the OAuth token when the credential status is "active".
    # Otherwise ("missing", "expired", or "error"), fall back to the
    # service account.
    oauth_token = (
        databricks_creds.get("accessToken")
        if databricks_creds.get("status") == "active"
        else None
    )

    return {
        "type": "databricks-jdbc",
        "url": os.environ["CUBEJS_DB_DATABRICKS_URL"],
        # Prefer the user's OAuth token; fall back to the service account token
        "token": oauth_token or os.environ["CUBEJS_DB_DATABRICKS_TOKEN"],
        "acceptPolicy": True,
        "catalog": os.environ.get("CUBEJS_DB_DATABRICKS_CATALOG"),
    }


@config("context_to_orchestrator_id")
def context_to_orchestrator_id(ctx: dict) -> str:
    # Give each user a separate orchestrator instance (DB connections,
    # execution queues, pre-aggregation caches). The driver is cached per
    # orchestrator, so the key also changes with the user's token.
    cube_cloud = ctx.get("securityContext", {}).get("cubeCloud", {})
    username = cube_cloud.get("username", "default")
    databricks_creds = cube_cloud.get("userCredentials", {}).get("databricks", {})
    token_key = (
        databricks_creds.get("issuedAt")
        if databricks_creds.get("status") == "active"
        else "fallback"
    )
    return f"CUBE_APP_{username}_{token_key}"

module.exports = {
  driverFactory: ({ securityContext }) => {
    // Extract the Cube security context, which contains
    // per-user OAuth credentials when available.
    // `databricks` is the Name of the OAuth app.
    const databricksCreds =
      securityContext?.cubeCloud?.userCredentials?.databricks ?? {};

    // Only use the OAuth token when the credential status is "active".
    // Otherwise ("missing", "expired", or "error"), fall back to the
    // service account.
    const oauthToken =
      databricksCreds.status === "active"
        ? databricksCreds.accessToken
        : null;

    return {
      type: "databricks-jdbc",
      url: process.env.CUBEJS_DB_DATABRICKS_URL,
      // Prefer the user's OAuth token; fall back to the service account token
      token: oauthToken || process.env.CUBEJS_DB_DATABRICKS_TOKEN,
      acceptPolicy: true,
      catalog: process.env.CUBEJS_DB_DATABRICKS_CATALOG,
    };
  },

  // Give each user a separate orchestrator instance (DB connections,
  // execution queues, pre-aggregation caches). The driver is cached per
  // orchestrator, so the key also changes with the user's token.
  contextToOrchestratorId: ({ securityContext }) => {
    const username = securityContext?.cubeCloud?.username ?? "default";
    const databricksCreds =
      securityContext?.cubeCloud?.userCredentials?.databricks ?? {};
    const tokenKey =
      databricksCreds.status === "active"
        ? databricksCreds.issuedAt
        : "fallback";
    return `CUBE_APP_${username}_${tokenKey}`;
  },
};

​

How it works

1. User makes a request — Cube attaches the user’s own OAuth credentials to securityContext.cubeCloud.userCredentials.<app_name>, where <app_name> is the Name of the OAuth app, as { status, accessToken, accessTokenExpiresAt, issuedAt }. issuedAt changes whenever the token is replaced. Requests that aren’t tied to a Cube user carry no user credentials, so they also fall back to the service account. This includes requests authenticated with your own JWT or checkAuth, unless their security context sets cubeCloud.username.
2. driver_factory resolves the credential — If the credential status is active, the user’s OAuth token is used. Otherwise — the user hasn’t authorized (missing), or the token is expired or in error — Cube falls back to the service account credential stored in environment variables.
3. Per-user orchestrator — context_to_orchestrator_id returns a unique key per username, so each user gets their own database connection pool, execution queues, and pre-aggregation table cache. Without this, Cube would share a single cached connection across all users, causing one user’s credentials to be reused for another user’s queries. Cube builds the driver once per orchestrator, so the key also includes the token’s issuedAt: when a user authorizes or their token is refreshed, Cube builds a new connection with the current token. The trade-off: each refresh starts the user on a new orchestrator with an empty cache and new connections, and superseded orchestrators keep theirs, which the liveness probe keeps testing, until they are evicted from the orchestrator cache.