Criar e gerenciar políticas ABAC

Esta página descreve como criar, editar, view e excluir políticas ABAC no Unity Catalog. Para uma visão geral dos conceitos de política, consulte Conceitos básicos para ABAC.

Requisitos

Todas as operações de política (criar, editar, excluir, mostrar, descrever) exigem MANAGE no objeto protegível ou na propriedade do objeto. A criação de uma política também exige:

• Databricks Runtime 16.4 ou superior, ou compute serverless . Consulte os requisitos de computação.
• Para a lógica de filtragem ou mascaramento, uma função definida pelo usuário (UDF) no Unity Catalog que você tenha EXECUTE ativada, ou uma função SQL que você define diretamente ao criar a política.
• tags regulamentadas aplicadas aos objetos de destino. Veja as tagsGoverned.

Criar uma política

Você pode criar uma política usando a interface do usuário do Catalog Explorer, a instrução SQL CREATE POLICY ou as APIs REST, SDKs e Terraform do Databricks.

Para criar uma política, você deve ter MANAGE no objeto protegível onde a política está anexada (catálogo, esquema ou tabela) ou ser o proprietário do objeto protegível e EXECUTE na UDF que implementa a lógica de filtragem ou mascaramento.

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog .

2. Selecione o objeto que determina o escopo da política, como um catálogo, esquema ou tabela.

3. Clique na guia Políticas .

4. Clique em Nova política .

5. Preencha a seção de identificação da política . A tabela a seguir resume cada campo:

campo	Descrição	Exemplo
Nome	Um nome para a política. Deve ser única entre todas as políticas definidas no mesmo objeto protegível.	hide_eu_customers, mask_ssn
Descrição	Opcional. Uma descrição da política. Aparece nos logs de auditoria e ajuda os administradores a entender a intenção da política.	Restrict EU customer rows from US analysts, Mask SSN for all account users

6. Preencha a seção Princípios e âmbito de aplicação . A tabela a seguir resume cada campo:

campo	Descrição	Exemplo
Aplicado a...	Os usuários, grupos ou entidade de serviço sujeitos à política. Quando esses usuários consultam as tabelas no escopo, o filtro de linha ou a máscara de coluna é aplicada. Para aplicar a política a todos os principais na account, selecione All account users.	us_analysts, All account users
Exceto por	Diretores estão isentos da política. Os clientes isentos não estão sujeitos a filtragem ou mascaramento e visualizam os dados completos e não modificados.	admins, compliance_team
Escopo	O objeto protegível ao qual a política está anexada. A política é avaliada em relação a todas as tabelas dentro do escopo selecionado. Selecione um catálogo, esquema ou tabela. A Databricks recomenda anexar políticas no nível mais alto aplicável.	Selecione o catálogo prod e, em seguida, selecione o esquema customers.
Condição da tabela	Determina a quais tabelas dentro do escopo a política se aplica. Sem condição : Aplica a política a todas as tabelas no escopo. Tabelas que correspondem a qualquer uma destas tags : Aplica a política à lista especificada de chave tag ou par tag key-valor. As tabelas que apresentarem qualquer um desses elementos correspondem à política. Tabelas que correspondem a uma expressão personalizada : Você pode construir uma expressão booleana usando has_tag e has_tag_value, combinada com AND, OR e NOT para uma lógica de correspondência mais complexa. Aplica a política às tabelas onde a expressão é avaliada como TRUE e corresponde à política. Se uma tabela no escopo não corresponder à condição, a política não se aplicará a essa tabela.	Selecione as tabelas que correspondem a qualquer uma dessas tags e, em seguida, escolha key tag sensitivity com o valor high para restringir a política apenas às tabelas confidenciais.

7. Em Tipo de política , escolha o tipo de controle de acesso a ser aplicado:

Opção	Descrição	Use quando
Filtro de linha	Cria uma política de filtro de linhas. A UDF avalia cada linha e retorna um valor booleano. As linhas em que a UDF retorna FALSE são excluídas dos resultados da consulta.	O acesso depende dos valores em cada linha, como por exemplo, filtrar pelos valores em uma coluna que contém regiões geográficas.
Máscara de coluna	Cria uma política de máscara de coluna. A função definida pelo usuário (UDF) recebe o valor da coluna como entrada e retorna o valor original ou uma versão mascarada. O tipo de retorno deve ser compatível com o tipo de dados da coluna de destino.	É necessário ocultar campos sensíveis, como números de segurança social, números de telefone ou endereços email , permitindo ainda que o usuário principal consulte a tabela.

8. As próximas seções dependem do tipo de política que você selecionar. Expanda a seção que corresponde à sua seleção:

Filtro de linha

Na seção Função de filtro de linha , escolha como especificar a função de filtro de linha:

