Pular para o conteúdo principal

Segredos no Unity Catalog

Um segredo do Unity Catalog é um objeto protegível que armazena uma credencial sensível, como uma senha, tokens ou key de API. Os segredos usam o namespace de três níveis (catalog.schema.secret) e estão disponíveis em todos os Workspace anexados ao metastore.

Você governa secrets com os mesmos privilégios do Unity Catalog que seus outros ativos de dados, até o secret individual. Os usuários podem navegar em um secret sem poder lê-lo ou usá-lo, você pode criptografar valores de secret com sua própria key, e os logs de auditoria registram cada leitura ou alteração.

Requirements​

Crie um segredo​

Segredos vivem em schemas. Crie segredos em um schema que apenas os principals que precisam deles possam acessar. Para decidir como agrupar segredos em schemas, consulte Agrupar segredos por quem precisa deles.

Criar um segredo gerenciado pelo Databricks​

Para criar um segredo gerenciado pelo Databricks, você precisa de USE CATALOG no catálogo e da propriedade do esquema ou de CREATE SECRET e USE SCHEMA nele.

Para criar um esquema para os segredos de um aplicativo, execução o seguinte:

SQL
CREATE SCHEMA IF NOT EXISTS main.orders_app;
  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 .

Conceder acesso a segredos​

Conceda o privilégio que corresponde ao que cada principal precisa fazer. Exceto com BROWSE, todo principal também precisa de USE CATALOG e USE SCHEMA no catálogo e no esquema pai. Um privilégio concedido em um catálogo ou esquema aplica-se aos segredos nele contidos, incluindo segredos criados posteriormente.

Para permitir que um principal

Conceder

Leia o valor em uma chamada de notebook, job ou API REST

READ SECRET

Descubra segredos específicos sem ver seus valores

REFERENCE SECRET no segredo ou esquema, quando BROWSE em todo o catálogo é muito amplo. Ele não oferece acesso de leitura nem permite que a entidade use o valor.

Atualizar o valor

WRITE SECRET. Conceder apenas esse privilégio não dá acesso de leitura ao segredo.

Criar segredos em um esquema

CREATE SECRET no esquema ou catálogo

Conceder privilégios em segredos para outros

Propriedade ou MANAGE no segredo, esquema ou catálogo

Para permitir que um principal

Conceder

Leia o valor em uma chamada de notebook, job ou API REST

READ SECRET

Descubra segredos específicos sem ver seus valores

REFERENCE SECRET no segredo ou esquema, quando BROWSE em todo o catálogo é muito amplo. Ele não oferece acesso de leitura nem permite que a entidade use o valor.

Atualizar o valor

WRITE SECRET. Conceder apenas esse privilégio não dá acesso de leitura ao segredo.

Criar segredos em um esquema

CREATE SECRET no esquema ou catálogo

Conceder privilégios em segredos para outros

Propriedade ou MANAGE no segredo, esquema ou catálogo

Para conceder privilégios, use o Catalog Explorer: abra o secret ou o esquema, clique na tab Permissões e clique em Conceder . Para conceder com SQL, execute o seguinte:

SQL
-- Let a job's service principal read every secret in a schema
GRANT USE CATALOG ON CATALOG main TO `etl-service-principal`;
GRANT USE SCHEMA, READ SECRET ON SCHEMA main.orders_app TO `etl-service-principal`;

-- Let the application's developers create secrets in its schema
GRANT USE SCHEMA, CREATE SECRET ON SCHEMA main.orders_app TO `orders-developers`;

Consulte Gerenciar privilégios no Unity Catalog.

Ler um segredo​

Para ler um valor de segredo, você precisa ser o proprietário do segredo ou ter READ SECRET no segredo ou no esquema ou catálogo dele.

A Databricks recomenda dbutils, porque isso redige o valor na saída da célula e nos logs. O exemplo a seguir lê um nome de usuário e senha de banco de dados para configurar uma leitura JDBC:

Python
username = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_username")
password = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_password")

df = (spark.read
.format("jdbc")
.option("url", "<jdbc-url>")
.option("dbtable", "<table-name>")
.option("user", username)
.option("password", password)
.load()
)

Consulte Utilidade de segredos (dbutils.secrets).

