Segredos no Unity Catalog

Esta página descreve como criar, ler, governar e gerenciar segredos no Unity Catalog. Um segredo do Unity Catalog é um objeto protegível que armazena material confidencial, como uma senha, token ou chave de API. Seus Notebooks e Jobs 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 Workspaces anexados a um metastore. Os privilégios do Unity Catalog os governam. Isso permite aplicar o mesmo modelo de acesso e auditoria que você usa para outros ativos de dados aos seus segredos.

nota

Os segredos do Unity Catalog são distintos dos segredos do Databricks em nível de Workspace, que são organizados em Secret Scopes. Utilize os segredos do Unity Catalog quando desejar governar segredos com privilégios do Unity Catalog e referenciá-los com o namespace de três níveis.

Como funcionam os segredos do Unity Catalog

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

Você pode usar um segredo do Unity Catalog das seguintes maneiras:

• Recupere o valor no código. Com acesso READ SECRET, os usuários podem recuperar um valor de segredo de Notebooks e Jobs usando dbutils ou a API REST do Unity Catalog. Eles podem então 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 uma UDF Python do Unity Catalog. Uma UDF escalar ou de lotes declara cada segredo em sua cláusula SECRETS. Consulte UDFs Python.
• Use o valor em uma UDF Scala do Unity Catalog. Uma UDF escalar declara cada segredo em sua cláusula SECRETS. Consulte UDFs Scala.

Para ver os requisitos e o comportamento de permissão entre os tipos de UDF, consulte Requisitos e permissões de UDF.

Requisitos e permissões de UDF

O comportamento de requisitos e permissões difere entre UDFs com escopo de sessão e do Unity Catalog.

UDFs com escopo de sessão

Um UDF Python com escopo de sessão recupera um segredo com databricks.secrets.get(), e um UDF Scala com escopo de sessão recupera um com com.databricks.Secrets.get(). O acesso a segredos usa as permissões do chamador.

Os requisitos de compute para acesso a secrets dependem da linguagem da UDF:

• Em compute serverless, a sessão do notebook ou job deve usar a versão de ambiente 6 ou acima para UDFs Python e Scala.
• No compute clássico, as UDFs Python com escopo de sessão exigem o Databricks Runtime 19 ou acima no modo de acesso padrão ou dedicado.
• Em compute clássico, as UDFs Scala com escopo de sessão exigem o Databricks Runtime 19 ou acima com o modo de acesso padrão.

UDFs do Unity Catalog

UDFs Python do Unity Catalog escalares e em lotes e UDFs Scala do Unity Catalog escalares declaram segredos na cláusula SECRETS e devem definir explicitamente environment_version como 6 ou acima. Elas dão suporte a compute Serverless, SQL Warehouse Serverless e compute clássico executando Databricks Runtime 19 ou acima com modo de acesso padrão.

Os Pro SQL Warehouse dão suporte a UDFs Python escalares e em lotes do Unity Catalog que usam segredos. As UDFs Scala do Unity Catalog que usam segredos não são compatíveis com os pro SQL warehouse.

Para criar ou substituir um UDF que declara um segredo, o 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 runtime, o UDF usa as permissões do proprietário atual da função. Os chamadores precisam dos privilégios de função usual, 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 falhará.

Usar UDFs habilitadas para segredo em máscaras de coluna em compute dedicado

Não é possível invocar uma UDF Python ou Scala do Unity Catalog que use a cláusula SECRETS diretamente em compute com modo de acesso dedicado. No entanto, você pode criar uma função SQL do Unity Catalog que chame a UDF habilitada para segredos e usar a função SQL como uma máscara de coluna de controle de acesso baseado em atributos (ABAC). Quando uma query é executada em compute dedicado, o Databricks delega a imposição da máscara de coluna ao compute serverless. Esta exceção se aplica apenas durante a imposição da máscara de coluna; ela não ativa a invocação direta da UDF habilitada para segredos em compute dedicado. Consulte Versões de compute não compatíveis.

atenção

