Using External Tokenization

Enterprise Edition Feature

This feature requires Enterprise Edition (or higher). To inquire about upgrading, please contact Snowflake Support.

.

Related Topics

• Understanding Column-level Security

This topic provides instructions on how to configure and use External Tokenization in Snowflake.

Snowflake supports External Tokenization on AWS, Azure, and Google Cloud Platform.

Important

External tokenization requires External Functions, which are included in the Snowflake Standard Edition, and you can use external functions with a tokenization provider.

However, if you choose to integrate your tokenization provider with Snowflake External Tokenization, you must upgrade to Enterprise Edition or higher.

To inquire about upgrading, please contact Snowflake Support.

External Tokenization on AWS

Snowflake supports two partner integrations to use External Tokenization on AWS:

Protegrity

To configure and use External Tokenization with Protegrity, register for the Protegrity + Snowflake Trial Experience. After registration, follow all instructions on the Protegrity website.

Baffle

To configure and use External Tokenization with Baffle, complete the steps in the Baffle documentation.

External Tokenization on Azure

Snowflake supports External Tokenization on Azure using a partner integration with Baffle or a custom integration.

Baffle

To use the Baffle integration, follow the instructions in the Baffle guide.

Custom integration

Use the representative procedure listed below to configure a custom External Tokenization integration on Azure.

Step 1: Create External Functions on Azure

External functions require your Azure environment to be configured to communicate with Snowflake.

Configure your Azure environment and Snowflake external functions using these steps.

Note

Consult the documentation for your tokenization provider to ensure any additional and necessary steps are completed, especially while configuring the API Management service.

Step 2: Grant Masking Policy Privileges to Custom Role

A security or privacy officer should serve as the masking policy administrator (i.e. custom role: MASKING_ADMIN) and have the privileges to define, manage, and apply masking policies to columns.

Snowflake provides the following privileges to grant to a security or privacy officer for Column-level Security masking policies:

Privilege	Description
CREATE MASKING POLICY	This schema-level privilege controls who can create masking policies.
APPLY MASKING POLICY	This account-level privilege controls who can [un]set masking policies on columns and is granted to the ACCOUNTADMIN role by default. . This privilege only allows applying a masking policy to a column and does not provide any additional table privileges described in Access Control Privileges.
APPLY ON MASKING POLICY	Optional. This policy-level privilege can be used by a policy owner to decentralize the [un]set operations of a given masking policy on columns to the object owners (i.e. the role that has the OWNERSHIP privilege on the object). . Snowflake supports discretionary access control where object owners are also considered data stewards. . If the policy administrator trusts the object owners to be data stewards for protected columns, then the policy administrator can use this privilege to decentralize applying the policy [un]set operations.

The following example creates the MASKING_ADMIN role and grants masking policy privileges to that role.

-- create a masking policy administrator custom role

CREATE ROLE masking_admin;

-- grant privileges to masking_admin role.

GRANT CREATE MASKING POLICY on SCHEMA <schema_name> to ROLE masking_admin;

GRANT APPLY MASKING POLICY on ACCOUNT to ROLE masking_admin;

-- allow table_owner role to set or unset the ssn_mask masking policy (optional)

GRANT APPLY ON MASKING POLICY ssn_mask to ROLE table_owner;

Where:

• schema_name

  Specifies the identifier for the schema for which the privilege should be granted.

For more information, see:

• GRANT <privileges> … TO ROLE

• Configuring Access Control

• Access Control Privileges

Step 3: Create a Masking Policy

In this representative example, users with the ANALYST custom role see the detokenized email values. Users without the ANALYST custom role see the tokenized values.

The external function to detokenize email values is de_email().

-- create masking policy

create or replace masking policy email_de_token as (val string) returns string ->
  case
    when current_role() in ('ANALYST') then de_email(val)
    else val
  end;

Tip

If you want to update an existing masking policy and need to see the current definition of the policy, call the GET_DDL function or run the DESCRIBE MASKING POLICY command.

Step 4: Apply the Masking Policy to a Table or View Column

These examples assume that a masking policy is not applied to the table column when the table is created and the view column when the view is created. You can optionally apply a masking policy to a table column when you create the table with a CREATE TABLE statement or a view column with a CREATE VIEW statement.

Execute the following statements to apply the policy to a table column or a view column.

-- apply masking policy to a table column

alter table if exists user_info modify column email set masking policy email_de_token;

-- apply the masking policy to a view column

alter view user_info_v modify column email set masking policy email_de_token;

Step 5: Query Data in Snowflake

Execute two different queries in Snowflake, one query with the ANALYST custom role and another query with a different role, to verify that users without the ANALYST custom role see tokenized values.

-- using the ANALYST custom role

use role ANALYST;
select email from user_info; -- should see plain text value

-- using the PUBLIC system role

use role public;
select email from user_info; -- should see tokenized value

External Tokenization on Google Cloud Platform

Snowflake supports External Tokenization on Google Cloud Platform (GCP) using custom integrations.

The following is a representative procedure to configure and use External Tokenization on GCP.

Step 1: Create External Functions on GCP

External functions require your GCP environment to be configured to communicate with Snowflake.

Configure your GCP environment and Snowflake external functions using these steps.

Note

Consult the documentation for your tokenization provider to ensure any additional and necessary steps are completed, especially while configuring the API Gateway service.

Step 2: Grant Masking Policy Privileges to Custom Role

A security or privacy officer should serve as the masking policy administrator (i.e. custom role: MASKING_ADMIN) and have the privileges to define, manage, and apply masking policies to columns.

Snowflake provides the following privileges to grant to a security or privacy officer for Column-level Security masking policies:

Privilege	Description
CREATE MASKING POLICY	This schema-level privilege controls who can create masking policies.
APPLY MASKING POLICY	This account-level privilege controls who can [un]set masking policies on columns and is granted to the ACCOUNTADMIN role by default. . This privilege only allows applying a masking policy to a column and does not provide any additional table privileges described in Access Control Privileges.
APPLY ON MASKING POLICY	Optional. This policy-level privilege can be used by a policy owner to decentralize the [un]set operations of a given masking policy on columns to the object owners (i.e. the role that has the OWNERSHIP privilege on the object). . Snowflake supports discretionary access control where object owners are also considered data stewards. . If the policy administrator trusts the object owners to be data stewards for protected columns, then the policy administrator can use this privilege to decentralize applying the policy [un]set operations.

The following example creates the MASKING_ADMIN role and grants masking policy privileges to that role.

-- create a masking policy administrator custom role

CREATE ROLE masking_admin;

-- grant privileges to masking_admin role.

GRANT CREATE MASKING POLICY on SCHEMA <schema_name> to ROLE masking_admin;

GRANT APPLY MASKING POLICY on ACCOUNT to ROLE masking_admin;

-- allow table_owner role to set or unset the ssn_mask masking policy (optional)

GRANT APPLY ON MASKING POLICY ssn_mask to ROLE table_owner;

Where:

• schema_name

  Specifies the identifier for the schema for which the privilege should be granted.

For more information, see:

• GRANT <privileges> … TO ROLE

• Configuring Access Control

• Access Control Privileges

Step 3: Create a Masking Policy

In this representative example, users with the ANALYST custom role see the detokenized email values. Users without the ANALYST custom role see the tokenized values.

The external function to detokenize email values is de_email().

-- create masking policy

create or replace masking policy email_de_token as (val string) returns string ->
  case
    when current_role() in ('ANALYST') then de_email(val)
    else val
  end;

Tip

If you want to update an existing masking policy and need to see the current definition of the policy, call the GET_DDL function or run the DESCRIBE MASKING POLICY command.

Step 4: Apply the Masking Policy to a Table or View Column

These examples assume that a masking policy is not applied to the table column when the table is created and the view column when the view is created. You can optionally apply a masking policy to a table column when you create the table with a CREATE TABLE statement or a view column with a CREATE VIEW statement.

Execute the following statements to apply the policy to a table column or a view column.

-- apply masking policy to a table column

alter table if exists user_info modify column email set masking policy email_de_token;

-- apply the masking policy to a view column

alter view user_info_v modify column email set masking policy email_de_token;

Step 5: Query Data in Snowflake

Execute two different queries in Snowflake, one query with the ANALYST custom role and another query with a different role, to verify that users without the ANALYST custom role see tokenized values.

-- using the ANALYST custom role

use role ANALYST;
select email from user_info; -- should see plain text value

-- using the PUBLIC system role

use role public;
select email from user_info; -- should see tokenized value

External Tokenization Best Practices

• Synchronizing systems. On AWS, it is helpful to synchronize users and roles in your organization’s identity provider (IdP) with Snowflake and Protegrity. If users and roles are not synchronized, there can be unexpected behaviors, error messages, and complex troubleshooting regarding external functions, API integrations, masking policies, and tokenization policies. One option is to use SCIM to keep users and roles synchronized with your IdP and Snowflake.

• Root cause for error(s). Since External Tokenization requires coordinating multiple systems (e.g. IdP, Snowflake, Protegrity, AWS, Azure, GCP), always verify the privileges, current limitations, external functions, API integration, masking policies, and the columns that have masking policies for External Tokenization in Snowflake. To help determine the root cause, see:

  • Understanding Column-level Security

  • Troubleshooting External Tokenization

  • Creating External Functions on AWS

  • Creating External Functions on Microsoft Azure

  • Creating External Functions on GCP

Next Topic:

• Advanced Column-level Security Topics