行筛选和列掩码的常见模式

本页介绍实现 ABAC 行筛选器和列掩码策略的常见模式。

与 Cast 兼容的掩码函数

Azure Databricks 会自动将掩码函数的输出转换为与目标列的数据类型匹配。 参阅 列掩码的自动类型转换。

以下模式可帮助你设计与强制转换兼容的掩码函数。

返回可转换类型

屏蔽某列时,请返回相同的数据类型或可转换为该数据类型的类型。 检查策略目标列的数据类型,并验证函数的每个分支是否返回兼容值。

-- Succeeds: Masks a DOUBLE column, returns DOUBLE in every branch
CREATE FUNCTION mask_salary(salary DOUBLE, user_role STRING)
RETURNS DOUBLE
RETURN CASE
  WHEN user_role IN ('admin', 'hr') THEN salary
  WHEN user_role = 'manager' THEN ROUND(salary / 1000) * 1000
  ELSE 0.0
END;

-- Fails: 'CONFIDENTIAL' cannot be cast to a DOUBLE column type
CREATE FUNCTION mask_salary_as_text(salary DOUBLE, user_role STRING)
RETURNS STRING
RETURN CASE
  WHEN user_role IN ('admin', 'hr') THEN CAST(salary AS STRING)
  ELSE 'CONFIDENTIAL'
END;

避免数值溢出

当掩码函数接受并返回比目标列更宽的数值类型时,结果会自动强制转换回列的类型。 如果返回的值超出较窄类型的范围,则强制转换溢出,并且查询在运行时失败。

-- The target column is TINYINT (max 127). The input is upcast to BIGINT
-- for the function. Adding 1000 produces a BIGINT result that overflows
-- when cast back to TINYINT.
CREATE FUNCTION mask_score(score BIGINT)
RETURNS BIGINT
RETURN score + 1000;

将 VARIANT 用于多种列数据类型

参见 用单一函数遮蔽多列类型。

测试类型转换兼容性

测试具有不同数据模式的掩码函数。

SELECT CAST(mask_salary(salary, 'admin') AS DOUBLE) FROM employees;
SELECT CAST(mask_salary(salary, 'manager') AS DOUBLE) FROM employees;
SELECT CAST(mask_salary(salary, 'viewer') AS DOUBLE) FROM employees;

使用单个函数屏蔽多个列类型

单个接受并返回 VARIANT 的掩码 UDF 可以对多种数据类型的列进行掩码处理,从而减少需要维护的 UDF 和策略数量。 Azure Databricks 在函数运行前将列值转换为 VARIANT,然后按照 ANSI SQL 规则将返回值转换回该列的类型。

在函数内部,使用 schema_of_variant() 检查该值,并根据其类型进行分支处理。 在每个分支中,返回一个可转换为目标列类型的值。

屏蔽多种数值类型

最VARIANT简单的掩码是返回一个常量,Azure Databricks 将该常量投射到每个列的类型中。 使用该函数的一个策略可以遮蔽 INT、 DOUBLE和 DECIMAL 列,而无需为每个精度单独使用函数:

CREATE FUNCTION mask_numeric(val VARIANT)
RETURNS VARIANT
DETERMINISTIC
RETURN 0::VARIANT;

要按类型返回不同的掩码值,请基于 schema_of_variant() 进行分支判断,并为每种类型返回相应的值:

CREATE FUNCTION flexible_mask(data VARIANT)
RETURNS VARIANT
RETURN CASE
  WHEN schema_of_variant(data) = 'BIGINT' THEN 0::VARIANT
  WHEN schema_of_variant(data) = 'DATE' THEN DATE'1970-01-01'::VARIANT
  WHEN schema_of_variant(data) = 'DOUBLE' THEN 0.00::VARIANT
  ELSE NULL::VARIANT
END;

整数类型在 VARIANT 中会提升为 BIGINT,因此应根据 BIGINT 进行分支,而不是根据 INT 或 TINYINT 进行分支。

