机密管理

通过 JDBC 访问外部数据源时，通常需要身份验证。 可以使用 Databricks 机密安全地存储凭据，并在笔记本和作业中引用它们，而不是直接将其输入到笔记本中。 此方法可增强安全性并简化凭据管理。 本页概述了 Databricks 机密。

机密概述

要配置和使用密钥，您可以：

1. 创建机密范围。 机密范围是按名称标识的机密的集合。
2. 将机密添加到范围
3. 分配对机密范围的权限。
4. 在代码中引用机密。

有关如何在工作流中使用机密的端到端示例，请参阅 教程：创建和使用 Databricks 机密。 若要在 Spark 配置属性或环境变量中使用机密，请参阅 在 Spark 配置属性或环境变量中使用机密。

管理机密范围

机密范围是按名称标识的机密的集合。 Databricks 建议将机密范围与角色或应用程序而非个人对齐。

有两种类型的机密范围：

• Azure 密钥库支持：可以使用 Azure 密钥库支持的机密范围引用存储在 Azure 密钥库中的机密。 Azure Key Vault 支持的机密范围是 Key Vault 的只读接口。 必须在 Azure 中管理 Azure Key Vault 支持的机密范围中的机密。
• Databricks 支持：Databricks 支持的机密范围存储在 Azure Databricks 拥有和管理的加密数据库中。

创建机密范围后，可以分配权限，以授予用户对读取、写入和管理机密范围的访问权限。

创建 Azure Key Vault 支持的机密范围

本部分介绍如何使用 Azure 门户和 Azure Databricks 工作区 UI 创建 Azure Key Vault 支持的机密范围。 也可以使用 Databricks CLI 创建 Azure Key Vault 支持的机密范围。

要求

• 必须具有 Azure 密钥保管库实例。 如果没有密钥保管库实例，请按照使用 Azure 门户创建 Key Vault 中的说明进行操作。
• 必须在要用于支持机密范围的 Azure Key Vault 实例上具有 Key Vault 参与者、参与者或所有者角色。

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"}}

为 Azure Databricks 配置 Azure 密钥保管库实例

1. 登录到 Azure 门户，查找并选择 Azure 密钥保管库实例。

2. 在“设置”下，单击“访问配置”选项卡。

3. 将 权限模型 设置为 保管库访问策略。

   注意

   创建一个由 Azure Key Vault 支持的机密范围角色，通过密钥保管库访问策略，将“获取”和“列出”权限授予 Azure Databricks 服务的应用 ID。 Azure Databricks 不支持 Azure 基于角色的访问控制权限模型。

4. 在设置下选择网络 。

5. 在“防火墙和虚拟网络”中，将“允许的访问来源：”设置为“允许从特定虚拟网络和 IP 地址公开访问”。

   在“例外”下，选中“允许受信任的 Microsoft 服务跳过此防火墙”。

   注意

   还可以将“允许的访问来源”设置为“允许来自所有网络的公共访问”。

创建 Azure Key Vault 支持的机密范围

1. 转到 https://<databricks-instance>#secrets/createScope。 （将 <databricks-instance> 替换为 Azure Databricks 部署的工作区 URL）。 此 URL 区分大小写。 例如，scope 在 createScope 中必须使用大写 S。

   

2. 输入机密范围的名称。 机密范围名称不区分大小写。

3. 在 “管理主体 ”中选择“ 创建者 ”或 “所有工作区”用户 ，以指定哪些用户对机密范围具有 MANAGE 权限。

   借助 MANAGE 权限，用户可以在范围中读取、写入和授予对范围的权限。 你的帐户必须具有 高级计划 才能选择 Creator。

4. 输入“DNS 名称”（例如 ）和“资源 ID”，例如：

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

   可从 Azure 门户中 Azure Key Vault 的“设置 > 属性”选项卡中使用这些属性。

5. 单击 “创建” 。

6. 使用 Databricks CLIdatabricks secrets list-scopes 命令验证是否已成功创建范围。

创建 Databricks 支持的机密范围

本部分介绍如何使用 Databricks CLI（版本 0.205 及更高版本）创建机密范围。 还可以使用机密 API。

机密范围名称：

• 在工作区中必须唯一。
• 必须包含字母数字字符、短划线、下划线 @和句点，并且不能超过 128 个字符。
• 不区分大小写。

机密范围名称被视为非敏感名称，可由工作区中的所有用户读取。

要使用 Databricks CLI 创建范围，请：

databricks secrets create-scope <scope-name>

