Políticas ABAC GRANT

As políticas ABAC GRANT concedem dinamicamente privilégios do Unity Catalog a objetos protegíveis cujas tags governadas correspondem a uma condição. Esta página aborda como criar, editar, listar e excluir políticas ABAC GRANT, como as políticas GRANT interagem com concessões diretas e o escopo e as limitações atuais.

É possível criar e gerenciar políticas de GRANT ABAC usando o Catalog Explorer, SQL ou a API REST para qualquer tipo protegível suportado.

Para uma visão geral do ABAC e de conceitos essenciais, incluindo tags governadas e funções integradas como has_tag e has_tag_value, consulte Conceitos essenciais para controle de acesso baseado em atributo (ABAC).

Compute requirements

Usar SQL para criar, modificar ou remover políticas de concessão (GRANT) requer um recurso de compute clássico executando o Databricks Runtime 18 LTS ou superior.

nota

O Databricks Runtime 18 é mais recente que o Databricks Runtime 18.0, 18.1 e 18.2. Os recursos que anteriormente teriam sido lançados como uma versão numerada posterior agora são lançados como atualizações datadas para o Databricks Runtime 18. Para obter detalhes, consulte Sobre as notas sobre a versão unificadas.

O que é uma GRANT policy

Uma política GRANT é uma política de controle de acesso baseada em atributos que concede dinamicamente privilégios do Unity Catalog a objetos protegíveis cujas tags governadas correspondem à condição da política. O Unity Catalog avalia a WHEN condição da política em relação às tags governadas em cada objeto seguro no escopo da política sempre que o acesso é verificado e concede o privilégio em cada objeto seguro que corresponde.

Em comparação, instruções diretas GRANT atribuem privilégios a objetos protegíveis identificados pelo seu namespace de três níveis (catalog.schema.object).

As políticas GRANT podem fazer referência a tags controladas que você cria ou tags do sistema predefinidas pela Databricks em suas condições.

Exemplos de policy GRANT

Estes exemplos se aplicam tanto a modelos MLflow registrados pelo cliente quanto a modelos de fundação hospedados pelo Databricks em system.ai. Para obter informações sobre como os modelos MLflow são registrados no Unity Catalog, consulte Gerenciar o ciclo de vida do modelo no Unity Catalog. Para modelos de fundação hospedados pelo Databricks, consulte Acessar modelos de AI e LLM do Unity Catalog.

A política a seguir usa a tag controlada lifecycle aplicada a modelos MLflow registrados pelo cliente em production.ml_models. A política concede EXECUTE apenas em modelos com a tag lifecycle = 'production':

SQL
CREATE POLICY grant_production_model_access
ON SCHEMA production.ml_models
COMMENT 'Grant EXECUTE on production MLflow models'
TO `analysts`
GRANT EXECUTE FOR MODELS
WHEN has_tag_value('lifecycle', 'production');

A política a seguir usa a tag de sistema ai.model_creator pré-aplicada para conceder EXECUTE em cada modelo de fundação hospedado pela Anthropic em system.ai a data_scientists, exceto contractors. A política cobre automaticamente qualquer modelo Anthropic que a Databricks adicionar posteriormente:

SQL
CREATE POLICY grant_anthropic_foundation_models
ON SCHEMA system.ai
COMMENT 'Grant EXECUTE on Anthropic foundation models'
TO `data_scientists`
EXCEPT `contractors`
GRANT EXECUTE FOR MODELS
WHEN has_tag_value('ai.model_creator', 'anthropic');

O acesso equivalente usando concessões diretas requer uma instrução por modelo em system.ai, reemitida à medida que a Databricks adiciona novos modelos da Anthropic:

SQL
GRANT EXECUTE ON MODEL `system`.`ai`.`databricks-claude-sonnet-4-6` TO `data_scientists`;
GRANT EXECUTE ON MODEL `system`.`ai`.`databricks-claude-opus-4-7` TO `data_scientists`;
GRANT EXECUTE ON MODEL `system`.`ai`.`databricks-claude-haiku-4-5` TO `data_scientists`;

