Backstage 集成 Okta OIDC 登录从应用创建、后端配置到登录页接入的完整指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文基于 Backstage 官方文档 Okta Authentication Provider完整讲解如何在 Backstage 中通过 Okta OpenID ConnectOIDC实现用户认证与登录包括在 Okta 控制台创建 OIDC Web 应用、在app-config.yaml中配置 provider 各参数、选择 sign-in resolver、安装后端模块并接入前端登录页。读完本文你将能够独立完成 Okta 与 Backstage 的本地开发及生产环境对接并理解backstage/plugin-auth-backend-module-okta-provider的底层实现与配置校验逻辑。一、在 Okta 上创建应用集成Backstage 官方提供的 Okta 认证 provider 位于core-plugin-api包中其核心实现模块为 plugins/auth-backend-module-okta-provider可借助 Okta 的 OpenID Connect 能力对用户进行认证。要在 Backstage 中使用它第一步是在 Okta 租户通常是company.okta.com中创建一个应用集成登录 Okta 管理后台一般为company.okta.com。进入Menu Applications Applications Create App Integration。在 Create a new app integration 表单中填写Sign-in method选择OIDC - OpenID ConnectApplication type选择Web Application点击Next在 New Web App Integration 表单中填写App integration nameBackstage或自定义应用名Grant type勾选Authorization Code与Refresh TokenSign-in redirect URIshttp://localhost:7007/api/auth/okta/handler/frameSign-out redirect URIshttp://localhost:7007Controlled access按组织策略选择访问控制范围点击Save上述配置示例适用于本地开发。生产环境部署时请将http://localhost:7007替换为你的 Backstage 实例实际对外可访问的地址。二、在 app-config.yaml 中配置 Okta Provider应用创建完成后将 provider 配置添加到app-config.yaml的根级auth配置下auth: environment: development providers: okta: development: clientId: ${AUTH_OKTA_CLIENT_ID} clientSecret: ${AUTH_OKTA_CLIENT_SECRET} audience: ${AUTH_OKTA_DOMAIN} authServerId: ${AUTH_OKTA_AUTH_SERVER_ID} # Optional idp: ${AUTH_OKTA_IDP} # Optional ## uncomment to set lifespan of user session # sessionDuration: { hours: 24 } # Optional: supports ms library format (e.g. 24h, 2 days), ISO duration, human duration as used in code # https://developer.okta.com/docs/reference/api/oidc/#scope-dependent-claims-not-always-returned additionalScopes: ${AUTH_OKTA_ADDITIONAL_SCOPES} # Optional signIn: resolvers: # See the Resolvers section below for more resolvers - resolver: emailMatchingUserEntityAnnotation与源码中的配置 Schema 对照见 config.d.tsOkta provider 支持以下字段配置项类型必填说明clientIdstring是Okta 应用生成的 Client ID形如3abe134ejxzF21HU74c1clientSecretstring是Okta 应用显示的 Client Secret标记为 secret不应出现在前端audiencestring否Okta 域名形如https://company.okta.com源码中缺省值为https://okta.comauthServerIdstring否应用的 Authorization Server IDidpstring否应用的 Identity Provider ID形如0oaulob4BFVa4zQvt0g3callbackUrlstring否自定义回调地址默认为 Backstage 自动生成的 handler 地址additionalScopesstring | string[]否附加 OAuth scope见下文sessionDurationHumanDuration | string否用户会话生命周期支持ms库格式如24h、2 days、ISO 时长格式及代码中使用的 human duration 写法signIn.resolversarray否登录身份解析器列表见下文 Resolvers 一节audience 参数的底层校验在 authenticator.ts 中audience并非简单地透传给 Okta而是先经过合法性校验const audience config.getOptionalString(audience) || https://okta.com; if (!audience.match(/^https?:\/\//)) { throw new Error( The provided audience ${audience} is not a valid URL. It must start with https:// or http://., ); }也就是说audience必须以http://或https://开头否则启动时会直接抛出异常。对应的测试用例位于 module.test.ts其中也验证了默认情况下 OAuth 授权请求会指向https://okta.com/oauth2/v1/authorize。additionalScopes 与 OIDC 声明ClaimsadditionalScopes是可选项接受空格分隔的字符串或字符串数组。它会与默认 scopeopenid profile email offline_access合并共同作为发送给 Okta 的scope。这一行为直接影响 Okta 返回的依赖声明scope-dependent claims。例如将additionalScopes设为groupsOkta 会额外返回一个groups声明内容为当前用户所属、且匹配客户端应用 ID token group filter 的组列表。源码佐证在 authenticator.ts 中必需的 scope 被定义为[openid, email, profile, offline_access]而在 module.test.ts 中当配置additionalScopes: groups phone后测试断言最终发出的授权请求 scope 为openid email profile offline_access groups phone且使用response_type: code即 Authorization Code 流程并携带client_id、redirect_uri指向/api/auth/okta/handler/frame与随机生成的state/nonce。三、登录身份解析器Sign-in ResolversOkta provider 默认只用于访问委托即代表用户向 Okta 请求资源并不会自动启用登录。要让用户能够通过 Okta 登录 Backstage必须在配置中显式提供signIn.resolvers。解析器resolver的作用是把 Okta 返回的外部身份映射为 Backstage 内部的用户身份。从源码看该 provider 通过 module.ts 将 Okta 特有 resolver 与 Backstage 通用 resolvercommonSignInResolvers合并注册因此你可选用的内置 resolver 如下emailMatchingUserEntityProfileEmail将 Okta 返回的 email 与 Catalog 中spec.profile.email匹配的 User 实体对应找不到匹配时抛出NotFoundError。emailLocalPartMatchingUserEntityName取 Okta 返回 email 的 local part前的部分与 Catalog 中 User 实体的name匹配找不到匹配时抛出NotFoundError。emailMatchingUserEntityAnnotationOkta 特有将 Okta 返回的 email 与 Catalog 中带有okta.com/email注解的 User 实体匹配找不到匹配时抛出NotFoundError。其实现见 resolvers.ts。注意多个 resolver 会按配置顺序依次尝试但只有抛出NotFoundError时才会跳过当前 resolver 继续尝试下一个。因此应只为一个登录 provider 配置 resolver避免身份混淆或账户劫持风险。resolver 的附加选项根据 config.d.ts 的 SchemaemailLocalPartMatchingUserEntityName额外支持allowedDomains字符串数组用于限定允许登录的邮箱域名强烈建议启用同时所有 resolver 都支持dangerouslyAllowSignInWithoutUserInCatalog布尔选项——开启后即使 Catalog 中不存在对应用户实体也会基于 resolver 层已有的身份信息签发 Backstage token。该选项在生产环境存在安全风险未纳入 Catalog 的用户将获得与 guest 用户相同的权限请谨慎使用。内置 resolver 无法满足需求时自定义 resolver如果内置 resolver 不适用可以参考 Sign-in Identities and Resolvers 文档的 Building Custom Resolvers 一节构建自定义 resolver。核心思路是从packages/backend/src/index.ts中移除 provider 模块的默认backend.add(import(...))改为通过createBackendModule构造自定义模块并用createOAuthProviderFactory注册自己的signInResolver例如import { createBackendModule } from backstage/backend-plugin-api; import { oktaAuthenticator } from backstage/plugin-auth-backend-module-okta-provider; import { authProvidersExtensionPoint, createOAuthProviderFactory, } from backstage/plugin-auth-node; const customAuth createBackendModule({ pluginId: auth, moduleId: custom-okta-provider, register(reg) { reg.registerInit({ deps: { providers: authProvidersExtensionPoint }, async init({ providers }) { providers.registerProvider({ providerId: okta, factory: createOAuthProviderFactory({ authenticator: oktaAuthenticator, async signInResolver(info, ctx) { // 自定义 resolver 逻辑info 为 Okta 登录结果ctx 提供 // findCatalogUser / signInWithCatalogUser / issueToken 等工具 }, }), }); }, }); }, }); backend.add(import(backstage/plugin-auth-backend)); backend.add(customAuth);注意使用自定义 resolver 时请确保app-config.yaml中不再包含signIn.resolvers字段否则配置中的 resolver 优先级更高、会覆盖代码中的自定义逻辑。四、后端安装与注册要启用该 provider首先在 Backstage 根目录执行以下命令安装依赖包# 在 Backstage 根目录下执行 yarn --cwd packages/backend add backstage/plugin-auth-backend-module-okta-provider然后在packages/backend/src/index.ts中注册该模块backend.add(import(backstage/plugin-auth-backend)); backend.add(import(backstage/plugin-auth-backend-module-okta-provider));这里的模块定义位于 module.ts其pluginId为auth、moduleId为okta-provider最终通过authProvidersExtensionPoint以providerId: okta注册 OAuth provider 工厂因此它对应配置文件中的auth.providers.okta。五、前端登录页接入后端配置完成后还需在前端应用中将 Okta 配置为登录方式。Backstage 通过SignInPage应用组件来渲染登录页登录成功后会通过onSignInSuccess回调注入当前用户身份随后渲染应用其余部分。根据 Authentication in Backstage 文档的说明在packages/app/src/App.tsx中添加如下内容以新前端系统为例import { createApp } from backstage/frontend-defaults; import { oktaAuthApiRef } 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: okta-auth-provider, title: Okta, message: Sign in using Okta, apiRef: oktaAuthApiRef, }} / ), }, }); export default createApp({ features: [ // ...其他插件 createFrontendModule({ pluginId: app, extensions: [signInPage], }), ], });其中oktaAuthApiRef由backstage/core-plugin-api导出见 auth.ts该 ref 实际重导出自backstage/frontend-plugin-api是前端访问 Okta 认证能力OAuth 授权、Profile 信息与会话管理的标准入口。如需同时支持多个登录方式可将provider改为providers数组例如追加guest或根据auth.environment配置条件渲染不同的登录方式。六、常见登录问题排查The Okta provider is not configured to support sign-in通常是因为signIn.resolvers未添加到 Okta provider 配置中或在app-config.yaml中存在配置语法错误。可通过yarn backstage-cli config:check --strict定位语法问题。Failed to sign-in, unable to resolve user identity说明所选 resolver 未能在 Catalog 中找到匹配的 User 实体。此时需要确保 Catalog 中已通过组织数据提供方例如 GitHub/GitLab 的 org 数据、自定义 Entity Provider导入对应的 User及 Group实体详见 identity-resolver.md。七、小结在 Backstage 中接入 Okta 认证的核心链路为Okta 控制台创建 OIDC Web 应用 →app-config.yaml配置auth.providers.okta→ 安装并注册backstage/plugin-auth-backend-module-okta-provider→ 前端通过oktaAuthApiRef配置SignInPage→ 按需选择或自定义 sign-in resolver。理解 authenticator.ts 中audience校验、scope 合并等底层逻辑以及 config.d.ts 所定义的配置 Schema能帮助你在配置出错时快速定位问题。生产环境请务必替换回调地址、启用域名白名单并对dangerouslyAllowSignInWithoutUserInCatalog等高风险选项保持警惕。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考