Backstage 接入 OneLogin OIDC 认证提供者从应用创建到登录解析器的完整实践指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageOneLogin 是常见的身份提供者IdP支持 OpenID ConnectOIDC协议。Backstage 的backstage/core-plugin-api内置了 OneLogin 认证提供者可让用户通过 OneLogin 账号完成 OpenID Connect 登录。本文以仓库文档 docs/auth/onelogin/provider.md 为骨架结合plugins/auth-backend-module-onelogin-provider的源码与测试完整讲解在 OneLogin 后台创建 OIDC 应用、在app-config.yaml中配置提供者、注册后端模块、配置前端登录页以及使用内置 sign-in 解析器把 OneLogin 用户身份映射到 Backstage Catalog 用户实体的全过程。读完本文你将能在自己的 Backstage 实例中端到端落地 OneLogin 单点登录。OneLogin 提供者概览OneLogin 提供者是 Backstage 内置认证提供者之一官方文档将它与 Auth0、GitHub、GitLab、Okta 等一并列入核心提供者清单见 docs/auth/index.md。它基于 OIDCOpenID Connect协议工作前端跳转到 OneLogin 授权端点用户完成登录后由 OneLogin 返回授权码后端使用授权码换取访问令牌与用户资料最终通过 sign-in 解析器把身份映射为 Backstage Catalog 中的 User 实体。从仓库实现看该提供者由一个独立的 auth 后端模块承载包名为backstage/plugin-auth-backend-module-onelogin-providerpackage.json其底层依赖passport-onelogin-oauth策略完成 OAuth 流程authenticator.ts。第一步在 OneLogin 后台创建 OIDC 应用要启用 OneLogin 认证首先需要在 OneLogin Admin Portal 中创建一个 OIDC 类型的 Application步骤如下进入 OneLogin 管理后台选择Applications点击Add App选择OpenID Connect应用类型在Display Name中填写Backstage或你自己的应用名点击Save保存进入该应用的Configuration标签页设置Login Urlhttp://localhost:3000对应 Backstage 前端地址Redirect URIshttp://localhost:7007/api/auth/onelogin/handler/frame对应 auth 后端回调地址点击Save进入SSO标签页设置Token EndpointAuthentication MethodPOST点击Save。其中Redirect URIs是 OIDC 流程中 OneLogin 回跳的地址路径中的/handler/frame表示使用 iframe 弹窗式登录流程。Token Endpoint的认证方式必须设为POST否则令牌交换可能失败。第二步在 app-config.yaml 中配置提供者OneLogin 提供者的配置需要添加到app-config.yaml根级auth配置下格式如下来自原文档并保持完整auth: environment: development providers: onelogin: development: clientId: ${AUTH_ONELOGIN_CLIENT_ID} clientSecret: ${AUTH_ONELOGIN_CLIENT_SECRET} issuer: https://company.onelogin.com/oidc/2 ## 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/onelogin/provider#resolvers for more resolvers - resolver: usernameMatchingUserEntityNameproviders.onelogin是一个结构体包含三个核心配置键这三个值都可在 OneLogin 应用的 SSO 标签页中找到clientIdOneLogin 应用的客户端 IDclientSecretOneLogin 应用的客户端密钥敏感信息建议通过环境变量注入如${AUTH_ONELOGIN_CLIENT_SECRET}issuer签发者 URL形如https://company.onelogin.com/oidc/2。其中issuer的company需要替换为你 OneLogin 租户的子域。issuer直接决定了授权端点与令牌端点地址——这一点可由源码与测试印证authenticator.ts中issuer被原样传给OneLoginStrategyauthenticator.ts而测试断言启动时跳转的地址为https://my-company.onelogin.com/oidc/2/authmodule.test.ts。可选配置sessionDurationsessionDuration用户会话的生命周期。支持ms库的格式如24h、2 days、ISO 8601 时长格式以及代码中使用的 human duration 写法如{ hours: 24 }。该字段在配置 schema 中的类型为HumanDuration | string见 config.d.ts。配置层级与多环境说明providers.onelogin下的第二层键如示例中的development对应认证环境名。Backstage 会根据本地auth.environment设置选择匹配的提供者配置因此可以同时配置多个环境如development、production让单个 auth 后端服务多个环境详见 docs/auth/index.md 中的说明。仓库测试即使用development环境验证配置加载与登录流程module.test.ts。callbackUrl可选配置 schema 还允许可选字段callbackUrlconfig.d.ts用于在需要覆盖默认回调地址时显式指定。第三步选择 Sign-in 解析器ResolversOneLogin 提供者开箱即用地包含多个 sign-in 解析器用于把 OneLogin 返回的用户信息映射为 Backstage Catalog 中的 User 实体emailMatchingUserEntityProfileEmail将认证提供者返回的邮箱地址与 User 实体中匹配的spec.profile.email匹配若未找到匹配会抛出NotFoundError。emailLocalPartMatchingUserEntityName将认证提供者返回邮箱地址的本地部分local part即之前的部分与 User 实体中匹配的name匹配若未找到匹配会抛出NotFoundError。usernameMatchingUserEntityName将认证提供者返回的用户名与 User 实体中匹配的name匹配若未找到匹配会抛出NotFoundError。:::note 多个解析器会按配置顺序依次尝试但只有抛出NotFoundError时才跳过当前解析器继续尝试下一个。 :::从配置 schema 看每个解析器还支持不同的选项config.d.tsemailLocalPartMatchingUserEntityName支持allowedDomains?: string[]限定允许的邮箱域名详见 docs/auth/identity-resolver.md 中的用法示例与dangerouslyAllowSignInWithoutUserInCatalog?: booleanemailMatchingUserEntityProfileEmail与usernameMatchingUserEntityName支持dangerouslyAllowSignInWithoutUserInCatalog?: boolean。dangerouslyAllowSignInWithoutUserInCatalog是一个需要谨慎使用的开关开启后当 Catalog 中找不到匹配用户实体时仍允许登录并回退到以该名称构造的实体引用。从实现看usernameMatchingUserEntityName在 OneLogin 用户资料缺少username时会直接抛出OneLogin user profile does not contain a username错误随后通过ctx.signInWithCatalogUser按{ entityRef: { name: id } }完成 Catalog 用户匹配resolvers.ts。内置解析器之外这些内置解析器由模块注册时与commonSignInResolvers通用解析器合并提供module.ts。如果内置解析器无法满足需求可以构建自定义解析器具体做法见 docs/auth/identity-resolver.md 的 Building Custom Resolvers 章节。第四步后端安装与注册将 OneLogin 提供者添加到后端需要先安装对应包在 Backstage 仓库根目录下执行yarn --cwd packages/backend add backstage/plugin-auth-backend-module-onelogin-provider然后在packages/backend/src/index.ts中添加如下代码backend.add(import(backstage/plugin-auth-backend)); backend.add(import(backstage/plugin-auth-backend-module-onelogin-provider));从源码层面看该模块通过createBackendModule定义pluginId为auth、moduleId为onelogin-provider在初始化阶段向authProvidersExtensionPoint注册providerId: onelogin的提供者工厂module.ts。因此注册后auth 后端会暴露/api/auth/onelogin相关端点。底层认证流程源码视角oneLoginAuthenticator基于createOAuthAuthenticator构建其关键行为authenticator.tsinitialize读取clientId、clientSecret、issuer三个必填配置构造OneLoginStrategystart强制设置 OAuth scope 为openid并附带accessType: offline、prompt: consent参数发起授权跳转refresh刷新令牌时同样把 scope 固定为openid。仓库测试验证了整个启动流程module.test.ts请求/api/auth/onelogin/start?envdevelopment返回 302 跳转到https://my-company.onelogin.com/oidc/2/auth携带response_typecode、scopeopenid、client_id、redirect_uri指向handler/frame及加密state参数同时设置onelogin-noncecookie——这正是 OIDC 授权码流程的标准行为可作为验证后端配置是否生效的参考。第五步前端登录页接入前端需要把提供者接入登录页。在packages/app/src/App.tsx中引入oneloginAuthApiRef引用和SignInPage组件参照 docs/auth/index.md 的 Sign-in Configuration 章节将示例中的githubAuthApiRef替换为oneloginAuthApiRef即可其余写法对内置提供者通用。完整示例以新前端系统SignInPageBlueprint写法为例同样来自 docs/auth/index.mdimport { createApp } from backstage/frontend-defaults; import { oneloginAuthApiRef } 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: onelogin-auth-provider, title: OneLogin, message: Sign in using OneLogin, apiRef: oneloginAuthApiRef, }} / ), }, }); export default createApp({ features: [ /* ...其他插件... */ createFrontendModule({ pluginId: app, extensions: [signInPage], }), ], });oneloginAuthApiRef定义于backstage/core-plugin-api的 API 定义文件中见 packages/core-plugin-api/src/apis/definitions/auth.ts与前端的 auth API 实现相配套。若希望支持多登录方式如同时提供 Guest 登录可使用SignInPage的providers数组属性也可通过app-config.yaml中的配置条件渲染登录提供者详见 docs/auth/index.md 的 Using Multiple Providers 与 Conditionally Render Sign In Provider 小节。常见问题与排错要点回调地址不匹配Redirect URIs必须与auth.environment对应的后端地址一致默认开发环境为http://localhost:7007/api/auth/onelogin/handler/frame若前端端口或后端端口变更需同步修改 OneLogin 后台与配置。环境选择错误providers.onelogin下的配置键development、production需与auth.environment匹配否则会提示找不到对应环境的提供者配置。令牌端点认证方式OneLogin 应用的Token Endpoint Authentication Method必须设为POST否则授权码换令牌环节会失败。无法登录 / 404确认后端已同时注册backstage/plugin-auth-backend与backstage/plugin-auth-backend-module-onelogin-provider两个模块缺少任一模块都会导致端点不可用。用户匹配失败检查所选 resolver 与 Catalog 中 User 实体的name、spec.profile.email是否一致多个 resolver 会按顺序尝试若全部抛出NotFoundError则登录失败可通过dangerouslyAllowSignInWithoutUserInCatalog慎用允许无实体登录。密钥安全clientSecret在配置 schema 中被标记为visibility secretconfig.d.ts应通过环境变量注入并避免明文落入版本库。小结接入 OneLogin 认证提供者共五步在 OneLogin 后台创建 OIDC 应用 → 在app-config.yaml中配置clientId/clientSecret/issuer→ 配置 sign-in 解析器 → 安装并注册后端模块 → 在前端App.tsx中接入oneloginAuthApiRef与SignInPage。整个过程既有标准的 OIDC 协议支撑passport-onelogin-oauth策略 授权码流程又有 Backstage 新后端系统模块化注册机制作为底座。如需更深入理解 sign-in 身份映射机制可继续阅读 docs/auth/identity-resolver.md如需了解其他内置提供者的接入方式可查阅 docs/auth/index.md 与 docs/auth/ 目录下的各提供者文档。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考