你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

安全地连接到 Azure 资源或克隆专用存储库

2025-10-08

在自定义过程中访问存储库或 Azure 资源等资源时，需要安全地进行身份验证。可以在自定义文件中引用 Azure Key Vault 机密，以避免公开敏感信息，并且可以使用服务主体向 Azure 进行身份验证，以确保资源访问的安全。本文介绍如何在开发框自定义期间安全地管理和访问资源。

在自定义文件中使用密钥保管库机密

在 YAML 自定义项中，使用 Azure Key Vault 中的密钥来克隆私有存储库或运行需要访问令牌的任务。例如，在自定义文件中，使用存储在 Azure Key Vault 中的个人访问令牌（PAT）访问专用存储库。

团队和用户自定义都支持从密钥保管库提取机密。使用映像定义文件的团队定制，使用 image 参数定义开发框的基础映像，并列出创建开发框时运行的任务。用户自定义项列出了创建开发框时运行的任务。

若要在自定义文件中使用机密（如 PAT），请将其存储为密钥保管库机密。以下示例演示如何在两种类型的自定义项中引用密钥保管库的机密信息。

为自定义功能配置密钥保管库访问权限

若要配置密钥保管库机密以用于团队或用户自定义，请确保开发人员中心项目的托管标识在密钥保管库上具有“密钥保管库机密用户”角色。

如果密钥保管库是专用的，请让受信任的Microsoft服务绕过防火墙，因为开发人员中心尚不支持服务标记。

以下屏幕截图显示了允许受信任的Microsoft服务绕过 Azure Key Vault 设置中的防火墙的选项。

若要详细了解如何让受信任的Microsoft服务绕过防火墙，请参阅配置 Azure Key Vault 网络设置。

用户自定义的其他配置

若要为用户自定义配置密钥保管库机密，请还执行以下步骤：

请确保开发人员中心项目的托管标识在密钥保管库上具有“密钥保管库读取者”角色和“密钥保管库机密用户”角色。
在开发箱定制期间，向需要相应机密的每个用户或组（包括开发人员中心的托管标识、管理员帐户和任何其他必要的用户或组）授予相应机密的“密钥保管库机密用户”角色。

团队自定义示例

此语法在映像定义文件中使用密钥保管库秘密 (PAT)。 KEY_VAULT_SECRET_URI是您密钥保管库中机密的 URI。

$schema: "<SCHEMA_VERSION>"
name: "<IMAGE_DEFINITION_NAME>"
image: "<BASE_IMAGE>"
description: "<DESCRIPTION>"

tasks:
  - name: <TASK_NAME>
    description: <TASK_DESCRIPTION>
    parameters:
      repositoryUrl: <REPOSITORY_URL>
      directory: <DIRECTORY_PATH>
      pat: "{{<KEY_VAULT_SECRET_URI>}}"

此示例使用 git-clone 任务：

$schema: "1.0"
name: "example-image-definition"
image: microsoftvisualstudio_visualstudioplustools_vs-2022-ent-general-win11-m365-gen2
description: "Clones a public example Git repository"

tasks:
  - name: git-clone
    description: Clone this repository into C:\workspaces
    parameters:
      repositoryUrl: https://github.com/example-org/example-repo.git
      directory: C:\workspaces
      pat: "{{https://contoso-vault.vault.azure.net/secrets/github-pat}}"

或者，您可以通过内置任务直接引用机密，如以下示例所示：

$schema: "1.0" 
name: "example-image-definition"
image: microsoftvisualstudio_visualstudioplustools_vs-2022-ent-general-win11-m365-gen2
description: "Clones a public example Git repository"

tasks:  
- name: git-clone
    description: Clone this repository into C:\Workspaces 
    parameters: 
    command: MyCommand –MyParam "{{KEY_VAULT_SECRET_URI}}"

用户自定义示例

通过用户自定义，可以获取 Azure DevOps 令牌以克隆专用存储库，而无需从 Key Vault 显式指定 PAT。该服务在运行时自动将你的 Azure 令牌交换为 Azure DevOps 令牌。

此示例显示 ADO 速记（{{ado://...}}）。该服务会在运行时将您的 Azure 令牌兑换为 Azure DevOps 令牌，因此您无需在 Key Vault 中存储持久访问令牌 (PAT)。

$schema: "1.0"
tasks:
  - name: git-clone
    description: Clone this repository into C:\workspaces
    parameters:
      repositoryUrl: https://dev.azure.com/example-org/MyProject/_git/example-repo
      directory: C:\workspaces
      pat: '{{ado://example-org}}'

Dev Box Visual Studio Code 扩展和 Dev Box CLI 不支持在内循环测试工作流中水化用于自定义的机密。

使用服务主体向 Azure 资源进行身份验证

使用服务主体可以对 Azure 资源进行安全的身份验证，而无需公开用户凭据。创建服务主体，分配所需的角色，并在自定义任务中使用它进行身份验证。使用现有的密钥管理功能在自定义过程中水化密钥管理库中的密码。

在 Azure Active Directory（Azure AD）中创建服务主体，并为要使用的资源分配必要的角色。

输出是一个 JSON 对象，其中包含服务主体的 appId、 displayName、密码和租户，用于在 Azure 自动化方案中进行身份验证和授权。

示例：创建服务主体时的 CLI 输出。将返回的密码存储在密钥管理库中，并为开发人员中心项目标识授予“密钥保管库机密用户”角色，以便自定义可以在运行时对机密进行水化。
```
$ az ad sp create-for-rbac -n DevBoxCustomizationsTest

{
  "appId": "...",
  "displayName": "DevBoxCustomizationsTest",
  "password": "...",
  "tenant": "..."
}
```
将上面返回的密码存储在 Key Vault 机密中，如下所示： https://mykeyvault.vault.azure.net/secrets/password
在 Key Vault 上，向项目标识授予 Key Vault 机密用户 角色。

现在可以在自定义任务中进行身份验证，并在自定义时解除 Key Vault 中的服务主体密码。

示例：从 Azure 存储下载文件

以下示例演示如何从存储帐户下载文件。 YAML 代码片段定义一个 Dev Box 自定义，该自定义项执行两个主要任务：

使用 winget 包管理器安装 Azure CLI。

运行 PowerShell 脚本，该脚本：

使用服务主体登录到 Azure，并从 Azure Key Vault 安全检索密码。
使用经过身份验证的会话从 Azure 存储帐户下载 Blob（文件）。

示例：自定义，用于水化密钥保管库中的服务主体密码，然后使用该水化密码下载 Azure 存储中的 Blob 并对其进行身份验证。将服务主体密码存储在 Key Vault 中，并确保项目标识具有 Key Vault 机密用户角色。

$schema: "1.0"
name: "devbox-customization"
tasks:
  - name: ~/winget
    parameters:
      package: Microsoft.AzureCLI
  - name: ~/powershell
    parameters:
      command: |
        az login --service-principal `
          --username <appId> `
          --password {{https://mykeyvault.vault.azure.net/secrets/password}} `
          --tenant <tenantId>
        az storage blob download `
          --account-name <storage_account_name> `
          --container-name <container_name> `
          --name <blob_name> `
          --file <local_file_path> `
          --auth-mode login

通过此设置，可以在 Dev Box 预配期间自动使用 Azure 资源，而无需在脚本中公开凭据。

示例：从 Azure DevOps 下载项目

使用服务主体进行身份验证，从 Azure DevOps (ADO) 下载版本项目。将服务主体的应用程序 ID（appId）添加为 Azure DevOps 组织中的用户，然后将主体分配给读者组。此步骤授予使用构建产物所需的权限。

配置这些步骤后，在自定义任务中使用服务主体凭据，从 Azure DevOps 安全地进行身份验证并下载工件。

将服务主体添加到 Azure DevOps 组织

若要将服务主体添加到 Azure DevOps 组织，请执行以下操作：

登录到 Azure DevOps 组织并打开 “组织”设置。
在菜单中，选择“ 用户”。
在“ 用户 ”页上，选择“ 添加用户”。
在 “添加新用户 ”对话框中，输入以下信息：
- 用户：输入服务主体的应用程序 ID（appId）作为用户电子邮件。
- 访问级别：选择 “基本”。
- 添加到项目：选择要在其中添加服务主体的项目。
- Azure DevOps 组：将服务主体分配给 读取者 组。
完成授予所需权限的过程。

有关如何将用户添加到 DevOps 组织的详细信息，请参阅添加组织用户和管理访问权限。

了解如何使用 Azure 门户在 Azure Key Vault 中设置和检索机密。
了解如何从 GitHub 或 Azure Repos 添加和配置目录。
了解如何在 Azure DevOps 中使用服务主体和托管标识。

反馈

此页面是否有帮助？