默认情况下，范围是使用创建范围的用户的 MANAGE 权限创建的。 创建 Databricks 支持的机密范围后，可以向其添加机密。

列出机密范围

要使用 CLI 列出工作区中的现有范围，请：

databricks secrets list-scopes

还可以使用 机密 API 列出机密范围。

删除机密范围

删除机密范围时会删除应用于该范围的所有机密和 ACL。 要使用 CLI 删除范围，请运行以下命令：

databricks secrets delete-scope <scope-name>

还可使用机密 API 来删除机密范围。

管理机密

机密是一个密钥值对，它使用在机密范围内唯一的密钥名称存储敏感材料。

本部分介绍如何使用 Databricks CLI（版本 0.205 及更高版本）创建机密范围。 还可以使用机密 API。 机密名称不区分大小写。

创建机密

创建机密的方法取决于使用的是 Azure Key Vault 支持的范围还是 Databricks 支持的范围。

在 Azure Key Vault 支持的范围中创建机密

若要在 Azure 密钥库中创建机密，请使用 Azure 门户 或 Azure 设置机密 REST API。 有关示例，请参阅步骤 4：将客户端密码添加到 Azure 密钥库。

在 Databricks 支持的范围中创建机密

本部分介绍如何使用 Databricks CLI（版本 0.205 及更高版本）或在笔记本中使用用于 Python 的Databricks SDK 创建机密。 还可以使用机密 API。 机密名称不区分大小写。

Databricks CLI（命令行界面）

在 Databricks 支持的作用域中创建机密时，可以通过以下三种方式之一指定机密值：

• 使用 –string-value 标志将值指定为字符串。
• 在系统以交互方式提示时输入机密（单行机密）。
• 使用标准输入（多行机密）传递机密。

例如：

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

如果要创建多行机密，则可以使用标准输入传递机密。 例如：

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

用于 Python 的 Databricks SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

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

读取机密

本部分介绍如何使用 Databricks CLI （版本 0.205 及更高版本）或在笔记本中使用 机密实用工具（dbutils.secrets）读取机密。

Databricks CLI（命令行界面）

若要使用 Databricks CLI 读取机密的值，必须解码 base64 编码的值。 可用于 jq 提取值并 base --decode 对其进行解码：

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

机密实用工具 (dbutils.secrets)

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

列出机密

要列出给定范围内的机密，请：

databricks secrets list-secrets <scope-name>

响应显示有关机密的元数据信息，例如机密的密钥名称。 可使用笔记本或作业中的机密实用工具 (dbutils.secrets) 来列出此元数据。 例如：

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

删除机密

要使用 Databricks CLI 从范围中删除机密，请：

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

还可以使用机密 API。

若要从 Azure Key Vault 支持的范围中删除机密，请使用 Azure SetSecret REST API 或 Azure 门户 UI。

管理机密范围权限

默认情况下，创建机密范围的用户被授予 MANAGE 权限。 这样，范围创建者就可以读取作用域中的机密、将机密写入范围，以及管理对范围的权限。

本部分介绍如何使用 Databricks CLI（版本 0.205 及更高版本）管理机密访问控制。 还可以使用机密 API。 有关机密权限级别，请参阅机密 ACL

授予用户对机密范围的权限

若要使用 Databricks CLI 授予用户对机密范围的权限，请执行以下操作：

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

对已经有一个应用的权限的主体发出 put 请求会覆盖现有权限级别。

principal 字段指定一个现有的 Azure Databricks 主体。 用户是使用其电子邮件地址指定的，服务主体是使用其 applicationId 值指定的，组是使用其组名称指定的。 有关详细信息，请参阅主体。

查看机密范围权限

如要查看给定机密范围的所有机密范围权限，请采取以下操作：

databricks secrets list-acls <scope-name>

要获取应用于给定机密范围的主体的机密范围权限，请：

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

如果给定主体和作用域不存在 ACL，则此请求将失败。

删除机密范围权限

要删除应用于指定机密范围的主体的秘密作用域权限，请按以下步骤操作：

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

机密编辑

将凭据存储为 Azure Databricks 密钥，可以在运行笔记本和作业时轻松保护凭据。 但是，很容易意外将机密打印到标准输出缓冲区，或在变量赋值期间显示该值。

为防止这种情况，Azure Databricks 会隐藏通过 dbutils.secrets.get() 读取并在 Spark 配置属性中引用的所有机密值。 显示时，机密值将替换为 [REDACTED]。

例如，如果使用 dbutils.secrets.get() 将变量设置为机密值，然后打印该变量，则该变量将替换为 [REDACTED]。