Segredos no Unity Catalog

Importante

Esse recurso está em Visualização Pública.

Esta página descreve como criar, ler, governar e gerenciar segredos no Catálogo do Unity. Um segredo do Catálogo do Unity é um objeto protegível que armazena material confidencial, como senha, token ou chave de API. Seus notebooks e tarefas podem referenciar o segredo sem expor o valor no código.

Os segredos do Unity Catalog usam o namespace de três níveis (catalog.schema.secret) e estão disponíveis em todos os espaços de trabalho vinculados a um metastore. Os privilégios do Catálogo do Unity os regem. Isso permite que você aplique o mesmo modelo de acesso e auditoria que você usa para outros ativos de dados aos seus segredos.

Note

Os segredos do Unity Catalog são distintos dos segredos do Azure Databricks no nível do espaço de trabalho, que são organizados em escopos de segredo. Use segredos do Catálogo do Unity quando quiser controlar segredos com privilégios do Catálogo do Unity e referenciá-los com o namespace de três níveis.

Como funcionam os segredos do Catálogo do Unity

Um segredo do Unity Catalog é um objeto protegível dentro de um esquema, com o nome totalmente qualificado catalog.schema.secret. Assim como outros objetos protegíveis do Unity Catalog, os segredos oferecem suporte à herança de privilégios a partir do catálogo e do esquema. Para obter mais informações sobre objetos protegíveis e herança, consulte a referência de objetos protegíveis do Catálogo do Unity.

Você pode usar um segredo do Catálogo do Unity das seguintes maneiras:

• Recupere o valor em código. Com acesso READ SECRET, os usuários podem recuperar um valor secreto em notebooks e jobs usando dbutils ou a API REST do Unity Catalog. Em seguida, eles podem usá-lo para autenticar com sistemas externos ou para criptografar e descriptografar dados.
• Referencie o valor de objetos do Catálogo do Unity. Objetos do Catálogo do Unity, como conexões do Catálogo do Unity, podem referenciar um segredo por nome para que uma integração possa usar o segredo sem conceder aos usuários acesso ao valor. Dependendo do objeto, fazer referência a um segredo requer um REFERENCE SECRET ou READ SECRET.

O Azure Databricks armazena criptografados os valores secretos do Unity Catalog e aplica o mascaramento de segredos para reduzir a exposição acidental em saídas e nos logs. Para rotacionar um segredo, atualize periodicamente seu valor na IU ou com a API REST do Unity Catalog.

Privilégios para segredos do Unity Catalog

Os privilégios a seguir governam os segredos. Você pode concedê-los no nível de catálogo, esquema ou segredo específico, e eles seguem a herança de privilégios do Unity Catalog.

Privilégio	Descrição
CREATE SECRET	Permite que um usuário crie um segredo em um esquema. Concedida no nível do catálogo ou do esquema.
READ SECRET	Permite que um usuário recupere um valor secreto.
WRITE SECRET	Permite que um usuário atualize um valor secreto.
REFERENCE SECRET	Permite que um usuário faça referência a um segredo, por exemplo, em uma conexão do Unity Catalog, sem ter acesso ao valor.

Para criar um segredo em um esquema, um usuário deve ter USE CATALOG permissão e ser proprietário do esquema ou ter CREATE SECRET e USE SCHEMA no esquema. Para saber como conceder privilégios, consulte Gerenciar privilégios no Catálogo do Unity.

Antes de começar

Para usar segredos do Catálogo do Unity, você deve atender aos seguintes requisitos:

• O workspace deve ser habilitado para o Unity Catalog. Para obter uma introdução, consulte o que é o Catálogo do Unity?.
• Você deve acessar os segredos em ambientes de computação habilitados para o Unity Catalog. Azure Databricks recomenda um dos seguintes:
  • Trabalhos e notebooks sem servidor usando o ambiente versão 4 ou superior.
  • Computação clássica no modo de acesso padrão executando o Databricks Runtime 17.3 LTS ou superior.
