Compartilhar via

Gerenciamento de segredos

Ao acessar fontes de dados externas por meio do JDBC, a autenticação geralmente é necessária. Em vez de inserir credenciais diretamente em notebooks, você pode armazenar credenciais com segurança usando segredos do Databricks e referenciá-las em seus notebooks e trabalhos. Essa abordagem aprimora a segurança e simplifica o gerenciamento de credenciais. Esta página fornece uma visão geral dos segredos do Databricks.

Observação

O Databricks recomenda usar o Catálogo do Unity para configurar o acesso aos dados no armazenamento em nuvem. Consulte Conectar-se ao armazenamento de objetos de nuvem usando o Catálogo do Unity.

Visão geral dos segredos

Para configurar e usar segredos:

  1. Crie um escopo de segredos. Um escopo de segredos é a coleção de segredos identificada por um nome.
  2. Adicione segredos ao escopo
  3. Atribua permissões ao escopo de segredos.
  4. Referencie os segredos em seu código.

Para obter um exemplo de ponta a ponta de como usar segredos em seus fluxos de trabalho, consulte Tutorial: Criar e usar um segredo do Databricks. Para usar um segredo em uma propriedade de configuração ou variável de ambiente do Spark, consulte Usar um segredo em uma propriedade de configuração ou variável de ambiente do Spark.

Aviso

Administradores de workspace, criadores secretos e usuários que receberam permissão podem acessar e ler segredos do Databricks. Embora o Databricks tente redigir valores secretos em saídas de notebook, não é possível impedir totalmente que esses usuários exibam conteúdo secreto. Sempre atribua permissões de acesso secreto cuidadosamente para proteger informações confidenciais.

Gerenciar os escopos de segredos

Um escopo de segredos é a coleção de segredos identificada por um nome. A Databricks recomenda alinhar escopos secretos a funções ou aplicativos em vez de indivíduos.

Há dois tipos de escopo secreto:

  • Suportado por Azure Key Vault: você pode fazer referência a segredos armazenados em um Azure Key Vault usando escopos de segredos suportados pelo Azure Key Vault. O escopo de segredos com suporte do Azure Key Vault é uma interface somente leitura para o Key Vault. Você deve gerenciar segredos em escopos de segredo suportados pelo Azure Key Vault no Azure.
  • Com suporte do Databricks: um escopo de segredos com suporte do Databricks é armazenado em um banco de dados criptografado de propriedade e gerenciado pelo Azure Databricks.

Depois de criar um escopo secreto, você pode atribuir permissões para conceder aos usuários acesso para ler, gravar e gerenciar escopos secretos.

Criar um escopo de segredos com suporte do Azure Key Vault

Esta seção descreve como criar um escopo de segredos com suporte do Azure Key Vault usando o portal do Azure e a interface do usuário do workspace do Azure Databricks. Você também pode criar um escopo de segredo com suporte do Azure Key Vault usando a CLI do Databricks.

Requisitos

  • Você deve ter uma instância do Azure Key Vault. Se você não tem uma instância do de cofre de chaves, siga as instruções em Criar um Key Vault usando o portal do Azure.
  • Você deve ter a função Colaborador do Key Vault, Colaborador ou Proprietário na instância do cofre de chaves do Azure que você quer usar para fazer o backup do escopo de segredos.

Observação

A criação de um escopo de segredos com suporte do Azure Key Vault requer a função Colaborador ou Proprietário na instância do cofre de chaves do Azure, mesmo que o serviço Azure Databricks tenha recebido acesso ao cofre de chaves.

Se o cofre de chaves existir em um tenant diferente do workspace do Azure Databricks, o usuário do Azure AD que cria o escopo de segredos deverá ter permissão para criar entidades de serviço no tenant do cofre de chaves. Caso contrário, o seguinte erro ocorrerá:

Unable to grant read/list permission to Databricks service principal to KeyVault 'https://xxxxx.vault.azure.net/': Status code 403, {"odata.error":{"code":"Authorization_RequestDenied","message":{"lang":"en","value":"Insufficient privileges to complete the operation."},"requestId":"XXXXX","date":"YYYY-MM-DDTHH:MM:SS"}}

Configure sua instância do Key Vault do Azure para o Azure Databricks

  1. Faça logon no Portal do Azure, localize e selecione a instância do cofre de chaves do Azure.

  2. Em Configurações, clique na guia Configuração de Acesso.

  3. Defina o Modelo de permissão como Política de acesso do cofre.

    Observação

    A criação de uma função de escopo de segredo com suporte do Azure Key Vault concede as permissões Obter e Listar à ID do aplicativo para o serviço Azure Databricks usando as políticas de acesso do cofre de chaves. O modelo de permissão de controle de acesso baseado em função do Azure não é compatível com o Azure Databricks.

  4. Em Configurações, selecione Rede.

  5. Em Firewalls e redes virtuais, defina Permitir acesso de: a Permitir acesso público de redes virtuais e endereços IP específicos.

    Em Exceção, selecione Permitir que serviços confiáveis da Microsoft contornem este firewall.

    Observação

    Você também pode definir Permitir acesso de: para Permitir acesso público de todas as redes.