• Selecionar existente : Selecione uma UDF já definida no Unity Catalog. A UDF avalia cada linha e retorna um valor booleano. As linhas em que a função retorna FALSE são excluídas dos resultados da consulta. Você deve ter EXECUTE na UDF.
• Criar : Defina uma função SQL para usar como lógica de filtro de linhas.

Na seção Entradas da função , forneça um valor para cada parâmetro da função. Cada entrada pode ser uma coluna que corresponde a tags, uma coluna que corresponde a uma expressão personalizada ou um valor constante.

Máscara de coluna

Na seção Condições da coluna , escolha como identificar as colunas a serem mascaradas:

• Colunas que correspondam a qualquer uma destas tags : Especifique uma lista de chave tag ou par key tag - valor. As colunas que contêm qualquer um desses elementos são mascaradas pela política.
• Colunas que correspondem a uma expressão personalizada : Crie uma expressão booleana usando has_tag e has_tag_value, combinada com AND, OR e NOT para uma lógica de correspondência mais complexa. As colunas onde a expressão resulta em TRUE são mascaradas.

Em seguida, escolha a função de mascaramento a ser aplicada às colunas correspondentes:

• Selecionar existente : Selecione uma UDF já definida no Unity Catalog. A UDF retorna o valor original ou o valor mascarado. O tipo de retorno deve ser compatível com o tipo de dados da coluna de destino. Você deve ter EXECUTE na UDF.
• Criar : Defina uma função SQL para usar como lógica de mascaramento de coluna.

Na seção Entradas da função , forneça um valor para cada parâmetro adicional da função. Cada entrada pode ser uma coluna que corresponde a tags, uma coluna que corresponde a uma expressão personalizada ou um valor constante.

Este exemplo usa um valor constante de 4 para mostrar os últimos 4 caracteres do SSN.

9. Clique em Criar política .

SQL

Para obter a documentação completa, consulte CRIAR POLÍTICA.

SQL

CREATE [OR REPLACE] POLICY policy_name
ON { CATALOG catalog_name | SCHEMA schema_name | TABLE table_name }
[COMMENT description]
{ row_filter_body | column_mask_body }

Corpo do filtro de linha:

SQL

ROW FILTER function_name
TO principal [, ...]
[EXCEPT principal [, ...]]
FOR TABLES
[WHEN condition]
[MATCH COLUMNS condition [[AS] alias] [, ...]]
[USING COLUMNS (function_arg [, ...])]

Corpo da máscara de coluna:

SQL

COLUMN MASK function_name
TO principal [, ...]
[EXCEPT principal [, ...]]
FOR TABLES
[WHEN condition]
[MATCH COLUMNS condition [[AS] alias] [, ...]]
ON COLUMN alias
[USING COLUMNS (function_arg [, ...])]

Parâmetros:

• policy_name: Um nome para a política. Deve ser única entre todas as políticas definidas no mesmo objeto protegível.
• ON { CATALOG | SCHEMA | TABLE }: O âmbito em que a política está vinculada. A política é avaliada em relação a todas as tabelas que são descendentes desse objeto protegível.
• function_name: O nome totalmente qualificado da UDF que implementa a lógica de filtragem ou mascaramento.
• TO principal [, ...]: os usuários, grupos ou entidade de serviço aos quais a política se aplica.
• EXCEPT principal [, ...]Diretores estão isentos da política. Os diretores isentos não estão sujeitos a filtragem ou mascaramento.
• FOR TABLES: Especifica que a política tem como alvo as tabelas. Atualmente, as tabelas são o único tipo de objeto protegível suportado, incluindo tabelas de transmissão e visualizações materializadas.
• WHEN conditionUma expressão booleana que determina a quais tabelas a política se aplica, com base em suas tags. Usa funções integradas has_tag('tag_name') e has_tag_value('tag_name', 'tag_value'). Se omitido, o padrão é TRUE (aplica-se a todas as tabelas no escopo).
• MATCH COLUMNS condition [[AS] alias] [, ...]Condições de coluna que identificam quais colunas a política visa. Cada condição é uma expressão booleana construída a partir de has_tag('tag_name') e has_tag_value('tag_name', 'tag_value'), opcionalmente combinada com AND, OR e NOT. Cada condição pode ser atribuído um alias para uso em ON COLUMN e USING COLUMNS. Uma política pode incluir até 3 expressões MATCH COLUMNS e todas devem corresponder para que a política seja aplicada.
• ON COLUMN alias: Para políticas de máscara de coluna, especifica a coluna correspondente a ser mascarada, referenciada por seu alias de MATCH COLUMNS.
• USING COLUMNS (function_arg [, ...])Argumentos passados para a UDF. Cada argumento pode ser um alias de MATCH COLUMNS ou uma constante literal.

