Segredos no Unity Catalog

Importante

Este recurso está no Public Preview.

Esta página descreve como criar, ler, governar e gerir segredos no Unity Catalog. Um segredo do Catálogo Unity é um objeto seguro que armazena material sensível, como uma palavra-passe, token ou chave API. Os teus cadernos e trabalhos podem referenciar o segredo sem expor o valor do código.

Os segredos do Catálogo Unity utilizam o namespace de três níveis (catalog.schema.secret) e estão disponíveis em todos os espaços de trabalho ligados a uma metastore. Os privilégios do Catálogo Unity regem-nos. Isto permite-lhe aplicar o mesmo modelo de acesso e auditoria que utiliza para outros ativos de dados aos seus segredos.

Observação

Os segredos do Unity Catalog distinguem-se dos segredos do Azure Databricks ao nível do espaço de trabalho, que estão organizados em escopos secretos. Usa os segredos do Unity Catalog quando quiseres governar segredos com privilégios do Unity Catalog e referencia-os com o namespace de três níveis.

Como funcionam os segredos do Catálogo Unity

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

Pode usar um segredo do Unity Catalog das seguintes formas:

• Recuperar o valor em código. Com acesso READ SECRET, os utilizadores podem recuperar um segredo em notebooks e jobs usando dbutils ou a API REST do Unity Catalog. Podem então usá-lo para autenticar com sistemas externos ou para encriptar e desencriptar dados.
• Referenciar o valor dos objetos do Catálogo Unity. Os objetos do Unity Catalog, como as ligações do Unity Catalog, podem referenciar um segredo pelo nome para que uma integração possa usar o segredo sem conceder aos utilizadores acesso ao valor. Dependendo do objeto, fazer referência a um segredo requer REFERENCE SECRET ou READ SECRET.

O Azure Databricks armazena os valores secretos do Unity Catalog encriptados e aplica a ocultação de segredos para reduzir a exposição acidental em saídas e registos. Para fazer a rotação de um segredo, atualize periodicamente o respetivo valor na interface de utilizador ou com a API REST do Unity Catalog.

Privilégios para segredos do Catálogo Unity

Os seguintes privilégios regem os segredos. Pode concedê-los ao nível do catálogo, esquema ou segredo individual, e eles seguem a herança de privilégios do Unity Catalog.

Privilégio	Description
CREATE SECRET	Permite ao utilizador criar um segredo num esquema. Concedido ao nível do catálogo ou esquema.
READ SECRET	Permite ao utilizador recuperar um valor secreto.
WRITE SECRET	Permite ao utilizador atualizar um valor secreto.
REFERENCE SECRET	Permite a um utilizador referenciar um segredo, por exemplo, a partir de uma ligação ao Unity Catalog, sem acesso ao valor.

Para criar um segredo num esquema, um utilizador tem de ter a permissão USE CATALOG e ser proprietário do esquema ou ter CREATE SECRET e USE SCHEMA no esquema. Para saber como conceder privilégios, consulte Gerir privilégios no Catálogo Unity.

Antes de começares

Para usar os segredos do Unity Catalog, deve cumprir os seguintes requisitos:

• O espaço de trabalho deve estar habilitado para o Catálogo Unity. Para uma introdução, veja O que é o Catálogo Unity?.
• Deve aceder a segredos de computação habilitada pelo Unity Catalog. O Azure Databricks recomenda um dos seguintes:
  • Trabalhos e notebooks serverless que usam o ambiente versão 4 ou superior.
  • Computação clássica em modo de acesso padrão com Databricks Runtime 17.3 LTS ou posterior.
• Para recuperar segredos com dbutils, a computação tem de ser executada no Databricks Runtime 17.3 LTS ou superior, ou num ambiente serverless de versão 4 ou superior.

Criar um segredo

A criação de um segredo requer que tenha a permissão USE CATALOG e seja proprietário do esquema, ou que tenha CREATE SECRET e USE SCHEMA no esquema. Consulte os privilégios dos segredos do Unity Catalog.

Explorador de Catálogos

1. No seu espaço de trabalho Azure Databricks, clique em Catalog para abrir o Catalog Explorer.
2. Vai ao esquema onde queres criar o segredo.
3. Clique em Criar > segredo.
4. Insira um nome e um valor. Opcionalmente, adiciona um comentário e uma data de validade. Se um segredo expirar, o Explorador de Catálogos mostra um aviso.
5. Clique em Criar.

API REST

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

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 o valor de um segredo, tem de ter READ SECRET no segredo ou num catálogo ou esquema superior.

Utilitário de Segredos (dbutils.secrets)

O Azure Databricks recomenda a utilização de dbutils para ler segredos, porque aplica a ocultação de segredos. Esta opção requer o Databricks Runtime 17.3 LTS ou superior, ou um ambiente serverless na versão 4 ou superior.

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

Para mais informações, consulte a utilidade Secrets (dbutils.secrets).

