Escopos secretos do espaço de trabalho

Um escopo de segredo do workspace é uma coleção nomeada de segredos em um único espaço de trabalho. Permissões de escopo secreto controlam quem pode ler, escrever e gerenciar os segredos nesse escopo. Permissões se aplicam a todo o escopo, não a segredos individuais, então um usuário que pode ler um segredo em um escopo pode ler todos os segredos. Para comparar escopos de secretos de workspace com segredos do Unity Catalog, veja Escolher onde armazenar um segredo.

Para usar um escopo secreto de workspace:

1. Crie um escopo de segredos.
2. Adicione secrets ao escopo.
3. Conceda permissões sobre o escopo.
4. Faça referência aos segredos no seu código ou em uma propriedade de configuração do Spark ou variável de ambiente. Confira Usar um segredo em uma propriedade de configuração ou variável de ambiente do Spark.

Gerenciar os escopos de segredos

O Azure Databricks recomenda alinhar escopos de segredo a papéis ou aplicações 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. Um escopo de segredo respaldado pelo Azure Key Vault é uma interface somente leitura para o Key Vault. Você gerencia os segredos dele 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

Crie um escopo de segredos respaldado pelo Azure Key Vault no portal do Azure e na interface do workspace do Azure Databricks. Você também pode usar a Databricks CLI.

Requirements

• 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.

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 login no portal do Azure, encontre e selecione a instância do Azure Key Vault.

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. Novos cofres de chaves adotam por padrão o controle de acesso baseado em função do Azure, o que não é compatível com os escopos de segredo com suporte do Azure Key Vault.

   Note

   Criar um escopo de segredo apoiado pelo Azure Key Vault concede as permissões Get e List à ID do aplicativo do serviço Azure Databricks usando políticas de acesso ao cofre.

4. Em Configurações, selecione Rede.

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

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

   Note

   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 espaço de trabalho da implantação do Azure Databricks. Essa URL diferencia maiúsculas de minúsculas. Por exemplo, scope em createScope deve usar uma letra maiúscula S.

   

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

Crie um escopo secreto com a CLI Databricks (versão 0.205 e superior) ou a API Secrets.

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.

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 .

Criar um segredo em um escopo com suporte do Databricks

Crie um segredo com a CLI Databricks (versão 0.205 e superior), o SDK Databricks para Python em um notebook ou a API Secrets. Os nomes dos segredos não diferenciam maiúsculas de minúsculas.

Interface de Linha de Comando 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 string com a --string-value flag.
• 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

Leia um segredo com a CLI Databricks (versão 0.205 e superior), ou em um notebook com o utilitário Secrets (dbutils.secrets).

Interface de Linha de Comando do Databricks

Para ler o valor de um segredo usando a CLI Databricks, você deve decodificar o valor codificado base64. Você pode usar jq para extrair o valor e base64 --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 mostra metadados sobre os segredos, como seus nomes das chaves. Para listar esses metadados em um notebook ou trabalho, use a ferramenta Secrets (dbutils.secrets). 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 um escopo secreto tem a MANAGE permissão sobre ele, o que permite ler segredos no escopo, escrever segredos nele e gerenciar suas permissões.

Gerencie permissões de escopo secreto com a CLI Databricks (versão 0.205 e superior) ou a Secrets API. Para níveis de permissão secretos, 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.

Por exemplo, para permitir que um grupo como datascience leia os segredos em um escopo, conceda-lhe READ:

databricks secrets put-acl <scope-name> <group> READ

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 ajuda a protegê-las quando você executa notebooks e jobs. No entanto, você ainda pode acidentalmente imprimir um segredo em buffers de saída padrão ou exibir o valor durante a atribuição de variáveis.

Para evitar isso, o Azure Databricks tenta redigir 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].

Redação secreta no SQL

O Azure Databricks tenta ocultar todos os comandos da linguagem de consulta de dados SQL (DQL) que invocam a função secreta, incluindo visualizaçõ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 da linguagem de manipulação de dados SQL (DML), o Azure Databricks permite consultas de segredos se o segredo for considerado seguro. Por exemplo, um segredo é seguro quando envolvido 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.

Recursos adicionais