# Configuring OAuth connections to Snowflake

As an admin, you can enable your CARTO organization to connect to Snowflake using OAuth, instead of requiring username and password. Once this integration is enabled, the option will be available for all users whenever they try to create a new [Snowflake connection](https://docs.carto.com/carto-user-manual/connections/snowflake).

{% hint style="success" %}
Although it requires an initial setup, **connecting CARTO and Snowflake via OAuth is the recommended approach**. It has multiple benefits:

* Security and traceability is improved since OAuth consent can be revoked easily, programmatically, and it can be set up to expire. This can be centralized in your organization using External OAuth.
* Connections with username and password are disabled by policy in some Snowflake accounts.
* Users can leverage their multi-factor authentication (MFA) to connect CARTO and Snowflake.

Additionally, it will lead to performance improvements in the future as newer versions of Snowflake APIs do not support username/password-based authentication.
{% endhint %}

To enable this for all users, navigate to **Settings > Advanced Settings > Integrations,** where you'll find an integration to start this process. Click on "Add" to configure the integration.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-146f2495a724fc7324b2aa205249ecf0a0e55b77%2FScreenshot%202023-11-20%20at%2014.31.41.png?alt=media" alt=""><figcaption></figcaption></figure>

## Choosing an OAuth type

Snowflake offers two different types of OAuth-based authentication:

* **Snowflake OAuth:** connect CARTO and Snowflake using your Snowflake credentials. [Follow this guide to configure Snowflake OAuth in CARTO](#snowflake-oauth).
* **External OAuth:** connect CARTO and Snowflake using your company credentials from Okta, Azure Active Directory or a different identity provider, that is also being used in Snowflake. [Follow this guide to connect CARTO and Snowflake using External OAuth](#external-oauth).

If you are not sure about which OAuth to configure or have any additional questions, please get in touch with our team, with your Snowflake administrators, or read the [Snowflake's introduction to OAuth](https://docs.snowflake.com/en/user-guide/oauth-intro) guide in their documentation.

## Configuring Snowflake OAuth

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-58e778d11705de24cadacc8822b57abf89fc6926%2FScreenshot%202023-11-20%20at%2014.34.33.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Requirements

{% hint style="warning" %}
To setup this integration you need to be able to run queries with the ACCOUNTADMIN role in Snowflake. Ask an Snowflake admin in your organization to help if you are not one.
{% endhint %}

#### Overview

The high-level process to allow users to connect CARTO and Snowflake using their Snowflake credentials is to create a `SECURITY INTEGRATION` in Snowflake for a custom OAuth client. Then, pass the details of this integration to CARTO.

{% hint style="info" %}
For the exact commands and steps in the Snowflake console, please refer to the [Configure Snowflake OAuth for Custom Clients](https://docs.snowflake.com/en/user-guide/oauth-custom) guide in the Snowflake documentation.
{% endhint %}

#### Step 1: Create an OAuth security integration in Snowflake

First we need to create the integration in your Snowflake console. To do this, **copy and paste** the provided SQL code and execute it in your Snowflake console. It will run the `CREATE SECURITY INTEGRATION` SQL command with all the necessary information already included.

#### Step 2: Get the necessary information from Snowflake and finish the setup in CARTO

Once the security integration has been created in Snowflake, you will need to fill the following fields in the CARTO integration panel:

* **Snowflake Account Name:** this is your Snowflake account name, in the following format: `<account_name>.snowflakecomputing.com`.
* **Auth URL:** The URL found under `OAUTH_ALLOWED_AUTHORIZATION_ENDPOINTS` in your newly created security integration in Snowflake. You can use the [DESCRIBE INTEGRATION](https://docs.snowflake.com/en/user-guide/oauth-custom#step-2-call-the-oauth-endpoints) command to obtain it.
* **Access Tokens URL:** The URL found under `OAUTH_ALLOWED_TOKEN_ENDPOINTS` in your newly created security integration in Snowflake. You can use the [DESCRIBE INTEGRATION](https://docs.snowflake.com/en/user-guide/oauth-custom#step-2-call-the-oauth-endpoints) command to obtain it.
* **OAuth Client ID:** The ID found under `OAUTH_CLIENT_ID` in your newly created security integration in Snowflake. Use the [SYSTEM$SHOW\_OAUTH\_CLIENT\_SECRETS](https://docs.snowflake.com/en/sql-reference/functions/system_show_oauth_client_secrets) with your integration name to obtain it.
* **OAuth Client Secret:** The secret found under `OAUTH_CLIENT_SECRET` in your newly created security integration in Snowflake. Use the [SYSTEM$SHOW\_OAUTH\_CLIENT\_SECRETS](https://docs.snowflake.com/en/sql-reference/functions/system_show_oauth_client_secrets) with your integration name to obtain it. Alternatively you can use the `OAUTH_CLIENT_SECRET_2` in case you're rotating the secret.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-bd96afe41ceb245344b224110a1a955ed7e711bd%2FScreenshot%202023-11-21%20at%2013.40.04.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Validating your setup

Once you've filled all this information, click on "Save". The integration will be saved and you will be back at the Integrations list. To validate your setup, try to create a Snowflake OAuth connection as described in our [Snowflake connection](https://docs.carto.com/carto-user-manual/connections/snowflake) guide.

## External OAuth

{% hint style="warning" %}
**Requirements**

* You will need to be able to run queries with the ACCOUNTADMIN role in Snowflake to setup this integration. Ask an Snowflake admin in your organization to help if you are not one.
* You will also need to be able to create resources in your company's directory (the identity provider, for example Azure AD or Okta). Ask an IT admin in your organization to help if you don't have the needed permissions.
  {% endhint %}

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-d7c626a5b5b4ac315e8ccd46be3f5161678a1a54%2FScreenshot%202023-11-20%20at%2014.36.15.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Overview

The high-level process to allow users to connect CARTO and Snowflake using an External OAuth server is to first create the necessary resources in your Identity Provider, and then use them to create a `SECURITY INTEGRATION` in Snowflake with `type = external_oauth`. Then, pass the same OAuth resources to CARTO.

#### Step 1: Choosing an Authorization server/Identity Provider (IdP)

{% hint style="info" %}
Steps 1 and 2 assume that your Snowflake environment does not have anything configured relating to Okta OAuth authorization servers, OAuth clients, scopes, and necessary metadata — Or that you want to set up a brand new configuration for CARTO.

If you want CARTO to reuse an existing configuration, skip to Step 3.
{% endhint %}

CARTO and Snowflake support any valid OAuth authorization server as an identity Provider. You can find more details in the [External OAuth section](https://docs.snowflake.com/en/user-guide/oauth-ext-overview#label-ext-oauth-overview) of the Snowflake documentation.

We have created unique flows for **Azure Active Directory**, **Okta**, and a **Custom** flow for any other identity provider.

#### Step 2: Connecting your Identity Provider and Snowflake

Snowflake has created different guides for each of the possible Identity Providers:

* **Microsoft Entra (formerly Azure AD):** Follow the steps in [Configure Microsoft Azure AD for External OAuth](https://docs.snowflake.com/en/user-guide/oauth-azure).
* **Okta:** Follow the steps in [Configure Okta for External OAuth](https://docs.snowflake.com/en/user-guide/oauth-okta).
* **Custom:** Follow the guide in [Configure Custom Authorization Servers for External OAuth](https://docs.snowflake.com/en/user-guide/oauth-ext-custom).

{% hint style="warning" %}
**For Microsoft Entra ID (formerly Azure AD) integrations**

CARTO expects `api://snowflake-carto` as the **Application ID URI** by default. This can be customized in the integration form.
{% endhint %}

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-10f7c04375afd0613d8cbf0e5ebc6cf6e373ee28%2Fimage.png?alt=media" alt=""><figcaption><p><strong>For Azure AD integrations</strong></p></figcaption></figure>

{% hint style="info" %}
**Tips and common pitfalls**

When executing the `CREATE SECURITY INTEGRATION` in Snowflake:

* We recommend enabling the ANY role mode as part of your setup. Read more about [using ANY role with External OAuth in the Snowflake documentation](https://docs.snowflake.com/en/user-guide/oauth-ext-custom#using-any-role-with-external-oauth).

<pre><code><strong>external_oauth_any_role_mode = 'ENABLE'
</strong></code></pre>

* Make sure you use the right claim for your Identity Provider

<pre><code><strong>external_oauth_token_user_mapping_claim = 'upn'  // Azure AD
</strong><strong>external_oauth_token_user_mapping_claim = 'sub   // Okta
</strong></code></pre>

Additionally, please make sure that the LOGIN\_NAME parameter in Snowflake matches the Identity Provider user that will be passed to CARTO later.
{% endhint %}

Make sure that in all cases you **create an OAuth Client** for this integration. You will later need to pass the Client ID and Client Secret to CARTO so that it can initiate the OAuth flow for the user.

Once you finish these steps you should have created a `SECURITY INTEGRATION` in Snowflake and your IdP will be connected to Snowflake using OAuth. Now we just need to pass the IdP information to CARTO to leverage this integration.

#### Step 3: Get the necessary information from the IdP and finish the setup in CARTO

Once the security integration has been created in Snowflake, you will need to fill the following fields in the CARTO integration panel:

* **Snowflake Account Name:** this is your Snowflake account name, in the following format: `<account_name>.snowflakecomputing.com`.
* **Auth URL:** The Authorization URL from your IdP that was used as `external_oauth_issuer` in your Snowflake security integration.
* **Access Tokens URL:** The URL from your IdP that was used as `external_oauth_jws_keys_url` in your Snowflake security integration. If that field wasn't used (for example, if you specified a public key), this needs to be an URL where you can download public keys or certificates to validate an External OAuth access token.
* **OAuth Client ID:** The ID for the OAuth client that was set up in your Authorization Server.
* **OAuth Client Secret:** The secret for the OAuth client that was set up in your Authorization Server.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-d2e2fa453d6b0844e83745a0bc2fbb3008234e73%2FScreenshot%202023-11-21%20at%2014.21.36.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Validating your setup

Once you've filled all this information, click on "Save". The integration will be saved and you will be back at the Integrations list. To validate your setup, try to create a Snowflake OAuth connection as described in our [Snowflake connection](https://docs.carto.com/carto-user-manual/connections/snowflake) guide.