屏蔽 STRUCT、ARRAY 和 MAP 列

该 VARIANT 方法还会掩盖复类型列,将 上述数值示例 扩展到嵌套数据。 STRUCT、ARRAY 或 MAP 列会以 VARIANT 的形式传递给该函数,而 Azure Databricks 会将该函数返回的任何内容转换回该列声明的类型。 返回的值必须与输入具有相同的架构,否则类型转换将失败,查询也会报错。

注释

Databricks Runtime 18.1 及更高版本支持 STRUCT 列。 在 Databricks Runtime 19 及更高版本中,支持 ARRAY 和 MAP 列。 这种类型转换仅适用于 ABAC 列掩码和行过滤策略,不适用于常规 SQL 或表级掩码。

以下示例函数遮罩特定的 STRUCT、 ARRAY和 MAP 类型。 为每个需要遮蔽的模式添加一个 WHEN 分支:

CREATE OR REPLACE FUNCTION generic_mask(val VARIANT)
RETURNS VARIANT
RETURN CASE
  -- STRUCT<id: INT, ssn: STRING>: keep id, redact ssn
  WHEN schema_of_variant(val) = 'OBJECT<id: BIGINT, ssn: STRING>' THEN
    to_variant_object(named_struct('id', val:id, 'ssn', 'xxx-xx-xxxx'))
  -- ARRAY<STRING>: return a single redacted element
  WHEN schema_of_variant(val) = 'ARRAY<STRING>' THEN
    to_variant_object(array('redacted'))
  -- MAP<STRING, STRING>: redact every value
  WHEN schema_of_variant(val) = 'OBJECT<key1: STRING, key2: STRING>' THEN
    to_variant_object(map('key1', 'redacted', 'key2', 'redacted'))
  ELSE NULL::VARIANT
END;

每个 WHEN 分支负责两项工作,具体描述如下:

  1. 识别变体模式。 每个 VARIANT 模式都需要自己的遮罩逻辑,因此函数会在返回的模式字符串 schema_of_variant(val) 上分支,对每个模式应用正确的遮蔽处理。

  2. 重建掩蔽值。 构建该列类型的脱敏值,并将其包装在 to_variant_object() 中,以返回一个 VARIANT。

其架构与任何分支都不匹配的值会落入 ELSE。

识别变体模式

根据值的 VARIANT 架构进行匹配,而不是根据列的声明类型:转换为 VARIANT 会将数据规范化,因此该架构可能与列的定义不同。 以下示例展示了常见情况:

列类型 schema_of_variant() 结果 备注
ARRAY<STRING> ARRAY<STRING>
ARRAY<INT> ARRAY<BIGINT> 整数类型扩展为 BIGINT。
STRUCT<id: INT, name: STRING> OBJECT<id: BIGINT, name: STRING> STRUCT 列和 MAP 列都变为 OBJECT。
STRUCT<name: STRING, id: INT> OBJECT<id: BIGINT, name: STRING> 字段按键字母顺序排序,而非声明顺序。
ARRAY<STRUCT<id: INT, name: STRING>> ARRAY<OBJECT<id: BIGINT, name: STRING>>
MAP<STRING, STRING> 判决 {a: 'x'} OBJECT<a: STRING> 每行不同:每行的键决定了模式。
MAP<STRING, STRING> 判决 {a: 'x', b: 'y'} OBJECT<a: STRING, b: STRING> 同一列的不同行会产生不同的模式。
MAP<STRING, STRING> 判决 {a: null} OBJECT<a: VOID> 空值变为 VOID。
MAP<STRING, STRUCT<id: INT, name: STRING>> 判决 {a: ...} OBJECT<a: OBJECT<id: BIGINT, name: STRING>, ...>

重建掩码值