Exemplo: política de máscara de coluna. Mascare todas as tags de coluna com pii:ssn no esquema prod.customers , mostrando apenas os últimos 4 caracteres. A política se aplica a us_analysts exceto admins.

SQL

CREATE FUNCTION ssn_to_last_nr (ssn STRING, nr INT) RETURNS STRING
  RETURN right(ssn, nr);

CREATE POLICY mask_ssn
ON SCHEMA prod.customers
COLUMN MASK ssn_to_last_nr
TO us_analysts EXCEPT admins
FOR TABLES
MATCH COLUMNS has_tag_value('pii', 'ssn') AS ssn
ON COLUMN ssn
USING COLUMNS (4);

Exemplo: política de filtro de linha. Excluir linhas com clientes europeus das tabelas com tags sensitivity:high no esquema prod.customers . A política se aplica a us_analysts e filtra linhas com base em uma coluna geo_region .

SQL

CREATE FUNCTION non_eu_region (geo_region STRING) RETURNS BOOLEAN
  RETURN geo_region <> 'eu';

CREATE POLICY hide_eu_customers
ON SCHEMA prod.customers
COMMENT 'Exclude rows with European customers from sensitive tables'
ROW FILTER non_eu_region
TO us_analysts
FOR TABLES
WHEN has_tag_value('sensitivity', 'high')
MATCH COLUMNS has_tag('geo_region') AS region
USING COLUMNS (region);

Python SDK

Para obter a documentação completa, consulte a documentação do SDK Databricks para Python.

Este exemplo cria uma política de filtro de linhas que exclui linhas com clientes europeus para analistas baseados nos EUA:

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import (
    FunctionArgument,
    MatchColumn,
    PolicyInfo,
    PolicyType,
    RowFilterOptions,
    SecurableType,
)

w = WorkspaceClient()

w.policies.create_policy(PolicyInfo(
    name="hide_eu_customers",
    comment="Exclude rows with European customers from sensitive tables",
    on_securable_type=SecurableType.SCHEMA,
    on_securable_fullname="prod.customers",
    for_securable_type=SecurableType.TABLE,
    policy_type=PolicyType.POLICY_TYPE_ROW_FILTER,
    to_principals=["us_analysts"],
    match_columns=[
        MatchColumn(condition="has_tag('geo_region')", alias="region"),
    ],
    row_filter=RowFilterOptions(
        function_name="prod.customers.non_eu_region",
        using=[FunctionArgument(alias="region")],
    ),
))

Este exemplo cria uma política de máscara de coluna que oculta os números de segurança social para analistas dos EUA, exceto aqueles no grupo admins :

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import (
    ColumnMaskOptions,
    FunctionArgument,
    MatchColumn,
    PolicyInfo,
    PolicyType,
    SecurableType,
)

w = WorkspaceClient()

w.policies.create_policy(PolicyInfo(
    name="mask_ssn",
    comment="Mask social security numbers",
    on_securable_type=SecurableType.SCHEMA,
    on_securable_fullname="prod.customers",
    for_securable_type=SecurableType.TABLE,
    policy_type=PolicyType.POLICY_TYPE_COLUMN_MASK,
    to_principals=["us_analysts"],
    except_principals=["admins"],
    match_columns=[
        MatchColumn(condition="has_tag_value('pii', 'ssn')", alias="ssn"),
    ],
    column_mask=ColumnMaskOptions(
        function_name="prod.customers.ssn_to_last_nr",
        on_column="ssn",
        using=[FunctionArgument(constant="4")],
    ),
))

Editar uma política

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog .
2. Selecione o objeto ao qual a política está associada.
3. Clique na guia Políticas .
4. Selecione a política que deseja editar.
5. Atualize os campos que desejar modificar. Você pode modificar a descrição, os princípios, o tipo de política, as condições e os mapeamentos de entrada de função. O nome da política e o objeto protegível ao qual a política é aplicada não podem ser editados. Para obter descrições dos campos, consulte Criar uma política.
6. Clique em Atualizar política .

SQL

CREATE OR REPLACE POLICY substitui toda a definição da política. Especifique todas as cláusulas, não apenas os campos que deseja alterar. A política de substituição deve ter o mesmo nome e estar no mesmo objeto protegível.

SQL

CREATE OR REPLACE POLICY mask_ssn
ON SCHEMA prod.customers
COLUMN MASK ssn_to_last_nr
TO us_analysts EXCEPT admins, compliance_team
FOR TABLES
MATCH COLUMNS has_tag_value('pii', 'ssn') AS ssn
ON COLUMN ssn
USING COLUMNS (4);

Python SDK

