通过

机密管理

  • 项目

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

机密概述

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

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

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

警告

具有权限的管理员、机密创建者和用户可读取 Azure Databricks 机密。 虽然 Databricks 会努力编修笔记本中可能会显示的机密值，但无法阻止此类用户读取机密。 请参阅机密编修。

管理机密范围

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

有两种类型的机密范围：

  • Azure Key Vault 支持：可以使用 Azure Key Vault 支持的机密范围引用存储在 Azure Key Vault 中的机密。 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 Key Vault 实例。 如果没有密钥保管库实例，请按照使用 Azure 门户创建 Key Vault 中的说明进行操作。
  • 必须对用于支持机密范围的 Azure Key Vault 实例具有“密钥保管库参与者”、“参与者”或“所有者”角色。

注意

创建 Azure Key Vault 支持的机密范围需要 Azure 密钥保管库实例上的“参与者”或“所有者”角色，即使 Azure Databricks 服务之前已被授予对密钥保管库的访问权限。

如果密钥保管库与 Azure Databricks 工作区位于不同的租户中，则创建机密范围的 Azure AD 用户必须具有在密钥保管库租户中创建服务主体的权限。 否则将发生以下错误：

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

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

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

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

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

    注意

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

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

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

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

    注意

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

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

  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 支持的机密范围

本节介绍如何使用什么是 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 Key Vault 中创建机密，请使用 Azure 门户或 Azure“设置机密”REST API。 有关示例，请参阅步骤 4：将客户端密码添加到 Azure Key Vault。

Azure Key Vault

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

本节介绍如何使用什么是 Databricks CLI？（0.205 及更高版本）创建机密，或在笔记本中使用 Databricks SDK for Python 创建机密。 还可以使用机密 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>

Databricks SDK for Python

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。

管理机密范围权限

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

注意

机密 ACL 位于作用域级别。 如果使用 Azure 密钥保管库支持的范围，则被授予该作用域访问权限的用户有权访问 Azure 密钥保管库中的所有机密。 若要限制访问，请使用单独的 Azure 密钥保管库实例。

本部分介绍如何使用什么是 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]。

警告

笔记本单元格输出的机密编修仅适用于文本。 机密编辑功能不会阻止机密文本的故意转换和任意转换。 为了确保对机密进行适当的控制，应使用访问控制列表来限制运行命令的权限。 这样做可防止未经授权访问共享笔记本上下文。