Segredos no Unity Catalog

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.

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.
• Utilize o valor numa UDF em Python ou Scala com âmbito de sessão. Ver UDFs com âmbito de sessão.
• Utilize o valor numa UDF Python do Unity Catalog. Uma UDF escalar ou em lote declara cada segredo na cláusula SECRETS. Veja UDFs em Python.
• Use o valor num UDF Scala do Unity Catalog. Uma UDF escalar declara cada segredo na cláusula SECRETS. Consulte UDFs em Scala.

Para requisitos e comportamento de permissões entre os tipos de UDF, consulte requisitos e permissões UDF.

Os UDFs podem usar segredos geridos pelo Azure Databricks ou segredos apoiados por um gestor de segredos externo. Ver Segredos Externos no Catálogo Unity.

Requisitos e permissões da UDF

Os requisitos e o comportamento de permissões diferem entre os UDFs com âmbito de sessão e os UDFs do Unity Catalog.

UDFs com âmbito de sessão

Uma UDF de Python ao nível da sessão recupera um segredo com databricks.secrets.get(), e uma UDF de Scala ao nível da sessão recupera outro com com.databricks.Secrets.get(). O acesso secreto utiliza as permissões do chamador.

Os requisitos de computação para acesso secreto dependem da linguagem UDF:

• Em computação serverless, o notebook ou a sessão de tarefa tem de utilizar a versão 6 ou superior do ambiente para UDFs de Python e Scala.
• Em computação clássica, as UDFs de Python com âmbito ao nível da sessão requerem o Databricks Runtime 19 ou superior nos modos de acesso padrão ou dedicado.
• Na computação clássica, as UDFs de Scala com âmbito de sessão requerem o Databricks Runtime 19 ou superior com o modo de acesso padrão.

UDFs do Catálogo Unity

As UDFs escalares e em lote de Python do Unity Catalog e as UDFs escalares de Scala do Unity Catalog declaram segredos na cláusula SECRETS e têm de definir explicitamente environment_version para 6 ou superior. Suportam computação serverless, armazéns SQL serverless e computação clássica com Databricks Runtime 19 ou superior em modo de acesso padrão.

Os SQL warehouses Pro suportam UDFs Python escalares e Batch do Unity Catalog que utilizam segredos. As UDFs em Scala do Unity Catalog que usam segredos não são suportadas em SQL warehouses Pro.

Para criar ou substituir uma UDF que declara um segredo, a entidade que executa a instrução tem de ter READ SECRET no segredo e USE CATALOG e USE SCHEMA no catálogo e esquema superiores. Em tempo de execução, o UDF utiliza as permissões do proprietário atual da função. Os chamadores precisam dos privilégios funcionais habituais, incluindo EXECUTE, mas não precisam de acesso direto aos segredos declarados. Se o proprietário da função perder a permissão para ler um segredo declarado, o UDF falha.

Utilize UDFs com suporte para segredos em máscaras de coluna na computação dedicada

Não é possível invocar diretamente, na computação com modo de acesso dedicado, uma UDF de Python ou Scala do Unity Catalog que utilize a cláusula SECRETS. No entanto, pode criar uma função SQL do Unity Catalog que chama o UDF habilitado por segredos e usar a função SQL como uma máscara de coluna de controlo de acesso baseada em atributos (ABAC). Quando uma consulta é executada em processamento dedicado, o Azure Databricks delega a aplicação da máscara de coluna ao processamento sem servidor. Esta exceção aplica-se apenas ao aplicar a máscara de coluna; não permite a invocação direta do UDF habilitado por segredo em computação dedicada. Ver Versões de computação não suportadas.

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.

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.

Requirements

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

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"

Use um segredo no seu código

Depois de ler um segredo do Catálogo Unity com dbutils.secrets.get, passe o valor devolvido para o seu código de aplicação. dbutils oculta o valor na saída da célula e nos registos, para que o possas usar sem o expor.

O exemplo seguinte usa um segredo como token portador para chamar uma API externa:

import requests

api_key = dbutils.secrets.get(catalog="main", schema="default", key="service_api_key")

response = requests.get(
    "https://api.example.com/v1/resource",
    headers={"Authorization": f"Bearer {api_key}"},
)
response.raise_for_status()

O exemplo seguinte recupera um valor secreto e passa-o para dbutils.credentials.getServiceCredentialsProvider configurar uma sessão boto3 para o AWS SDK. Um nome de credencial de serviço não é, por si só, sensível, pelo que este exemplo armazena um nome de credencial num segredo apenas para ilustrar como encadear um valor secreto recuperado noutra chamada ao SDK. Para mais informações sobre credenciais de serviço, consulte Usar credenciais de serviço do Catálogo Unity para se ligar a serviços na cloud externos.

import boto3

credential_name = dbutils.secrets.get(catalog="main", schema="default", key="service_credential_name")

boto3_session = boto3.Session(
    botocore_session=dbutils.credentials.getServiceCredentialsProvider(credential_name),
    region_name="your-aws-region",
)
sm = boto3_session.client("secretsmanager")

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

Use page_size para controlar o número de resultados por página. Se houver mais resultados disponíveis, a resposta inclui um next_page_token:

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

Para recuperar a página seguinte, passe o next_page_token valor da resposta anterior como page_token parâmetro:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  --data-urlencode "page_token=<next_page_token>" \
  "$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.

Utilizar um gestor de segredos externo para gerir segredos

Em vez de o Azure Databricks armazenar valores secretos, pode fazer backup de um esquema com um gestor de segredos externo para que os valores fiquem no seu gestor de segredos na cloud, mantendo-se governáveis no Unity Catalog. O AWS Secrets Manager na AWS e o Azure Key Vault no Azure são suportados. Para saber como funcionam os segredos externos, veja Segredos externos no Catálogo Unity. Para suportar um esquema com um gestor de segredos externo, consulte Configurar segredos externos no Unity Catalog.

Limitações

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

• Acesso direto limitado a partir de armazéns SQL. Não podes recuperar os segredos do Unity Catalog diretamente dos warehouses SQL. As UDFs Python escalares e em lote do Unity Catalog podem aceder a segredos declarados nas suas cláusulas SECRETS em armazéns de SQL pro e serverless. As UDFs Scala escalares do Unity Catalog só podem aceder a segredos definidos em SQL warehouses sem servidor.
• Não há invocação direta SECRETS do UDF em computação dedicada. Não pode invocar diretamente UDFs Python escalares ou em lote do Unity Catalog, nem UDFs Scala escalares do Unity Catalog que utilizem a cláusula SECRETS, em computação com modo de acesso dedicado. Para a exceção de máscaras de coluna, veja Utilizar UDFs com segredos ativados em máscaras de coluna na computação dedicada.
• 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.