Azure DevOps 自托管 Agent 如何用 Service Principal 安全接入 Azure

Azure DevOps 使用服务主体配置自托管代理配置指南1. 概述2. 在 Azure AD 中创建服务主体 (SP)3. 授予 Azure DevOps 权限3.1. 组织层级用户身份与访问级别3.2. 组织层级Agent pools管理员3.3. 在 Linux VM 上安装和配置代理3.4. 启动并设置为系统服务3.5. 授予 Azure 资源权限 (可选用于部署)版本:1.0最后更新:2025年7月24日1. 概述本文档旨在提供一个安全、可靠且可重复的详细步骤指导如何在 Linux 环境下使用服务主体 (Service Principal) 作为身份验证方式成功配置和运行一个 Azure DevOps 自托管代理。好对于在生产环境或任何需要高安全性的自动化场景中最佳实践是使用服务主体 (Service Principal, SP)。服务主体 (SP)是 Azure 中一个独立的、非人类的身份标识专为应用程序、服务或自动化工具比如我们的 self-hosted agent设计。适用场景:生产环境部署:这是绝对的首选。当你的代理需要访问 Azure 资源例如部署到虚拟机、应用服务或管理资源时使用 SP 可以实现最小权限原则。自动化脚本/无人值守环境:任何不需要人工干预的场景SP 都是最理想的选择因为它不需要用户账户的生命周期管理。需要精细化权限控制:你可以为一个 SP 分配一个非常具体且权限受限的角色 (Role)比如只允许它对某个特定资源组有“参与者(Contributor)”权限。验证方式核心场景安全性推荐指数 (生产环境)Service Principal (SP)生产环境、自动化、需要访问 Azure 资源最高★★★★★ (强烈推荐)Personal Access Token (PAT)快速测试、个人项目、无云资源访问较低★★☆☆☆ (不推荐用于生产)Device code flow交互式设置、需要 MFA 的环境较高★★★☆☆ (适用于手动设置阶段)Integrated (Windows)内网域环境、与本地 AD 集成较高★★★★☆ (特定企业场景下推荐)2. 在 Azure AD 中创建服务主体 (SP)登录 Azure 门户点击侧边栏Entra ID选择应用注册注册创建一个新的服务主体。复制客户端ID和租户ID点击客户端凭据添加新的Secret。立即复制并永久保存Secret的值往后不再出现3. 授予 Azure DevOps 权限3.1. 组织层级用户身份与访问级别进入 Azure DevOpsOrganization Settings-General-Users。确认你的 服务主体 已经出现在用户列表中添加进入分配Project Contributor权限。Access Level将其修改为Basic。这是它能执行有效操作的基础。3.2. 组织层级Agent pools管理员回到Organization Settings-Pipelines-Agent pools。选择你要使用的代理池例如Default。进入Security标签页。点击Add 搜索并添加你的 SP并授予其Administrator角色。目的这是我们最关键一步。授予代理程序本身注册、连接和管理自己的权限。打开Third-party application access via OAuth它控制了 是否允许 OAuth 授权的 AAD 应用包括你创建的 Service Principal访问 Azure DevOps API3.3. 在 Linux VM 上安装和配置代理在Project层级或者组织层级选择Agent Pool添加New Agent点击Download下载vsts-agent-linux-x64-4.258.1.tar.gz包传输到Linux主机上创建目录并解压代理文件。mkdirmyagentcdmyagenttarzxvf{your_path}/vsts-agent-linux-x64-4.258.1.tar.gz ./config.sh跟随以下步骤输入Enter(Y/N)Accept the Team Explorer Everywhere license agreement now?(press enterforN)YConnect: Enter server URLhttps://dev.azure.com/{yourorganization}Enter authenticationtype(press enterforPAT)sp Enter Client(App)ID{your_Client(App)ID}Enter Tenant ID{your_Tenant ID}Enter Client secret**************************************** Connecting to server...Register Agent: Enter agent pool(press enterfordefault)default Enter agent name(press enterforMyProxy)MyProxy Scanningfortool capabilities. Connecting to the server. Successfully added the agent Testing agent connection. Enter work folder(press enterfor_work)/home/MyProxy/myagent/_work3.4. 启动并设置为系统服务安装服务为了安全建议指定一个普通用户需提前创建来运行该服务。如果使用当前用户请确保其权限适当。# 推荐以指定用户身份安装sudo./svc.shinstall[username]# 或者以 root 身份安装不推荐# sudo ./svc.sh install启动服务sudo./svc.sh start检查状态sudo./svc.sh status此时回到 DevOps 界面代理状态应为绿色的Online。3.5. 授予 Azure 资源权限 (可选用于部署)如果你的流水线需要部署 Azure 资源请确保 SP 拥有对应资源的 IAM 权限。在Azure 门户中导航到具体的目标资源如 App Service, 虚拟机。进入Access control (IAM)。点击Add role assignment将你的 SP 添加到具有最小必要权限的角色中如Website Contributor。