Backstage Azure DevOps 集成配置指南:认证方式与多组织支持全解析

原创2026-09-11 10:16:061,727 阅读
文章标签:开发者门户前端后端插件系统代码生成文档研发协作云原生

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)配置联合凭据:

  1. 在 Entra ID 中创建一个应用注册(或使用已有应用注册);
  2. 进入该应用注册的 “Certificates & secrets” 标签页;
  3. 使用 “Customer managed keys” 场景添加一个新的联合凭据;
  4. 选择用于生成客户端断言的那个托管身份;
  5. 填写名称与描述;
  6. 点击 “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:

  1. 使用 ManagedIdentityCredential 向 Azure 令牌服务申请访问令牌,请求的 scope 为 api://AzureADTokenExchange;
  2. 将该令牌作为客户端断言传给 @azure/identity 的 ClientAssertionCredential(tenantId, clientId, () => assertion)(CachedAzureDevOpsCredentialsProvider.ts),从而以服务主体的身份换取 Azure DevOps 访问令牌;
  3. 断言会被缓存复用,仅当距离过期时间不足 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 的 email 权限——它允许应用读取已登录用户的邮箱地址;但如果没有 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.com host 使用非 PAT 凭据等都会在配置加载阶段被拒绝(config.ts);
  • 确认网络环境:托管身份认证要求 Backstage 后端运行在启用了对应托管身份的 Azure 资源内;本地开发调试时优先使用 PAT;
  • 确认权限授予:无论采用哪种凭据,都需在 Azure DevOps 侧为对应身份(服务主体 / 托管身份 / PAT 所属用户)授予目标组织与仓库的读取权限,否则实体加载会因 401/403 失败;
  • 使用静态目录配置接入:完成认证配置后,即可在静态目录配置中声明 dev.azure.com 上的仓库位置,Backstage 会以该集成凭据拉取并解析其中的 catalog-info.yaml 实体。
登录后查看全文
backstage