Listar, atualizar e excluir segredos​

Para atualizar um valor, você precisa de WRITE SECRET no segredo. Para alterar seu comentário ou data de expiração, ou para excluí-lo, você precisa ser proprietário do segredo ou ter MANAGE nele, em seu esquema ou em seu catálogo.

  1. No Catalog Explorer, vá para o esquema e clique em Segredos no painel Visão geral para listar seus segredos.
  2. Clique no segredo que você deseja alterar.
  3. No canto superior direito, clique no menu kebab (pontos verticais) e selecione Editar ou Excluir .
  4. Para editar, insira um novo valor ou data de expiração e clique em Confirmar . Para excluir, insira o nome completo do segredo e clique em Excluir .

Auditar acesso a segredos​

A tabela do sistema system.access.audit registra eventos de segredos. As leituras aparecem com action_name = 'getSecret'. Para listar os últimos 7 dias de eventos de segredos, execução o seguinte:

SQL
SELECT event_time, user_identity.email, action_name, request_params
FROM system.access.audit
WHERE service_name = 'unityCatalog'
AND action_name LIKE '%Secret%'
AND event_date >= current_date() - INTERVAL 7 DAYS
ORDER BY event_time DESC;

Veja Referência da tabela do sistema de logs de auditoria.

Criptografar valores de segredo com chaves gerenciadas pelo cliente​

O Databricks criptografa valores de segredos com chaves gerenciadas pelo Databricks por default. Para usar sua própria key, configure as definições de key gerenciada pelo cliente (CMK) no catalog que guarda os segredos. Os valores de segredos são armazenados no Unity Catalog, não na localização de armazenamento do catalog, então isso funciona para qualquer catalog, incluindo um com uma localização de armazenamento externa. Para requisitos e configuração, consulte key gerenciadas pelo cliente para o Unity Catalog.

Usar segredos em UDFs​

Um UDF Python ou Scala do Unity Catalog pode usar um valor secreto sem dar aos chamadores acesso ao segredo. Declare o segredo na cláusula SECRETS do UDF. O UDF o lê com as permissões do proprietário da função:

  • O proprietário precisa de READ SECRET no segredo para criar ou substituir o UDF. Se o proprietário perder READ SECRET, o UDF falhará.
  • Os chamadores precisam apenas de EXECUTE no UDF e nenhum privilégio no secret.

A definição de UDF deve definir environment_version como 6 ou acima. No compute clássico, use o Databricks Runtime 19 e acima no modo de acesso padrão. Para ver exemplos, consulte UDFs do Python e UDFs do Scala.

UDFs com escopo de sessão, que usam databricks.secrets.get() ou com.databricks.Secrets.get(), leem segredos com as permissões do chamador, portanto, cada chamador precisa de READ SECRET. Consulte UDFs Python e UDFs Scala.

No compute de modo de acesso dedicado, você não pode chamar essas UDFs diretamente. Você pode chamar um de uma função SQL do Unity Catalog que você usa como uma máscara de coluna de controle de acesso baseada em atributo (ABAC), que o Databricks aplica no compute serverless. Consulte Versões de compute sem suporte.

atenção

Use valores secretos apenas dentro do UDF. Não os retorne nos resultados do UDF. A redação reduz a exposição acidental em erros e logs, mas não impede que o código UDF retorne um segredo nos resultados da query.

Limitações​

  • Quotas : Um esquema pode conter até 1.000 segredos, e um metastore até 10.000.
  • Sem pesquisa global ou esquema de informações : Os segredos não aparecem na pesquisa global ou nas tabelas de esquema de informações. Use o Catalog Explorer, dbutils ou a API REST.
  • Escopo da API OAuth : A API de segredos do Unity Catalog requer o escopo da API OAuth unity-catalog. O escopo secrets aplica-se apenas aos Secret Scopes do Workspace.
  • Init scripts : Você não pode usar segredos do Unity Catalog em init scripts globais ou com escopo de cluster.
  • Desenvolvimento remoto : Databricks Connect e modos de execução JAR compilados não podem ler secrets do Unity Catalog, porque dbutils.secrets requer um notebook ou job com base no Databricks Runtime.

Outros recursos​