As políticas GRANT diferem das políticas de filtro de linha e de máscara de coluna de duas maneiras:

As políticas de filtros de linha e máscaras de coluna restringem o conteúdo de dados ao qual um usuário já tem acesso. GRANT políticas determinam se o usuário pode acessar o objeto.
As políticas de filtro de linha e de máscara de coluna exigem uma função definida pelo usuário (UDF) para implementar o filtro ou a máscara. As políticas GRANT não utilizam UDFs. A condição é expressa em linha na definição de política.

Os privilégios que você pode conceder dependem do tipo protegível. Para a lista completa de tipos suportados e seus privilégios concedíveis por política, consulte Tipos protegíveis e privilégios suportados.

Tipos protegíveis e privilégios suportados

A tabela a seguir mostra os tipos suportados e seus privilégios que podem ser concedidos por política. O Unity Catalog valida os privilégios que você nomeia em relação ao tipo protegível quando você cria a política, e rejeita qualquer privilégio que o tipo não suporte.

Tipo protegível	`APPLY_TAG`	`EXECUTE`	`READ_METADATA`
Modelo	✓	✓	✓
Serviço de modelo	✓	✓	✓
Serviço de provedor de modelos	✓	✓	✓
Serviço MCP	✓	✓	✓
Serviço de agente	✓	✓	✓

Em SQL, use o tipo de securable no plural após FOR, como GRANT EXECUTE FOR MODEL SERVICES. Você pode escrever o tipo com espaços, como MODEL SERVICES, ou com underscores, como MODEL_SERVICES. Formas no singular não são aceitas. Na API REST, defina for_securable_type para a forma no singular com underscores, por exemplo MODEL_SERVICE.

Políticas de GRANT podem ser anexadas a um catálogo ou a um esquema.

Para a lista completa de privilégios que você pode conceder diretamente em cada tipo de objeto, consulte referência de privilégios do Unity Catalog.

Como as políticas GRANT interagem com as concessões diretas

Os privilégios efetivos em um objeto são a união de concessões diretas e quaisquer políticas GRANT aplicáveis. Esta lógica de união se aplica a todos os tipos e privilégios compatíveis em tipos e privilégios compatíveis. O exemplo a seguir usa EXECUTE em um modelo. Um principal detém EXECUTE em um modelo quando qualquer uma das seguintes condições for verdadeira:

Uma política GRANT anexada ao catálogo ou esquema do modelo lista o principal em TO (e não em EXCEPT), e a condição WHEN da política corresponde às tags no modelo.
Um GRANT EXECUTE direto no modelo, em seu esquema ou em seu catálogo está em vigor para esse principal, seja concedido diretamente, por meio de associação a grupos ou por meio de outros privilégios administrativos.

Como o acesso é a união dessas fontes, uma política GRANT mais seletiva não significa que um principal excluído não tenha EXECUTE. O principal ainda pode deter o privilégio por meio de uma concessão direta no modelo, ou em seu esquema pai ou catálogo pai. Caso se pretenda utilizar políticas GRANT como a principal forma de controlar EXECUTE em modelos, primeiramente, determine se quaisquer concessões diretas já existentes possam sobrepor a política:

Use SHOW EFFECTIVE POLICIES ON SCHEMA <parent_schema> (ou ON CATALOG <parent_catalog>) para listar cada política GRANT cujo escopo abrange os modelos nesse esquema ou catálogo. SHOW EFFECTIVE POLICIES não oferece suporte direto a ON MODEL. A REST API equivalente é GET /api/2.1/unity-catalog/policies/{on_securable_type}/{on_securable_fullname}?include_inherited=true (Python SDK: w.policies.list_policies(..., include_inherited=True)).
Use SHOW GRANTS no modelo e em seus ancestrais para enumerar concessões diretas. A API REST equivalente para concessões diretas em um objeto seguro é GET /api/2.1/unity-catalog/permissions/{securable_type}/{full_name} (SDK Python: w.grants.get(...)); para a união de concessões diretas e herdadas, use GET /api/2.1/unity-catalog/effective-permissions/{securable_type}/{full_name} (SDK Python: w.grants.get_effective(...)).

