工作区秘密作用域是一组命名的秘密集合,集中在一个工作区中。 密钥作用域权限控制谁可以读取、写入和管理其中的密钥。 权限适用于整个作用域,而非单个秘密,因此能读取一个权限域内一个秘密的用户可以读取所有所有秘密。 要比较工作空间机密范围与 Unity Catalog 机密,请参见 “选择存储机密的位置”。
要使用工作区机密范围:
创建机密范围。
向作用域中添加机密。
授予范围权限。
在你的代码中引用这些机密,或者在 Spark 配置属性或环境变量中引用这些机密。 请参阅在 Spark 配置属性或环境变量中使用机密。
Warning
工作区管理员、机密创建者以及获得权限的用户都可以访问并读取 Azure Databricks 的机密。 尽管 Azure Databricks 尝试在笔记本输出中遮蔽秘密值,但无法完全阻止这些用户查看秘密内容。 始终仔细分配机密访问权限以保护敏感信息。
管理机密范围
Azure Databricks 建议将机密范围与角色或应用程序对应,而不是与个人对应。
有两种类型的机密范围:
Azure 密钥库支持:可以使用 Azure 密钥库支持的机密范围引用存储在 Azure 密钥库中的机密。 Azure 密钥保管库 支持的机密范围是 密钥保管库 的只读接口。 你在 Azure 中管理它的机密。
Databricks 支持:Databricks 支持的机密范围存储在 Azure Databricks 拥有和管理的加密数据库中。
Important
由 Azure 密钥保管库 提供支持的机密作用域只支持 Vault 访问策略权限模型,不支持 Azure 基于角色的访问控制 (RBAC)。 新 Azure 密钥库默认使用 Azure RBAC。 如果你的密钥库使用 Azure RBAC,在创建 Azure 密钥保管库 支持的秘密作用域之前,先将其权限模型切换为 Vault 访问策略。
创建机密范围后,可以分配权限,以授予用户对读取、写入和管理机密范围的访问权限。
创建 Azure 密钥保管库 支持的机密范围
在 Azure portal 和 Azure Databricks workspace UI 中创建由 Azure 密钥保管库 提供支持的机密范围。 你也可以使用 Databricks 的 CLI。
Requirements
必须具有 Azure 密钥保管库实例。 如果没有密钥保管库实例,请按照使用 Azure 门户创建 密钥保管库 中的说明进行操作。
必须在要用于支持机密范围的 Azure 密钥保管库 实例上具有 密钥保管库 参与者、参与者或所有者角色。
Note
创建由 Azure 密钥保管库 支持的密钥范围需要在 Azure 密钥保管库实例上拥有“参与者”或“所有者”角色,即使 Azure Databricks 服务之前已被授予访问密钥保管库的权限。
如果密钥库存在于与 Azure Databricks 工作区不同的租户中,创建秘密范围的 Microsoft Entra ID 用户必须在密钥库的租户中拥有创建服务主体的权限。 否则将发生以下错误:
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 密钥保管库实例
登录 Azure 门户,找到并选择 Azure 密钥 Vault 实例。
在“设置”下,单击“访问配置”选项卡。
将 权限模型 设置为 保管库访问策略。 新的密钥库默认使用 Azure 基于角色的访问控制,而由 Azure 密钥保管库 支持的机密范围不支持该控制。
Note
创建由 Azure 密钥保管库 提供支持的机密作用域时,会通过保管库访问策略向 Azure Databricks 服务所使用的应用程序 ID 授予 Get 和 List 权限。
在设置下选择网络 。
在“防火墙和虚拟网络”中,将“允许的访问来源”设置为“允许从特定虚拟网络和 IP 地址进行公众访问”。
在“例外”下,选中“允许受信任的 Microsoft 服务跳过此防火墙”。
Note
还可以将“允许的访问来源”设置为“允许来自所有网络的公共访问”。
创建 Azure 密钥保管库 支持的机密范围
转到
https://<databricks-instance>#secrets/createScope。 将<databricks-instance>替换为 Azure Databricks 部署中的 workspace URL。 此 URL 区分大小写。 例如,scope在createScope中必须使用大写S字母。
输入机密范围的名称。 机密范围名称不区分大小写。
在“管理主体”中,选择“创建者”或“所有工作区用户”,以指定哪些用户对机密范围具有“管理”权限。
“管理”权限允许用户读取、写入和授予对范围的权限。 你的帐户必须具有 高级计划 才能选择 Creator。
输入“DNS 名称”(例如 )和“资源 ID”,例如:
/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/databricks-rg/providers/Microsoft.KeyVault/vaults/databricksKV可从 Azure 门户中 Azure 密钥保管库 的“设置 > 属性”选项卡中使用这些属性。
单击 “创建” 。
使用 Databricks CLI
databricks secrets list-scopes命令验证是否已成功创建范围。
创建 Databricks 提供的秘钥范围
用 Databricks CLI (版本 0.205 及以上)或 Secrets 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 来删除机密范围。
管理机密
机密是一个键值对,它使用在机密范围内唯一的键名来存储敏感材料。
创建机密的方法取决于使用的是 Azure 密钥保管库 支持的范围还是 Databricks 支持的范围。
在由 Azure 密钥保管库 支持的范围中创建一个机密
若要在 Azure 密钥库中创建机密,请使用 Azure 门户 或 Azure 设置机密 REST API。
在由 Databricks 支持的授权范围中创建机密
可以用 Databricks CLI(版本 0.205 及以上)、笔记本中的 Python Databricks SDK 或 Secrets 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 及以上)读取机密,或者在笔记本中用 Secrets 工具(dbutils.secrets)读取。
Databricks 命令行界面 (CLI)
要使用 Databricks CLI 读取秘密值,必须解码 base64 编码值。 可用于 jq 提取值并 base64 --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>
响应显示了关于秘密的元数据,比如密钥名。 要在笔记本或作业任务中列出这些元数据,可以使用 Secrets 工具(dbutils.secrets)。 例如:
dbutils.secrets.list('my-scope')
删除机密
使用 Databricks CLI 从范围中删除机密:
databricks secrets delete-secret <scope-name> <key-name>
还可以使用机密 API。
若要从 Azure 密钥保管库 支持的范围中删除机密,请使用 Azure SetSecret REST API 或 Azure 门户 UI。
管理机密范围权限
默认情况下,创建秘密作用域的用户对其具有 MANAGE 权限,这使他们能够读取该作用域中的秘密、向其中写入秘密,并管理其权限。
Note
机密访问控制列表(ACL)位于作用域级别。 如果使用 Azure 密钥保管库支持的范围,则被授予该作用域访问权限的用户有权访问 Azure 密钥保管库中的所有机密。 若要限制访问,请使用单独的 Azure 密钥保管库实例。
使用 Databricks CLI (版本0.205及以上)或 Secrets API管理秘密范围权限。 关于 Secret 权限级别,请参见 Secret ACLs。
授予用户对机密范围的权限
Note
授予秘密范围权限需要高级 套餐。
若要使用 Databricks CLI 授予用户对机密范围的权限,请执行下面的操作:
databricks secrets put-acl <scope-name> <principal> <permission>
对已经有一个应用的权限的主体发出 put 请求会覆盖现有权限级别。
principal 字段指定一个现有的 Azure Databricks 主体。 用户是使用其电子邮件地址指定的,服务主体是使用其 applicationId 值指定的,组是使用其组名称指定的。 有关详细信息,请参阅Principal。
例如,要让像 datascience 这样的组读取作用域中的机密,请授予它 READ:
databricks secrets put-acl <scope-name> <group> READ
查看机密范围权限
若要查看给定机密范围的所有权限,请执行下面的命令:
databricks secrets list-acls <scope-name>
要获取应用于给定机密范围的主体的机密范围权限,请:
databricks secrets get-acl <scope-name> <principal>
如果给定主体和作用域不存在 ACL,则此请求将失败。
删除机密范围权限
要删除应用于指定机密范围的主体的秘密作用域权限,请按以下步骤操作:
databricks secrets delete-acl <scope-name> <principal>
机密删减
将凭据存储为 Azure Databricks secret,有助于在运行笔记本和作业时保护它们。 不过,你仍然可能会不小心将密钥打印到标准输出缓冲区,或者在变量赋值时显示该值。
为防止这种情况,Azure Databricks 会尝试遮蔽使用 dbutils.secrets.get() 读取并在 Spark 配置属性中引用的机密值。 显示时,机密值将替换为 [REDACTED]。
例如,如果使用 dbutils.secrets.get() 将变量设置为机密值,然后打印该变量,则该变量将替换为 [REDACTED]。
Warning
编修仅适用于字面机密值。 机密编辑功能不会阻止机密文本的故意转换和任意转换。 要控制密钥,可以使用 访问控制列表 限制执行命令的权限。 这样做可防止未经授权访问共享笔记本上下文。
SQL 中的机密编修
Azure Databricks 尝试遮蔽所有调用秘密函数的 SQL 数据查询语言(DQL)命令,包括引用视图和用户自定义函数。 使用secret函数时,会在可能的情况下将输出替换为[REDACTED]。 与笔记本编修一样,这仅适用于字面值,而不适用于转换或间接引用的秘密。
对于 SQL 数据操作语言(DML)命令,如果机密被视为安全,Azure Databricks 允许检索机密。 例如,秘密在封装于密码函数(如 sha() 或 aes_encrypt())中时是安全的,这些函数防止原始值未加密存储。
SQL 中的机密验证
Azure Databricks 还对 SQL DML 命令应用验证,以阻止可能导致未加密的机密保存到表中的操作。 查询分析器尝试识别和防止这些方案,这有助于避免以纯文本意外存储敏感信息。
其他资源
| 资源 | Description |
|---|---|
| 机密管理 | 比较工作空间的秘密范围和 Unity Catalog 的秘密,看看你分别可以在何处使用它们。 |
| 在 Spark 配置属性或环境变量中使用机密 | 在 Spark 配置属性和环境变量中引用机密。 |