API REST

Warning

Os valores secretos recuperados com a API REST do Unity Catalog não estão sujeitos a redação secreta, embora o acesso continue a ser registado nos registos de auditoria. Azure Databricks recomenda dbutils em vez disso.

Para devolver 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 sobre segredos

Conceda permissões CREATE SECRET ao nível do catálogo ou do esquema para controlar quem pode criar segredos. Conceda READ SECRET, WRITE SECRET, ou REFERENCE SECRET ao nível de catálogo, esquema ou segredo individual para controlar o acesso. Aplica-se a herança de privilégios. Para saber mais sobre como conceder e revogar privilégios, consulte Gerir privilégios no Unity Catalog.

Conceder a capacidade de criar segredos

Explorador de Catálogos

1. No Explorador de Catálogos, vai ao esquema.

2. Clique na guia Permissões .

3. Clique em Conceder.

4. Selecione os princípios a conceder acesso e depois selecione CRIAR SEGREDO.

   Se um diretor não tiver USE SCHEMA, um aviso incentiva-o a concedê-lo. USE SCHEMA também é necessário para criar credenciais secretas 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 /api/2.1/unity-catalog/permissions/schema/{schema_name} endpoint:

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

Explorador de Catálogos

1. No Explorador de Catálogos, aceda ao segredo e clique nele.
2. Clique na guia Permissões .
3. Clique em Conceder.
4. Selecione os princípios e os privilégios a conceder, depois 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 /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} endpoint:

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 eliminar segredos

Listar segredos

Explorador de Catálogos

1. No Explorador de Catálogos, vai ao esquema.
2. No painel de 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

Os pedidos 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 o valor de um segredo, tem de ter WRITE SECRET no segredo.

Explorador de Catálogos

1. No Explorador de Catálogos, vai ao esquema e clica em Segredos no painel de Visão Geral .
2. Clique no segredo para atualizar.
3. No canto superior direito, clique no menu do kebab (pontos verticais) e selecione Editar.
4. Introduza um novo valor ou data de validade, depois clique em Confirmar.

API REST

Os pedidos de atualização requerem o update_mask parâmetro. Apenas os campos incluídos em ambos update_mask e o corpo do pedido 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=*"

Eliminar um segredo

Explorador de Catálogos

1. No Explorador de Catálogos, vai ao esquema e clica em Segredos no painel de Visão Geral .
2. Clica no segredo para apagar.
3. No canto superior direito, clique no menu do kebab (pontos verticais) e selecione Apagar.
4. Introduza o nome completo do segredo e depois clique em Apagar.

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 Unity

A system.access.audit tabela do sistema regista eventos relacionados com os segredos do Catálogo Unity. Por exemplo, para ver todos os eventos secretos de um utilizador numa 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 mais informações sobre registos de auditoria, consulte a referência da tabela do sistema de registos de auditoria.

Encriptar valores secretos com chaves geridas pelo cliente

Por defeito, o Azure Databricks encripta valores secretos com chaves geridas pelo Databricks. Em vez disso, pode usar chaves geridas pelo cliente (CMK). Se ativar a funcionalidade de catálogo gerido encriptado com CMK e anexar uma configuração CMK à sua conta, o Azure Databricks usa o CMK para encriptar valores secretos. Para mais informações, consulte Chaves geridas pelo cliente para o Catálogo Unity.

Limitações

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

• Sem armazéns SQL. Os segredos do Unity Catalog não são suportados em armazéns SQL. Exigem Databricks Runtime 17.3 LTS ou superior em computação habilitada pelo Unity Catalog, ou serverless.
• Nenhuma descoberta global. Os segredos do Unity Catalog não aparecem na pesquisa global.
• Sem suporte para permissões de navegação. BROWSE num catálogo não se aplica aos segredos do Unity Catalog. Para tornar um segredo detetável, conceda READ SECRET ou REFERENCE SECRET sobre o segredo específico ou o respetivo esquema.
• Sem scripts de init. Não é possível utilizar segredos do Unity Catalog nos scripts globais ou nos scripts de inicialização do cluster. O Azure Databricks recomenda usar funcionalidades dedicadas em vez de scripts de init sempre que possível.
• Sem esquema de informação. As tabelas de esquema de informação para segredos ainda não estão disponíveis. Use o Explorador de Catálogos ou a API REST para descoberta.
• dbutils âmbito de tempo de execução. dbutils A recuperação é suportada em notebooks e tarefas baseados no Databricks Runtime. Contextos de execução não-Databricks, como desenvolvimento remoto ou modos de execução JAR compilados, não são suportados.
• Escopo OAuth API. A API de segredos do Unity Catalog só é acessível com o âmbito da unity-catalog OAuth API. Utilize o âmbito da API secrets apenas para segredos do Azure Databricks ao nível do espaço de trabalho.
• Limites das quotas. Até 100 segredos por esquema e 1.000 por metastore.