Backstage v1.2.0-next.3 变更日志深度解读：Kubernetes 插件 OIDC 认证支持与前端组件体验优化

Backstage v1.2.0-next.3 变更日志深度解读Kubernetes 插件 OIDC 认证支持与前端组件体验优化【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文基于仓库中 docs/releases/v1.2.0-next.3-changelog.md 展开系统梳理 Backstage v1.2.0 系列第三个预发布next.3版本中 8 个软件包的 Patch 级变更。文章以本次变更中技术含量最高的 Kubernetes 插件 OIDC 认证支持为主线结合仓库源码还原其前后端实现原理与配置方式同时覆盖core-components的无障碍改进、home/org插件增强以及scaffolder/techdocs的依赖回退帮助读者在升级到该版本时准确评估影响面并完成相应配置。版本定位v1.2.0-next.3 是什么next系列是 Backstage 官方在正式版本发布前迭代的预发布版本采用vX.Y.Z-next.N的命名约定用于在最终发布前对候选变更进行集成验证。本变更日志对应v1.2.0-next.3是v1.2.0正式版发布前的第三个迭代快照包含 8 个软件包的变更软件包变更版本变更性质backstage/core-components0.9.4-next.2Patch组件修复与无障碍改进backstage/plugin-home0.4.21-next.3PatchStarredEntities 卡片增强backstage/plugin-kubernetes0.6.5-next.3Patch新增 oidc 认证backstage/plugin-kubernetes-backend0.5.1-next.2Patch新增 oidc 认证backstage/plugin-kubernetes-common0.2.10-next.1Patch新增 oidc 认证backstage/plugin-org0.5.5-next.3PatchMyGroupSidebarItem 修复backstage/plugin-scaffolder1.2.0-next.3Patch依赖回退backstage/plugin-techdocs1.1.1-next.3Patch依赖回退值得注意的是plugin-kubernetes三个软件包前端插件、后端插件、公共类型包共享同一个变更标识447e060872表明 OIDC 认证是一次贯穿前后端的系统性能力新增。核心变更一Kubernetes 插件新增 OIDC 认证支持变更内容与意义本次变更447e060872为 Kubernetes 插件新增了oidc认证策略authProvider并引入可选的oidcTokenProvider配置项Add support for oidc as authProvider for kubernetes authentication and adds optional oidcTokenProvider config value. This will allow users to authenticate to kubernetes cluster using id tokens obtained from the configured auth provider in their backstage instance.这一能力让用户可以直接使用 Backstage 实例中已配置的认证提供方如 Okta、Microsoft、Google、GitLab、OneLogin 等颁发的 ID Token 来访问 Kubernetes API Server而无需再为每个集群单独维护 Service Account Token。这意味着只要集群启用了 OIDC 认证Backstage 用户即可借助单点登录体系无缝访问 Kubernetes 资源。后端实现OidcStrategy 认证策略在 plugins/kubernetes-backend/src/auth/OidcStrategy.ts 中实现了OidcStrategy它实现了AuthenticationStrategy接口。核心逻辑如下export class OidcStrategy implements AuthenticationStrategy { public async getCredential( clusterDetails: ClusterDetails, authConfig: KubernetesRequestAuth, ): PromiseKubernetesCredential { const oidcTokenProvider clusterDetails.authMetadata[ANNOTATION_KUBERNETES_OIDC_TOKEN_PROVIDER]; if (!oidcTokenProvider || oidcTokenProvider ) { throw new Error(oidc authProvider requires a configured oidcTokenProvider); } const token (authConfig.oidc as JsonObject | null)?.[oidcTokenProvider]; if (!token) { throw new Error( Auth token not found under oidc.${oidcTokenProvider} in request body, ); } return { type: bearer token, token: token as string }; } public validateCluster(authMetadata: AuthMetadata): Error[] { const oidcTokenProvider authMetadata[ANNOTATION_KUBERNETES_OIDC_TOKEN_PROVIDER]; if (!oidcTokenProvider || oidcTokenProvider ) { return [new Error(Must specify a token provider for oidc strategy)]; } return []; } }从源码可以提炼出三个关键实现事实必须指定oidcTokenProvidergetCredential与validateCluster双重校验若集群未配置 token provider会直接抛出错误对应测试用例见 OidcStrategy.test.ts其中验证了oidc authProvider requires a configured oidcTokenProvider错误路径token 按 provider 名索引请求体中的authConfig.oidc是一个以 provider 名为键的对象例如{ oidc: { okta: id_token } }后端按集群配置的 provider 名取出对应 ID Token透传为 Bearer Token取出的 token 最终以bearer token类型凭证发给 Kubernetes API Server。该策略通过 buildDefaultAuthStrategyMap.ts 注册到默认策略表export const buildDefaultAuthStrategyMap ({ logger, config }) new Map([ [aks, new AksStrategy()], [aws, new AwsIamStrategy({ config })], [azure, new AzureIdentityStrategy(logger)], [google, new GoogleStrategy()], [googleServiceAccount, new GoogleServiceAccountStrategy({ config })], [localKubectlProxy, new AnonymousStrategy()], [oidc, new OidcStrategy()], // -- 本次新增 [serviceAccount, new ServiceAccountStrategy()], ]);当某个集群的authProvider为oidc时请求分发逻辑见 DispatchStrategy.ts会从策略表中查找对应的AuthenticationStrategy若配置了不存在的 provider 值则会抛出authProvider xxx has no AuthenticationStrategy associated with it的错误。配置方式config 定位器OIDC 认证同时支持config与catalog两种集群定位方式。方式一通过app-config.yaml配置在config集群定位器中为集群设置authProvider: oidc并指定oidcTokenProvider。oidcTokenProvider的值必须与auth下已配置的认证提供方名称一致例如使用 Oktakubernetes: clusterLocatorMethods: - type: config clusters: - name: test-cluster url: http://localhost:8080 authProvider: oidc oidcTokenProvider: okta # 此值需与 auth.providers 下的配置项匹配 auth: providers: okta: development: clientId: ${AUTH_OKTA_CLIENT_ID} clientSecret: ${AUTH_OKTA_CLIENT_SECRET} audience: ${AUTH_OKTA_AUDIENCE}在 ConfigClusterLocator.ts 中后端通过clusterConfig.getOptionalString(oidcTokenProvider)读取该字段并将其映射为集群元数据注解ANNOTATION_KUBERNETES_OIDC_TOKEN_PROVIDER即kubernetes.io/oidc-token-provider。方式二通过 catalog 注解配置当使用catalog集群定位器时需要在kubernetes-cluster类型的 Resource 实体上添加注解。注解常量定义在 catalog-entity-constants.tsexport const ANNOTATION_KUBERNETES_OIDC_TOKEN_PROVIDER kubernetes.io/oidc-token-provider;对应的实体示例如下完整示例见 configuration.mdapiVersion: backstage.io/v1alpha1 kind: Resource metadata: name: my-cluster annotations: kubernetes.io/api-server: https://my-cluster.example.com kubernetes.io/api-server-certificate-authority: # base64 编码的 CA kubernetes.io/auth-provider: oidc kubernetes.io/oidc-token-provider: microsoft kubernetes.io/skip-metrics-lookup: true spec: type: kubernetes-cluster owner: user:guest前端配合oidc provider 注册与请求体注入前端插件plugin-kubernetes0.6.5-next.3同步升级以配合后端新策略。前端通过KubernetesAuthProviders见 KubernetesAuthProviders.ts在构造时注册oidcProviders把认证提供方OpenIdConnectApi映射为oidc.provider形式的认证策略if (options.oidcProviders) { Object.keys(options.oidcProviders).forEach(provider { this.authProviders[oidc.${provider}] new OidcKubernetesAuthProvider( oidc.${provider}, options.oidcProviders![provider], ); }); }实际请求时OidcKubernetesAuthProvider见 OidcKubernetesAuthProvider.ts会调用getBackstageIdentityResponse之类的认证 API 获取 ID Token并将其写入请求体的auth.oidc.provider字段。对应测试KubernetesAuthProviders.test.ts验证了oidc.okta的 token 注入结果{ auth: { oidc: { okta: oktaToken } } }。此外前端会在请求头中携带 provider 信息KubernetesBackendClient见 KubernetesBackendClient.ts对于oidc认证会将请求头拼接为Backstage-Kubernetes-Authorization-oidc-okta格式便于后端进行代理转发鉴权测试用例见 KubernetesBackendClient.test.ts。使用前提与限制集群必须支持 OIDC这是硬性前提。官方文档明确指出截至文档编写时 AKS 集群尚不支持 OIDC见 configuration.md 中authProvider取值表对oidc的说明前端开箱即用的 providergitlab需在认证应用中授予openidscope、google、microsoft、okta、oneloginoidcTokenProvider本质是 token 的签发方issuer例如完全可以用microsoft作为 EKS 集群的 token 签发方provider 名称与集群云厂商无关与serviceAccount策略相比OIDC 方案避免了在配置中存储长期有效的 Service Account Token更适合需要用户级身份区分与凭证轮换的场景。核心变更二core-components 前端组件修复与无障碍改进backstage/core-components0.9.4-next.2包含三项独立变更均为视觉与可访问性a11y层面的打磨1. Avatar 组件有图片时不再强制设置背景色变更52c02ac02b当 Avatar 组件带有图片picture时不再设置背景色。这是典型的视觉回归修复——此前有头像图片的元素也会被渲染背景色可能导致图片周围出现色块。升级后仅对无图片的 Avatar 保留背景色用于占位展示。2. OAuthRequestDialogARIA 语义完善变更3603014e0e为 OAuth 请求对话框OAuthRequestDialog添加了 ARIA landmarkmain、label 和标题heading并移除了嵌套的可交互控件button。这项改进对使用屏幕阅读器的用户意义重大对话框现在有明确的语义区域与可读标题同时消除了按钮嵌套按钮这类违反 HTML 规范、会导致辅助技术误读的结构问题。3. Sidebar 子菜单与 SidebarPage 修复变更2025d7c123是一组侧边栏相关问题修复同样影响plugin-org见下文正确高亮SidebarSubmenuItem下拉项在 hover 时的状态SidebarSubmenu中较长的标签使用省略号ellipsis样式避免文本溢出SidebarSubmenuItem的icon和to属性改为可选修复SidebarPage的 padding使其能响应侧边栏的固定pinned状态避免内容布局抖动。由于plugin-home、plugin-org、plugin-scaffolder、plugin-techdocs等插件均依赖core-components此版本的依赖升级会随Updated dependencies一并带入这些插件详见各自变更条目中的依赖列表。核心变更三home 与 org 插件增强plugin-homeStarredEntities 卡片显示实体标题backstage/plugin-home0.4.21-next.3的变更69093c5f91主页星标实体StarredEntities卡片在实体定义了标题title时显示标题并且不再展示已不存在的实体例如从 catalog 中被删除的实体。这一改进直接提升了主页信息质量此前卡片只显示metadata.name对带有友好标题的实体不够直观同时旧版本可能在列表中残留已删除实体造成点击后跳转到失效详情页的体验问题。plugin-orgMyGroupSidebarItem 命名空间与多组路由修复backstage/plugin-org0.5.5-next.3的变更同样归属于2025d7c123MyGroupSidebarItem在用户所属组不在默认命名空间时会在侧边栏项中包含命名空间同时当用户属于多个组时移除根项root item路由避免多个组的入口都映射到同一路由导致冲突。该变更与core-components的SidebarSubmenuItem修复同属侧边栏体系的一次整体打磨升级时建议将两个包一并更新保证 API 行为一致。核心变更四scaffolder 与 techdocs 依赖版本回退backstage/plugin-scaffolder1.2.0-next.3与backstage/plugin-techdocs1.1.1-next.3共享同一变更cc8ddd0979将依赖event-source-polyfill回退到1.0.25。event-source-polyfill是用于在浏览器中模拟 Server-Sent EventsSSE的 polyfill 库scaffolder 的任务日志流式输出与 techdocs 的构建状态推送均依赖该机制。回退到1.0.25通常意味着此前升级到的新版本存在回归问题如事件流中断、连接异常属于典型的升级后发现兼容问题而回退的工程决策。对于使用这两个插件的用户此变更基本透明无需额外配置若此前手动升级过该依赖建议与插件版本保持一致。升级与验证建议按依赖图整体升级core-components处于依赖链上游plugin-home、plugin-org、plugin-scaffolder、plugin-techdocs都通过Updated dependencies引用它升级时建议使用 Backstage 官方推荐的backstage-cli versions:bump流程保持各包版本一致若启用 Kubernetes OIDC 认证同时升级plugin-kubernetes、plugin-kubernetes-backend、plugin-kubernetes-common三个包它们由同一变更引入并按上文配置authProvider: oidc与oidcTokenProvider确保auth.providers中对应 provider 已启用且授予了openidscope验证路径配置完成后可在 catalog 实体页打开 Kubernetes 面板观察 Pod 等资源是否成功返回后端日志若出现Must specify a token provider for oidc strategy说明集群缺少oidcTokenProvider配置若出现Auth token not found under oidc.provider in request body说明前端 provider 注册与后端配置不一致预发布版本说明next系列为发布候选版本建议在非生产环境先行验证确认无回归后再等待正式版v1.2.0发布后升级。小结v1.2.0-next.3 虽以 Patch 级变更为主但 Kubernetes 插件的 OIDC 认证支持是架构层面的一次能力扩充后端通过OidcStrategy将 ID Token 转换为 Bearer Token 访问集群前端通过oidcProviders注册机制完成 token 获取与注入配置侧同时覆盖config与catalog两种集群来源。其余变更集中在侧边栏交互、无障碍语义、主页实体展示与依赖版本治理上均为低风险的体验优化。开发者在升级时可重点关注 OIDC 相关配置项即可平滑完成版本过渡。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考