Ao contrário de CREATE OR REPLACE POLICY em SQL, update_policy suporta atualizações parciais. Use o parâmetro update_mask para especificar quais campos devem ser alterados. Somente esses campos são atualizados. Se update_mask for "*" ou estiver vazio, todos os campos em policy_info serão aplicados.

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import PolicyInfo

w = WorkspaceClient()

w.policies.update_policy(
    on_securable_type="SCHEMA",
    on_securable_fullname="prod.customers",
    name="mask_ssn",
    policy_info=PolicyInfo(
        except_principals=["admins", "compliance_team"],
    ),
    update_mask="except_principals",
)

Excluir uma política

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog .
2. Selecione o objeto ao qual a política está associada.
3. Clique na guia Políticas .
4. Selecione a política.
5. Clique em Excluir política .

SQL

Use DROP POLICY para excluir uma política.

SQL

DROP POLICY policy_name ON { CATALOG | SCHEMA | TABLE } securable_name

Exemplos:

SQL

DROP POLICY mask_ssn ON SCHEMA prod.customers;
DROP POLICY hide_eu_customers ON SCHEMA prod.customers;

Python SDK

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.policies.delete_policy(
    on_securable_type="SCHEMA",
    on_securable_fullname="prod.customers",
    name="mask_ssn",
)

Mostrar políticas

Use SHOW POLICIES para listar as políticas definidas em um objeto protegível. Use SHOW EFFECTIVE POLICIES para incluir também políticas de escopos pai, como políticas de nível de catálogo que afetam uma tabela.

SQL

SHOW [EFFECTIVE] POLICIES ON { CATALOG | SCHEMA | TABLE } securable_name

O resultado inclui o nome da política, o tipo de política e o catálogo, esquema ou tabela onde cada política está definida.

A visualização das políticas efetivas de uma tabela não requer permissões no catálogo ou esquema pai. Isso permite que um administrador de tabela veja as regras aplicáveis sem ter acesso de leitura às políticas das tabelas irmãs.

Exemplo:

SQL

SHOW EFFECTIVE POLICIES ON SCHEMA prod.customers;

nome_da_política	tipo_de_política	catálogo	esquema	Comentário
ocultar_clientes_da_eu	FILTRO DE LINHA	produção	clientes
máscara_ssn	MÁSCARA DE COLUNA	produção	clientes

Descreva uma política

Use DESCRIBE POLICY para view os detalhes de uma política específica. Requer MANAGE no objeto protegível de destino ou propriedade do objeto.

SQL

{ DESC | DESCRIBE } POLICY policy_name ON { CATALOG | SCHEMA | TABLE } securable_name

O resultado mostra as propriedades da política como pares key-valor, incluindo nome, tipo de objeto protegível, nome do objeto protegível, entidades, condições, nome da função e registros de data e hora.

Exemplo:

SQL

DESCRIBE POLICY hide_eu_customers ON SCHEMA prod.customers;

nome_da_informação	valor_da_informação
Nome	ocultar_clientes_da_eu
Sobre o tipo seguro	Esquema
Em segurança	clientes de produção
Aos diretores	analistas dos EUA
Para o tipo seguro	Tabela
Colunas correspondentes	tem a tag ('geo_region') como região
Tipo de apólice	FILTRO_DE_LINHAS
Nome da função	prod.clientes.região_não_eu
Utilizando colunas	Região

Registro de auditoria

Databricks logs as operações tag controladas e políticas ABAC na tabela log de auditoria do sistema. Abaixo seguem exemplos de consultas. Para mais informações, consulte logsde auditoria.

SQL

-- All tag assignment and deletion events from the audit log
SELECT
  event_time,
  action_name,
  user_identity.email AS actor,
  request_params.workspace_id,
  request_params.metastore_id,
  request_params.tag_assignment,
  response.status_code,
  source_ip_address
FROM system.access.audit
WHERE service_name = 'unityCatalog'
  AND action_name IN (
    'createEntityTagAssignment',
    'deleteEntityTagAssignment'
  )
ORDER BY event_time DESC;

-- All ABAC policy CRUD operations
SELECT
  event_time,
  action_name,
  user_identity.email AS actor,
  request_params.name AS policy_name,
  request_params.on_securable_type,
  request_params.on_securable_fullname,
  request_params.policy_info,
  response.status_code
FROM system.access.audit
WHERE service_name = 'unityCatalog'
  AND action_name IN ('createPolicy', 'deletePolicy', 'getPolicy', 'listPolicies')
ORDER BY event_time DESC;

Mais informações

• Conceitos básicos para ABAC
• Avaliação de políticas e comportamento em tempo de execução
• Considerações sobre desempenho para políticas ABAC
• Tutorial ABAC
• tagsregulamentadas
• Funções definidas pelo usuário Unity Catalog