Criar uma política GRANT

Você pode criar uma política GRANT por meio da interface do usuário do Catalog Explorer, com a instrução SQL CREATE POLICY ou com a API REST.

Para criar uma política GRANT, é necessário ter MANAGE no catálogo ou esquema onde a política está anexada, ou ser o proprietário desse objeto protegível.

Catalog Explorer
SQL
REST API

No seu Databricks workspace, clique em Catálogo .
Selecione o catálogo ou esquema onde deseja anexar a política. As políticas GRANT só podem ser anexadas no nível de catálogo ou esquema.
Clique na guia Políticas .
Clique em Nova política .
Em **Identificação da Política**, insira um **Nome da política** e uma **Descrição** opcional.
Em Entidades e escopo :
- Em Aplicado a , selecione as entidades (usuários, grupos ou entidades de serviço) às quais a política se aplica.
- Em **Exceto por**, selecione opcionalmente os principais a serem excluídos da política.
- Em **Escopo**, confirme o catálogo ou esquema onde a política está vinculada.
Em **Tipo de política**, selecione **Conceder acesso**.
Em Objetos protegíveis , selecione o tipo protegível ao qual a política se aplica. Consulte tipos e privilégios compatíveis.
Em Condição , escolha como definir o escopo da política para protegíveis do tipo selecionado no catálogo ou esquema:
- No condition aplica a política a todos os objetos protegíveis desse tipo no catálogo ou esquema selecionado.
- Objetos protegíveis que correspondem a qualquer uma dessas tags aplica a política apenas a objetos protegíveis que contenham pelo menos uma das tags governadas selecionadas.
- Securables matching a custom expression permite que você escreva uma expressão baseada em tags para determinar a quais objetos protegíveis a política se aplica. Consulte Condições e funções integradas para ver as funções de condição disponíveis.
Em Privileges , selecione os privilégios a conceder. Os privilégios disponíveis dependem do tipo de objeto protegível que você escolheu. Consulte tipos e privilégios suportados.
Clique em Mostrar código para revisar a instrução SQL equivalente antes de salvar e, depois, clique em Criar política .

A sintaxe SQL para uma política GRANT usa um corpo GRANT ... FOR ... WHEN ... em vez de ROW FILTER ou COLUMN MASK.

SQL
CREATE [OR REPLACE] POLICY policy_name
ON { METASTORE | CATALOG catalog_name | SCHEMA schema_name }
[COMMENT description]
TO principal [, ...]
[EXCEPT principal [, ...]]
GRANT privilege [, ...] FOR securable_type
[WHEN condition]

Parâmetros:

policy_name: Um nome para a política. Deve ser único entre todas as políticas definidas no mesmo objeto seguro.
ON { METASTORE | CATALOG | SCHEMA }: o escopo onde a política está vinculada. As políticas GRANT podem ser anexadas no nível de metastore, catálogo ou esquema, e não em um objeto protegível individual. Use ON METASTORE para aplicar a política em todos os catálogos do metastore. ON METASTORE não aceita nenhum nome e tem como alvo o metastore em que você está operando no momento. Consulte Políticas ABAC no nível do metastore (Beta).
TO principal [, ...]: Os usuários, grupos ou entidades de serviço aos quais a política se aplica.
EXCEPT principal [, ...]Diretores estão isentos da política.
GRANT privilege [, ...] FOR securable_type: Os privilégios a conceder e o tipo protegível ao qual se aplicam. Os privilégios válidos dependem do tipo. Consulte tipos e privilégios suportados.
WHEN condition: Uma expressão booleana baseada em tags que determina a quais protegíveis a política se aplica dentro do escopo. Usa funções integradas has_tag('tag_name') e has_tag_value('tag_name', 'tag_value'). Se omitido, assume o default TRUE (aplica-se a todos os protegíveis do tipo no escopo). Consulte Condições e funções integradas para as funções de condição disponíveis.

