Backstage 使用 Azure EasyAuth 提供商接入 Microsoft Entra ID 认证配置、源码原理与故障排查【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南聚焦 Backstage 的azureEasyAuth认证提供商讲解如何为托管在 Azure PaaS典型如 Azure App Services上的 Backstage 接入 Microsoft Entra ID原 Azure Active Directory认证。读完本文你将掌握在 Azure 侧启用 EasyAuth 与 Token Store 的完整配置、在app-config.yaml与后端代码中接入该提供商的具体步骤、三种内置 Sign-In Resolver 的选型逻辑以及该提供商底层基于请求头令牌与运行环境校验的源码级实现原理。一、什么是 Azure EasyAuth 提供商Backstage 的core-plugin-api包内置了微软认证能力而azureEasyAuth提供商是其针对 AzurePaaS 托管场景的专用实现。它面向支持 Easy AuthApp Service 认证的 Azure 服务典型代表是Azure App Services。与传统的 OAuth 流程不同EasyAuth 提供商并不由 Backstage 主动发起 OAuth 授权码交换而是复用 Azure 平台层已经完成的认证结果App Services 的 EasyAuth 在请求到达你的应用之前会把用户的 ID Token 和 Access Token 注入到 HTTP 请求头中Backstage 端只需读取并解析这些令牌即可完成登录。这意味着 Backstage 不需要维护客户端密钥、也不需要自行对接login.microsoftonline.com认证链路完全托管在 Azure 平台侧。该提供商的实现位于 plugins/auth-backend-module-azure-easyauth-provider包名为backstage/plugin-auth-backend-module-azure-easyauth-provider。二、Azure 侧配置以 App Services 为例如何配置 Azure 取决于你托管 Backstage 的具体服务。对于Azure App Services需要完成两件事开启 Entra ID原 Azure Active Directory认证启用 Token Store——这是关键前提EasyAuth 只有在 Token Store 开启时才会把令牌注入请求头。下面的示例展示了如何通过 bicep 模板完成上述配置resource webApp Microsoft.Web/sites2022-03-01 existing { name: MY-WEBAPP-NAME resource authConfig config { name: authsettingsV2 properties: { globalValidation: { redirectToProvider: AzureActiveDirectory requireAuthentication: true unauthenticatedClientAction: RedirectToLoginPage } login: { tokenStore: { enabled: true } } platform: { enabled: true } identityProviders: { azureActiveDirectory: { enabled: true login: { loginParameters: [ domain_hintMYCOMPANY.COM ] } registration: { clientId: CLIENT-ID clientSecretSettingName: CLIENT-SECRET-NAME openIdIssuer: https://sts.windows.net/${tenant().tenantId}/v2.0 } } } } } }配置要点说明globalValidation.requireAuthentication: true表示所有请求必须先通过 EasyAuth 认证unauthenticatedClientAction: RedirectToLoginPage会把未认证用户重定向到微软登录页login.tokenStore.enabled: true开启 Token StoreBackstage 才能从请求头拿到令牌identityProviders.azureActiveDirectory.registration中的clientId是你的应用注册App Registration客户端 IDclientSecretSettingName指向保存客户端机密的 App Service 应用设置名openIdIssuer使用sts.windows.net的 v2.0 端点loginParameters中的domain_hint可减小多租户场景下用户的登录摩擦。三、在 app-config.yaml 中启用提供商在app-config.yaml的根级auth配置下添加如下内容auth: providers: azureEasyAuth: signIn: resolvers: # 更多 resolver 见后续章节 - resolver: idMatchingUserEntityAnnotation注意azureEasyAuth是代理proxy型提供商不需要配置clientId/clientSecret/tenantId因为它不直接发起 OAuth 流程而是信任 Azure 平台注入的令牌。四、Sign-In Resolvers身份到 Catalog 实体的映射该提供商开箱即用地提供了多个 Resolver用于把认证结果映射到 Backstage 软件目录Catalog中的 User 实体emailMatchingUserEntityProfileEmail用认证方返回的邮箱地址匹配spec.profile.email相同的 User 实体找不到匹配会抛出NotFoundError。emailLocalPartMatchingUserEntityName用邮箱地址的本地部分local part即之前的部分匹配name相同的 User 实体找不到匹配会抛出NotFoundError。idMatchingUserEntityAnnotation用认证方返回的用户 Id 匹配带有graph.microsoft.com/user-id注解的 User 实体找不到匹配会抛出NotFoundError。注意多个 Resolver 会按顺序依次尝试但只有抛出NotFoundError时才会跳过当前 Resolver 继续下一个其他类型的错误会直接中断登录流程。如果内置 Resolver 不满足需求可以参考 Building Custom Resolvers 章节自行实现自定义 Resolver。Resolver 的源码级实现从源码看idMatchingUserEntityAnnotation的实现位于 resolvers.ts它从info.result.fullProfile.id取出用户 Id若为空则抛出Error(User profile contained no id)随后调用ctx.signInWithCatalogUser按graph.microsoft.com/user-id注解匹配 Catalog 用户。它还暴露了一个可选配置项dangerouslyAllowSignInWithoutUserInCatalog开启后当 Catalog 中找不到对应用户时会以{ entityRef: { name: id } }作为兜底实体引用完成登录——该选项名称中的 dangerously 提示这是一个需要谨慎使用的逃生门。此外模块注册时还合并了通用 Resolver在 module.ts 中可以看到signInResolverFactories同时包含...commonSignInResolvers与...azureEasyAuthSignInResolvers这意味着你还可以使用plugin-auth-node提供的公共 Resolver。五、后端安装与注册1. 安装依赖包在 Backstage 根目录执行yarn --cwd packages/backend add backstage/plugin-auth-backend-module-azure-easyauth-provider2. 注册后端模块在packages/backend/src/index.ts中添加注册代码backend.add(import(backstage/plugin-auth-backend)); /* highlight-add-start */ backend.add( import(backstage/plugin-auth-backend-module-azure-easyauth-provider), ); /* highlight-add-end */模块的默认导出authModuleAzureEasyAuthProvider通过createBackendModule注册为auth插件的azure-easyauth-provider子模块见 module.ts并使用createProxyAuthProviderFactory将azureEasyAuthAuthenticator注册为azureEasyAuth提供商。六、前端接入Sign-In with Proxy Providers前端需要将azureEasyAuth作为提供商名称配置到登录页。具体的 Sign-In 页面搭建方法参见 Sign-In with Proxy Providers该文档同时覆盖了本地开发的平滑处理方式。需要特别指出如果你提供了自定义 Sign-In Resolver可以完全省略signIn配置块——此时提供商只负责认证登录身份映射完全交给自定义 Resolver 处理。七、源码原理令牌来源与环境校验1. 从请求头解析令牌EasyAuth 提供商的核心认证逻辑在 authenticator.ts它定义了两个关键请求头常量x-ms-token-aad-id-tokenID Token与x-ms-token-aad-access-tokenAccess Token这两个头部由 Azure App Services 的 EasyAuth 平台注入认证时若缺少x-ms-token-aad-id-token头会抛出AuthenticationError(Missing x-ms-token-aad-id-token header)拿到 ID Token 后用jose的decodeJwt解码并校验claims.ver必须为2.0否则抛出id_token is not version 2.0从令牌声明中提取oid用户 Id、name显示名、email、preferred_username构造 Passport Profile 对象Access Token 会原样透传作为providerInfo.accessToken提供给后续流程使用。2. 运行时环境强校验这是该提供商最重要的安全设计由于 Backstage 完全信任请求头中的令牌一旦部署在非 Azure App Services环境例如直连公网、或配置不当的容器攻击者可以轻易伪造请求头冒充任意用户。为此 module.ts 在模块初始化时强制校验四个环境变量任一不满足即拒绝启动环境变量要求校验失败时的错误信息WEBSITE_SKU必须已定义Backstage is not running on Azure App ServicesWEBSITE_AUTH_ENABLED必须为trueAzure App Services does not have authentication enabledWEBSITE_AUTH_DEFAULT_PROVIDER必须为azureactivedirectoryAuthentication provider is not Entra IDWEBSITE_AUTH_TOKEN_STORE必须为trueToken Store is not enabled这四项校验有明确出处注释中引用了AzureAD/microsoft-identity-web项目中AppServicesAuthenticationInformation的既有实现逻辑其核心目的是确认 Backstage 确实运行在正确配置的 Azure App Services 之上。八、测试验证理解预期行为仓库中的测试用例可以帮你快速验证对提供商行为的理解authenticator.test.ts 覆盖了三种成功/失败场景提供合法ver: 2.0的 ID Token 时认证成功并正确解析出fullProfile同时提供 Access Token 时其会透传到providerInfo缺少 ID Token 抛出Missing x-ms-token-aad-id-token header令牌非法抛出JWTInvalid令牌版本为1.0时抛出id_token is not version 2.0。module.test.ts 逐一验证了第四节中的四项环境校验在非 App Services 环境、认证未开启、默认提供商非 Entra ID、Token Store 未开启四种情况下后端启动都会以对应错误信息失败只有四项环境变量全部满足时才成功启动。这意味着当你遇到 Backstage is not running on Azure App Services 之类的启动报错时应优先检查部署环境与上述四个环境变量。九、常见问题与排查要点后端启动即失败报Backstage is not running on Azure App Services确认 Backstage 确实运行在 Azure App Services 上且WEBSITE_SKU环境变量存在本地开发时该提供商无法启动请改用 Azure 标准 OAuth 提供商。报Token Store is not enabled回到 bicep 配置确保login.tokenStore.enabled已设为true且WEBSITE_AUTH_TOKEN_STOREtrue。登录成功但无法解析用户检查 Catalog 中的 User 实体是否带有graph.microsoft.com/user-id注解使用idMatchingUserEntityAnnotation时或spec.profile.email/name与认证信息一致也可以考虑启用dangerouslyAllowSignInWithoutUserInCatalog作为临时兜底。本地开发如何联调EasyAuth 依赖 App Services 平台注入令牌本地无法直接模拟建议参考 Sign-In with Proxy Providers 中关于本地开发的处理建议。通过以上配置托管在 Azure App Services 上的 Backstage 即可实现零密钥维护的 Entra ID 登录认证、令牌注入与续期全部由 Azure 平台托管Backstage 侧只负责解析与身份映射同时借助严格的环境校验守住安全底线。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考