Use valores secretos apenas dentro da implementação da UDF. Não retorne valores secretos nem os inclua nos resultados da UDF. A redação de segredos ajuda a reduzir a exposição acidental em erros e logs, mas não impede que o código da UDF exponha material secreto em resultados de query.

O Databricks armazena valores secretos do Unity Catalog criptografados e aplica a redação secreta para reduzir a exposição acidental em saídas e logs. Para rotacionar um segredo, atualize periodicamente seu valor na interface do usuário ou com a API REST do Unity Catalog.

Privilégios para segredos do Unity Catalog

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

Privilégio	Descrição
CREATE SECRET	Permite que o usuário crie um segredo em um esquema. Concedido 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 sem acesso ao valor.

Privilégio	Descrição
CREATE SECRET	Permite que o usuário crie um segredo em um esquema. Concedido 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 sem acesso ao valor.

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

Requirements

Para usar segredos do Unity Catalog, você deve atender aos seguintes requisitos:

• O Workspace deve estar habilitado para o Unity Catalog. Para uma introdução, consulte O que é o Unity Catalog?.

• É preciso acessar segredos de um ambiente de compute habilitado para o Unity Catalog. A Databricks recomenda uma das seguintes opções:

  • Jobs e notebooks Serverless que usam a versão 4 ou acima do ambiente.
  • Compute clássico em modo de acesso padrão executando o Databricks Runtime 17.3 LTS ou acima.

• Para recuperar segredos com dbutils, o compute deve executar o Databricks Runtime 17.3 LTS ou acima, ou a versão 4 ou acima do ambiente Serverless.

Crie um segredo

A criação de um segredo exige que você tenha permissão USE CATALOG e seja proprietário do esquema ou tenha CREATE SECRET e USE SCHEMA no esquema. Consulte Privilégios para segredos do Unity Catalog.

Catalog Explorer

1. No seu Workspace do Databricks, clique em Catálogo para abrir o Catalog Explorer.
2. Vá para o esquema onde 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 expiração**. Se um segredo expirar, o Catalog Explorer exibirá um aviso.
5. Clique em Criar .

REST API

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

Bash

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 de segredo, você deve ter READ SECRET no segredo ou em um catálogo ou esquema pai.

Secrets utility (dbutils.secrets)

O Databricks recomenda dbutils para ler segredos, porque ele aplica a redação secreta. Esta opção requer Databricks Runtime 17.3 LTS ou superior, ou a versão 4 do ambiente Serverless ou superior.

Python

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

Para mais informações, consulte Utilitário de segredos (dbutils.secrets).

REST API

atenção

Os valores secretos recuperados com a API REST do Unity Catalog não estão sujeitos à redação de segredos, embora o acesso ainda seja registrado nos Logs de auditoria. A Databricks recomenda dbutils em vez disso.

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

Bash

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

Após ler um segredo do Unity Catalog com dbutils.secrets.get, passe o valor retornado para o código do seu aplicativo. dbutils edita 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 do portador para chamar uma API externa:

Python

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 de segredo e o passa para dbutils.credentials.getServiceCredentialsProvider para configurar uma sessão boto3 para o AWS SDK. Um nome de credencial de serviço não é, por si só, confidencial; portanto, este exemplo armazena um em um segredo apenas para ilustrar o encadeamento de um valor de segredo recuperado em outra chamada de SDK. Para obter mais informações sobre credenciais de serviço, consulte Usar credenciais de serviço do Unity Catalog para conectar a serviços de cloud externos.

Python

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

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

Conceder a capacidade de criar segredos

Catalog Explorer

1. No Catalog Explorer, acesse o esquema.

2. Clique na guia Permissões .

3. Clique em Conceder .

4. Selecione os principais aos quais conceder acesso e, em seguida, selecione **CRIAR SEGREDO**.

   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

SQL

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

REST API

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

Bash

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

Catalog Explorer

1. No Catalog Explorer, vá para o segredo e clique nele.
2. Clique na guia Permissões .
3. Clique em Conceder .
4. Selecione as entidades de segurança e os privilégios a conceder, então clique em Confirmar .