A política a seguir concede EXECUTE em cada serviço MCP em analytics.tools marcado para o domínio financeiro:

SQL
CREATE POLICY grant_finance_mcp_services
ON SCHEMA analytics.tools
COMMENT 'Grant EXECUTE on finance MCP services'
TO `analysts`
GRANT EXECUTE FOR MCP SERVICES
WHEN has_tag_value('domain', 'finance');

Para exemplos de modelos, consulte O que é uma política de concessão (GRANT).

Este exemplo cria uma política de GRANT que concede EXECUTE em cada modelo de base hospedado pela Anthropic em system.ai para data_scientists, exceto contratados:

Bash
curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/policies" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @- << 'EOF'
{
  "name": "grant_anthropic_foundation_models",
  "comment": "Grant EXECUTE on Anthropic foundation models",
  "on_securable_type": "SCHEMA",
  "on_securable_fullname": "system.ai",
  "for_securable_type": "MODEL",
  "policy_type": "POLICY_TYPE_GRANT",
  "to_principals": ["data_scientists"],
  "except_principals": ["contractors"],
  "grant": {
    "privileges": ["EXECUTE"]
  },
  "when_condition": "has_tag_value('ai.model_creator', 'anthropic')"
}
EOF

name, on_securable_type, on_securable_fullname, for_securable_type, policy_type, to_principals e grant.privileges são obrigatórios. comment, except_principals e when_condition são opcionais.

Para obter detalhes sobre solicitação e resposta, consulte Criar política na referência da API REST.

Os privilégios válidos em grant.privileges dependem de for_securable_type. Consulte tipos e privilégios compatíveis.

Editar uma política GRANT

Catalog Explorer
SQL
REST API

Gerencie políticas de GRANT na aba Policies do catálogo pai ou esquema ao qual estão vinculadas.

No seu Databricks workspace, clique em Catálogo .
Selecione o catálogo ou o esquema ao qual a política está vinculada.
Clique na guia Políticas .
Selecione a política que deseja editar.
Atualize os campos que deseja modificar.
Clique na **Política de Atualização**.

Para editar uma política de GRANT com SQL, execute CREATE OR REPLACE POLICY com o mesmo nome e destino. Consulte Criar uma política GRANT.

Ao contrário de CREATE OR REPLACE POLICY em SQL, PATCH oferece suporte a atualizações parciais. Use o parâmetro de query update_mask para especificar quais campos alterar. Apenas esses campos são atualizados, e os campos ausentes do corpo da solicitação permanecem inalterados. Se você omitir update_mask, todos os campos no corpo da solicitação serão atualizados. Se você definir update_mask como *, o corpo da solicitação também deverá incluir todos os campos obrigatórios: to_principals, for_securable_type, policy_type e grant.privileges.

Este exemplo adiciona interns aos principais excluídos da política:

Bash
curl -X PATCH "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/policies/SCHEMA/system.ai/grant_anthropic_foundation_models?update_mask=except_principals" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @- << 'EOF'
{
  "except_principals": ["contractors", "interns"]
}
EOF

O valor que você envia substitui a lista existente em vez de adicionar a ela, portanto, você deve incluir todos os principais que deseja excluir, não apenas os novos.

Excluir política de GRANT

Catalog Explorer
SQL
REST API

Gerencie políticas de GRANT na aba Policies do catálogo pai ou esquema ao qual estão vinculadas.

No seu Databricks workspace, clique em Catálogo .
Selecione o catálogo ou o esquema ao qual a política está vinculada.
Clique na guia Políticas .
Selecione a política.
Clique em Excluir política .

