Backstage v1.24.0 发布解读:安全默认的认证架构演进与新后端系统正式默认化

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

Backstage v1.24.0 发布解读:安全默认的认证架构演进与新后端系统正式默认化

v1.24.0 是 Backstage 在安全与后端架构上一次里程碑式的版本:以 BEP-0003 Auth 架构演进 为蓝本,为实例接入"默认安全"的内置访问保护,并正式让新后端系统(new backend system)成为新建项目的默认选择。本文以官方发布说明为主线,结合仓库内 BEP 提案与 auth-backend-module-guest-provider 等插件的源码实现,逐条拆解本次版本中的破坏性变更、新能力、配置项与迁移要点,帮助你判断升级路径并正确接入新认证体系。

版本概览:一次聚焦"认证"与"后端系统"的大版本

v1.24.0 的核心变化集中在三块:

  • 认证(Auth)系统重构(BREAKING):引入 AuthService、HttpAuthService、UserInfoService 等新服务接口,实现默认访问保护,并重构了用户令牌与服务间通信令牌的形态;
  • 事件(Events)系统重构(BREAKING):所有事件通信改为通过新的 EventsService 进行,与旧后端系统解耦;
  • 新后端系统默认化:@backstage/create-app 新建的项目默认基于新后端系统,@backstage/cli 创建的插件也默认支持新系统。

此外还带来 guest 认证模块、配置项支持 null、scaffolder 动作测试工具、新的后端插件扩展点以及核心组件 I18n 支持等能力。该版本不包含任何安全修复(security fixes)。

BREAKING:认证系统大改版,安全默认成为现实

本次认证改进的完整方案与动机记录在 BEP-0003 中,核心目标只有一个:让 Backstage 实例默认就安全,不再依赖外部网关或手工配置来保护实例不被未授权访问。在此之前,Backstage 的 API 请求认证需要依赖 contrib/ 下的教程手工搭建,且在"保护实例"这件事上效果不佳;本次将其变成内置能力,同时也大幅降低了启用权限系统(permission system)的门槛——因为访问限制已经内置。

绝大多数改进只作用于新后端系统,但新的服务接口带有向后兼容层,旧后端系统中同样可以使用。这是整个认证改版的第一阶段,包含了所有预期的破坏性变更,后续改进将不再引入新的破坏。

新增的服务接口:AuthService / HttpAuthService / UserInfoService

从 BEP-0003 设计细节 可以看出,这次引入的两个底层服务取代了原有的 IdentityService 与 TokenManagerService:

  • AuthService(低层服务):负责对所有类型的 Backstage 身份(用户、服务、代表用户发起请求的服务)进行认证与 Bearer Token 签发。核心方法包括:

    • authenticate(token, { allowLimitedAccess }):校验令牌并返回不透明的 BackstageCredentials;
    • isPrincipal(credentials, type):判断凭据主体类型;
    • getOwnServiceCredentials():获取插件自身服务凭据;
    • getPluginRequestToken({ onBehalfOf, targetPluginId }):为发往指定目标插件的上游请求签发 OBO 令牌;
    • getLimitedUserToken(credentials):签发受限作用域的用户令牌(用于 Cookie 认证等场景)。
  • HttpAuthService(高层服务):面向插件路由,统一处理请求凭据的读取与 Cookie 签发。核心方法:

    • credentials(req, { allow: ['user'|'service'|'unauthenticated'|...], allowLimitedAccess }):解析请求中的凭据,不满足条件即抛错;
    • issueUserCookie(res, { credentials }):为响应写入用户 Cookie。
  • UserInfoService(由 auth-backend 提供):返回 { userEntityRef, ownershipEntityRefs }。这一设计的直接原因是 BEP 决定从用户令牌中移除所有权信息(ent claim)——用户令牌中嵌入的所有权实体引用会让令牌体积膨胀,尤其在 Cookie 认证受 4KB 大小限制的背景下问题更突出。仓库中目前仅有 permission-backend 与 signal-backend 依赖该信息,改由 UserInfoService 提供,后续将透明迁移到 auth-backend 新增的 /v1/userinfo 端点。

默认认证策略与 HttpRouterService 扩展

为保证"默认安全",BEP 为所有插件路由设定了 default auth policy(默认认证策略):仅允许已认证的用户与服务访问。该策略实现在 HttpRouterService 中,插件若要开放免认证或仅 Cookie 认证的路径,必须通过新增的 addAuthPolicy() 方法显式退出:

export interface HttpRouterServiceAuthPolicy {
  // 路径匹配方式与传给 express.Router.use(path, ...) 时一致
  path: string;
  allow: 'unauthenticated' | 'user-cookie';
}

export interface HttpRouterService {
  // 默认情况下所有路由仅允许已认证的用户与服务访问
  use(handler: Handler): void;

  // 这些策略是可叠加的,最宽松的访问级别优先生效
  addAuthPolicy(policy: HttpRouterServiceAuthPolicy): void;
}

BEP-0003 给出的三种典型用法 值得直接对照实现:

1. 标准插件(只允许已认证用户与服务)——绝大多数插件采用此模式,无需任何额外代码:

export default createBackendPlugin({
  pluginId: 'todo',
  register(env) {
    env.registerInit({
      deps: { http: coreServices.httpRouter },
      async init({ http }) {
        http.use(await createRouter(/* ... */));
      },
    });
  },
});

2. 带 Cookie 认证端点的插件(如 TechDocs 这类需要浏览器直连静态资源的场景)——先签发 Cookie,再为该路径声明 user-cookie 策略,两次调用的顺序无关紧要:

export default createBackendPlugin({
  pluginId: 'techdocs',
  register(env) {
    env.registerInit({
      deps: {
        auth: coreServices.auth,
        httpAuth: coreServices.httpAuth,
        http: coreServices.httpRouter,
      },
      async init({ auth, httpAuth, http }) {
        const router = Router();

        // 为用户设置 Cookie 的端点
        router.get('/cookie', async (req, res) => {
          const { expiresAt } = await httpAuth.issueUserCookie(res);
          res.json({ expiresAt: expiresAt.toISOString() });
        });

        // 由 Cookie 认证保护的端点
        router.get('/static', express.static(/* ... */));

        http.use(router);
        http.addAuthPolicy({ path: '/static', allow: 'user-cookie' });
      },
    });
  },
});

3. 完全关闭默认认证策略、自行处理认证的插件(典型如 app 插件):

export default createBackendPlugin({
  pluginId: 'app',
  register(env) {
    env.registerInit({
      deps: { http: coreServices.httpRouter },
      async init({ http }) {
        http.use(await createRouter(/* ... */));
        http.addAuthPolicy({ path: '/', allow: 'unauthenticated' });
      },
    });
  },
});

请求处理中的新用法:读取凭据与签发 OBO 令牌

结合 BEP-0003 的用法示例,升级后插件代码中常见的认证处理会变成如下形态。

要求用户认证的请求,用 httpAuth.credentials 配合 allow 校验,并结合 userInfo 获取所有权信息:

router.get('/read-data', (req, res) => {
  const credentials = await httpAuth.credentials(req, { allow: ['user'] }); // 不满足则抛错
  const { ownershipEntityRefs } = await userInfo.getUserInfo(credentials);
  console.log(
    `User ref=${credentials.principal.userEntityRef} ownership=${ownershipEntityRefs}`,
  );
  // ...
});

允许用户与服务两种主体的请求,则根据 principal.type 分流处理。

后端到后端的请求不再直接复用用户令牌,而是通过 auth.getPluginRequestToken() 按"代表调用方(on-behalf-of)"方式签发服务令牌:

const { token } = await auth.getPluginRequestToken({
  onBehalfOf: await auth.getOwnServiceCredentials(),
  targetPluginId: 'example',
});

const baseUrl = await discovery.getBaseUrl('example');
const res = await fetch(`${baseUrl}/some-resource`, {
  headers: { Authorization: `Bearer ${token}` },
});

服务端将收到的用户凭据以 BackstageCredentials 对象继续向下游传递(而非转发原始用户令牌),由 API 客户端层负责换取 OBO 令牌,这也是"封装用户凭据、避免在服务间裸传用户令牌"这一设计目标的落地方式。

令牌形态:Cookie 令牌与 OBO 令牌

BEP-0003 明确说明本节为参考性描述,不构成规范,令牌形态与主要流程如下(详见 Token Details):

  • Backstage 用户身份令牌:JWT,ES256 非对称签名,iss 为 auth 后端外部地址,sub 为用户名实体引用,aud 固定为 "backstage"。本次改版计划移除其中的 ent 所有权声明;
  • 旧服务令牌:JWT,HS256 对称签名,密钥来自 app-config 的 backend.auth.keys 首项,不含调用方与接收方信息,本版起将逐步调整;
  • Cookie 令牌流:面向浏览器直连静态资源(如 TechDocs)的场景。插件前端在渲染静态内容前先调用插件后端的 Cookie 端点,后端校验身份令牌后写入受限作用域的用户 Cookie,后续静态资源请求由浏览器自动携带。受限令牌以本插件自身为 audience,无法在 Bearer 场景或其它插件中复用;
  • 服务 OBO 令牌流:后端服务向上游发起请求时,以目标服务为 audience、自身为 subject,同时封装原始调用方身份信息,令牌被限定为仅可用于目标插件。

Cookie 令牌流的时序图(Auth 架构演进 BEP 中定义)

服务间 On-Behalf-Of 令牌流的时序图(以 scaffolder 请求 catalog 为例)

BEP 以 scaffolder 后端向 catalog 插件发起 OBO 请求为例说明了上述流程(见 OBO 时序图说明)。

关闭内置访问控制:dangerouslyDisableServiceAuth

当访问保护已由外部服务承担、需要允许实例内部免认证访问时,可通过配置关闭内置保护:

backend:
  dangerouslyDisableServiceAuth: true

其具体影响是:HttpRouterService 实现不再做检查(等效于对所有路由应用 unauthenticated 级别),同时 AuthService.getPluginRequestToken() 对 'none' 主体签发空令牌而非抛错(详见 BEP-0003 的 Access Control Configuration)。

旧后端系统的兼容层与迁移要点

  • 旧后端系统不会应用任何访问限制,HttpRouterService 的默认保护只在新后端系统生效;
  • 兼容层行为(来自 BEP-0003 Release Plan):auth.authenticate() 依据令牌 audience 判断用户主体或服务主体,getLimitedUserToken() 为 no-op(直接返回原令牌),issueUserCookie() 为 no-op(旧系统不支持 Cookie 认证)等;
  • 由于 IdentityService / TokenManagerService 将在新 AuthService 之上实现并被弃用,部分后端插件在旧后端系统中现在要求从插件环境转发 discovery 服务,升级时需要补上;
  • @backstage/plugin-auth-node 中导出的 getBearerTokenFromAuthorizationHeader 已被弃用,官方明确不鼓励继续使用,应迁移到新的 HttpAuthService.credentials() 方案。

BREAKING:事件系统统一收敛到 EventsService

事件系统本次重构的目标是与新后端系统更好地兼容:所有事件通信统一改由新的事件服务(EventsService)承载。受影响的模块从实现 EventSubscriber 接口改为接收新的 EventsService 作为输入,具体迁移方式见各模块的 changesets。

在旧后端系统中接线事件服务的方式,以及事件后端(events backend)在旧系统中的安装方式,分别记录在 plugins/events-node 与 plugins/events-backend 的 README(#legacy-backend-system 章节)及其 CHANGELOG 中。该改动由 @pjungermann 在 PR #22344 中贡献。

新后端系统成为新建项目的默认选择

从 v1.24.0 起:

  • 使用 @backstage/create-app 创建的新项目,生成的 backend 直接基于新后端系统构建;
  • 使用 @backstage/cli 创建的插件,默认同样支持新后端系统。

这意味着新项目从一开始就能享受到新后端系统的模块化架构,以及上文所述内置安全认证策略等新能力;而认证改版的破坏性变更集中在首个阶段,也正是在新后端系统 API 稳定之前完成这部分工作的原因(参见 BEP-0003 动机)。

新增 guest 认证模块:本地开发与测试的官方方案

发布说明中提到的 guest auth provider 对应仓库内的 auth-backend-module-guest-provider。与旧版 'guest' 认证(不签发令牌、完全存储在前端状态)不同,新模块能签发合法的会话与 Backstage 用户令牌,适合本地开发与测试场景。

安装与启用三步走:

# 1. 将包加入后端依赖
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-guest-provider
// 2. 在 packages/backend/src/index.ts 中注册模块
const backend = createBackend();
backend.add(import('@backstage/plugin-auth-backend-module-guest-provider'));
# 3. 在 app-config.yaml 中启用(注意:不要放在 app-config.production.yaml)
auth:
  providers:
    guest: {}

注意配置中的双大括号 {} 对应一个空对象,即使用全部默认设置。从 模块实现 可以看到,该模块通过 createProxyAuthProviderFactory 注册 guest provider,默认设置如下:

  • 用户以 user:development/guest 身份登录;
  • 用户仅通过该 ref 声明所有权;
  • 仅开发模式可用:非开发环境下默认拒绝登录(安全原因)。

可配置项详解

config.d.ts 中定义了以下可选配置(一旦在 guest 键下添加选项,就需去掉双大括号):

配置项 说明 默认值
auth.providers.guest.userEntityRef 访客用户的实体引用 user:development/guest
auth.providers.guest.ownershipEntityRefs 当 catalog 中找不到该用户时,用于声明所有权的实体引用列表 [userEntityRef]
auth.providers.guest.dangerouslyAllowOutsideDevelopment 是否允许在非开发环境使用 guest 登录 false
auth:
  providers:
    guest:
      userEntityRef: user:development/guest
      ownershipEntityRefs:
        - user:development/guest
        - group:development/guests
      dangerouslyAllowOutsideDevelopment: false

从源码看其工作逻辑(resolvers.ts):登录解析器会先检查环境——NODE_ENV !== 'development' 且未显式开启 dangerouslyAllowOutsideDevelopment 时直接抛出 NotImplementedError;随后优先尝试通过 signInWithCatalogUser 走 catalog 用户登录,若 catalog 中不存在该 guest 用户,则降级直接签发包含 sub 与 ent 声明的用户令牌,保证用户即使不在 catalog 中也能继续浏览。对应的 authenticator.ts 在初始化时即计算"非开发环境且未显式允许"的禁用标记,并在 authenticate 阶段对禁用场景抛出 NotAllowedError。

配置项支持 null:显式"重置"配置值

从 v1.24.0 起,配置中的 null 值被视作显式的未定义值,且不会回退到其它配置文件。这意味着你可以在配置中用 null 重置或取消某段配置——典型场景是关闭某个 auth provider:

auth:
  providers:
    github: null   # 显式关闭 GitHub 登录,不会回退到其他配置文件中的定义

这为多环境配置覆盖提供了更精确的控制手段。

Scaffolder 动作测试工具:createMockActionContext

本次发布了新包 @backstage/plugin-scaffolder-node-test-utils(仓库目录 plugins/scaffolder-node-test-utils),核心是提供 createMockActionContext,让 scaffolder 自定义动作的单元测试编写更简单、更不易受动作上下文(action context)新增字段的破坏性影响。官方建议将现有测试迁移到该工具,以规避未来动作上下文演进带来的破坏性变更。

新后端系统新增插件扩展点

  • @backstage/plugin-catalog-node/alpha 导出的 catalogModelExtensionPoint:可在新后端系统中替换默认的实体数据解析器(entity data parser)与字段校验规则;
  • @backstage/plugin-techdocs-node 导出的 techdocsGeneratorExtensionPoint:可设置自定义的 TechDocs 生成器。

两者的源码与类型定义分别位于 plugins/catalog-node 与 plugins/techdocs-node 中,为插件作者提供了更强的定制能力。

核心组件 I18n:coreComponentsTranslationRef

v1.24.0 让 @backstage/core-components 的绝大部分组件支持国际化。消息定制通过 @backstage/core-components/alpha 导出的 coreComponentsTranslationRef 实现,你可以在应用中按国际化文档的方式覆盖这些消息(可参考 docs/plugins/internationalization.md 中关于应用开发者覆写插件消息的说明)。该贡献来自 @mario-mui 的 PR #20932。

升级路径与建议

官方建议保持 Backstage 项目跟随最新版本。升级指引详见 keeping-backstage-updated 文档。结合本次发布说明,升级 v1.24.0 时需要重点检查以下事项:

  1. 认证相关:旧后端系统插件是否已转发 discovery 服务;是否还在使用已弃用的 getBearerTokenFromAuthorizationHeader;新后端系统插件是否需要在特定路径上显式调用 addAuthPolicy 开放访问;
  2. 事件相关:events 相关模块是否已迁移到新的 EventsService 接线方式;
  3. 新项目默认形态:新建项目已默认采用新后端系统,模板与脚手架行为发生变化;
  4. 配置语义:确认配置中是否利用了新的 null 语义来显式关闭功能。

相关资源索引

登录后查看全文
backstage