Backstage v1.24.0 发布解读:安全默认的认证架构演进与新后端系统正式默认化
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 决定从用户令牌中移除所有权信息(entclaim)——用户令牌中嵌入的所有权实体引用会让令牌体积膨胀,尤其在 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,同时封装原始调用方身份信息,令牌被限定为仅可用于目标插件。
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 时需要重点检查以下事项:
- 认证相关:旧后端系统插件是否已转发
discovery服务;是否还在使用已弃用的getBearerTokenFromAuthorizationHeader;新后端系统插件是否需要在特定路径上显式调用addAuthPolicy开放访问; - 事件相关:events 相关模块是否已迁移到新的
EventsService接线方式; - 新项目默认形态:新建项目已默认采用新后端系统,模板与脚手架行为发生变化;
- 配置语义:确认配置中是否利用了新的
null语义来显式关闭功能。
相关资源索引
- 认证架构演进完整提案与设计细节:BEP-0003,配套时序图见同目录
token-sequence-cookie.drawio.svg与token-sequence-obo.drawio.svg; - guest 认证模块:plugins/auth-backend-module-guest-provider/README.md;
- 事件系统:plugins/events-node 与 plugins/events-backend;
- Scaffolder 动作测试工具:plugins/scaffolder-node-test-utils;
- 完整变更日志见 docs/releases/v1.24.0-changelog.md;Backstage 的版本与支持策略见 docs/overview/versioning-policy.md。