Para excluir uma política GRANT com SQL, execute DROP POLICY:

SQL
DROP POLICY grant_anthropic_foundation_models ON SCHEMA system.ai;

Bash
curl -X DELETE "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/policies/SCHEMA/system.ai/grant_anthropic_foundation_models" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Mostrar políticas

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

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

O resultado inclui o nome da política, o tipo de política, o catálogo e o esquema do objeto protegível no qual cada política é definida, além do tipo e do nome completo desse objeto protegível. As políticas GRANT são retornadas com o tipo de política GRANT juntamente com quaisquer políticas de filtro de linha, máscara de coluna e DENY anexadas no mesmo escopo. A coluna Table é preenchida somente quando uma política é definida em uma tabela. Isso se aplica a políticas de filtro de linha e máscara de coluna. Para políticas GRANT e DENY, a coluna Table é NULL.

Exemplo:

SQL
SHOW EFFECTIVE POLICIES ON SCHEMA system.ai;

Text
Policy Name                        Policy Type  Catalog  Schema  Table  Comment                                       on_securable_type  on_securable_fullname
---------------------------------  -----------  -------  ------  -----  --------------------------------------------  -----------------  ---------------------
grant_anthropic_foundation_models  GRANT        system   ai      NULL   Grant EXECUTE on Anthropic foundation models  SCHEMA             system.ai

Descrever uma política

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

SQL
{ DESC | DESCRIBE } POLICY policy_name ON { METASTORE | CATALOG | SCHEMA } securable_name

O resultado mostra as propriedades da política como pares key-value, incluindo nome, tipo de objeto protegível, nome do objeto protegível, entidades, privilégios e a condição WHEN.

Exemplo:

SQL
DESCRIBE POLICY grant_anthropic_foundation_models ON SCHEMA system.ai;

info_name	valor da informação
Nome	Conceder Modelos de Base da Anthropic
Tipo Protegível	Esquema
No Securable	system.ai
Para principals	cientistas de dados
Exceto principals	prestadores de serviço
Para o Tipo Seguro	Modelo
Tipo de política	Conceder
Privilégios Concedidos	Executar
Quando Condição	has_tag_value('ai.model_creator', 'anthropic')

info_name	valor da informação
Nome	Conceder Modelos de Base da Anthropic
Tipo Protegível	Esquema
No Securable	system.ai
Para principals	cientistas de dados
Exceto principals	prestadores de serviço
Para o Tipo Seguro	Modelo
Tipo de política	Conceder
Privilégios Concedidos	Executar
Quando Condição	has_tag_value('ai.model_creator', 'anthropic')

Definições de política de informação com query Schema

Você pode consultar definições de política GRANT no catálogo atual usando INFORMATION_SCHEMA.ABAC_POLICY_DEFINITIONS:

SQL
SELECT *
FROM information_schema.abac_policy_definitions
WHERE policy_type = 'GRANT';

Para as colunas disponíveis e exemplos adicionais, consulte ABAC_POLICY_DEFINITIONS.

Tags de sistema em modelos de fundação em `system.ai`

Os modelos de base que o Databricks hospeda em system.ai vêm pré-marcados com tags de sistema que as políticas de GRANT podem referenciar diretamente. Não é necessário tag esses modelos para usá-los em uma política.

Etiqueta	Valores de exemplo
`ai.model_creator`	`anthropic`, `openai`, `google`, `meta`
`ai.model_family`	`claude-opus`, `gpt`, `gemini`, `qwen`

Para modelos que registrar em seus próprios catálogos e esquemas, aplique tags governadas por meio do fluxo de trabalho de tag padrão do Unity Catalog. Consulte Tags governadas.

Cotas de política

Recursos	Limite
Políticas por metastore (todos os objetos)	10.000
Políticas por metastore, anexadas diretamente (Beta)	100
Políticas por catálogo	100
Políticas por esquema	100