• Para recuperar segredos com dbutils, o recurso de computação deve estar executando o Databricks Runtime 17.3 LTS ou superior, ou o ambiente serverless versão 4 ou superior.

Criar um segredo

Criar um segredo requer que você tenha a permissão USE CATALOG e seja proprietário do esquema ou tenha CREATE SECRET e USE SCHEMA sobre o esquema. Consulte os segredos do Catálogo do Privileges for Unity.

Gerenciador de Catálogos

1. No workspace Azure Databricks, clique em Catálogo para abrir o Gerenciador de Catálogos.
2. Vá para o esquema no qual você deseja criar o segredo.
3. Clique em Criar > segredo.
4. Insira um nome e um valor. Opcionalmente, adicione um comentário e uma data de validade. Se um segredo expirar, o Gerenciador de Catálogos mostrará um aviso.
5. Clique em Criar.

API REST

Execute o seguinte comando cURL usando o endpoint /api/2.1/unity-catalog/secrets:

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_name": "main",
    "schema_name": "default",
    "name": "example_secret",
    "value": "your_secret_value",
    "comment": "your secret description"
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Ler um segredo

Para ler um valor secreto, você deve ter READ SECRET no segredo ou em um catálogo ou esquema pai.

Utilitário de segredos (dbutils.secrets)

Azure Databricks recomenda usar dbutils para ler segredos, pois aplica o mascaramento de segredos. Essa opção requer o Databricks Runtime 17.3 LTS ou superior ou o ambiente sem servidor versão 4 ou superior.

# Read a specific secret
my_secret = dbutils.secrets.get(catalog="main", schema="default", key="example_secret")

Para obter mais informações, consulte o utilitário Segredos (dbutils.secrets).

API REST

Aviso

Os valores secretos recuperados com a API REST do Catálogo do Unity não estão sujeitos à redação secreta, embora o acesso ainda seja registrado nos logs de auditoria. O Azure Databricks recomenda dbutils em vez disso.

Para retornar o valor, defina include_value=true e leia o effective_value campo na resposta:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "include_value=true" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Gerenciar permissões dos segredos

Conceda CREATE SECRET no nível do catálogo ou do esquema para controlar quem pode criar segredos. Conceda READ SECRET, WRITE SECRET ou REFERENCE SECRET no nível de catálogo, esquema ou segredo específico para controlar o acesso. A herança de privilégios se aplica. Para saber mais sobre como conceder e revogar privilégios, consulte Gerenciar privilégios no Catálogo do Unity.

Conceder a capacidade de criar segredos

Gerenciador de Catálogos

1. No Catalog Explorer, acesse o esquema.

2. Clique na guia Permissões.

3. Selecione Conceder.

4. Selecione as entidades de segurança às quais conceder acesso e selecione CREATE SECRET.

   Se um principal não tiver USE SCHEMA, um aviso solicitará que você o conceda. USE SCHEMA também é necessário para criar segredos no esquema.

5. Clique em Confirmar.

SQL

GRANT CREATE SECRET, USE SCHEMA ON SCHEMA main.default TO `user@example.com`;

API REST

Execute o seguinte comando cURL usando o endpoint /api/2.1/unity-catalog/permissions/schema/{schema_name}:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["CREATE_SECRET", "READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/schema/{schema_name}"

Conceder acesso a um segredo

Gerenciador de Catálogos

1. No Gerenciador de Catálogos, vá para o segredo e clique nele.
2. Clique na guia Permissões.
3. Selecione Conceder.
4. Selecione as entidades de segurança e os privilégios a serem concedidos e, em seguida, clique em Confirmar.

SQL

GRANT READ SECRET ON SECRET main.default.example_secret TO `user@example.com`;

API REST

Execute o seguinte comando cURL usando o endpoint /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret}:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret}"

Listar, atualizar e excluir segredos

Listar segredos

Gerenciador de Catálogos

1. No Catalog Explorer, vá para o esquema.
2. No painel Visão geral , clique em Segredos para ver todos os segredos no esquema.

Utilitário de segredos (dbutils.secrets)

