Backstage 接入 VMware Cloud 身份源backstage/plugin-auth-backend-module-vmware-cloud-provider 完整配置指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 通过backstage/plugin-auth-backend-module-vmware-cloud-provider后端模块允许用户使用自己的 VMware Cloud 账号以 OAuth 授权码 PKCE 流程登录。本文基于 docs/auth/vmware-cloud/provider.md 与模块源码完整覆盖 VMware Cloud Console 侧的 OAuth App 创建、app-config.yaml的vmwareCloudServices配置、内置 Sign-in Resolvers 的选型、前后端代码接入并结合 plugins/auth-backend-module-vmware-cloud-provider 的实现源码与测试用例讲解该 Provider 在组织 ID 绑定、PKCE 会话存储、ID Token 校验等环节的底层行为帮助你在自己的 Backstage 实例中真正跑通 VMware Cloud SSO。一、在 VMware Cloud Console 创建 OAuth App启用登录前需要在 VMware Cloud Console 中创建一个 Web/Mobile 类型的 OAuth App流程如下登录 VMware Cloud Console进入Identity Access Management OAuth Apps打开Owned Apps标签页。注意如果你不是 Organization Owner 或 Administrator 而只是 Member除非角色勾选了Developer否则看不到该导航入口。点击Create App选择Web/Mobile app点击Continue。除以下项外保持默认设置App Name与App Description自行填写Redirect URIs填写${baseUrl}/api/auth/vmwareCloudServices/handler/frame其中baseUrl是 Backstage 后端可访问的地址。注意 VMware Cloud不支持http://协议与localhost主机名的组合本地调试时建议把后端地址设为http://127.0.0.1:7007Refresh Token勾选Issue refresh token。refresh token 是必需的否则用户刷新浏览器页面时会被迫重新登录Define Scopes在列表底部勾选OpenID。点击Create在弹出的对话框中记下App ID——这就是 Backstage 配置中使用的 client ID。同时准备另一个关键值ORG_ID即 VMware Cloud 中希望启用登录的 Organization 的 long ID。该值会随授权请求下发给 VMware Cloud并在登录后用于与 ID Token 中的组织声明做一致性校验见 plugins/auth-backend-module-vmware-cloud-provider/src/authenticator.ts。二、app-config.yaml 配置详解在app-config.yaml的根级auth配置下追加如下内容auth: session: secret: your session secret environment: development providers: vmwareCloudServices: development: clientId: ${APP_ID} organizationId: ${ORG_ID} ## 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 signIn: resolvers: # See https://backstage.io/docs/auth/vmware-cloud/provider#resolvers for more resolvers - resolver: emailMatchingUserEntityProfileEmail其中APP_ID为创建 OAuth App 时获取的 IDORG_ID为组织 long ID。各配置项在类型定义 plugins/auth-backend-module-vmware-cloud-provider/config.d.ts 中声明汇总如下配置项必填说明clientId是OAuth App 的App ID即 client IDorganizationId是VMware Cloud 组织的 long ID未配置时初始化直接抛错Missing required config value at organizationId见 authenticator.test.ts 的断言sessionDuration否用户会话寿命支持ms库格式如24h、2 days、ISO duration 或代码中使用的 human duration类型上对应HumanDuration \| stringconsoleEndpoint否VMware Console 端点覆盖项默认https://console.cloud.vmware.com见 authenticator.ts一般无需修改additionalScopes否额外 scope字符串或字符串数组scope否已废弃旧版 scope 配置。从源码看只要配置中存在该键initialize会直接抛出“不再支持scope请改用additionalScopes”的错误见 authenticator.tssignIn.resolvers是Sign-in 身份解析器列表详见下一节必须设置 auth.session.secretPKCE 的硬依赖VMware Cloud 要求 OAuth App 在执行授权码流程时必须使用 PKCE而底层passport-oauth2库实现 PKCE 依赖 Express 的 session 中间件把code_verifier存入服务端会话。因此auth.session.secret必须替换为一个长的、复杂的、唯一的字符串它充当 Backstage 签名会话 Cookie 的密钥若请求中缺少 session认证器会直接以requires session support失败——测试用例 authenticator.test.ts 专门验证了这一点PKCE 采用 S256 方式授权请求会携带code_challenge_methodS256与code_challenge参数code_verifier则写入req.session[oauth2:console.cloud.vmware.com]测试断言见 authenticator.test.ts。三、Sign-in ResolversID Token 到 Catalog 用户的映射用户通过 VMware Cloud 登录后Backstage 需要把 profile 映射到软件目录中的 User 实体。该 Provider 通过 plugins/auth-node/src/sign-in/commonSignInResolvers.ts 内置了两个通用解析器在 module.ts 中以...commonSignInResolvers的形式挂到工厂上emailMatchingUserEntityProfileEmail用认证方返回的邮箱地址匹配目录中spec.profile.email相同的 User 实体找不到时抛NotFoundError。源码中还有一个细节首次匹配失败且邮箱含 plus addressing如joeworkacme.com时会自动去掉work部分再重试一次见 commonSignInResolvers.ts。emailLocalPartMatchingUserEntityName用邮箱的 local part之前的部分匹配 User 实体的name找不到时抛NotFoundError。两个解析器都支持以下可选项由 zod schema 校验见 commonSignInResolvers.tssignIn: resolvers: - resolver: emailMatchingUserEntityProfileEmail allowedDomains: [acme.com] # 仅允许指定邮箱域localPart 解析器同样支持 dangerouslyAllowSignInWithoutUserInCatalog: falseallowedDomains邮箱域名不在白名单内时抛NotAllowedErrorSign-in user email is not from an allowed domaindangerouslyAllowSignInWithoutUserInCatalog允许目录中查无此人时仍按邮箱生成 entity ref 兜底登录生产环境应谨慎开启。::: note 多个 resolvers 会按配置顺序依次尝试只有当某个 resolver 抛出NotFoundError时才会跳到下一个抛出其他错误如NotAllowedError则直接终止流程。 :::如果内置解析器不满足需求可以编写自定义 resolver方法见 docs/auth/identity-resolver.md 中的 Building Custom Resolvers 章节。四、后端接入安装模块并注册从 Backstage 根目录执行# from your Backstage root directory yarn --cwd packages/backend add backstage/plugin-auth-backend-module-vmware-cloud-provider然后在 packages/backend/src/index.ts 中追加import { backend } from backstage/backend-defaults; import authPlugin from backstage/plugin-auth-backend; import vmwareCloudProvider from backstage/plugin-auth-backend-module-vmware-cloud-provider; backend.add(authPlugin); backend.add(vmwareCloudProvider);该模块本身是一个标准的createBackendModulepluginId为auth、moduleId为vmware-cloud-provider在初始化时向authProvidersExtensionPoint注册一个providerId为vmwareCloudServices的 Provider见 module.ts。这也解释了前面 Redirect URI 与配置段为什么统一使用vmwareCloudServices这个命名。五、前端接入SignInPage 与 vmwareCloudAuthApiRef按照 docs/auth/index.md 中 Adding the provider to the sign-in page 的流程在应用入口注册vmwareCloudAuthApiRef并在SignInPage的providers中加入import { vmwareCloudAuthApiRef } from backstage/core-plugin-api; SignInPage titleContent{...} providers{[ // 其他 provider... vmwareCloudAuthApiRef, ]} /;前端 API 的具体实现见 packages/core-app-api/src/apis/implementations/auth/vmwareCloud/VMwareCloudAuth.ts它复用通用OAuth2.create默认 provider 元数据为{ id: vmwareCloudServices, title: VMware Cloud }默认请求 scope 为[openid]。用户点击登录按钮后前端经 discovery 找到/api/auth/vmwareCloudServices并发起 OAuth 重定向与后端 handler 形成闭环。六、源码级解析认证流程的关键环节以下细节均可在 plugins/auth-backend-module-vmware-cloud-provider/src/authenticator.ts 中直接验证理解它们有助于排查登录问题。1. 端点与组织绑定initialize阶段从配置读取端点见 authenticator.ts授权端点${consoleEndpoint}/csp/gateway/discovery令牌端点${consoleEndpoint}/csp/gateway/am/api/auth/tokenclient secret 固定为空字符串通过customHeaders以Authorization: Basic base64(clientId:)的形式下发——测试中令牌请求没有 Authorization 头会返回 500正是这一机制的验证见 authenticator.test.ts。start阶段发起授权重定向时会把配置中的organizationId追加为 URL 的orgId查询参数authenticator.ts并携带accessTypeoffline、promptconsent。测试用例 authenticator.test.ts 逐条断言了重定向 URL 的 hostconsole.cloud.vmware.com、路径/csp/gateway/discovery、client_id、orgId、redirect_uri与scope参数可作为联调时的对照清单。2. state 参数与会话的双重编码由于 VMware 侧与OAuth2Strategy在开启 PKCE 后都会尝试控制state源码对策略的_stateStore做了一层代理见 authenticator.tsstore 时把会话句柄handle与req.state合并后经encodeOAuthState重新编码输出verify 时再解出handle交回会话存储校验。测试state param is compatibleauthenticator.test.ts验证了start产生的 state 能原样在authenticate阶段被接受并取回idToken。3. ID Token 声明校验与 Profile 生成defaultProfileTransformauthenticator.ts用jose的decodeJwt解码会话中的id_token并强制要求email、given_name、family_name、context_name四个 claim 必须存在且为字符串缺失或类型不符分别抛出ID token missing required claims: .../ID token claims type mismatch: ...context_name必须等于配置中的organizationId否则抛出ID token organizationId mismatch——这是防止把 A 组织的令牌用于 B 组织配置的一道防线。校验通过后profile 输出为{ displayName: given_name family_name, email }随后交给上一节所述的 resolvers 完成目录用户匹配。4. 必需 scope 与 refresh 行为认证器声明scopes.required: [openid, offline_access]authenticator.ts与 Console 侧勾选 OpenID scope、开启 refresh token 的要求一一对应。authenticate成功后 refresh token 与会话一起写入 cookie测试断言见 authenticator.test.tsrefresh阶段用 refresh token 换新令牌并复用同一套 profile 变换逻辑authenticator.test.ts这就是刷新页面不丢登录态的机制来源。七、验证与排错清单上线前建议按以下顺序自检organizationId已配置——否则后端启动即报Missing required config value at organizationIdRedirect URI 与 Console 中登记完全一致本地环境使用http://127.0.0.1:7007而非localhostConsole 中已开启Issue refresh token并勾选OpenIDscope否则拿不到id_token/ refresh tokenauth.session.secret已设置为强随机串且后端具备 session 支持PKCE 依赖会话存储目录中存在spec.profile.email与 VMware Cloud 账号邮箱一致的 User 实体否则默认 resolver 会抛NotFoundError登录后若报ID token organizationId mismatch说明 ID Token 的context_name与organizationId配置不一致检查是否登入了非目标组织。小结VMware Cloud Provider 的接入路径是Console 侧创建带 refresh token 与 OpenID scope 的 OAuth App 并登记/api/auth/vmwareCloudServices/handler/frame回调 →app-config.yaml配置clientId/organizationId/ resolvers 并保证auth.session.secret可用 → 后端安装并backend.add模块 → 前端注册vmwareCloudAuthApiRef。实现层面模块以 PKCE 空 client secret 的 OAuth2 策略对接 VMware Gateway 端点用orgId参数与context_nameclaim 双重绑定组织身份再以通用 sign-in resolvers 完成目录用户映射。相关源码与测试分别位于 plugins/auth-backend-module-vmware-cloud-provider 与 plugins/auth-node/src/sign-in/commonSignInResolvers.ts可直接用于对照排错。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考