Backstage 接入 Auth0 身份认证Provider 配置、后端模块与登录实践全指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageAuth0 是 Backstage 内置的 OAuth 认证 Provider 之一可通过标准的 OAuth 2.0 / OIDC 流程让用户使用 Auth0 账号登录开发门户。本文以仓库中 docs/auth/auth0/provider.md 为核心骨架结合backstage/plugin-auth-backend-module-auth0-provider的源码实现与测试用例完整讲解 Auth0 应用创建、app-config.yaml配置、后端模块安装、前端登录页接入与身份解析器Sign-in Resolver的使用帮助你在自己的 Backstage 实例中快速、安全地落地 Auth0 登录。前置认知Backstage 认证体系中的 Auth0在 Backstage 的认证体系中详见 docs/auth/index.md内置认证 Provider 处理特定服务的认证流程包括所需 scope、回调等负责两件事Sign-in登录身份识别将 Auth0 外部身份映射为 Backstage 用户身份访问委托Access Delegation代表用户向第三方资源请求访问权限。Auth0 是核心库中内置的 Provider 之一前端由core-plugin-api提供认证 API 引用后端由独立的后端模块backstage/plugin-auth-backend-module-auth0-provider提供实现源码见 plugins/auth-backend-module-auth0-provider。该模块通过createBackendModule注册providerId: auth0并复用backstage/plugin-auth-node中的createOAuthProviderFactory与commonSignInResolvers见 module.ts。第一步在 Auth0 控制台创建应用登录 Auth0 Dashboard导航到Applications创建 ApplicationNameBackstage或你的自定义应用名Application typeSingle Page Web Application进入Settings标签页在Application URIsAllowed Callback URLs中加入回调地址http://localhost:7007/api/auth/auth0/handler/frame点击Save Changes保存。回调路径中的/handler/frame是 Backstage 前端 OAuth 弹窗/iframe 流程使用的回调端点。若前端配置了实验性重定向流程enableExperimentalRedirectFlow回调地址规则会有所不同可参见 docs/auth/index.md。第二步在 app-config.yaml 中配置 Auth0 Provider在app-config.yaml的根级auth配置下添加 Provider 配置auth: environment: development providers: auth0: development: clientId: ${AUTH_AUTH0_CLIENT_ID} clientSecret: ${AUTH_AUTH0_CLIENT_SECRET} domain: ${AUTH_AUTH0_DOMAIN_ID} audience: ${AUTH_AUTH0_AUDIENCE} connection: ${AUTH_AUTH0_CONNECTION} connectionScope: ${AUTH_AUTH0_CONNECTION_SCOPE} organization: ${AUTH_AUTH0_ORGANIZATION_ID} ## uncomment to let Auth0 determine whether to prompt the user # prompt: auto ## uncomment to set lifespan of user session # sessionDuration: { hours: 24 } # supports ms library format (e.g. 24h, 2 days), ISO duration, human duration as used in code session: secret: ${AUTH_SESSION_SECRET}必填配置项配置键说明clientIdAuth0 Application 的 Client ID在 Auth0 Application 页面查看clientSecretAuth0 Application 的 Client Secret在 Auth0 Application 页面查看domainAuth0 Application 的 Domain在 Auth0 Application 页面查看如your-tenant.auth0.comsession.secret会话密钥用于对应用设置的 Cookie 进行签名和/或加密以维持会话状态应替换为仅你的应用知晓的、足够长且复杂唯一的随机字符串Auth0 登录依赖会话session因此必须为session配置secret。从源码看clientId、clientSecret、domain三个键在 authenticator.ts 中通过config.getString(...)强制读取缺任一配置都会在模块初始化阶段直接报错而audience、connection、connectionScope、prompt、organization均通过config.getOptionalString(...)读取见 authenticator.ts为可选配置。可选配置项配置键说明audienceToken 的目标接收方intended recipients标识connection社交身份提供商名称可用社交连接列表参见 Auth0 Social Connections 市场connectionScope交互式 Token 请求中的附加 scope必须与connection参数组合使用prompt控制发送给 Auth0 的 prompt 参数。设为auto时省略该参数由 Auth0 自行决定是否提示用户其他值原样透传给 Auth0。默认值为consentsessionDuration用户会话的存活时长支持ms库格式如24h、2 days、ISO 时长格式及代码中使用的人类可读时长格式organization指定登录流程中要定向的特定组织 IDcallbackUrl覆盖默认回调地址可选federatedLogout是否执行联合登出同时清除 Auth0 会话与上游 IdP 会话默认false以上配置项与模块中的类型定义一一对应完整 schema 见 config.d.ts。其中clientSecret在 schema 中被标记为visibility secretclientId标记为visibility frontend——前者确保敏感信息不会下发到前端。配置项的底层行为源码级解读在 authenticator.ts 的initialize阶段prompt未配置时默认取consentconfig.getOptionalString(prompt) ?? consent配置prompt: auto时start阶段会通过...(prompt ! auto ? { prompt } : {})将该参数从授权请求中完全省略见 authenticator.tsaudience、connection、connectionScope在start与authenticate阶段都会作为附加参数传给 Auth0start阶段固定附带accessType: offline用于请求 Refresh Token支撑后续的 token 刷新与长期会话。此外由于passport-auth0强制options.state true而passport-oauth2在 state 开启时需要 express-session 存储 state 参数实现中通过一个与passport-oauth2中NullStore行为一致的 StateStore 桩实现规避了对 express-session 的依赖见 authenticator.ts这使得 Backstage 后端无需额外引入会话中间件即可与 Auth0 集成。domain的另一处关键作用体现在 strategy.ts模块基于domain动态拼接 Auth0 的四个端点——https://{domain}/authorize授权端点、https://{domain}/oauth/token令牌端点、https://{domain}/userinfo用户信息端点与https://{domain}/api。组织登录Organization的特殊行为配置organization后strategy.ts 会校验请求 query 中携带的organization参数若请求中的组织与策略中配置的组织不一致会抛出InputErrorOrganization mismatch. ...。同时该策略还支持透传invitation组织邀请、screen_hint、login_hint等请求参数到 Auth0 授权流程。第三步后端安装 Auth0 Provider 模块从 Backstage 根目录执行yarn --cwd packages/backend add backstage/plugin-auth-backend-module-auth0-provider然后在packages/backend/src/index.ts中注册模块import { createBackend } from backstage/backend-defaults; //... backend.add(import(backstage/plugin-auth-backend)); // highlight-add-next-line backend.add(import(backstage/plugin-auth-backend-module-auth0-provider)); //...模块的默认导出是authModuleAuth0Provider见 index.ts注册时声明了对authProvidersExtensionPoint与coreServices.cache的依赖前者用于向 auth 插件注册auth0Provider后者用于 token 刷新时的用户资料缓存详见下文刷新与缓存小节。第四步前端登录页接入新版前端系统New Frontend System在packages/app/src/App.tsx中通过SignInPageBlueprint定义登录页并传入 Auth0 的auth0AuthApiRefimport { createApp } from backstage/frontend-defaults; import catalogPlugin from backstage/plugin-catalog/alpha; import { navModule } from ./modules/nav; import { auth0AuthApiRef } from backstage/core-plugin-api; import { SignInPageBlueprint } from backstage/plugin-app-react; import { SignInPage } from backstage/core-components; import { createFrontendModule } from backstage/frontend-plugin-api; const signInPage SignInPageBlueprint.make({ params: { loader: async () props ( SignInPage {...props} provider{{ id: auth0-auth-provider, title: Auth0, message: Sign in using Auth0, apiRef: auth0AuthApiRef, }} / ), }, }); export default createApp({ features: [ catalogPlugin, navModule, createFrontendModule({ pluginId: app, extensions: [signInPage], }), ], });SignInPage会在应用其他路由渲染前呈现负责提供当前用户身份用户成功登录后通过onSignInSuccess回调获得合法的 Backstage 身份其余应用才被渲染参见 docs/auth/index.md。若同时启用多种登录方式例如开发环境允许 Guest 登录可将provider换成providers数组也可基于configApi.getString(auth.environment)条件渲染在生产环境仅展示 Auth0 入口完整示例见 docs/auth/index.md。关于 auth0AuthApiRef 的重要迁移说明需要特别指出auth0AuthApiRef属于backstage/core-plugin-api中因过于通用、缺乏实际契约而被弃用并最终移除的 Utility API Ref与oauth2ApiRef、oidcAuthApiRef、samlAuthApiRef一同处理见 docs/api/deprecations.md。如果你使用的是较新版本依赖应按如下方式自定义 API Ref 并基于OAuth2工厂实现// 在 packages/app/src/apis.ts或共享包中定义 export const acmeAuthApiRef: ApiRef OAuthApi OpenIdConnectApi ProfileInfoApi BackstageIdentityApi SessionApi createApiRef({ id: internal.auth.auth0, });// 工厂实现替换原 auth0AuthApiRef 的用法 createApiFactory({ api: acmeAuthApiRef, deps: { discoveryApi: discoveryApiRef, oauthRequestApi: oauthRequestApiRef, configApi: configApiRef, }, factory: ({ discoveryApi, oauthRequestApi, configApi }) OAuth2.create({ discoveryApi, oauthRequestApi, provider: { id: auth0, title: Auth0, icon: () null, }, defaultScopes: [openid, email, profile], environment: configApi.getOptionalString(auth.environment), }), });如需在设置页展示该 Provider还需在packages/app/src/App.tsx的 settings 路由中通过ProviderSettingsItem将acmeAuthApiRef传入UserSettingsPage。完整迁移步骤参见 docs/api/deprecations.md。第五步配置 Sign-in Resolver 映射用户身份默认情况下每个 Backstage 认证 Provider 仅用于访问委托若要用 Auth0 登录用户必须显式配置 sign-in 并选择身份解析器详见 docs/auth/identity-resolver.md。Auth0 模块内置了以下开箱即用的 ResolveremailMatchingUserEntityProfileEmail将 Auth0 提供的邮箱地址与 Software Catalog 中spec.profile.email匹配的 User 实体对应未匹配到时抛出NotFoundErroremailLocalPartMatchingUserEntityName将 Auth0 邮箱地址的本地部分之前的局部名与 Catalog 中name匹配的 User 实体对应未匹配到时抛出NotFoundError。多个 Resolver 会按顺序尝试但只有在抛出NotFoundError时才会跳过当前解析器、继续尝试下一个。在app-config.yaml中 Auth0 Provider 配置旁添加signIn.resolversauth: environment: development providers: auth0: development: clientId: ${AUTH_AUTH0_CLIENT_ID} clientSecret: ${AUTH_AUTH0_CLIENT_SECRET} domain: ${AUTH_AUTH0_DOMAIN_ID} signIn: resolvers: - resolver: emailMatchingUserEntityProfileEmail若内置 Resolver 无法满足需求可参考 docs/auth/identity-resolver.md#building-custom-resolvers 构建自定义 Resolver。需要注意只应为一个认证 Provider 配置单个 sign-in resolver多 Provider/多 Resolver 登录会增加账户劫持风险。从模块实现看后端在注册 Provider 时通过createOAuthProviderFactory({ authenticator, signInResolverFactories: { ...commonSignInResolvers } })将通用 Resolver 集挂载到auth0Provider 上见 module.ts因此上述两个 Resolver 可直接以字符串形式在配置中引用。进阶原理Token 刷新、资料缓存与登出backstage/plugin-auth-backend-module-auth0-provider的 authenticator.ts 对 OAuth 生命周期做了完整实现刷新与缓存refresh刷新时先通过PassportHelpers.executeRefreshTokenStrategy使用 Refresh Token 换取新令牌再解码新id_token中的sub声明作为缓存键auth0-profile:${sub}。命中缓存则直接复用用户资料避免重复请求 Auth0 的/userinfo缓存未命中时通过helper.fetchProfile(accessToken)拉取资料并以 1 分钟 TTL 写入缓存见 [authenticator.ts](https://link.gitcode.com/i/b9813af99e9b93006315155f236d7c82#L31-L34, L143-L178)。这一行为被 authenticator.test.ts 的测试用例覆盖同一sub二次刷新时不再调用fetchProfile而sub变化不同用户时会重新拉取资料。若id_token中不含sub则绕过缓存直接拉取资料。登出logout登出时构造https://{domain}/v2/logout登出端点附带client_id若配置了federatedLogout: true则追加federated参数以同时清除上游 IdP 会话若请求携带origin头则作为returnTo参数传回见 authenticator.ts。小结将 Auth0 接入 Backstage 的完整链路可以概括为四步① 在 Auth0 控制台创建 Single Page Web Application 并配置回调地址 → ② 在app-config.yaml的auth.providers.auth0下填写clientId/clientSecret/domain及可选参数并配置session.secret→ ③ 安装并注册backstage/plugin-auth-backend-module-auth0-provider后端模块 → ④ 在前端通过SignInPage与 Auth0 认证 API 接入登录并配置 sign-in resolver 完成用户身份映射。实际落地时请留意两处易错点其一auth0AuthApiRef已从core-plugin-api中移除需按 docs/api/deprecations.md 的指引自定义 API Ref其二session.secret是硬性要求且应使用足够长的随机字符串。以上配置与代码示例均可在当前仓库的 docs/auth/auth0/provider.md、plugins/auth-backend-module-auth0-provider 及 docs/auth/index.md 中找到对应依据可直接对照验证。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考