对于你匹配的每个模式,构建一个相同结构的已编辑值,然后将其包裹为 to_variant_object():

  • 用 named_struct() 来重建一个 STRUCT,保留你想要的字段,替换其余的。

  • 使用 array() 重建 ARRAY。

  • 使用 map() 重建具有已编辑值的 MAP。

Azure Databricks 会将返回的 VARIANT 转换回该列声明的类型,因此每个重建的值都必须能够转换为该类型。

测试一个变体掩模

在你把函数附加到策略上之前,你可以先用纯查询测试它,确认被掩蔽的输出。 以下函数会对列 ARRAY<STRUCT<id: BIGINT, value: FLOAT>> 进行掩蔽,并对任何其他模式发送错误:

CREATE OR REPLACE FUNCTION mask_points(v VARIANT)
RETURNS VARIANT
RETURN CASE
  WHEN schema_of_variant(v) = 'ARRAY<OBJECT<id: BIGINT, value: FLOAT>>' THEN
    to_variant_object(array(named_struct('id', 1, 'value', 2.1)))
  ELSE raise_error('Unexpected VARIANT schema: ' || schema_of_variant(v))
END;

使用 to_variant_object() 转换该列,应用掩码函数,然后使用 variant_get() 将经过掩码处理的 VARIANT 强制转换回该列的类型。 这与该策略在运行时的作用相呼应:

SELECT variant_get(mask_points(to_variant_object(points)), '$', typeof(points)) AS masked
FROM my_catalog.my_schema.my_table;

Limitations

  • 包含 CHAR、VARCHAR、GEOMETRY、GEOGRAPHY 或 TIME 的复杂列无法使用 VARIANT 进行屏蔽。

  • MAP 密钥必须是 STRING。 输入为 MAP<INT, ...>、 MAP<DATE, ...>、 等的列不会被转换。

在标记敏感列之前阻止访问

常见的治理模式是基于数据是否已分类来控制访问。 可以使用默认限制性标记和策略来实现此方案,这些标记和策略根据分类状态强制实施不同级别的保护。

  1. 默认情况下,通过自动化或通过标记继承将标记 classification : unverified 应用于所有新对象,方法是在目录或架构级别应用标记,以便添加到目录或架构的任何新表都自动继承标记。

  2. 创建阻止访问标记 classification : unverified表的行筛选器策略。

  3. 创建一个列掩码策略,用于屏蔽标记不再存在的表中的 classification : unverified 敏感列。

  4. 数据专员完成分类后,更新标记。 阻止策略不再匹配,掩码策略生效。

-- Block access to unverified tables for all non-admin users
CREATE FUNCTION catalog.schema.block_all() RETURNS BOOLEAN
  RETURN FALSE;

CREATE POLICY block_unverified
ON CATALOG my_catalog
ROW FILTER catalog.schema.block_all
TO `account users` EXCEPT `data_admins`
FOR TABLES
WHEN has_tag_value('classification', 'unverified');

若要在对敏感数据进行分类后保护敏感数据,请定义一个列掩码策略, classification : unverified 该策略在标记不再存在时生效:

CREATE FUNCTION catalog.schema.mask_pii(val STRING)
RETURNS STRING
RETURN '***';

CREATE POLICY mask_reviewed_pii
ON CATALOG my_catalog
COLUMN MASK catalog.schema.mask_pii
TO `account users`
EXCEPT `data_admins`
FOR TABLES
WHEN NOT has_tag_value('classification', 'unverified')
MATCH COLUMNS (has_tag_value('pii', 'name') OR has_tag_value('pii', 'address')) AS m
ON COLUMN m;

不使用正则表达式的部分显示

使用字符串操作而不是正则表达式显示敏感值的一部分。 基于正则表达式的掩码扫描每一行的整个值,这在大型文本字段上非常昂贵(请参阅 避免大型文本字段上的正则表达式掩码)。

CREATE FUNCTION mask_ssn(ssn STRING, show_last INT) RETURNS STRING
DETERMINISTIC
  RETURN CONCAT('***-**-', RIGHT(ssn, show_last));

一致的哈希(确定性假名化)

一致的哈希(也称为确定性假名化)将敏感数据替换为多个表中相同的哈希值。 将 DETERMINISTIC 函数标记为告知引擎,该函数始终为相同的输入返回相同的结果,这有助于优化查询。 请参阅 “使用确定性、错误安全的表达式”。

以下函数一致地对字符串值进行哈希处理,并使用 version 参数来支持密钥轮换。 通过策略的version子句增量USING COLUMNS数字,以生成新的哈希,同时不影响使用以前版本的历史数据。 该函数在进行哈希处理之前将原始值与版本号连接在一起,因此具有相同版本的相同输入始终生成相同的哈希。

CREATE FUNCTION pseudonymize(val STRING, version INT) RETURNS STRING
DETERMINISTIC
  RETURN SHA2(CONCAT(val, CAST(version AS STRING)), 256);

使用仅列谓词的行筛选

使用仅引用表列的简单布尔逻辑筛选行。 仅限于列的谓词实现谓词下推,这允许引擎在扫描期间跳过不相关的数据(参见 了解受保护表的谓词下推)。

CREATE FUNCTION filter_by_region(region STRING, allowed STRING)
RETURNS BOOLEAN
DETERMINISTIC
  RETURN array_contains(split(allowed, ','), lower(region));

与将允许的区域作为常量传递的策略一起使用:

CREATE POLICY regional_access
ON CATALOG analytics
ROW FILTER filter_by_region
TO 'emea_team'
FOR TABLES
MATCH COLUMNS has_tag('region') AS rgn
USING COLUMNS (rgn, 'emea,apac');

当表具有表示相关属性的多个列(例如,ship_to_country和bill_to_country)时,你可以通过单独的标记条件匹配它们,并将两者传递给单个 UDF。 这可避免为每个列创建单独的策略。 行过滤策略最多可包含六个列表达式,列掩码策略可在 MATCH COLUMNS 子句中包含最多三个列表达式(参见 策略配额)。

CREATE FUNCTION filter_by_countries(ship_country STRING, bill_country STRING, allowed STRING)
RETURNS BOOLEAN
DETERMINISTIC
  RETURN array_contains(split(allowed, ','), lower(ship_country))
      OR array_contains(split(allowed, ','), lower(bill_country));

CREATE POLICY regional_orders
ON SCHEMA prod.orders
ROW FILTER filter_by_countries
TO analysts
FOR TABLES
WHEN has_tag_value('sensitivity', 'high')
MATCH COLUMNS
  has_tag('ship_country') AS ship,
  has_tag('bill_country') AS bill
USING COLUMNS (ship, bill, 'us,ca,mx');

分析师只能看到发货国家或计费国家位于其允许列表中的订单。

ABAC 策略 UDF 中的查找表

如果访问规则因每个用户而异,并且不能单独通过策略的 TO/EXCEPT 子句表示,则可以针对小型查阅表格检查访问权限。 尽可能使用 TO/EXCEPT ,因为它是针对主体的首选方法(请参阅 面向主体的方法)。 使查阅表格保持较小,以便优化器将子查询转换为广播哈希联接(请参阅 “保持查找表较小”。

CREATE TABLE access_rules (
  principal VARCHAR(255),
  priority VARCHAR(64)
);

INSERT INTO access_rules VALUES
  ('alice@company.com', '1-URGENT'),
  ('alice@company.com', '2-HIGH'),
  ('bob@company.com', '1-URGENT');

CREATE FUNCTION priority_allowed(o_priority STRING) RETURNS BOOLEAN
RETURN EXISTS (
  SELECT 1 FROM access_rules
  WHERE principal = session_user() AND priority = o_priority
);

CREATE POLICY priority_filter
ON CATALOG operations
ROW FILTER priority_allowed
TO `account users`
FOR TABLES
MATCH COLUMNS has_tag('priority') AS pri
USING COLUMNS (pri);