机密范围Secret scopes

管理机密时首先需要创建机密范围。Managing secrets begins with creating a secret scope. 机密范围是由名称标识的机密的集合。A secret scope is collection of secrets identified by a name. 一个工作区最多只能有 100 个机密范围。A workspace is limited to a maximum of 100 secret scopes.

概述Overview

有两种类型的机密范围:Azure Key Vault 支持和 Databricks 支持。There are two types of secret scope: Azure Key Vault-backed and Databricks-backed.

Azure Key Vault 支持的范围Azure Key Vault-backed scopes

若要引用 Azure Key Vault 中存储的机密,可以创建 Azure Key Vault 支持的机密范围。To reference secrets stored in an Azure Key Vault, you can create a secret scope backed by Azure Key Vault. 然后,你可以利用该机密范围中相应 Key Vault 实例中的所有机密。You can then leverage all of the secrets in the corresponding Key Vault instance from that secret scope. 由于 Azure Key Vault 支持的机密范围是 Key Vault 的只读接口,因此不允许进行 PutSecretDeleteSecret 机密 API 操作。Because the Azure Key Vault-backed secret scope is a read-only interface to the Key Vault, the PutSecret and DeleteSecret Secrets API operations are not allowed. 若要在 Azure Key Vault 中管理机密,必须使用 Azure SetSecret REST API 或 Azure 门户 UI。To manage secrets in Azure Key Vault, you must use the Azure SetSecret REST API or Azure portal UI.

Databricks 支持的范围Databricks-backed scopes

Databricks 支持的机密范围存储在 Azure Databricks 拥有并管理的加密数据库中并由该数据库支持。A Databricks-backed secret scope is stored in (backed by) an encrypted database owned and managed by Azure Databricks. 机密范围名称:The secret scope name:

  • 在工作区中必须唯一。Must be unique within a workspace.
  • 必须包含字母数字字符、短划线、下划线和句点,并且不得超过 128 个字符。Must consist of alphanumeric characters, dashes, underscores, and periods, and may not exceed 128 characters.

这些名称被视为是非敏感信息,工作区中的所有用户都可读取它们。The names are considered non-sensitive and are readable by all users in the workspace.

使用 Databricks CLI(版本 0.7.1 及更高版本)创建 Databricks 支持的机密范围。You create a Databricks-backed secret scope using the Databricks CLI (version 0.7.1 and above). 也可以使用机密 APIAlternatively, you can use the Secrets API.

范围权限Scope permissions

使用 ACL 控制的权限创建范围。Scopes are created with permissions controlled by ACLs. 默认情况下,使用创建范围的用户(创建者)的 MANAGE 权限创建范围,这使创建者可以读取范围中的机密、将机密写入范围以及更改范围的 ACL。By default, scopes are created with MANAGE permission for the user who created the scope (the “creator”), which lets the creator read secrets in the scope, write secrets to the scope, and change ACLs for the scope. 如果你的帐户具有 Azure Databricks 高级计划,则可以在创建范围后随时分配细粒度权限。If your account has the Azure Databricks Premium Plan, you can assign granular permissions at any time after you create the scope. 有关详细信息,请参阅机密访问控制For details, see Secret access control.

你还可以替代默认值,并在创建范围时向所有用户显式授予 MANAGE 权限。You can also override the default and explicitly grant MANAGE permission to all users when you create the scope. 事实上,如果你的帐户不具有 Azure Databricks 高级计划,则必须执行此操作。In fact, you must do this if your account does not have the Azure Databricks Premium Plan.

最佳做法 Best practices

作为团队主管,你可能想要为 Azure Synapse Analytics 和 Azure Blob 存储凭据创建不同的范围,然后在团队中提供不同的子组来访问这些范围。As a team lead, you might want to create different scopes for Azure Synapse Analytics and Azure Blob storage credentials and then provide different subgroups in your team access to those scopes. 你应考虑如何使用不同的范围类型来实现此目的:You should consider how to achieve this using the different scope types:

  • 如果你使用 Databricks 支持的范围并在这两个范围中添加机密,它们将是不同的机密(Azure Synapse Analytics 在范围 1 中,Azure Blob 存储在范围 2 中)。If you use a Databricks-backed scope and add the secrets in those two scopes, they will be different secrets (Azure Synapse Analytics in scope 1, and Azure Blob storage in scope 2).
  • 如果你使用 Azure Key Vault 支持的范围,每个范围都引用不同的 Azure Key Vault,并将机密添加到这两个 Azure Key Vault,则它们将是不同的机密集(Azure Synapse Analytics 在范围 1 中,Azure Blob 存储在范围 2 中)。If you use an Azure Key Vault-backed scope with each scope referencing a different Azure Key Vault and add your secrets to those two Azure Key Vaults, they will be different sets of secrets (Azure Synapse Analytics ones in scope 1, and Azure Blob storage in scope 2). 这些范围的工作方式类似于 Databricks 支持的范围。These will work like Databricks-backed scopes.
  • 如果你使用两个 Azure Key Vault 支持的范围,且两个范围都引用同一个 Azure Key Vault,并将机密添加到该 Azure Key Vault,则所有 Azure Synapse Analytics 和 Azure Blob 存储机密都将可用。If you use two Azure Key Vault-backed scopes with both scopes referencing the same Azure Key Vault and add your secrets to that Azure Key Vault, all Azure Synapse Analytics and Azure Blob storage secrets will be available. 由于 ACL 处于范围级别,因此这两个子组中的所有成员都可看到所有机密。Since ACLs are at the scope level, all members across the two subgroups will see all secrets. 这种安排并不满足你限制每个组访问一组机密的用例。This arrangement does not satisfy your use case of restricting access to a set of secrets to each group.

创建 Azure Key Vault 支持的机密范围 Create an Azure Key Vault-backed secret scope

可以使用 UI 或 Databricks CLI 创建 Azure Key Vault 支持的机密范围。You can create an Azure Key Vault-backed secret scope using the UI or using the Databricks CLI.

使用 UI 创建 Azure Key Vault 支持的机密范围Create an Azure Key Vault-backed secret scope using the UI

  1. 验证你是否对要用于支持机密范围的 Azure Key Vault 实例具有“参与者”权限。Verify that you have Contributor permission on the Azure Key Vault instance that you want to use to back the secret scope.

    如果没有 Key Vault 实例,请按照快速入门:使用 Azure 门户创建 Key Vault 中的说明进行操作。If you do not have a Key Vault instance, follow the instructions in Quickstart: Create a Key Vault using the Azure portal.

  2. 转到 https://<databricks-instance>#secrets/createScopeGo to https://<databricks-instance>#secrets/createScope. 此 URL 区分大小写;createScope 中的范围必须大写。This URL is case sensitive; scope in createScope must be uppercase.

    创建范围Create scope

  3. 输入机密范围的名称。Enter the name of the secret scope. 机密范围名称不区分大小写。Secret scope names are case insensitive.

  4. 使用“管理主体”下拉列表指定是所有用户都对此机密范围具有 MANAGE 权限,还是仅机密范围的创建者具有该权限 。Use the Manage Principal drop-down to specify whether All Users have MANAGE permission for this secret scope or only the Creator of the secret scope (that is to say, you).

    MANAGE 权限允许用户在此机密范围内进行读取和写入,如果是 Azure Databricks 高级计划中的帐户,还允许更改范围的权限。MANAGE permission allows users to read and write to this secret scope, and, in the case of accounts on the Azure Databricks Premium Plan, to change permissions for the scope.

    你的帐户必须具有 Azure Databricks 高级计划,你才能选择“创建者”。Your account must have the Azure Databricks Premium Plan for you to be able to select Creator. 建议的做法是:在创建机密范围时向“创建者”授予 MANAGE 权限,然后在测试范围后分配更细粒度的访问权限。This is the recommended approach: grant MANAGE permission to the Creator when you create the secret scope, and then assign more granular access permissions after you have tested the scope. 有关示例工作流的信息,请参阅机密工作流示例For an example workflow, see Secret workflow example.

    如果你的帐户具有标准计划,则必须将 MANAGE 权限设置为“所有用户”组。If your account has the Standard Plan, you must set the MANAGE permission to the “All Users” group. 如果在此处选择“创建者”,则在尝试保存该范围时,将看到一条错误消息。If you select Creator here, you will see an error message when you try to save the scope.

    有关 MANAGE 权限的详细信息,请参阅机密访问控制For more information about the MANAGE permission, see Secret access control.

  5. 输入“DNS 名称”(例如 https://databrickskv.vault.azure.net/)和“资源 ID”,例如 :Enter the DNS Name (for example, https://databrickskv.vault.azure.net/) and Resource ID, for example:

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

    可从 Azure 门户中 Azure Key Vault 的“属性”选项卡中使用这些属性。These properties are available from the Properties tab of an Azure Key Vault in your Azure portal.

    Azure Key Vault 的“属性”选项卡Azure Key Vault Properties tab

  6. 单击“创建” 按钮。Click the Create button.

  7. 使用 Databricks CLI databricks secrets list-scopes 命令验证是否已成功创建范围。Use the Databricks CLI databricks secrets list-scopes command to verify that the scope was created successfully.

有关访问 Azure Blob 存储时使用机密的示例,请参阅装载 Azure Blob 存储容器For an example of using secrets when accessing Azure Blob storage, see Mount an Azure Blob storage container.

使用 Databricks CLI 创建 Azure Key Vault 支持的机密范围Create an Azure Key Vault-backed secret scope using the Databricks CLI

  1. 安装 Databricks CLI 并将其配置为使用 Azure Active Directory (Azure AD) 令牌进行身份验证。Install the Databricks CLI and configure it to use an Azure Active Directory (Azure AD) token for authentication.

    请参阅安装 CLISee Install the CLI.

  2. 创建 Azure Key Vault 范围:Create the Azure Key Vault scope:

    databricks secrets create-scope --scope <scope-name>    --scope-backend-type AZURE_KEYVAULT --subscription-id <azure-keyvault-subscription-id> --dns-name <azure-keyvault-dns-name>
    

    默认情况下,使用创建范围的用户的 MANAGE 权限创建范围。By default, scopes are created with MANAGE permission for the user who created the scope. 如果你的帐户没有 Azure Databricks 高级计划,则必须替代此默认值,并在创建范围时向 users(所有用户)组显式授予 MANAGE 权限:If your account does not have the Azure Databricks Premium Plan, you must override that default and explicitly grant the MANAGE permission to the users (all users) group when you create the scope:

     databricks secrets create-scope --scope <scope-name>    --scope-backend-type AZURE_KEYVAULT --subscription-id <azure-keyvault-subscription-id> --dns-name <azure-keyvault-dns-name> --initial-manage-principal users
    

    如果你的帐户具有 Azure Databricks 高级计划,则可以在创建范围后随时更改权限。If your account in on the Azure Databricks Premium Plan, you can change permissions at any time after you create the scope. 有关详细信息,请参阅机密访问控制For details, see Secret access control.

    创建 Databricks 支持的机密范围后,可以添加机密Once you have created a Databricks-backed secret scope, you can add secrets.

有关访问 Azure Blob 存储时使用机密的示例,请参阅装载 Azure Blob 存储容器For an example of using secrets when accessing Azure Blob storage, see Mount an Azure Blob storage container.

创建 Databricks 支持的机密范围Create a Databricks-backed secret scope

机密范围名称不区分大小写。Secret scope names are case insensitive.

使用 Databricks CLI 创建范围:To create a scope using the Databricks CLI:

databricks secrets create-scope --scope <scope-name>

默认情况下,使用创建范围的用户的 MANAGE 权限创建范围。By default, scopes are created with MANAGE permission for the user who created the scope. 如果你的帐户没有 Azure Databricks 高级计划,则必须替代此默认值,并在创建范围时向“用户”(所有用户)组显式授予 MANAGE 权限:If your account does not have the Azure Databricks Premium Plan, you must override that default and explicitly grant the MANAGE permission to “users” (all users) when you create the scope:

databricks secrets create-scope --scope <scope-name> --initial-manage-principal users

如果你的帐户具有 Azure Databricks 高级计划,则可以在创建范围后随时更改权限。If your account has the Azure Databricks Premium Plan, you can change permissions at any time after you create the scope. 有关详细信息,请参阅机密访问控制For details, see Secret access control.

创建 Databricks 支持的机密范围后,可以添加机密Once you have created a Databricks-backed secret scope, you can add secrets.

列出机密范围 List secret scopes

列出工作区中的现有范围:To list the existing scopes in a workspace:

databricks secrets list-scopes

删除机密范围Delete a secret scope

删除机密范围时会删除应用于该范围的所有机密和 ACL。Deleting a secret scope deletes all secrets and ACLs applied to the scope. 删除范围:To delete a scope:

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