Backstage Azure DevOps 集成配置指南:认证方式与多组织支持全解析
Backstage Azure DevOps 集成配置指南:认证方式与多组织支持全解析
Azure DevOps(dev.azure.com)是 Backstage 软件目录(Software Catalog)最常用的源码托管集成之一。本文基于 Backstage 官方文档与仓库源码(packages/integration/src/azure/)全面讲解如何将存放在 Azure DevOps 中的源码接入 Backstage Catalog,重点覆盖服务主体(Service Principal)、托管身份(Managed Identity)、个人访问令牌(PAT)等多种认证方式,以及面向多组织、跨租户、旧版 {org}.visualstudio.com 域名等真实场景的配置技巧。读完本文,你将能够根据自身安全与运维要求,为 Backstage 配置一套正确、可维护的 Azure DevOps 集成。
Azure DevOps 集成能做什么
Azure DevOps 集成允许 Backstage 从 Azure DevOps 加载 Catalog 实体(Entity)。实体既可以添加到静态目录配置中,也可以通过 catalog-import 插件在界面上注册导入。无论是哪种方式,Backstage 后端都需要通过集成配置获得访问 Azure DevOps API 的凭据。
从源码结构看,Azure 集成主要由以下模块构成:
- 配置解析:读取
integrations.azure配置段并校验凭据合法性; - 凭据分发:根据目标 URL 的 host 与组织名匹配对应的凭据;
- 凭据获取与缓存:负责换取并缓存访问令牌(Access Token);
- URL 解析:处理带
path查询参数等特殊形式的 Azure 仓库 URL。
认证方式总览
Azure 集成支持多种认证方式,不同方式在安全性、配置复杂度和适用环境上各有侧重:
| 认证方式 | 凭据种类 | 适用场景 | 配置字段 |
|---|---|---|---|
| 服务主体 + 客户端密钥(Client Secret) | ClientSecret |
有独立应用注册(App Registration)的团队 | clientId、clientSecret、tenantId |
| 系统分配托管身份 | ManagedIdentity |
Backstage 部署在 Azure 资源上,希望免密钥管理 | clientId: system-assigned |
| 用户分配托管身份 | ManagedIdentity |
同一托管身份复用于多个 Azure 资源 | clientId: <托管身份 Client ID> |
| 个人访问令牌(PAT) | PersonalAccessToken |
本地开发、Azure DevOps Server、快速验证 | personalAccessToken |
| 服务主体 + 托管身份签发客户端断言(Client Assertion) | ManagedIdentityClientAssertion |
跨租户认证等高级场景,密钥零管理 | clientId、managedIdentityClientId、tenantId |
其中“服务主体”本质是 Entra ID(原 Azure Active Directory)中的一个身份,拥有客户端 ID 与客户端密钥(相当于用户名与密码);而托管身份(Managed Identity)是 Entra ID 中绑定到特定 Azure 资源的身份,由 Azure 负责管理其生命周期与密钥。
你还可以为不同的 Azure DevOps 组织分别配置不同的认证方式——当你拥有多个组织且各组织需要(或不得不)使用不同凭据时,这一能力非常实用。
方式一:使用服务主体与客户端密钥
服务主体是 Entra ID 身份,通过 clientId + clientSecret(类比用户名 + 密码)认证。配置示例如下:
integrations:
azure:
- host: dev.azure.com
credentials:
- clientId: ${AZURE_CLIENT_ID}
clientSecret: ${AZURE_CLIENT_SECRET}
tenantId: ${AZURE_TENANT_ID}
三个字段对应源码中的 AzureClientSecretCredential 类型(config.ts):
clientId:服务主体的客户端 ID;clientSecret:服务主体的客户端密钥;tenantId:服务主体所在的 Entra ID 租户 ID。
运行时,CachedAzureDevOpsCredentialsProvider 会使用 @azure/identity 的 ClientSecretCredential(tenantId, clientId, clientSecret) 换取访问令牌,并以 Bearer <token> 的形式附加到请求头。
方式二:使用托管身份(Managed Identity)
托管身份分为系统分配(system-assigned)与用户分配(user-assigned)两种。
系统分配托管身份
系统分配托管身份与某个具体 Azure 资源绑定,生命周期随资源同生共死,Azure 保证该身份只能被这个特定资源使用:
integrations:
azure:
- host: dev.azure.com
credentials:
- clientId: system-assigned
用户分配托管身份
用户分配托管身份是用户单独创建、可挂载到多个 Azure 资源的独立身份,适合多资源复用的场景:
integrations:
azure:
- host: dev.azure.com
credentials:
- clientId: ${AZURE_CLIENT_ID}
源码中对应 AzureManagedIdentityCredential 类型(config.ts),clientId 取 system-assigned 时构造无参的 ManagedIdentityCredential(),否则传入指定的 Client ID(CachedAzureDevOpsCredentialsProvider.ts)。这意味着 Backstage 应运行在启用了对应托管身份的 Azure 环境(如 Azure VM、App Service、Container Instance)中,Azure 会为它自动颁发令牌。
注意:托管身份认证仅适用于由 Microsoft Entra ID 托管的 Azure DevOps 组织,且只能用于
dev.azure.com云端服务,不能用于 Azure DevOps Server(本地部署版)。
方式三:使用个人访问令牌(PAT)
PAT 是你在 Azure DevOps 中按需生成、带有指定作用域(Scope)和有效期(Expiration)的令牌,Backstage 可以代表你访问 Azure DevOps:
integrations:
azure:
- host: dev.azure.com
credentials:
- personalAccessToken: ${PERSONAL_ACCESS_TOKEN}
几点关键说明:
- PAT 必须以原始字符串形式提供(
raw_token格式),不要做 Base64 编码——格式化和 Base64 转换由底层依赖库在处理 Azure DevOps API 时自动完成; - 从源码看,PAT 凭据在请求头中以
Basic认证呈现(Authorization: Basic base64(:token)),而其他基于 Entra ID 的凭据则以Bearer <token>呈现; - 在与
dev.azure.com不同的 host(例如 Azure DevOps Server 或旧版visualstudio.com域名)上,只允许使用 PAT,这是配置解析阶段就强制校验的规则(config.ts)。
方式四:服务主体 + 托管身份签发客户端断言(高级场景)
当你想让托管身份代替你为某个服务主体生成“客户端断言”(Client Assertion,即 JWT)时,需要使用这种方式。它最典型的用途是跨租户认证;如果只是普通单租户场景,直接使用系统分配托管身份通常更合适。
前置步骤:在 Entra ID 中添加联合凭据(Federated Credential)
要使用托管身份生成客户端断言,必须先为应用注册(App Registration)配置联合凭据:
- 在 Entra ID 中创建一个应用注册(或使用已有应用注册);
- 进入该应用注册的 “Certificates & secrets” 标签页;
- 使用 “Customer managed keys” 场景添加一个新的联合凭据;
- 选择用于生成客户端断言的那个托管身份;
- 填写名称与描述;
- 点击 “Add” 完成添加。
完成后,在 Backstage 中补充如下配置。其中 ${APP_REGISTRATION_CLIENT_ID} 是添加了联合凭据的应用注册的客户端 ID。
使用系统分配托管身份生成客户端断言
这是最安全的选项——Azure 保证该身份只能被绑定它的特定资源使用,而用户分配托管身份可能被同租户内的任意资源挂载:
integrations:
azure:
- host: dev.azure.com
credentials:
- clientId: ${APP_REGISTRATION_CLIENT_ID}
managedIdentityClientId: system-assigned
tenantId: ${AZURE_TENANT_ID}
使用用户分配托管身份生成客户端断言
integrations:
azure:
- host: dev.azure.com
credentials:
- clientId: ${APP_REGISTRATION_CLIENT_ID}
managedIdentityClientId: ${MANAGED_IDENTITY_CLIENT_ID}
tenantId: ${AZURE_TENANT_ID}
底层原理
从源码看,这条链路对应 AzureManagedIdentityClientAssertionCredential(config.ts)与 ManagedIdentityClientAssertion:
- 使用
ManagedIdentityCredential向 Azure 令牌服务申请访问令牌,请求的 scope 为api://AzureADTokenExchange; - 将该令牌作为客户端断言传给
@azure/identity的ClientAssertionCredential(tenantId, clientId, () => assertion)(CachedAzureDevOpsCredentialsProvider.ts),从而以服务主体的身份换取 Azure DevOps 访问令牌; - 断言会被缓存复用,仅当距离过期时间不足 5 分钟时才重新获取(ManagedIdentityClientAssertion.ts)。
系统分配托管身份之所以被推荐为最安全选项,原因有二:
- Azure 保证该身份只能被绑定资源使用,而用户分配托管身份可被任意资源使用;
- 无需自行管理底层密钥,密钥的轮换与保管由 Azure 全权负责。
多组织认证:按组织分发凭据
当你有多个 Azure DevOps 组织时,可以在凭据上通过 organizations 字段指定它适用于哪些组织:
integrations:
azure:
- host: dev.azure.com
credentials:
- organizations:
- my-org
- my-other-org
clientId: ${AZURE_CLIENT_ID}
clientSecret: ${AZURE_CLIENT_SECRET}
tenantId: ${AZURE_TENANT_ID}
- organizations:
- another-org
clientId: ${AZURE_CLIENT_ID}
- organizations:
- yet-another-org
personalAccessToken: ${PERSONAL_ACCESS_TOKEN}
分发规则与源码中的实现完全一致:
- 如果凭据没有指定
organizations字段,它将被用作所有未配置专属凭据的组织的兜底凭据(fallback); - 凭据提供器会按
host/组织名建立凭据映射,解析请求 URL 时依次匹配dev.azure.com/{organization}、Azure DevOps Server 的/tfs/{organization}路径、旧版{org}.visualstudio.com域名,最后回落到按 host 匹配的默认凭据; - 配置校验还会检测同一个组织被多个凭据重复指定的情况,并直接抛出配置错误(config.ts);
- 每个 host 上不带
organizations的凭据最多只能有一个(config.ts)。
跨租户认证:其他租户中的 Azure DevOps 组织
当需要认证的 Azure DevOps 组织与服务主体不在同一个 Entra ID 租户时,你需要:
重要提示:请确保你的应用至少请求一项 Graph API 权限,这是应用能在其他租户中被安装的前提。所需权限的最小集是类型为
Delegated的openid权限,用户实际上无法完成登录。
转换完成后,由目标租户的管理员访问以下 URL 为应用提供管理员同意(Admin Consent):
https://login.microsoftonline.com/<other-tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=<redirect-uri>
参数说明:
<other-tenant-id>:目标(其他)租户的租户 ID;<client-id>:你所在租户中应用注册的客户端 ID;<redirect-uri>:应用注册中配置的重定向 URI。它必须是应用注册中真实存在的合法 URI,但实际用途不限,例如https://backstage.io即可。
管理员同意后,目标租户内会创建一个与应用注册同 Client ID 的企业应用(Enterprise Application,即 Service Principal)。此时即可为该服务主体授予目标租户内 Azure DevOps 组织的访问权限,并在 Backstage 中改用目标租户的租户 ID 进行认证:
integrations:
azure:
- host: dev.azure.com
credentials:
- clientId: ${APP_REGISTRATION_CLIENT_ID}
managedIdentityClientId: system-assigned
tenantId: ${OTHER_TENANT_ID}
其中 ${APP_REGISTRATION_CLIENT_ID} 是你自己租户中创建的多租户应用注册的客户端 ID,${OTHER_TENANT_ID} 是目标租户的租户 ID。
上面的示例使用的是系统分配托管身份生成客户端断言;你也可以改用用户分配托管身份生成客户端断言,或直接使用客户端密钥为该应用认证。不过如前文所述,系统分配托管身份由于身份唯一绑定、密钥零管理,仍是跨租户场景下最安全的选择。
旧版 {org}.visualstudio.com 域名
Backstage 同时支持旧版 {org}.visualstudio.com 域名,以上所有认证方式均可使用。唯一的限制是:每个 Azure DevOps 组织都需要在配置中单独定义一个 host 条目,并且每个 host 只能配置一个凭据。
下面的写法是合法的(服务主体方式):
integrations:
azure:
- host: my-org.visualstudio.com
credentials:
- clientId: ${AZURE_CLIENT_ID}
clientSecret: ${AZURE_CLIENT_SECRET}
tenantId: ${AZURE_TENANT_ID}
以下写法同样合法(PAT 方式):
integrations:
azure:
- host: my-other-org.visualstudio.com
credentials:
- personalAccessToken: ${PERSONAL_ACCESS_TOKEN}
但下面的写法不会生效——因为 {org}.visualstudio.com 域名下无法像 dev.azure.com 那样通过 organizations 字段区分组织,一个 host 对应一个组织、一个凭据:
integrations:
azure:
- host: my-org.visualstudio.com
credentials:
- organizations:
- my-org
- my-other-org
clientId: ${AZURE_CLIENT_ID}
clientSecret: ${AZURE_CLIENT_SECRET}
tenantId: ${AZURE_TENANT_ID}
从源码看,isVisualStudioDomain 通过判断 URL 是否以 .visualstudio.com 结尾来识别这类旧域名,凭据提供器会直接按 url.host 精确匹配对应的凭据条目(DefaultAzureDevOpsCredentialsProvider.ts)。
配置结构(Configuration Schema)详解
integrations.azure 是一个数组,每个条目包含以下元素:
host(必填):目标主机名,如dev.azure.com。目前仅支持dev.azure.com,配置缺省时源码会默认填入dev.azure.com(config.ts);credentials(可选):凭据数组,每一项必须是以下四种之一:- 使用客户端密钥的服务主体;
- 使用托管身份客户端断言的服务主体;
- 托管身份;
- 个人访问令牌。
commitSigningKey(可选):用于提交签名的密钥(对应源码中的AzureIntegrationConfig,config.ts)。
credentials 数组中每一项的字段组合是精确限定的,源码通过字段映射表强制校验(config.ts):
| 凭据类型 | 允许的字段(必须全部提供) | 禁止出现的字段 |
|---|---|---|
ClientSecret |
clientId、clientSecret、tenantId |
managedIdentityClientId、personalAccessToken |
ManagedIdentity |
clientId(system-assigned 或 Client ID) |
clientSecret、managedIdentityClientId、tenantId、personalAccessToken |
ManagedIdentityClientAssertion |
clientId、managedIdentityClientId、tenantId |
clientSecret、personalAccessToken |
PersonalAccessToken |
personalAccessToken |
clientId、clientSecret、managedIdentityClientId、tenantId |
对 ManagedIdentityClientAssertion 而言,managedIdentityClientId 的取值规则为:系统分配托管身份填字面量 system-assigned;用户分配托管身份填其 Client ID。
补充注意事项
- 服务主体 / 托管身份不适用于 Azure DevOps Server(本地部署)组织,此类环境只能使用 PAT;
- 服务主体 / 托管身份仅适用于 Microsoft Entra ID 托管的 Azure DevOps 组织(即云端
dev.azure.com); - 每个 host 上未指定组织的凭据只能有一个;
- PAT 需以原始字符串提供(
raw_token),不要预先 Base64 编码; - 用于生成客户端断言的托管身份必须与应用注册处于同一个 Entra ID 租户;
- 旧的
credential与token配置项已被移除,源码会检测到它们并直接报错,提示改用credentials(config.ts),升级配置时请务必迁移。
令牌缓存与性能考量
为了减少对 Azure 令牌服务的往返请求,CachedAzureDevOpsCredentialsProvider 会对获取到的访问令牌做缓存:
- 非 PAT 凭据以
Bearer <token>形式携带令牌,请求 scope 为499b84ac-1321-427f-aa17-267ca6975798/.default(Azure DevOps 专属 scope); - 缓存会在令牌实际过期前 10 分钟提前失效并刷新,避免因时钟偏差导致令牌在传输途中失效;
- PAT 凭据不涉及令牌交换,直接被封装为
Basic认证头。
验证与排错建议
- 检查配置是否被正确解析:可在 Backstage 后端启动日志中观察是否存在
Invalid Azure integration config ...之类的报错;凭据字段组合不合规、同一组织被重复指定、非dev.azure.comhost 使用非 PAT 凭据等都会在配置加载阶段被拒绝(config.ts); - 确认网络环境:托管身份认证要求 Backstage 后端运行在启用了对应托管身份的 Azure 资源内;本地开发调试时优先使用 PAT;
- 确认权限授予:无论采用哪种凭据,都需在 Azure DevOps 侧为对应身份(服务主体 / 托管身份 / PAT 所属用户)授予目标组织与仓库的读取权限,否则实体加载会因 401/403 失败;
- 使用静态目录配置接入:完成认证配置后,即可在静态目录配置中声明
dev.azure.com上的仓库位置,Backstage 会以该集成凭据拉取并解析其中的catalog-info.yaml实体。