机密管理

有时，访问数据需要通过 JDBC 对外部数据源进行身份验证。 无需直接在笔记本中输入凭据，而是可以使用 Azure Databricks 机密来存储凭据并在笔记本和作业中引用这些凭据。 本文概要介绍 Azure Databricks 机密。

若要配置和使用机密，请执行以下操作：

1. 创建机密范围。 机密范围是由名称标识的机密的集合。
2. 将机密添加到范围
3. 分配对机密范围的权限。
4. 使用 Databricks 实用工具访问机密，请参阅机密实用工具 (dbutils.secrets)。

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

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

有两种类型的机密范围：

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

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

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

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

Unable to grant read/list permission to Databricks service principal to KeyVault 'https://xxxxx.vault.azure.cn/': 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"}}

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

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

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

   备注

   创建 Azure Key Vault 支持的机密范围角色会使用密钥保管库访问策略授予对 Azure Databricks 服务的应用 ID 的“获取”和“列表”权限。 Azure Databricks 不支持 Azure 基于角色的访问控制权限模型。

4. 在“设置”下选择“网络” 。

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

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

   备注

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

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

   

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

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

   “管理”权限允许用户读取、写入和授予对范围的权限。 帐户必须具有高级计划才能选择“创建者”。

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

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

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

5. 单击 “创建” 。

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

本节介绍如何使用什么是 Databricks CLI？（0.205 及更高版本）创建机密范围。 还可以使用机密 API。

机密范围名称：

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

机密范围名称被视为是非敏感信息，工作区中的所有用户都可读取它们。

使用 Databricks CLI 创建范围：

databricks secrets create-scope <scope-name>

默认情况下，使用创建范围的用户的“管理”权限创建范围。 创建 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“设置机密”REST API。 有关示例，请参阅步骤 4：将客户端密码添加到 Azure Key Vault。

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

在 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>

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

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

要读取笔记本或作业中的机密，必须使用机密实用程序 (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。

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

本部分介绍如何使用什么是 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() 读取的所有机密值。 在笔记本单元格输出中显示时，机密值将替换为 [REDACTED]。

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