Criar um escopo de segredo com suporte do Azure Key Vault

  1. Acesse https://<databricks-instance>#secrets/createScope. Substitua <databricks-instance> pela URL do workspace da sua implantação do Azure Databricks. Essa URL diferencia maiúsculas de minúsculas. Por exemplo, scope em createScope deve usar uma maiúscula S).

    Criar escopo

  2. Insira o nome do escopo de segredos. Os nomes do escopo de segredos não diferenciam maiúsculas de minúsculas.

  3. Em Gerenciar entidade de segurança, selecione Criador ou Todos os usuários do workspace para especificar quais usuários têm a permissão MANAGE no escopo de segredos.

    A permissão MANAGE permite que os usuários leiam, escrevam e concedam permissões no escopo. Sua conta deve ter o plano Premium para escolher Creator.

  4. Insira o Nome DNS (por exemplo, https://databrickskv.vault.azure.net/) e a ID do Recurso, por exemplo:

    /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/databricks-rg/providers/Microsoft.KeyVault/vaults/databricksKV

    Essas propriedades estão disponíveis na guia Configurações > Propriedades de um Azure Key Vault no portal do Azure.

  5. Clique em Criar.

  6. Use o comando Databricks CLI para verificar se o escopo foi criado com sucesso.

Criar um escopo de segredos com suporte do Databricks

Esta seção descreve como criar um escopo secreto usando a CLI do Databricks (versão 0.205 e superior). Você também pode usar a API de Segredos.

Nomes do escopo de segredos:

  • Deve ser exclusivo dentro de um espaço de trabalho.
  • Deve consistir em caracteres alfanuméricos, traços, @sublinhados e pontos, e não pode exceder 128 caracteres.
  • Não diferencia maiúsculas de minúsculas.

Os nomes de escopo secreto são considerados não sensíveis e podem ser lidos por todos os usuários no espaço de trabalho.

Para criar um escopo usando a CLI do Databricks:

databricks secrets create-scope <scope-name>

Por padrão, os escopos são criados com a permissão MANAGE atribuída ao usuário que criou o escopo. Depois de criar um escopo de segredo com suporte do Databricks, você pode adicionar segredos a ele.

Listar âmbitos secretos

Para listar os escopos existentes em um workspace usando a CLI:

databricks secrets list-scopes

Você também pode listar escopos secretos usando a API Secrets.

Excluir um escopo de segredos

A exclusão de um escopo de segredos exclui todos os segredos e ACLs aplicados ao escopo. Para excluir um escopo usando a CLI, execute o seguinte:

databricks secrets delete-scope <scope-name>

Você também pode excluir um escopo de segredos usando a API de Segredos.

Gerenciar segredos

Um segredo é um par de chave-valor que armazena material confidencial usando um nome de chave exclusivo dentro de um escopo secreto.

Esta seção descreve como criar um escopo secreto usando a CLI do Databricks (versão 0.205 e superior). Você também pode usar a API de Segredos. Os nomes dos segredos não diferenciam maiúsculas de minúsculas.

Criar um segredo

O método usado para criar um segredo depende do fato de você estar usando um escopo com suporte do Azure Key Vault ou um escopo com suporte do Databricks.

Criar um segredo em um escopo com suporte do Azure Key Vault

Para criar um segredo no Azure Key Vault, use o portal do Azure ou a API REST do Azure Set Secret . Para obter um exemplo, consulte Etapa 4: Adicionar o segredo do cliente ao Azure Key Vault.

Criar um segredo em um escopo com suporte do Databricks

Esta seção descreve como criar um segredo usando a CLI do Databricks (versão 0.205 e superior) ou em um notebook usando o SDK do Databricks para Python. Você também pode usar a API de Segredos. Os nomes dos segredos não diferenciam maiúsculas de minúsculas.

CLI do Databricks

Ao criar um segredo em um escopo com suporte do Databricks, você pode especificar o valor do segredo de uma das três maneiras:

  • Especifique o valor como uma cadeia de caracteres usando o sinalizador –string-value.
  • Insira o segredo quando solicitado de forma interativa (segredos de linha única).
  • Passe o segredo usando a entrada padrão (segredos de várias linhas).

Por exemplo:

databricks secrets put-secret --json '{
  "scope": "<scope-name>",
  "key": "<key-name>",
  "string_value": "<secret>"
}'

Se você estiver criando um segredo de várias linhas, poderá passar o segredo usando a entrada padrão. Por exemplo:

(cat << EOF
this
is
a
multi
line
secret
EOF
) | databricks secrets put-secret <scope-name> <key-name>

SDK do Databricks para Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.secrets.put_secret("<secret_scope>","<key-name>",string_value ="<secret>")

Ler um segredo

Esta seção descreve como ler um segredo usando a CLI do Databricks (versão 0.205 e superior) ou em um notebook usando o utilitário Secrets (dbutils.secrets).

CLI do Databricks