As políticas GRANT e DENY compartilham uma cota combinada para cada objeto. Essas cotas são separadas das cotas para políticas de filtro de linha e máscara de coluna.

Registro de auditoria

As operações GRANT de criação, alteração e descarte de políticas são registradas sob as mesmas ações createPolicy, deletePolicy, getPolicy e listPolicies que as políticas de filtro de linha e de máscara de coluna. Consulte Registro de auditoria para obter exemplos de consultas de log de auditoria.

Práticas recomendadas

Use grupos em TO e EXCEPT, não usuários individuais. Adicionar ou remover usuários de um grupo nomeado em uma política muda a quem a política se aplica, sem editar a política.
Anexe as políticas no menor escopo que abranja os alvos. Utilize o escopo mais restrito que contém os recursos aos quais a política deve ser aplicada. Um escopo mais amplo incorpora recursos protegíveis não relacionados à correspondência de tags da política e pode conceder acesso onde não se pretendia.
Utilize a herança de tags para defaults seguros. Os valores de tag padrão devem ser aplicados no catálogo ou esquema pai para que os descendentes os herdem. A tag herdada deve ser sobrescrita apenas nos objetos específicos que precisam de um valor diferente. Combine isso com EXCEPT para lidar com exceções controladas a uma política.
Não misture políticas GRANT e concessões diretas para o mesmo privilégio. Para um determinado privilégio em um securable, escolha políticas GRANT ou concessões diretas, não ambos. As políticas de GRANT se unem às concessões diretas; portanto, misturá-las no mesmo recurso protegível dificulta a compreensão de quem tem acesso e a auditoria das alterações.
Use concessões diretas para os pré-requisitos USE CATALOG e USE SCHEMA, e políticas GRANT para os privilégios suportados pelo tipo. As políticas GRANT não concedem os pré-requisitos USE CATALOG e USE SCHEMA necessários para acessar um objeto protegível. Conceda-os diretamente e use uma política GRANT para definir o escopo dos privilégios suportados pelo tipo por tag, como EXECUTE onde houver suporte.

Limitações

Os privilégios CREATE MODEL e CREATE MODEL VERSION não são compatíveis com políticas GRANT e devem ser concedidos diretamente. Para os privilégios compatíveis com MODEL, consulte tipos e privilégios compatíveis.
ALL_PRIVILEGES, MANAGE e MODIFY não são suportados por políticas de GRANT.
As permissões de pré-requisito USE SCHEMA e USE CATALOG, que um usuário precisa para acessar um objeto protegível, não são suportadas por políticas GRANT e devem ser concedidas diretamente.
Uma política pode ser anexada ao catálogo ou ao esquema, não a um objeto protegível individual.
Os privilégios concedidos por uma política GRANT não são retornados por SHOW GRANTS.
A exclusão de um modelo ou de uma versão do modelo não é contemplada pelas políticas GRANT. Consulte Gerenciar o ciclo de vida do modelo no Unity Catalog para saber como excluir versões e modelos de modelo.
Você não pode usar o Delta Sharing para compartilhar modelos que tenham políticas de concessão (GRANT) definidas neles. O Delta Sharing não oferece suporte ao compartilhamento de serviços de modelo, serviços de provedor de modelos, serviços MCP ou serviços de agente, independentemente da aplicação de uma política GRANT.

Mais informações

Consulte também Gerenciar privilégios no Unity Catalog.

Compute requirements​

O que é uma GRANT policy​

Exemplos de policy GRANT​

Tipos protegíveis e privilégios suportados​

Como as políticas GRANT interagem com as concessões diretas​

Criar uma política GRANT​

Editar uma política GRANT​

Excluir política de GRANT​

Mostrar políticas​

Descrever uma política​

Definições de política de informação com query Schema​

Tags de sistema em modelos de fundação em system.ai​

Cotas de política​

Registro de auditoria​

Práticas recomendadas​

Limitações​

Mais informações​