Segredos no Unity Catalog

info

Visualização

Este recurso está em Pré-visualização Pública.

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.
• Referencie o valor de objetos do Unity Catalog. Objetos do Unity Catalog, como conexões do Unity Catalog, podem referenciar um segredo pelo nome para que uma integração possa usar o segredo sem conceder acesso aos usuários ao valor. Dependendo do objeto, referenciar um segredo requer REFERENCE SECRET ou READ SECRET.

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 referencie um segredo, por exemplo, a partir de uma conexão do Unity Catalog, 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 referencie um segredo, por exemplo, a partir de uma conexão do Unity Catalog, 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.

Antes de começar

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"

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

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

Bash

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.

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:

• **Nenhum SQL warehouse.** Os segredos do Unity Catalog não são suportados em SQL warehouses. Eles exigem Databricks Runtime 17.3 LTS ou acima em compute habilitado para Unity Catalog, ou Serverless.
• 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.