Azure Pipelines Agent 使用 Azure Linux VM 托管身份认证的实践指南

背景介绍

在 Azure DevOps 的持续集成/持续部署(CI/CD)流程中，自托管代理(Self-Hosted Agent)是一种常见的部署方式。传统上，这些代理通常使用个人访问令牌(PAT)进行身份验证，但这种方法存在一定的安全风险和管理复杂性。

托管身份认证的优势

Azure 托管身份(Managed Identity)为 Azure 资源提供了自动管理的身份，可以安全地访问其他 Azure 资源和服务。相比传统的服务主体(Service Principal)加密钥的方式，托管身份具有以下优势：

1. 无需管理凭证轮换
2. 消除了密钥存储的安全风险
3. 简化了权限管理流程
4. 与 Azure RBAC 深度集成

配置步骤详解

1. 准备工作

首先确保你的 Azure Linux VM 已经启用了用户分配的托管身份(User Assigned Managed Identity)。可以通过 Azure 门户或 CLI 完成此操作。

2. 验证托管身份访问权限

在配置代理前，建议先验证托管身份是否具有访问 Azure DevOps 的权限。可以使用以下脚本测试：

#!/bin/bash
export AZP_TOKEN=$(curl 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=499b84ac-1321-427f-aa17-267ca6975798' -H Metadata:true | jq -r '.access_token')
export AZP_URL="https://dev.azure.com/yourorg"
export RESPONSE=$(curl -s -H "Authorization: Bearer $AZP_TOKEN" -H "Content-Type: application/json" "$AZP_URL/_apis/projects?api-version=6.0-preview")
echo $RESPONSE

如果返回项目列表，说明托管身份已正确配置。

3. 代理配置脚本

关键的配置脚本应包含以下内容：

#!/bin/bash

# 获取托管身份令牌
export AZP_TOKEN=$(curl 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=499b84ac-1321-427f-aa17-267ca6975798' -H Metadata:true | jq -r '.access_token')

# 设置必要环境变量
export AZP_URL="https://dev.azure.com/yourorg"
export AZP_AGENT_NAME="agentname"
export AZP_POOL="poolname"
export AZP_WORK="azpwork"

# 执行代理配置
./config.sh --unattended \
  --agent "${AZP_AGENT_NAME:-$(hostname)}" \
  --url "$AZP_URL" \
  --auth "PAT" \  # 注意这里必须使用PAT认证类型
  --token "$AZP_TOKEN" \
  --pool "${AZP_POOL:-Default}" \
  --work "${AZP_WORK:-_work}" \
  --replace \
  --acceptTeeEula

# 安装并启动服务
./svc.sh install
./svc.sh start

关键注意事项

1. 认证类型选择：尽管使用托管身份令牌，但在配置代理时仍需将--auth参数设置为"PAT"，这是当前实现的一个特殊要求。

2. 权限配置：确保托管身份在Azure DevOps组织中具有足够的权限，至少需要代理池的管理员权限。

3. 令牌有效期：托管身份令牌默认有效期为24小时，代理会自动处理令牌刷新。

4. 网络连接：确保VM能够访问Azure Instance Metadata Service(169.254.169.254)和Azure DevOps服务端点。

常见问题排查

如果遇到"VS30063: You are not authorized to access"错误，请检查：

1. 托管身份是否正确分配给了VM
2. 托管身份是否已添加到Azure DevOps组织
3. 托管身份是否具有代理池的适当权限
4. 认证类型是否正确设置为"PAT"

安全最佳实践

1. 遵循最小权限原则，仅授予托管身份必要的权限
2. 定期审计托管身份的访问权限
3. 考虑使用专用代理池隔离不同安全级别的构建任务
4. 监控代理活动日志以检测异常行为

通过采用托管身份认证方式，可以显著提高Azure Pipelines代理的安全性和可管理性，同时减少手动凭证管理的负担。