Para ler o valor de um segredo usando a CLI do Databricks, você deve decodificar o valor codificado em base64. Você pode usar jq para extrair o valor e base --decode decodificá-lo:

databricks secrets get-secret <scope-name> <key-name> | jq -r .value | base64 --decode

Utilitário de segredos (dbutils.secrets)

password = dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")

Listar segredos

Para listar segredos em um determinado escopo:

databricks secrets list-secrets <scope-name>

A resposta exibe informações de metadados sobre os segredos, como os nomes de chave dos segredos. Use o utilitário Secrets (dbutils.secrets) em um notebook ou trabalho para listar esses metadados. Por exemplo:

dbutils.secrets.list('my-scope')

Excluir um segredo

Para excluir um segredo de um escopo com a CLI do Databricks:

databricks secrets delete-secret <scope-name> <key-name>

Você também pode usar a API de Segredos.

Para excluir um segredo de um escopo com suporte do Azure Key Vault, use a API REST do Azure SetSecret ou a interface do usuário do portal do Azure.

Gerenciar permissões de escopo secreto

Por padrão, o usuário que cria os escopos secretos recebe a permissão MANAGE. Isso permite que o criador do escopo leia segredos no escopo, grave segredos no escopo e gerencie permissões no escopo.

Observação

As ACLs do segredo estão no nível do escopo. Se você usar escopos com suporte do Azure Key Vault, os usuários que recebem acesso ao escopo terão acesso a todos os segredos no Azure Key Vault. Para restringir o acesso, utilize instâncias separadas do Azure Key Vault.

Esta seção descreve como gerenciar o controle de acesso secreto usando a CLI do Databricks (versão 0.205 e superior). Você também pode usar a API de Segredos. Para níveis de permissão secretas, veja ACLs Secretas

Conceder permissões a um usuário em um escopo secreto

Para conceder permissões a um usuário em um escopo secreto usando a CLI do Databricks:

databricks secrets put-acl <scope-name> <principal> <permission>

Fazer uma solicitação Put para uma entidade de segurança que já tenha uma permissão aplicada substitui o nível de permissão existente.

O principal campo especifica uma entidade de segurança existente do Azure Databricks. Um usuário é especificado usando seu endereço de email, uma entidade de serviço usando o valor applicationId e um grupo usando o respectivo nome de grupo. Para obter mais informações, veja Entidade de segurança.

Exibir permissões de escopo secreto

Para exibir todas as permissões do escopo de segredos para um determinado escopo de segredos:

databricks secrets list-acls <scope-name>

Para obter as permissões do escopo de segredos aplicadas a uma entidade de segurança para um determinado escopo de segredos:

databricks secrets get-acl <scope-name> <principal>

Se nenhuma ACL existir para a entidade de segurança e o escopo especificados, essa solicitação falhará.

Excluir uma permissão do escopo de segredos

Para excluir uma permissão do escopo de segredos aplicada a uma entidade de segurança para um determinado escopo de segredos:

databricks secrets delete-acl <scope-name> <principal>

Redação secreta

Armazenar credenciais como segredos do Azure Databricks facilita a proteção de suas credenciais quando você executa notebooks e trabalhos. No entanto, é fácil imprimir acidentalmente um segredo para os buffers de saída padrão ou exibir o valor durante a atribuição de variáveis.

Para evitar isso, o Azure Databricks redige todos os valores secretos que são lidos usando dbutils.secrets.get() e referenciados em uma propriedade de configuração do Spark. Quando exibidos, os valores secretos são substituídos por [REDACTED].

Por exemplo, se você definir uma variável como um valor de segredo usando dbutils.secrets.get() e imprimir essa variável, essa variável será substituída por [REDACTED].

Aviso

A redação se aplica apenas a valores de segredo literal. A funcionalidade de redação de segredo não impede transformações deliberadas e arbitrárias de um literal do segredo. Para garantir o controle adequado dos segredos, você deve usar listas de controle de acesso para limitar as permissões para executar comandos. Isso impede o acesso não autorizado a contextos de notebook compartilhados.

Redação secreta no SQL

O Azure Databricks tenta redigir todos os comandos DQL do SQL (Linguagem de Consulta de Dados) que invocam a função secreta, incluindo exibições referenciadas e funções definidas pelo usuário. Quando a função secret é usada, a saída é substituída por [REDACTED] quando possível. Assim como a redação do notebook, isso só se aplica a valores literais, não a segredos transformados ou referenciados indiretamente.

Para comandos DML do SQL (Linguagem de Manipulação de Dados), o Azure Databricks permite pesquisas secretas se o segredo for considerado seguro, por exemplo, quando encapsulado em uma função criptográfica, como sha() ou aes_encrypt(), que impedem que valores brutos sejam armazenados sem criptografia.

Validação secreta no SQL

O Azure Databricks também aplica a validação para bloquear comandos DML do SQL que podem resultar em segredos não criptografados sendo salvos em tabelas. O analisador de consulta tenta identificar e impedir esses cenários, o que ajuda a evitar o armazenamento acidental de informações confidenciais em texto sem formatação.