SQL

SQL

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

REST API

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

Bash

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

Catalog Explorer

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

Secrets utility (dbutils.secrets)

Python

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

REST API

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

Bash

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 valor next_page_token da resposta anterior como o parâmetro page_token:

Bash

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.

Catalog Explorer

1. No Catalog Explorer, vá para o esquema e clique em Segredos no painel Visão geral .
2. Clique no segredo para atualizar.
3. No canto superior direito, clique no menu kebab (pontos verticais) e selecione Editar .
4. Insira um novo valor ou data de expiração e clique em Confirmar .

REST API

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

Bash

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

Catalog Explorer

1. No Catalog Explorer, vá para o esquema e clique em Segredos no painel Visão geral .
2. Clique no segredo para excluir.
3. No canto superior direito, clique no menu kebab (três pontos verticais) e selecione Excluir .
4. Insira o nome completo do segredo e clique em Excluir.

REST API

Bash

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 de sistema system.access.audit registra eventos relacionados a segredos do Unity Catalog. Por exemplo, para ver todos os eventos de segredo de um usuário em uma data específica, execute a seguinte query:

SQL

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 logs de auditoria, consulte Referência da tabela do sistema de logs de auditoria.

Criptografar valores secretos com chaves gerenciadas pelo cliente

Por default, a Databricks criptografa valores secretos com chaves gerenciadas pela Databricks. Você pode, em vez disso, usar chaves gerenciadas pelo cliente (CMK). Se você habilitar o recurso de catálogo gerenciado e criptografado por CMK e anexar uma configuração de CMK à sua account, a Databricks usará o CMK para criptografar valores secretos. Para obter mais informações, consulte Chaves gerenciadas pelo cliente para o Unity Catalog.

Limitações

Os segredos do Unity Catalog têm as seguintes limitações:

• Acesso direto limitado de SQL warehouses. Não é possível recuperar secrets do Unity Catalog diretamente dos SQL warehouses. UDFs Python escalares e de lotes do Unity Catalog podem acessar secrets declarados em suas cláusulas SECRETS em SQL Warehouse pro e Serverless. UDFs Scala escalares do Unity Catalog podem acessar secrets declarados somente em SQL warehouses serverless.
• Nenhuma invocação direta de UDF do SECRETS em compute dedicado. Não é possível invocar diretamente UDFs Python escalares ou de lotes do Unity Catalog ou UDFs Scala escalares do Unity Catalog que usam a cláusula SECRETS em compute de modo de acesso dedicado. Para obter informações sobre a exceção de máscara de coluna, consulte Usar UDFs habilitadas para segredo em máscaras de coluna em compute dedicado.
• Nenhuma descoberta global. Os segredos do Unity Catalog não aparecem na busca global.
• **Sem suporte para permissão BROWSE.** BROWSE em um catálogo não se aplica aos segredos do Unity Catalog. Para tornar um segredo detectável, conceda READ SECRET ou REFERENCE SECRET no segredo individual ou em seu esquema.
• Nenhum init script. Não é possível usar segredos do Unity Catalog em init scripts globais ou de cluster. O Databricks recomenda o uso de recursos dedicados em vez de init scripts sempre que possível.
• Nenhum esquema de informação. As tabelas do esquema de informação para segredos ainda não estão disponíveis. Use o Catalog Explorer ou a API REST para descoberta.
• Escopo de Runtimedbutils. A recuperação dbutils é compatível com Notebooks e Jobs compatíveis com o Databricks Runtime. Contextos que não são do Databricks Runtime, como desenvolvimento remoto ou modos de execução de JAR compilados, não têm suporte.
• **Escopo de API do OAuth.** A API de segredos do Unity Catalog é acessível somente com o escopo de API unity-catalog do OAuth. Use o escopo de API secrets somente para segredos da Databricks em nível de workspace.
• Limites de cota. Até 100 segredos por esquema e 1.000 por metastore.