# Configure a Snowflake Integration

{% hint style="warning" %}
**Deprecation notice**

Support for configuring the Snowflake integration using this legacy workflow has been deprecated. Instead, configure your integration and register your data using [connections](https://documentation.immuta.com/SaaS/configuration/integrations/snowflake/how-to-guides/connect-snowflake).
{% endhint %}

{% hint style="info" %}
**Warehouse sizing recommendations**

Before configuring the integration, review the [Warehouse sizing recommendations guide](https://documentation.immuta.com/SaaS/configuration/integrations/snowflake/reference-guides/warehouse-sizing-recommendations) to ensure that you use Snowflake compute resources cost effectively.
{% endhint %}

## Permissions

The permissions outlined in this section are the Snowflake privileges required for a basic configuration. See the [Snowflake reference guide](https://documentation.immuta.com/SaaS/configuration/integrations/reference-guides/snowflake-overview#required-snowflake-privileges) for a list of privileges necessary for additional features and settings.

* `APPLICATION_ADMIN` Immuta permission
* The Snowflake user [running the installation script](#user-content-fn-1)[^1] must have the following privileges:
  * `CREATE DATABASE ON ACCOUNT WITH GRANT OPTION`
  * `CREATE ROLE ON ACCOUNT WITH GRANT OPTION`
  * `CREATE USER ON ACCOUNT WITH GRANT OPTION`
  * `MANAGE GRANTS ON ACCOUNT WITH GRANT OPTION`
  * `APPLY MASKING POLICY ON ACCOUNT WITH GRANT OPTION`
  * `APPLY ROW ACCESS POLICY ON ACCOUNT WITH GRANT OPTION`
* The Snowflake user [registering data sources](https://documentation.immuta.com/SaaS/configuration/integrations/data-and-integrations/registering-metadata/register-data-sources/snowflake-tutorial) must have the following privileges on all securables:
  * `USAGE` on all databases and schemas with registered data sources
  * `REFERENCES` on all tables and views registered in Immuta
  * [`SELECT` on all tables and views registered in Immuta](#user-content-fn-2)[^2]

{% hint style="warning" %}
**Different accounts**

The setup account used to enable the integration must be different from the account used to register data sources in Immuta.
{% endhint %}

## Configure the integration

{% hint style="warning" %}
**Snowflake resource names**: Use uppercase for the names of the Snowflake resources you create below.
{% endhint %}

1. [Opt to configure private connectivity for Snowflake](https://documentation.immuta.com/SaaS/configuration/application-configuration/how-to-guides/private-networking-support/data-connection-private-networking/index-1).
2. Click the <i class="fa-gear">:gear:</i> **App Settings** icon in the navigation menu.
3. Click the **Integrations** tab.
4. Click the **+Add Integration** button and select **Snowflake** from the dropdown menu.
5. Complete the **Host**, **Port**, and **Default Warehouse** fields.
6. Opt to check the **Enable Project Workspace** box. This will allow for managed write access within Snowflake. *Note: Project workspaces still use Snowflake views, so the default role of the account used to create the data sources in the project must be added to the **Excepted Roles List**.* This option is unavailable when [table grants](https://documentation.immuta.com/SaaS/configuration/integrations/snowflake/how-to-guides/integration-settings/table-grants) is enabled.
7. Opt to check the **Enable Impersonation** box and customize the **Impersonation Role** to allow Immuta users to impersonate another user. *You cannot edit this choice after you configure the integration.* Once you finish configuring the integration, you can grant the `IMPERSONATE_USER` permission to Immuta users. See the [Managing users and permissions guide](https://documentation.immuta.com/SaaS/people/users-index/how-to-guides/managing-personas-and-permissions#add-permission-to-user) for instructions.
8. [Snowflake query audit](https://documentation.immuta.com/SaaS/govern/detect-your-data/audit/reference-guides/query-audit-logs/snowflake) is enabled by default.
   1. Configure the [audit frequency](https://documentation.immuta.com/SaaS/govern/detect-your-data/audit/reference-guides/query-audit-logs/snowflake#audit-frequency) by scrolling to **Integrations Settings** and find the **Snowflake Audit Sync Schedule** section.
   2. Enter how often, in hours, you want Immuta to ingest audit events from Snowflake as an integer between 1 and 24.
   3. Continue with your integration configuration.

### Select your configuration method

{% hint style="warning" %}
[**Altering parameters**](https://docs.snowflake.com/en/sql-reference/sql/alter-account) **in Snowflake at the account level may cause unexpected behavior of the Snowflake integration in Immuta**

The [<mark style="color:blue;">`QUOTED_IDENTIFIERS_IGNORE_CASE`</mark> <mark style="color:blue;">parameter</mark>](https://docs.snowflake.com/en/sql-reference/identifiers-syntax#controlling-case-using-the-quoted-identifiers-ignore-case-parameter) must be set to `false` (the default setting in Snowflake) at the account level. Changing this value to `true` causes unexpected behavior of the Snowflake integration.
{% endhint %}

You have two options for configuring your Snowflake environment:

* [Automatic setup](#automatic-setup): Grant Immuta one-time use of credentials to automatically configure your Snowflake environment and the integration.
* [Manual setup](#manual-setup): Run the Immuta script in your Snowflake environment yourself to configure your Snowflake environment and the integration.

#### Automatic setup

**Required permissions:** When performing an automatic setup, the credentials provided must have the [permissions listed above](#permissions).

The setup will use the provided credentials to create a user called `IMMUTA_SYSTEM_ACCOUNT` and grant the following privileges to that user:

* `CREATE ROLE ON ACCOUNT WITH GRANT OPTION`
* `APPLY MASKING POLICY ON ACCOUNT WITH GRANT OPTION`
* `APPLY ROW ACCESS POLICY ON ACCOUNT WITH GRANT OPTION`
* `MANAGE GRANTS ON ACCOUNT WITH GRANT OPTION`

Alternatively, you can use the [manual setup method](#manual-setup) and edit the provided script to grant the Immuta system account `OWNERSHIP` on the objects that Immuta will secure, instead of granting `MANAGE GRANTS ON ACCOUNT`. The current role that has `OWNERSHIP` on the securables will need to be granted to the Immuta system role. However, if granting `OWNERSHIP` instead of `MANAGE GRANTS ON ACCOUNT`, Immuta will not be able to manage the role that is granted to the account, so it is recommended to run the script as-is, without changes.

{% hint style="info" %}
These credentials will be used to create and configure a new `IMMUTA` database within the specified Snowflake instance. The credentials are not stored or saved by Immuta, and Immuta doesn’t retain access to them after initial setup is complete.

You can create a new account for Immuta to use that has these privileges, or you can grant temporary use of a pre-existing account. By default, the pre-existing account with appropriate privileges is `ACCOUNTADMIN`. If you create a new account, it can be deleted after initial setup is complete.
{% endhint %}

From the **Select Authentication Method Dropdown**, select one of the following authentication methods:

* **Username and Password** ([Not recommended](https://docs.snowflake.com/en/user-guide/security-mfa-rollout?mkt_tok=MjUyLVJGTy0yMjcAAAGZu09Et_t5L994WaIvRvYZpAk-JOLFLHEkGfyJN2h85O_TaxTTXefu85qCiUxOO4CmgNx6eMMiPzwJUIwKNNgqMz8ICtR7CchZKPbZ9oN-cIaE3oqTfg#label-security-mfa-milestone-service-new)): Complete the **Username**, **Password**, and **Role** fields.
* [**Key Pair Authentication**](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-authentication):
  1. Complete the **Username** field. This user must be [assigned the public key in Snowflake](https://docs.snowflake.com/en/user-guide/key-pair-auth#assign-the-public-key-to-a-snowflake-user).
  2. When using an encrypted private key, enter the private key file password in the **Additional Connection String Options**. Use the following format: `PRIV_KEY_FILE_PWD=<your_pw>`
  3. Click **Key Pair (Required)**, and upload a Snowflake private key pair file.
  4. Complete the **Role** field.

#### Manual setup

**Required permissions:** When performing a manual setup, the Snowflake user running the script must have the [permissions listed above](#permissions).

It will create a user called `IMMUTA_SYSTEM_ACCOUNT`, and grant the following privileges to that user:

* `CREATE ROLE ON ACCOUNT WITH GRANT OPTION`
* `APPLY MASKING POLICY ON ACCOUNT WITH GRANT OPTION`
* `APPLY ROW ACCESS POLICY ON ACCOUNT WITH GRANT OPTION`
* `MANAGE GRANTS ON ACCOUNT WITH GRANT OPTION`

Alternatively, you can grant the Immuta system account `OWNERSHIP` on the objects that Immuta will secure, instead of granting `MANAGE GRANTS ON ACCOUNT`. The current role that has `OWNERSHIP` on the securables will need to be granted to the Immuta system role. However, if granting `OWNERSHIP` instead of `MANAGE GRANTS ON ACCOUNT`, Immuta will not be able to manage the role that is granted to the account, so it is recommended to run the script as-is, without changes.

#### Run the script

1. Select **Manual**.
2. Use the **Dropdown Menu** to select your **Authentication Method**:
   * **Username and password** ([Not recommended](https://docs.snowflake.com/en/user-guide/security-mfa-rollout?mkt_tok=MjUyLVJGTy0yMjcAAAGZu09Et_t5L994WaIvRvYZpAk-JOLFLHEkGfyJN2h85O_TaxTTXefu85qCiUxOO4CmgNx6eMMiPzwJUIwKNNgqMz8ICtR7CchZKPbZ9oN-cIaE3oqTfg#label-security-mfa-milestone-service-new)): Enter the **Username** and **Password** and set them in the bootstrap script for the Immuta system account credentials.
   * [**Key Pair Authentication**](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-authentication): Upload the **Key Pair** file and when using an encrypted private key, enter the private key file password in the **Additional Connection String Options**. Use the following format: `PRIV_KEY_FILE_PWD=<your_pw>`
   * **Snowflake External OAuth**:
     1. [Create a security integration for your Snowflake External OAuth](https://docs.snowflake.com/en/sql-reference/sql/create-security-integration-oauth-external.html). *Note that if you have an existing security integration,* [*<mark style="color:blue;">then the Immuta system role must be added to the existing</mark>* *<mark style="color:blue;">`EXTERNAL_OAUTH_ALLOWED_ROLES_LIST`</mark>*](https://docs.snowflake.com/en/sql-reference/sql/alter-security-integration-oauth-external.html)*. The Immuta system role will be the Immuta database provided above with `_SYSTEM`. If you used the default database name it will be `IMMUTA_SYSTEM`.*
     2. Fill out the **Token Endpoint**. This is where the generated token is sent.
     3. Fill out the **Client ID**. This is the subject of the generated token.
     4. Select the method Immuta will use to obtain an access token:
        * **Certificate**
          1. Keep the **Use Certificate** checkbox enabled.
          2. Opt to fill out the **Resource** field with a URI of the resource where the requested token will be used.
          3. Enter the **x509 Certificate Thumbprint**. This identifies the corresponding key to the token and is often abbreviated as `x5t` or is called `sub` (Subject).
          4. Upload the **PEM Certificate**, which is the client certificate that is used to sign the authorization request.
        * **Client secret**
          1. Uncheck the **Use Certificate** checkbox.
          2. Enter the **Scope** (string). The scope limits the operations and roles allowed in Snowflake by the access token. See the [OAuth 2.0 scopes documentation](https://oauth.net/2/scope/) for details about scopes.
          3. Enter the **Client Secret** (string). Immuta uses this secret to authenticate with the authorization server when it requests a token.
3. In the **Setup section**, click **bootstrap script** to download the script. Then, fill out the appropriate fields and run the bootstrap script in Snowflake.

### Select available warehouses (optional)

If you enabled a Snowflake workspace, select **Warehouses** from the dropdown menu that will be available to project owners when creating Snowflake workspaces. Select from a list of all the warehouses available to the privileged account entered above. *Note that any warehouse accessible by the PUBLIC role does not need to be explicitly added.*

### Select excepted roles and users

Enter the **Excepted Roles/User List**. Each role or username (both case-sensitive) in this list should be separated by a comma. Wildcards are unsupported.

{% hint style="warning" %}
**Excepted roles/users will have no policies applied to queries**

Any user with the username or acting under the role in this list will have no policies applied to them when querying Immuta protected Snowflake tables in Snowflake. Therefore, this list should be used for service or system accounts and the default role of the account used to create the data sources in the Immuta projects (if you have Snowflake workspace enabled).
{% endhint %}

### Save the configuration

Click **Save**.

## Opt to enable Snowflake tag ingestion

To allow Immuta to automatically import table and column tags from Snowflake, enable Snowflake tag ingestion in the external catalog section of the Immuta app settings page.

**Requirements**:

* A configured Snowflake integration or connection
* The [Snowflake user configuring the Snowflake tag ingestion](#user-content-fn-3)[^3] must have the following privileges and should be able to access all securables registered as data sources:
  * `IMPORTED PRIVILEGES ON DATABASE snowflake`
  * `APPLY TAG ON ACCOUNT`

1. Navigate to the <i class="fa-gear">:gear:</i> **App Settings** page.
2. Scroll to **2 External Catalogs**, and click **Add Catalog**.
3. Enter a **Display Name** and select **Snowflake** from the dropdown menu.
4. Enter the **Account**.
5. Enter the **Authentication** information based on your authentication method:
   1. **Username and password**: Fill out **Username** and **Password**.
   2. **Key pair**:
      1. Fill out **Username**.
      2. Click **Upload Certificates** to enter in the **Certificate Authority**, **Certificate File**, and **Key File**.
      3. Close the modal and opt to enter the **Encrypted Key File Passphrase**.
6. Enter the additional Snowflake details: **Port**, **Default Warehouse**, and **Role**.
7. Opt to enter the **Proxy Host** and **Proxy Port**.
8. Click the **Test Connection** button.
9. Click the **Test Data Source Link**.
10. Once both tests are successful, click **Save**.

## Register data

[Register Snowflake data in Immuta](https://documentation.immuta.com/SaaS/configuration/integrations/data-and-integrations/registering-metadata/register-data-sources/snowflake-tutorial).

[^1]: If configuring the integration using the [automatic setup method](#automatic-setup), the credentials provided must have these privileges.

[^2]: Only required when using [identification](https://documentation.immuta.com/SaaS/configuration/tags/data-discovery) or [specialized masking policies that require fingerprinting](https://documentation.immuta.com/SaaS/govern/secure-your-data/authoring-policies-in-secure/data-policies/reference-guides/masking-matrix-functions#types-limited-to-snowflake).

[^3]: If using connections, add the required privileges to your system account role, and use the system account credentials to set up the tag ingestion.