Segredos no Unity Catalog

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 fazer referência ao 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.

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 trabalhos 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.
• Use o valor em uma UDF Python ou Scala com escopo de sessão. Consulte UDFs com escopo de sessão.
• Use o valor em um UDF Python do Unity Catalog. Um escalar ou UDF Batch declara cada segredo em sua SECRETS cláusula. Veja UDFs em Python.
• Use o valor em um UDF Scala do Unity Catalog. Uma UDF escalar declara cada segredo em sua cláusula SECRETS. Veja UDFs em Scala.

Para requisitos e comportamentos de permissões entre os tipos de UDF, veja requisitos e permissões do UDF.

UDFs podem usar segredos gerenciados pelo Azure Databricks ou segredos respaldados por um gerenciador externo de segredos. Veja os segredos externos no Unity Catalog.

Requisitos e permissões da UDF

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

UDFs com escopo de sessão

Uma UDF em Python com escopo da sessão recupera um segredo com databricks.secrets.get(), e uma UDF em Scala com escopo da sessão recupera um segredo 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:

• Na computação serverless, o notebook ou a sessão de trabalho deve usar a versão 6 ou superior do ambiente para UDFs em Python e Scala.
• No compute clássico, UDFs de Python com escopo de sessão exigem o Databricks Runtime 19 ou superior no modo de acesso padrão ou dedicado.
• Na computação clássica, UDFs em Scala com escopo de sessão exigem o Databricks Runtime 19 ou acima no modo de acesso padrão.

UDFs do Unity Catalog

UDFs escalares e em lote do Unity Catalog para Python e UDFs escalares do Unity Catalog para Scala declaram segredos na cláusula SECRETS e devem definir explicitamente environment_version como 6 ou superior. Eles oferecem suporte à computação sem servidor, a warehouses SQL sem servidor e à computação clássica executando o Databricks Runtime 19 ou superior com modo de acesso padrão.

Os warehouses Pro SQL oferecem suporte a UDFs Python escalares e em lote do Unity Catalog que usam segredos. As UDFs em Scala do Unity Catalog que usam segredos não têm suporte em warehouses SQL Pro.

Para criar ou substituir uma UDF que declara um segredo, a entidade principal que executa a instrução deve ter READ SECRET no segredo e USE CATALOG e USE SCHEMA em seu catálogo e esquema pai. Em tempo de execução, o UDF usa as permissões do dono 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.

Use UDFs habilitadas para segredos em máscaras de coluna em computação dedicada

Você não pode chamar uma UDF do Unity Catalog em Python ou Scala que use a cláusula SECRETS diretamente na computação com modo de acesso dedicado. No entanto, você pode criar uma função SQL do Unity Catalog que chama a UDF com suporte a segredos e usar a função SQL como uma máscara de coluna para controle de acesso baseado em atributos (ABAC). Quando uma consulta é executada em computação dedicada, o Azure Databricks delega a aplicação da máscara de coluna à computação sem servidor. Essa exceção se aplica apenas ao aplicar a máscara de coluna; ela não permite a invocação direta do UDF habilitado por segredo em computação dedicada. Veja Versões de computação não suportadas.

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.

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.

Requirements

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 posterior.
  • 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 posterior, ou o ambiente sem servidor versão 4 ou posterior.

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)

O Azure Databricks recomenda 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

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"

Use um segredo no seu código

Depois de ler um segredo do Unity Catalog com dbutils.secrets.get, passe o valor retornado para o código da sua aplicação. dbutils oculta o valor na saída da célula e nos logs, para que você possa usá-lo sem expô-lo.

O exemplo a seguir 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 a seguir recupera um valor secreto e o passa para dbutils.credentials.getServiceCredentialsProvider configurar uma sessão boto3 para o AWS SDK. O nome de uma credencial de serviço não é, por si só, sensível; portanto, este exemplo armazena esse nome em um segredo apenas para ilustrar o encadeamento de um valor secreto recuperado em outra chamada ao SDK. Para mais informações sobre credenciais de serviço, veja Usar credenciais de serviço do Catálogo Unity para se conectar a serviços em nuvem 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 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 uma entidade de segurança não tiver USE SCHEMA, um aviso solicitará que você a 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 Catalog Explorer, 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, acesse 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

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 próxima página, passe o next_page_token valor da resposta anterior como parâmetro page_token :

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 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 Unity Catalog

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.

Armazene segredos com um gerenciador externo de segredos

Em vez do Azure Databricks armazenar valores secretos, você pode fazer backup de um esquema com um gerenciador de segredos externo para que os valores permaneçam no seu gerenciador de segredos na nuvem enquanto permanecem governáveis no Unity Catalog. AWS Secrets Manager na AWS e Azure Key Vault no Azure são suportados. Para saber como funcionam segredos externos, veja Segredos externos no Catálogo Unity. Para respaldar um esquema com um gerenciador de segredos externo, veja Configurar segredos externos no Unity Catalog.

Limitations

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

• Acesso direto limitado a partir de SQL warehouses. Você não pode recuperar segredos do Unity Catalog diretamente de warehouses SQL. UDFs Python do Catálogo do Unity escalares e em lote podem acessar segredos declarados em suas cláusulas SECRETS em data warehouses SQL profissionais e sem servidor. UDFs Scala escalares do Unity Catalog podem acessar segredos declarados somente em warehouses SQL sem servidor.
• Não há invocação direta SECRETS de UDF em computação dedicada. Você não pode invocar diretamente UDFs Python do Catálogo do Unity escalares ou em lote, ou UDFs Scala do Catálogo do Unity escalares que usam a cláusula SECRETS em computação no modo de acesso dedicado. Para a exceção de máscara de coluna, consulte Usar UDFs habilitadas por segredo em máscaras de coluna na computação dedicada.
• 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.
• Escopo do runtime dbutils. A recuperação dbutils é aceita 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 Unity Catalog 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.