Using External Tokenization

This topic provides instructions on how to use External Tokenization in Snowflake with partner integrations and how to create a custom External Tokenization integration.

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

Note that an external tokenization masking policy can be assigned to a tag to provide tag-based external tokenization. For details about assigning a masking policy to a tag, see Tag-based masking policies.

Important

External tokenization requires Writing 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 partner integrations

The following partners facilitate external tokenization in Snowflake. To use these partner integrations, follow the instructions in the partner documentation or contact the partner to begin the configuration process:

Create a custom External Tokenization integration

Complete the following steps to create a custom integration for External Tokenization:

Step 1: Create an external function

Create an external function in Snowflake and configure your cloud provider environment to communicate with the external function. For details, see:

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:

use role useradmin;
CREATE ROLE masking_admin;
Copy

Grant privileges to masking_admin role:

use role securityadmin;
GRANT CREATE MASKING POLICY on SCHEMA <db_name.schema_name> to ROLE masking_admin;
GRANT APPLY MASKING POLICY on ACCOUNT to ROLE masking_admin;
Copy

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;
Copy

Where:

  • db_name.schema_name

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

For more information, see:

Step 3: Grant the Custom Role to a User

Grant the MASKING_ADMIN custom role to a user serving as the security or privacy officer.

use role useradmin;
grant role masking_admin to user jsmith;
Copy

Step 4: 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;
Copy

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 5: 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;
Copy

Step 6: 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
Copy

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:

Next Topic: