Using External Tokenization¶
This feature requires Enterprise Edition (or higher). To inquire about upgrading, please contact Snowflake Support.
This topic provides instructions on how to configure and use External Tokenization in Snowflake.
Snowflake supports External Tokenization on AWS and Azure.
Important
External tokenization requires External Functions, which are included in the Snowflake Standard Edition, and you can use external functions with a tokenization provider (i.e. Protegrity).
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.
Using External Tokenization on AWS¶
To configure and use External Tokenization on AWS with Snowflake and Protegrity, register for the Protegrity + Snowflake Trial Experience.
After registration, follow all instructions on the Protegrity website to configure and use External Tokenization.
External Tokenization on Azure¶
The following is a representative procedure to configure and use External Tokenization 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_nameSpecifies the identifier for the schema for which the privilege should be granted.
For more information, see:
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 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¶
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¶
Preview Feature — Open
External Tokenization on Google Cloud Platform is in Preview.
The following is a representative procedure to configure and use External Tokenization on Google Cloud Platform (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_nameSpecifies the identifier for the schema for which the privilege should be granted.
For more information, see:
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 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¶
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:
Next Topic: