Skip to main content

Set up external OAuth with Snowflake EnterpriseEnterprise +

note

This feature is currently only available for Okta and Entra ID identity providers.

dbt Enterprise and Enterprise+ plans support OAuth authentication with external providers. When External OAuth is enabled, users can authorize their Development credentials using single sign-on (SSO) via the identity provider (IdP). External OAuth authorizes users to access multiple applications, including dbt, without sharing their static credentials with the service. This makes the process of authenticating for development environments easier for the user and provides an additional layer of security to your dbt account.

Getting started

The process of setting up external OAuth will require a little bit of back-and-forth between your dbt, IdP, and data warehouse accounts, and having them open in multiple browser tabs will help speed up the configuration process:

  • dbt: You’ll primarily be working in the Account settings —> Integrations page. You will need proper permission to set up the integration and create the connections.

Identity providers:

  • Okta: You’ll be working in multiple areas of the Okta account, but you can start in the Applications section. You will need permissions to create an application and an authorization server.
  • Entra ID An admin with access to create Entra ID apps who is also a user in the data warehouse is required.

Data warehouse:

If the admins that handle these products are all different people, it’s better to have them coordinating simultaneously to reduce friction.

Snowflake and IdP username matching required

Ensure that the username/email address entered by the IdP admin matches the Snowflake credentials username. If the email address used in the dbt setup is different from the Snowflake email address, the connection will fail or you may run into issues.

Data warehouse configurations

The following is a template for creating the OAuth configurations in the Snowflake environment:


create security integration your_integration_name
type = external_oauth
enabled = true
external_oauth_type = okta
external_oauth_issuer = ''
external_oauth_jws_keys_url = ''
external_oauth_audience_list = ('')
external_oauth_token_user_mapping_claim = 'sub'
external_oauth_snowflake_user_mapping_attribute = 'email_address'
external_oauth_any_role_mode = 'ENABLE'

The external_oauth_token_user_mapping_claim and external_oauth_snowflake_user_mapping_attribute can be modified based on the your organizations needs. These values point to the claim in the users’ token. In the example, Snowflake will look up the Snowflake user whose email matches the value in the sub claim.

Notes:

  • The Snowflake default roles ACCOUNTADMIN, ORGADMIN, or SECURITYADMIN, are blocked from external OAuth by default and they will likely fail to authenticate. See the Snowflake documentation for more information.
  • The value for external_oauth_snowflake_user_mapping_attribute must map correctly to the Snowflake username. For example, if email_address is used, the email in the token from the IdP must match the Snowflake username exactly.

Identity provider configuration

Select a supported identity provider (IdP) for instructions on configuring external OAuth in their environment and completing the integration in dbt:

1. Initialize the dbt settings

  1. In your dbt account, navigate to Account settings —> Integrations.
  2. Scroll down to Custom integrations and click Add integrations
  3. Leave this window open. You can set the Integration type to Okta and note the Redirect URI at the bottom of the page. Copy this to your clipboard for use in the next steps.
Copy the callback URI at the bottom of the integration page in dbt.Copy the callback URI at the bottom of the integration page in dbt.

2. Create the Okta app

  1. Expand the Applications section from the Okta dashboard and click Applications. Click the Create app integration button.
  2. Select OIDC as the sign-in method and Web applications as the application type. Click Next.
The Okta app creation window with OIDC and Web Application selected.The Okta app creation window with OIDC and Web Application selected.
  1. Give the application an appropriate name, something like “External OAuth app for dbt,” that will make it easily identifiable.
  2. In the Grant type section, enable the Refresh token option.
  3. Scroll down to the Sign-in redirect URIs option. You’ll need to paste the redirect URI you gathered from dbt in step 1.3.
The Okta app configuration window with the sign-in redirect URI configured to the dbt value.The Okta app configuration window with the sign-in redirect URI configured to the dbt value.
  1. Save the app configuration. You’ll come back to it, but move on to the next steps for now.

3. Create the Okta API

  1. Expand the Security section and click API from the Okta sidebar menu.
  2. On the API screen, click Add authorization server. Give the authorization server a name (a nickname for your data warehouse account would be appropriate). For the Audience field, copy and paste your data warehouse login URL (for example, https://abdc-ef1234.snowflakecomputing.com). Give the server an appropriate description and click Save.
The Okta API window with the Audience value set.The Okta API window with the Audience value set.
  1. On the authorization server config screen, open the Metadata URI in a new tab. You’ll need information from this screen in later steps.
The Okta API settings page with the metadata URI highlighted.The Okta API settings page with the metadata URI highlighted.
Sample output of the metadata URI.Sample output of the metadata URI.
  1. Click on the Scopes tab and Add scope. In the Name field, add session:role-any. (Optional) Configure Display phrase and Description and click Create.
API scope configured in the Add Scope window.API scope configured in the Add Scope window.
  1. Open the Access policies tab and click Add policy. Give the policy a Name and Description and set Assign to as The following clients. Start typing the name of the app you created in step 2.3, and you’ll see it autofill. Select the app and click Create Policy.
Assignment field autofilling the value.Assignment field autofilling the value.
  1. On the access policy screen, click Add rule.
API Add rule button highlighted.API Add rule button highlighted.
  1. Give the rule a descriptive name and scroll down to token lifetimes. Configure the Access token lifetime is, Refresh token lifetime is, and but will expire if not used every settings according to your organizational policies. We recommend the defaults of 1 hour and 90 days. Stricter rules increase the odds of your users having to re-authenticate.
Token lifetime settings in the API rule window.Token lifetime settings in the API rule window.
  1. Navigate back to the Settings tab and leave it open in your browser. You’ll need some of the information in later steps.

4. Create the OAuth settings in the data warehouse

  1. Open up a Snowflake worksheet and copy/paste the following:

create security integration your_integration_name
type = external_oauth
enabled = true
external_oauth_type = okta
external_oauth_issuer = ''
external_oauth_jws_keys_url = ''
external_oauth_audience_list = ('')
external_oauth_token_user_mapping_claim = 'sub'
external_oauth_snowflake_user_mapping_attribute = 'email_address'
external_oauth_any_role_mode = 'ENABLE'

  1. Change your_integration_name to something appropriately descriptive. For example, dev_OktaAccountNumber_okta. Copy the external_oauth_issuer and external_oauth_jws_keys_url from the metadata URI in step 3.3. Use the same Snowflake URL you entered in step 3.2 as the external_oauth_audience_list.

Adjust the other settings as needed to meet your organization's configurations in Okta and Snowflake.

The issuer and jws keys URIs in the metadata URLThe issuer and jws keys URIs in the metadata URL
  1. Run the steps to create the integration in Snowflake.
Username consistency

Ensure that the username (for example, email address) entered in the IdP matches the Snowflake credentials for all users. Mismatched usernames will result in authentication failures.

5. Configuring the integration in dbt

  1. Navigate back to the dbt Account settings —> Integrations page you were on at the beginning. It’s time to start filling out all of the fields.

    1. Integration name: Give the integration a descriptive name that includes identifying information about the Okta environment so future users won’t have to guess where it belongs.
    2. Client ID and Client secrets: Retrieve these from the Okta application page.
    The client ID and secret highlighted in the Okta app.The client ID and secret highlighted in the Okta app.
    1. Authorize URL and Token URL: Found in the metadata URI.
    The authorize and token URLs highlighted in the metadata URI.The authorize and token URLs highlighted in the metadata URI.
  2. Save the configuration

6. Create a new connection in dbt

  1. Navigate to Account settings and click Connections from the menu. Click New connection.
  2. Configure the Account, Database, and Warehouse as you normally would, and for the OAuth method, select the external OAuth you just created.
The new configuration window in dbt with the External OAuth showing as an option.The new configuration window in dbt with the External OAuth showing as an option.
  1. Scroll down to the External OAuth configurations box and select the config from the list.
The new connection displayed in the External OAuth Configurations box.The new connection displayed in the External OAuth Configurations box.
  1. Save the connection, and you have now configured External OAuth with Okta!

FAQs

Receiving a `Failed to connect to DB` error when connecting to Snowflake

Was this page helpful?

0