Unity Catalog 机密是一个安全对象,用于存储敏感的凭据,如密码、令牌或 API 密钥。 机密使用三级命名空间(catalog.schema.secret),并且在连接到元存储的每个工作区中都可以使用。
你使用与其他数据资产相同的 Unity Catalog 权限来管理密钥,甚至精确到单个密钥。 用户可以浏览机密而无法读取或使用,你可以用自己的密钥加密机密值,审计日志记录每一次读取或变更。
Unity Catalog 机密可以由 Azure Databricks 管理,也可以由 Azure 密钥保管库提供后端支持。 请参见Unity Catalog中的Azure 密钥保管库 secrets。
Requirements
- 必须为 Unity Catalog 启用该工作区。 请参阅什么是 Unity Catalog?。
- 要使用
dbutils读取机密,请使用环境版本 4 及更高版本上的无服务器笔记本和作业,或运行 Databricks Runtime 17.3 LTS 及更高版本的经典计算。 Azure Databricks 推荐使用无服务器或标准访问模式。 - 要在 UDF 中使用机密,请参阅在 UDF 中使用机密。
创建机密
机密存放在架构中。 在只有需要这些机密的委托人才能访问的架构中创建机密。 要决定如何将机密分组到架构中,请参阅按需要机密的用户对机密进行分组。
一个架构只能存放由 Azure Databricks 管理的机密或由 Azure 密钥保管库支持的机密,不能同时存放两者,因此你在设置架构时就要选择值的存储位置。 有关 Azure 密钥保管库支持的架构,请参阅在 Azure 密钥保管库支持的架构中创建机密。
创建 Azure Databricks 管理机密
要创建由 Azure Databricks 托管的机密,你需要在目录上拥有 USE CATALOG 权限,并且拥有该架构的所有权,或者在该架构上拥有 CREATE SECRET 和 USE SCHEMA 权限。
要为应用程序的机密创建架构,请运行以下命令:
CREATE SCHEMA IF NOT EXISTS main.orders_app;
目录资源管理器
- 在Azure Databricks工作区中,单击“目录”以打开目录资源管理器。
- 转到要创建机密的架构。
- 单击“ 创建 > 机密”。
- 输入名称和值。 (可选)添加 注释 和 到期日期。 如果机密过期,目录资源管理器会显示警告。
- 单击 “创建” 。
REST API
要创建机密,请运行以下命令:
curl -X POST \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"catalog_name": "main",
"schema_name": "orders_app",
"name": "db_password",
"value": "your_secret_value",
"comment": "Password for the orders database"
}' \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"
在 Azure 密钥保管库支持的架构中创建机密
管理员只需为架构配置一次 Azure 密钥保管库支持。 之后,你在 Azure 密钥保管库中创建、更新和轮换其机密,这些机密会出现在 Unity Catalog 的架构中。 要为架构提供后端支持,请参阅 Unity Catalog 中的 Azure 密钥保管库机密。
- 在支持该架构的 Azure 密钥保管库中创建机密。
- 按名称读取机密。 参见 阅读秘密。
授予访问机密的权限
授予与每个主体需要执行的操作相匹配的特权。 除了 BROWSE,每个主体对父目录和架构也需要 USE CATALOG 和 USE SCHEMA 权限。 在目录或架构上授予的特权适用于其中的机密,包括之后创建的机密。
| 要让某个主体 | 授予 |
|---|---|
| 在笔记本、作业或REST API调用中读取该值 | READ SECRET |
| 发现特定机密而不查看其值 | 当对整个目录授予 BROWSE 过于宽泛时,在机密或架构上授予 REFERENCE SECRET。 它不会给主体读取权限,也不允许主体使用该值。 |
| 更新数值 |
WRITE SECRET。 仅授予此特权并不会给予该机密的读取访问权限。 |
| 在架构中创建机密 | 架构或目录上的 CREATE SECRET 权限 |
| 向他人授予对机密的特权 | 所有权,或在机密、架构或目录上拥有 MANAGE 权限 |
要授予特权,可以使用目录资源管理器:打开机密或架构,单击权限选项卡,然后单击授予。 要使用 SQL 授予权限,请运行以下操作:
-- Let a job's service principal read every secret in a schema
GRANT USE CATALOG ON CATALOG main TO `etl-service-principal`;
GRANT USE SCHEMA, READ SECRET ON SCHEMA main.orders_app TO `etl-service-principal`;
-- Let the application's developers create secrets in its schema
GRANT USE SCHEMA, CREATE SECRET ON SCHEMA main.orders_app TO `orders-developers`;
读取机密
要读取机密值,你需要拥有该机密的所有权,或者在该机密或其架构或目录上拥有 READ SECRET 权限。
机密实用工具 (dbutils.secrets)
Azure Databricks 推荐 dbutils,因为它会在单元格输出和日志中隐藏该值。 以下示例读取数据库用户名和密码以配置 JDBC 读取操作:
username = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_username")
password = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_password")
df = (spark.read
.format("jdbc")
.option("url", "<jdbc-url>")
.option("dbtable", "<table-name>")
.option("user", username)
.option("password", password)
.load()
)
参见 Secrets 实用工具 (dbutils.secrets)。
REST API
Warning
Unity Catalog REST API 不会对返回的值进行遮蔽。 审计日志仍然记录每一次读取。 Azure Databricks建议dbutils改用。
若要返回值,请在响应中设置 include_value=true 和读取 effective_value 字段:
curl -G \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
--data-urlencode "include_value=true" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.orders_app.db_password"
列出、更新和删除机密
要更新一个值,你需要在机密上拥有 WRITE SECRET 权限。 要更改其注释或过期日期,或是要删除它,你需要拥有该机密的所有权,或者在该机密、其架构或其目录上拥有 MANAGE 权限。
对于 Azure 密钥保管库 支持的 schema,在 Azure 密钥保管库 中更新并删除机密。 删除操作会同步到 Unity Catalog。
目录资源管理器
- 在目录资源管理器中,转到该架构,并在概述窗格中单击机密,以列出其中的机密。
- 单击要更改的机密。
- 在右上角,点击更多菜单(竖排省略号),选择 编辑 或 删除。
- 要编辑,请输入新的值或有效期,然后点击 确认。 要删除,请输入机密的完整名称,然后单击删除。
机密实用工具 (dbutils.secrets)
要列出你可以在某个架构中访问的机密,请运行以下命令:
all_secrets = dbutils.secrets.list(catalog="main", schema="orders_app")
REST API
要列出机密,请运行以下命令。 如果有更多结果,请将响应 next_page_token 传递为 page_token:
curl -G \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
--data-urlencode "catalog_name=main" \
--data-urlencode "schema_name=orders_app" \
--data-urlencode "page_size=100" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"
要更新一个值,请执行以下操作。 只有在 update_mask 和请求体中同时存在的字段才会发生变化:
curl -X PATCH \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"value": "new_secret_value"}' \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.orders_app.db_password?update_mask=*"
要删除机密,请运行以下命令:
curl -X DELETE \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.orders_app.db_password"
为机密添加标签
Unity Catalog 机密支持键值标签,例如用于对机密进行分类或记录所属团队或成本中心。 请参阅“将标记应用于 Unity Catalog 安全对象”。
要在密钥上添加或删除标签,您必须拥有该密钥或拥有以下所有权限:
-
APPLY TAG对该密钥 -
USE SCHEMA在密钥的父架构模式上 -
USE CATALOG对该秘密的父编目
要分配受治理标签,您还需要对该受治理标签拥有 ASSIGN 权限。 请参阅 管理受治理标记的权限。
要使用 SQL 添加或删除标签,请运行以下操作:
SET TAG ON SECRET main.orders_app.db_password cost_center = hr;
UNSET TAG ON SECRET main.orders_app.db_password cost_center;
要查看密钥上的标签,请使用以下方法之一:
目录资源管理器
- 在目录资源管理器中,转到架构,然后在“概述”窗格中单击“机密”。
- 点击密文。 其标签显示在“标签”下的“概览”选项卡。
REST API
要在密钥上列出标签,请运行以下操作。 如果有更多结果,请将响应 next_page_token 传递为 page_token:
curl \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/entity-tag-assignments/secrets/main.orders_app.db_password/tags"
CLI
要在密钥上列出标签,请运行以下操作:
databricks entity-tag-assignments list secrets main.orders_app.db_password
密钥标签不会出现在 DESCRIBE SECRET输出中,不会出现在获取密钥的 API 响应中、信息模式表或工作区搜索中。
审核机密访问
system.access.audit 系统表记录机密事件。 读取结果显示为 action_name = 'getSecret'。 要列出最近7天的秘密活动,请运行以下内容:
SELECT event_time, user_identity.email, action_name, request_params
FROM system.access.audit
WHERE service_name = 'unityCatalog'
AND action_name LIKE '%Secret%'
AND event_date >= current_date() - INTERVAL 7 DAYS
ORDER BY event_time DESC;
请参阅审核日志系统表参考。
用客户管理的密钥加密秘密值
Azure Databricks默认用Azure Databricks管理的密钥加密秘密值。 要使用自己的密钥,请在存储机密的编目中配置客户管理密钥(CMK)设置。 机密值存储在 Unity Catalog 中,而不是存储在目录的存储位置中,因此这适用于任何目录,包括具有外部存储位置的目录。 关于需求和设置,请参见 Unity Catalog 的客户管理的密钥。
外部秘密值会保留在你的云秘密管理器中,它用自己的密钥加密它们。 目录上的 CMK 设置不适用于它们。
在 UDF 中使用密钥
Unity Catalog Python 或 Scala UDF 可以使用秘密值,而不允许调用者访问该秘密。 在 UDF 的 SECRETS 子句中声明该机密。 UDF在函数所有者的权限下读取它:
- 所有者需要在机密上拥有
READ SECRET权限才能创建或替换 UDF。 如果所有者失去READ SECRET,UDF 就会失败。 - 调用方只需在 UDF 上拥有
EXECUTE权限,无需对该机密拥有任何特权。
UDF定义必须将 environment_version 设置为 6 或更高版本。 在经典计算模式下,在标准访问模式下,使用 Databricks Runtime 19 及以上版本。 示例请参见 Python UDF 和 Scala UDF。
会话范围的 UDF 使用 databricks.secrets.get() 或 com.databricks.Secrets.get(),以调用者的权限读取密钥,因此每个调用者都需要 READ SECRET。 参见 Python UDF 和 Scala UDF。
在专用访问模式计算中,你不能直接调用这些UDF。 你可以从一个 Unity Catalog SQL 函数中调用它,并将该函数用作基于属性的访问控制 (ABAC) 列掩码,Azure Databricks 会在无服务器计算上强制执行该掩码。 参见 不支持的计算版本。
Warning
只在UDF内部使用秘密值。 不要在 UDF 结果中返回它们。 遮蔽减少了错误和日志中的意外暴露,但并不能阻止 UDF 代码在查询结果中返回机密信息。
局限性
- 配额:一个架构最多可容纳 1,000 个机密,元存储库最多可容纳 10,000 个。
-
无全局搜索或信息架构:机密不会出现在全局搜索或信息架构表中。 可以使用 Catalog Explorer、
dbutils或 REST API。 -
OAuth API 作用域:Unity Catalog 密钥 API 需要
unity-catalogOAuth API 作用域。 该secrets作用域仅适用于工作区机密作用域。 - Init 脚本:你不能在全局或集群范围的初始化脚本中使用 Unity Catalog 机密。
-
远程开发:Databricks Connect 和编译后的 JAR 运行模式无法读取 Unity Catalog 的密钥,因为
dbutils.secrets需要由 Databricks Runtime 提供支持的笔记本或作业。
附加资源
| Resource | 说明 |
|---|---|
| Unity Catalog 机密的最佳实践 | 按环境、应用程序或团队组织机密,让工作负载使用机密而不读取它们。 |
| 机密管理 | 比较 Unity Catalog 机密与工作区机密范围,并了解它们各自可以在何处使用。 |