# Set up BigQuery OAuth dbt platform | Enterprise, Enterprise+ Enterprise-tier feature This guide describes a feature available in the dbt platform Enterprise and Enterprise+ plans. If you’re interested in learning more about our Enterprise-tier plans, contact us at . The dbt platform supports [OAuth](https://cloud.google.com/bigquery/docs/authentication) with BigQuery, providing an additional layer of security for dbt enterprise users. ## Set up BigQuery native OAuth When BigQuery OAuth is enabled for a dbt platform project, all dbt platform developers must authenticate with BigQuery to access development tools, such as the Studio IDE. To set up BigQuery OAuth in the dbt platform, a BigQuery admin must: 1. [Locate the redirect URI value](#locate-the-redirect-uri-value) in the dbt platform. 2. [Create a BigQuery OAuth 2.0 client ID and secret](#creating-a-bigquery-oauth-20-client-id-and-secret) in BigQuery. 3. [Configure the connection](./set-up-bigquery-oauth.md#configure-the-connection-in-dbt) in the dbt platform. To use BigQuery in the Studio IDE, all developers must: 1. [Authenticate to BigQuery](#authenticating-to-bigquery) in their profile credentials. ### Locate the redirect URI value To get started, locate the connection's redirect URI for configuring BigQuery OAuth. To do so: 1. Navigate to your account name, above your profile icon on the left side panel. 2. Select **Account settings** from the menu. 3. From the left sidebar, select **Connections**. 4. Click the BigQuery connection. 5. Locate the **Redirect URI** field under the **Development OAuth** section. Copy this value to your clipboard to use later on. [![Accessing the BigQuery OAuth configuration in dbt](/img/docs/dbt-platform/using-dbt-platform/dbt-platform-enterprise/BQ-auth/dbt-cloud-bq-id-secret-02.png?v=2 "Accessing the BigQuery OAuth configuration in dbt")](#)Accessing the BigQuery OAuth configuration in dbt ### Creating a BigQuery OAuth 2.0 client ID and secret note The dbt platform will request the required BigQuery scopes automatically during the OAuth flow. [Configuring scopes in the BigQuery OAuth consent screen](https://developers.google.com/workspace/guides/configure-oauth-consent) is optional and not required for dbt platform to connect to BigQuery. Required scopes are requested and approved when users authenticate with OAuth. To get started, you need to create a client ID and secret for [authentication](https://cloud.google.com/bigquery/docs/authentication) with BigQuery. This client ID and secret will be stored in the dbt platform to manage the OAuth connection between the dbt platform users and BigQuery. 1. In the BigQuery console, navigate to **APIs & Services** and select **Credentials**: [![BigQuery navigation to credentials](/img/docs/dbt-platform/using-dbt-platform/dbt-platform-enterprise/BQ-auth/BQ-nav.gif?v=2 "BigQuery navigation to credentials")](#)BigQuery navigation to credentials On the **Credentials** page, you can see your existing keys, client IDs, and service accounts. 2. Set up an [OAuth consent screen](https://support.google.com/cloud/answer/6158849) if you haven't already. 3. Click **+ Create Credentials** at the top of the page and select **OAuth client ID**. 4. Fill in the client ID configuration. **Authorized JavaScript Origins** are not applicable. 5. Add an item to **Authorized redirect URIs** and replace `REDIRECT_URI` with the value you copied to your clipboard earlier from the connection's **OAuth 2.0 Settings** section in the dbt platform: | Config | Value | | ---------------------------- | --------------- | | **Application type** | Web application | | **Name** | dbt platform | | **Authorized redirect URIs** | `REDIRECT_URI` |
6. Click **Create** to create the BigQuery OAuth app and see the app client ID and secret values. These values are available even if you close the app screen, so this isn't the only chance you have to save them. [![Create an OAuth app in BigQuery](/img/docs/dbt-platform/using-dbt-platform/dbt-platform-enterprise/BQ-auth/bq-oauth-app-02.png?v=2 "Create an OAuth app in BigQuery")](#)Create an OAuth app in BigQuery ### Configure the Connection in dbt Now that you have an OAuth app set up in BigQuery, you'll need to add the client ID and secret to the dbt platform. To do so: 1. Navigate back to the Connection details page, as described in [Locate the redirect URI value](#locate-the-redirect-uri-value). 2. Add the client ID and secret from the BigQuery OAuth app under the **OAuth 2.0 Settings** section. 3. Enter the BigQuery token URI. The default value is `https://oauth2.googleapis.com/token`. ### Authenticating to BigQuery Once the BigQuery OAuth app is set up for a dbt platform project, each dbt platform user will need to authenticate with BigQuery in order to use the Studio IDE. To do so: 1. Navigate to your account name, above your profile icon on the left side panel. 2. Select **Account settings** from the menu. 3. From the left sidebar, select **Credentials**. 4. Choose the project from the list. 5. Ensure the **Authentication Method** is set to **Native OAuth**. 6. Select **Connect to BigQuery**. [![Navigate to account settings in dbt platform.](/img/guides/dbt-ecosystem/dbt-python-snowpark/5-development-schema-name/1-settings-gear-icon.png?v=2 "Navigate to account settings in dbt platform.")](#)Navigate to account settings in dbt platform. [![Connect BigQuery account.](/img/docs/dbt-platform/connect-to-bigquery.png?v=2 "Connect BigQuery account.")](#)Connect BigQuery account. You will then be redirected to BigQuery and asked to approve the drive, cloud platform, and BigQuery scopes, unless the connection is less privileged. [![BigQuery access request](/img/docs/dbt-platform/using-dbt-platform/dbt-platform-enterprise/BQ-auth/BQ-access.png?v=2 "BigQuery access request")](#)BigQuery access request Select **Allow**. This redirects you back to the dbt platform. You are now an authenticated BigQuery user and can begin accessing dbt development tools. ## Set up BigQuery Workload Identity Federation [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") Workload Identity Federation (WIF) allows application workloads, running outside the dbt platform, to act as a service account without the need to manage service accounts or other keys for deployment environments. The following instructions will enable you to authenticate your BigQuery connection in the dbt platform using WIF. Currently, Microsoft Entra ID is the only supported identity provider (IdP). If you need additional IdP support, please contact your account team. ### 1. Set up Entra ID Create an app in Entra where dbt will request access tokens when authenticating to BigQuery via the workload identity pool: 1. From the **app registrations** screen, click **New registration**. 2. Give the app a name that makes it easily identifiable. 3. Ensure **Supported account types** are set to “Accounts in this organizational directory only (Org name - Single Tenant).” 4. Click **Register** to see the application’s overview screen. 5. From the **app overview**, click **Expose an API** in the left menu. 6. Click **Add** next to Application ID URI. The field will automatically populate. 7. Click **Save**. 8. (Optional) To include the `sub` claim in tokens issued by this application, configure [optional claims in Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims?tabs=appui).
The `sub` (subject) claim uniquely identifies the user or service principal for whom the token is issued.
When you configure service account impersonation in GCP, the Workload Identity Federation mapping uses this `sub` value to verify the identity of the calling Entra application. 9. (Optional but recommended) Test your Entra ID configuration by requesting a token: Run the following command, replacing ``, ``, ``, and `` with your actual values: ```bash curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \ -d 'client_id= \ &scope=/.default \ &client_secret= \ &grant_type=client_credentials' \ 'https://login.microsoftonline.com//oauth2/v2.0/token' ``` The response will include an `access_token`. You can decode this token using [jwt.io](https://jwt.io) to view the `sub` claim value. Workload Identity Federation utilizes a machine-to-machine OAuth flow that is unattended by the user; as such, a redirect URI won't need to be set for the application. Step 3 in this section is crucial because it determines the audience for tokens issued from the app and informs the workpool in GCP whether the calling application has permission to access the resources guarded by the workpool. * **Related documentation:** [GCP — Prepare your external identity provider](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#create) ### 2. Create a Workpool and Workpool Provider in GCP 1. In your GCP account's main menu, navigate to **IAM & Admin** and click the **Workload Identity Federation** option (not to be confused with the **Work\_force\_ Identity Federation** option directly adjacent). 2. If you haven’t created a workpool yet, click **Get started** or create a new workpool (use button near the top of the page). 3. Give the workpool a name and description. Per the [GCP documentation](https://cloud.google.com/iam/docs/workload-identity-federation#pools), a new pool should be created for each non-Google Cloud environment that needs to access Google Cloud resources, such as development, staging, or production environments. The workpool should be named accordingly to make it easily identifiable in the future. 4. When creating your provider: * Set the type of the provider to **OpenID Connect (OIDC)**. * Name the provider something identifiable, like `Entra ID`. * Set the URL to . This can be found in the token itself, if you decode it via jwt.io. You can also see a reference to the expected issuer URL for Entra in the [GCP documentation for WIF](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#create_the_workload_identity_pool_and_provider). * Replace `YOUR_TENANT_ID` with your tenant ID. * The tenant (provider) ID can be found in the app registration created in [section 1 of these instructions](#1-set-up-entra-id); it's called **Directory (tenant) ID** and can be found in the overview section for the application. * For **Audiences**, select **Allowed Audiences** and set the value to the **Application ID URI** that was defined for your Entra ID app. 5. Click **Continue**. 6. Under **Configure provider attributes**, set the mapping for `google.subject` to `assertion.sub`. 7. Click **Save**. ### 3. Service Account Impersonation A workpool either uses a service account or is granted direct resource access to determine which resources a caller can access. The [GCP documentation](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#access) provides more detailed information on configuring both for your workpool. We chose the service account approach in our implementation because it offered greater flexibility. If you haven’t already, create a new service account: 1. From the main menu, select **IAM & Admin** 2. Click **Service Accounts**. 3. Click **Create service account**. Google recommends creating a service account per workload. 4. Assign the relevant roles you would like this service account to have. In our experience, `BigQuery Admin` is the default role with required access. Once you've created the service account, navigate back to the workpool you created in the previous step: 1. Click the **Grant Access** option at the top of the page. 2. Select **Grant access using Service Account Impersonation**. 3. Select the service account you just created. 4. Under **Select Principals**, set `subject` as the **Attribute Name**. For the **Attribute Value**, set it to the `sub` (subject) claim value from the Entra ID access token.  Obtain the sub value To obtain the `sub` value, request an access token from Entra ID. The `sub` claim is consistent across all tokens issued by this application: Run the following command, replacing ``, ``, ``, and `` with your actual values: ```bash curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \ -d 'client_id= \ &scope=/.default \ &client_secret= \ &grant_type=client_credentials' \ 'https://login.microsoftonline.com//oauth2/v2.0/token' ``` The response will include an `access_token`. You can decode this token using [jwt.io](https://jwt.io) to view the `sub` claim value. ### 4. Set up dbt To configure a BigQuery connection to use WIF authentication in the dbt platform, you must set up a custom OAuth integration configured with details from the Entra application used as your workpool provider in GCP. dbt platform: 1. Navigate to **Account settings** --> **Integrations**. 2. Scroll down to the section for **Custom OAuth Integrations** and create a new integration. 3. Fill out all fields with the appropriate information from your IdP environment. * The Application ID URI should be set to the expected audience claim on tokens issued from the Entra application. It will be the same URI your workpool provider has been configured to expect. * You do not have to add the Redirect URI to your Entra application. ### 5. Create connections in dbt To get started, create a new connection in the dbt platform: 1. Navigate to **Account settings** --> **Connections**. 2. Click **New connection** and select **BigQuery** as the connection type. You will then see the option to select **BigQuery** or **BigQuery (Legacy)**. Select **BigQuery**. 3. For the **Deployment Environment Authentication Method**, select **Workload Identity Federation**. 4. Fill out the **Google Cloud Project ID** and any optional settings you need. 5. Select the OAuth Configuration you created in the previous section from the drop-down. 6. Configure your development connection: * [BigQuery OAuth](../connect-data-platform/connect-bigquery.md#bigquery-oauth) (recommended). * Set this up in the same connection as the one you're using for WIF under **`OAuth2.0 settings`** * Service JSON. * You must create a separate connection with the Service JSON configuration. ### 6. Set up project To connect a new project to your WIF configuration: 1. Navigate to **Account settings** --> **Projects**. 2. Click **New project**. 3. Give your project a name and (optional) subdirectory path and click **Continue**. 4. Select the **Connection** with the WIF configuration. 5. Configure the remainder of the project with the appropriate fields. ### 7. Set up deployment environment Create a new or updated environment to use the WIF connection. When you set your environment connection to the WIF configuration, you will then see two fields appear under the Deployment credentials section: * **Workload pool provider path:** This field is required for all WIF configurations. For example: * `//iam.googleapis.com/projects//locations/global/workloadIdentityPools//providers/` * **Service account impersonation URL:** Used only if you’ve configured your workpool to use a service account impersonation for accessing your BigQuery resources (as opposed to granting the workpool direct resource access to the BigQuery resources). For example: * `https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/:generateAccessToken` To avoid errors from incorrect casing or typos, we recommend retrieving these values directly from GCP rather than constructing them manually: 1. In the GCP console, go to **IAM & Admin > Workload Identity Federation**. 2. Click your workload identity pool, then click the provider you created for this configuration. 3. Click **Download configuration** at the top of the provider detail page. 4. Open the downloaded JSON file and copy the following values: * The `audience` field — paste into the **Workload pool provider path** field in dbt. * The `service_account_impersonation_url` field — paste into the **Service account impersonation URL** field in dbt. If you don't already have a job based on the deployment environment with a connection set up for WIF, you should create one now. Once you've configured it with the preferred settings, run the job. ## FAQs Why does the BigQuery OAuth application require scopes to Google Drive? BigQuery supports external tables over both personal Google Drive files and shared files. For more information, refer to [Create Google Drive external tables](https://cloud.google.com/bigquery/docs/external-data-drive). ## Troubleshooting The following section provides troubleshooting steps for common issues with BigQuery OAuth connections. #### Connection fails after granting Google permissions When connecting a BigQuery account, you may successfully sign in to Google and approve the requested permissions, but then see an error page (like `403 Account restricted`) instead of returning to the dbt platform. This typically appears as a server error message rather than the credentials page you started from. This can happen when your Google Workspace organization restricts which third-party applications can access Google services. Even though Google allowed you to sign in and view the consent screen, the organization's security policy blocked the final step of issuing credentials to the dbt platform. This troubleshooting section will explain Why this happens, how to resolve it, and what to do if it keeps happening.  1. Why this affects BigQuery OAuth Google classifies OAuth scopes into three tiers: non-sensitive, sensitive, and restricted. Applications that only request non-sensitive scopes (such as basic sign-in) typically work without additional admin approval. The BigQuery OAuth connection requires scopes that Google classifies as [restricted](https://support.google.com/cloud/answer/9110914), which always require explicit admin trust regardless of your organization's default policy for third-party apps. The BigQuery OAuth connection requests these restricted scopes: * `bigquery` — Required to run queries and access BigQuery resources * `cloud-platform` — Required for cross-project BigQuery access and service interoperability * `drive` — Required to support [BigQuery external tables over Google Drive](https://cloud.google.com/bigquery/docs/external-data-drive) Other applications you use may connect without this approval step because they likely request only non-sensitive or sensitive scopes that don't trigger the same restriction.  2. How to resolve it Your Google Workspace administrator must trust the OAuth client ID that your dbt platform BigQuery connection uses. Find this client ID in the dbt platform under **Account settings** > **Connections** > your BigQuery connection > **OAuth 2.0 Settings**. Once you have the client ID, ask your Google Workspace administrator to: 1. Sign in to the [Google Workspace Admin Console](https://admin.google.com). 2. Navigate to **Security** > **Access and data control** > **API controls** > **Manage third-party app access**. 3. Click **Add app** > **OAuth App Name Or Client ID**. 4. Enter the client ID from your dbt platform BigQuery connection. 5. Set the access level to **Trusted**. 6. Apply the setting to the relevant organizational unit or the entire organization. After the administrator completes these steps, retry the BigQuery connection from your credentials page in the dbt platform. For more details, see Google's documentation on [controlling third-party app access to Google Workspace data](https://support.google.com/a/answer/7281227).  3. If the issue persists If the connection still fails after your administrator trusts the OAuth client in Google Workspace, ask your GCP project administrator to check whether a Google Cloud [Organization Policy](https://cloud.google.com/resource-manager/docs/organization-policy/overview) restricts external OAuth clients. The relevant constraint is `constraints/iam.allowedExternalOAuthClients`. If neither of these steps resolves the issue, contact [dbt Support](https://docs.getdbt.com/community/resources/getting-help#dbt-cloud-support) with the approximate time of the failed connection attempt and the email address you used to authenticate with Google. ## Was this page helpful? YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy)[Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply.