通过

教程：通过 Azure 密钥保管库存储和使用 Azure Cosmos DB 凭据

  • 项目

适用对象： NoSQL MongoDB Cassandra Gremlin 表

重要

建议使用系统分配的托管标识来访问 Azure Cosmos DB。 如果托管标识解决方案和基于证书的解决方案都不能满足你的需求，请使用本文介绍的 Azure 密钥保管库解决方案。

如果你使用 Azure Cosmos DB 作为数据库，请使用 SDK、API 终结点以及主密钥或辅助密钥连接到数据库、容器和项。

将终结点 URI 和敏感的读写密钥直接存储在应用程序代码或配置文件中并不是良好的做法。 最好从主机中的环境变量读取这些数据。 在 Azure 应用服务中，可以使用应用设置为 Azure Cosmos DB 帐户注入运行时凭据，而无需开发人员以不安全的明文形式存储这些凭据。

Azure 密钥保管库进一步完善了这项最佳做法，它不仅使你能够安全地存储这些凭据，而且还为 Azure 应用服务等服务提供对凭据的托管访问权限。 Azure 应用服务将从 Azure 密钥保管库安全地读取凭据，并将这些凭据注入到正在运行的应用程序中。

按照这项最佳做法，开发人员可以存储 Azure Cosmos DB 模拟器等工具的凭据。 然后，运营团队可以确保在运行时注入正确的生产设置。

在本教程中，你将了解如何执行以下操作：

  • 创建 Azure Key Vault 实例
  • 将 Azure Cosmos DB 凭据作为机密添加到密钥保管库
  • 创建并注册一个 Azure 应用服务资源并授予“读取密钥”权限
  • 将密钥保管库机密注入到应用服务资源中

注意

本教程和示例应用程序使用 Azure Cosmos DB for NoSQL 帐户。 可以使用其他 API 执行许多相同的步骤。

先决条件

  • 一个现有的 Azure Cosmos DB for NoSQL 帐户。
  • GitHub 帐户。

开始之前：获取 Azure Cosmos DB 凭据

在开始之前，需要获取现有帐户的凭据。

  1. 导航到现有 Azure Cosmos DB for NoSQL 帐户的 Azure 门户页。

  2. 从 Azure Cosmos DB for NoSQL 帐户页中，选择“密钥”导航菜单选项。

    Azure Cosmos DB SQL API 帐户页的屏幕截图。导航菜单中突出显示了“密钥”选项。

  3. 记录“URI”和“主密钥”字段中的值。 稍后你将在本教程中使用这些值。

    “密钥”页的屏幕截图，其中显示了 Azure Cosmos DB SQL API 帐户的各种凭据。

创建 Azure 密钥保管库资源

首先，创建一个新的密钥保管库用于存储 API for NoSQL 凭据。

  1. 登录 Azure 门户。

  2. 选择“创建资源”>“安全性”>“Key Vault”。

  3. 在“创建密钥保管库”页上输入以下信息：

    设置 说明
    订阅 选择要用于此 Azure Cosmos 帐户的 Azure 订阅。
    资源组 选择一个资源组，或者选择“新建”，然后输入新资源组的唯一名称。
    密钥保管库名称 为密钥保管库输入多区域唯一的名称。
    区域 选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置，使他们能够以最快的速度访问数据。
    定价层 选择“标准”。

  4. 将其余设置保留默认值。

  5. 选择“查看 + 创建”。

  6. 查看提供的设置，然后选择“创建”。 创建帐户需要几分钟时间。 等待门户页显示“部署已完成”后再继续。

将 Azure Cosmos DB 访问密钥添加到 Key Vault

现在，将 Azure Cosmos DB 凭据作为机密存储到该密钥保管库中。

  1. 选择“转到资源”转到 Azure 密钥保管库资源页。

  2. 在 Azure 密钥保管库资源页中，选择“机密”导航菜单选项。

  3. 在菜单中选择“生成/导入”。

    密钥保管库菜单中的“生成/导入”选项的屏幕截图。

  4. 在“创建机密”页上输入以下信息：

    设置 说明
    上传选项 手动
    名称 cosmos-endpoint
    机密值 输入前面在本教程中复制的 URI。

    Azure 门户中“创建机密”对话框的屏幕截图，其中显示了 URI 机密的详细信息。

  5. 选择“创建”以创建新的 cosmos-endpoint 机密。

  6. 再次在菜单中选择“生成/导入”。 在“创建机密”页上输入以下信息：

    设置 说明
    上传选项 手动
    名称 cosmos-readwrite-key
    机密值 输入前面在本教程中复制的主密钥。

    Azure 门户中“创建机密”对话框的屏幕截图，其中显示了主密钥机密的详细信息。

  7. 选择“创建”以创建新的 cosmos-readwrite-key 机密。

  8. 创建机密后，在“机密”页中的机密列表中查看这些机密。

    密钥保管库机密列表的屏幕截图。

  9. 选择每个密钥，选择最新版本，然后复制“机密标识符”。 稍后在本教程中，你将为 cosmos-endpoint 和 cosmos-readwrite-key 机密使用该标识符。

    提示

    机密标识符采用 https://<key-vault-name>.vault.azure.cn/secrets/<secret-name>/<version-id> 格式。 例如，如果密钥保管库的名称为 msdocs-key-vault，密钥的名称为 cosmos-readwrite-key，版本为 83b995e363d947999ac6cf487ae0e12e，则机密标识符为 https://msdocs-key-vault.vault.azure.cn/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12e。

    名为 cosmos-readwrite-key 的密钥保管库机密的机密标识符的屏幕截图。

创建一个 Azure Web 应用并将其注册到 Azure 密钥保管库

在本部分创建新的 Azure Web 应用，部署一个示例应用程序，然后将该 Web 应用的托管标识注册到 Azure 密钥保管库。

  1. 使用 cosmos-db-nosql-dotnet-sample-web-environment-variables 模板创建新的 GitHub 存储库。

  2. 在 Azure 门户中，选择“创建资源”>“Web”>“Web 应用”。

  3. 在“创建 Web 应用”页和“基本信息”选项卡上，输入以下信息：

    设置 说明
    订阅 选择要用于此 Azure Cosmos 帐户的 Azure 订阅。
    资源组 选择一个资源组，或者选择“新建”，然后输入新资源组的唯一名称。
    名称 为 Web 应用输入多区域唯一的名称。
    发布 选择“代码”。
    运行时堆栈 选择 .NET 6 (LTS)。
    操作系统 选择“Windows”。
    区域 选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置，使他们能够以最快的速度访问数据。

  4. 将其余设置保留默认值。

  5. 选择“下一步: 部署”。

  6. 在“部署”选项卡上输入以下信息：

    设置 说明
    持续部署 选择“启用”。
    GitHub 帐户 选择“授权”。 按照 GitHub 帐户授权提示为 Azure 授予读取新建的 GitHub 存储库的权限。
    组织 为新的 GitHub 存储库选择组织。
    存储库 为新的 GitHub 存储库选择名称。
    分支 选择“主要”。

  7. 选择“查看 + 创建”。

  8. 查看提供的设置，然后选择“创建”。 创建帐户需要几分钟时间。 等待门户页显示“部署已完成”后再继续。

  9. 可能需要额外等待几分钟时间，以便在 Web 应用中完成 Web 应用程序的初始部署。 在 Azure Web 应用资源页中，选择“浏览”以查看应用的默认状态。

    处于没有凭据的默认状态的 Web 应用程序的屏幕截图。

  10. 选择“标识”导航菜单选项。

  11. 在“标识”页上，选择“系统分配”的托管标识对应的“打开”，然后选择“保存”。

    在“标识”页中启用系统分配的托管标识的屏幕截图。

将 Azure 密钥保管库机密注入为 Azure Web 应用中的应用设置

最后，将存储在密钥保管库中的机密注入为 Web 应用中的应用设置。 在运行时，这些应用设置又会将凭据注入到应用程序中，而不会以明文形式存储凭据。

  1. 返回到 Azure 门户中的密钥保管库页。 从导航菜单中选择“访问策略”。

  2. 在“访问策略”页上，从菜单中选择“创建”。

    “访问策略”菜单中“创建”选项的屏幕截图。

  3. 在“创建访问策略”页的“权限”选项卡上，选择“机密权限”部分中的“获取”选项。 选择“下一步”。

    为“机密权限”启用了“获取”权限的屏幕截图。

  4. 在“主体”选项卡上，选择前面在本教程中创建的 Web 应用的名称。 选择“下一步”。

    分配到权限的 Web 应用托管标识的屏幕截图。

    注意

    在此示例屏幕截图中，该 Web 应用名为 msdocs-dotnet-web。

  5. 再次选择“下一步”以跳过“应用程序”选项卡。在“查看 + 创建”选项卡上查看你提供的设置，然后选择“创建”。

  6. 返回到 Azure 门户中的 Web 应用页。 从导航菜单中选择“配置”。

  7. 在“配置”页上，选择“新建应用程序设置”。 在“添加/编辑应用程序设置”对话框中输入以下信息：

    设置 说明
    名称 CREDENTIALS__ENDPOINT
    键 获取在本教程的前面部分你在密钥保管库中创建的 cosmos-endpoint 机密的机密标识符。 按照以下格式输入标识符：@Microsoft.KeyVault(SecretUri=<secret-identifier>)。

    提示

    确保环境变量包含双下划线 (__) 值而不是单下划线。 双下划线是 .NET 在所有平台上支持的键分隔符。 有关详细信息，请参阅环境变量配置。

    注意

    例如，如果机密标识符是 https://msdocs-key-vault.vault.azure.cn/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07，则引用将是 @Microsoft.KeyVault(SecretUri=https://msdocs-key-vault.vault.azure.cn/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07)。

    “添加/编辑应用程序设置”对话框的屏幕截图，其中显示了引用密钥保管库机密的新应用设置。

  8. 选择“确定”以保存新的应用设置

  9. 再次选择“新建应用程序设置”。 在“添加/编辑应用程序设置”对话框中输入以下信息，然后选择“确定”：

    设置 说明
    名称 CREDENTIALS__KEY
    键 获取在本教程的前面部分你在密钥保管库中创建的 cosmos-readwrite-key 机密的机密标识符。 按照以下格式输入标识符：@Microsoft.KeyVault(SecretUri=<secret-identifier>)。

  10. 返回“配置”页，选择“保存”以更新 Web 应用的应用设置。

    “配置”页菜单中的“保存”选项的屏幕截图。

  11. 等待几分钟，让 Web 应用使用新应用设置重启。 此时，新应用设置应指示它们是“密钥保管库引用”。

    Web 应用中的两项应用设置指明“密钥保管库引用”的屏幕截图。

  12. 从导航菜单中选择“概述”。 选择“浏览”以查看填充了凭据的应用。

    具有有效 Azure Cosmos DB for NoSQL 帐户凭据的 Web 应用程序的屏幕截图。

后续步骤