# List all secrets in a schema
all_secrets = dbutils.secrets.list(catalog="main", schema="default")

API REST

As solicitações de listagem usam page_size para controlar o número de resultados:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Atualizar um segredo

Para atualizar um valor secreto, você deve ter WRITE SECRET no segredo.

Gerenciador de Catálogos

1. No Gerenciador de Catálogos, vá para o esquema e clique em Segredos no painel Visão Geral .
2. Clique no segredo que deseja atualizar.
3. No canto superior direito, clique no menu kebab (pontos verticais) e selecione Editar.
4. Insira um novo valor ou data de validade e clique em Confirmar.

API REST

As solicitações de atualização exigem o update_mask parâmetro. Somente os campos incluídos em ambos update_mask e no corpo da solicitação são atualizados:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value": "new_secret_value"}' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret?update_mask=*"

Excluir um segredo

Gerenciador de Catálogos

1. No Gerenciador de Catálogos, vá para o esquema e clique em Segredos no painel Visão Geral .
2. Clique no segredo que deseja excluir.
3. No canto superior direito, clique no menu kebab (pontos verticais) e selecione Excluir.
4. Insira o nome completo do segredo e clique em Excluir.

API REST

curl -X DELETE \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Eventos de auditoria para segredos do Catálogo do Unity

A tabela do sistema system.access.audit registra eventos relacionados aos segredos do Unity Catalog. Por exemplo, para ver todos os eventos secretos de um usuário em uma data específica, execute a seguinte consulta:

SELECT * FROM system.access.audit
WHERE
  user_identity.email = "user@example.com"
  AND event_date = "2026-02-20"
  AND service_name = "unityCatalog"
  AND action_name LIKE "%Secret%";

Para obter mais informações sobre logs de auditoria, consulte a referência da tabela do sistema de logs de auditoria.

Criptografar valores secretos com chaves gerenciadas pelo cliente

Por padrão, Azure Databricks criptografa valores secretos com chaves gerenciadas pelo Databricks. Em vez disso, você pode usar CMK (chaves gerenciadas pelo cliente). Se você habilitar o recurso de catálogo gerenciado criptografado por CMK e anexar uma configuração de CMK à sua conta, Azure Databricks usará o CMK para criptografar valores secretos. Para obter mais informações, consulte chaves gerenciadas pelo cliente para o Catálogo do Unity.

Limitations

Os segredos do Catálogo do Unity têm as seguintes limitações:

• Sem armazéns SQL. Não há suporte para segredos do Unity Catalog em warehouses SQL. Eles exigem o Databricks Runtime 17.3 LTS ou superior na computação habilitada para Catálogo do Unity ou sem servidor.
• Nenhuma descoberta global. Os segredos do Catálogo do Unity não aparecem na pesquisa global.
• Sem suporte à permissão BROWSE. BROWSE em um catálogo não se aplica aos segredos do Unity Catalog. Para tornar um segredo localizável, conceda READ SECRET ou REFERENCE SECRET no segredo específico ou no esquema dele.
• Nenhum script de inicialização. Você não pode usar segredos do Catálogo do Unity em scripts de inicialização globais ou de cluster. O Azure Databricks recomenda usar recursos dedicados em vez de scripts de inicialização, sempre que possível.
• Nenhum esquema de informações. As tabelas de esquema de informações para segredos ainda não estão disponíveis. Use o Gerenciador de Catálogos ou a API REST para descoberta.
• dbutils escopo de tempo de execução. dbutils há suporte para recuperação em notebooks e trabalhos com suporte do Databricks Runtime. Não há suporte para contextos que não sejam do Databricks Runtime, como desenvolvimento remoto ou modos de execução de JAR compilado.
• Escopo da API OAuth. A API de segredos do Catálogo do Unity só pode ser acessada com o escopo da API OAuth unity-catalog . Use o escopo de API secrets somente para segredos do Azure Databricks no nível do workspace.
• Limites de quota. Até 100 segredos por esquema e 1.000 por metastore.