Backstage 登录实战从 GitHub OAuth 配置到登录验证与问题排查【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南以 docs/getting-started/logging-in.md 为主线系统讲解如何在本地 Backstage 实例中完成登录从基于 GitHub OAuth App 的认证配置、前端登录页接入、后端 provider 注册到 Sign-in Resolver 的用户身份映射以及登录失败的常见报错排查。读完本文你将能够在自己的 Backstage 应用中启用真实的 GitHub 登录、通过 Catalog 中的 User 实体完成身份解析并具备独立诊断登录链路问题的能力。前置条件在开始之前你需要先完成两件事拥有一个可运行的独立 Backstage 应用使用npx backstage/create-applatest创建并启动完整步骤见 独立安装指南。安装完成后在应用根目录执行yarn start即可同时拉起前端http://localhost:3000与后端http://localhost:7007。完成 GitHub OAuth App 的创建与配置这一步的详细操作见 认证配置教程。注意该教程面向新前端系统编写如果你仍在使用旧前端系统请参考 旧版认证配置。默认创建的应用自带一个 guest Sign In Resolver所有用户共享同一个 guest 身份仅用于快速跑通流程生产环境必须替换为真实身份提供商。关于 guest provider 与身份解析的更多说明可阅读 Sign-in Identities and Resolvers。1. 登录 Backstage在应用根目录运行yarn start然后访问http://localhost:3000。如果当前尚未登录你会看到如下登录界面登录步骤在登录页选择GitHubprovider点击Sign in按钮浏览器将重定向到 GitHub 的 OAuth 授权页面核对授权页面上展示的scopes是否与你之前在 认证配置教程 中的设置一致点击Confirm授权后浏览器会跳回 Backstage 界面此时你已成功登录。如果你此前已经登录过会话仍然有效打开http://localhost:3000会被自动带入 Backstage 实例不再显示登录页。从链路角度看这个登录过程实际发生的是前端登录页通过githubAuthApiRef发起 OAuth 流程 → 用户被重定向到 GitHub → GitHub 回调到 auth 后端的http://localhost:7007/api/auth/github/handler/frame→ 后端完成令牌签发后回到前端。回调地址的7007端口正是后端服务默认监听端口这也是为什么创建 OAuth App 时必须把 Authorization callback URL 指向该地址。2. 验证登录状态登录成功后在左侧导航栏找到Settings并点击进入你将看到自己的用户档案Profile。如果这里显示了来自 GitHub 的头像和用户名恭喜你——GitHub 认证集成已完全生效。如果看不到头像和用户名请按以下顺序排查回查 认证配置教程 中的每一步是否全部完成尤其是app-config.yaml中clientId/clientSecret的拼写、缩进与取值确认 Sign-in Resolver 已经配置且能在 Catalog 中匹配到对应的 User 实体见下文第 4 节若仍然无解可结合第 5 节的报错信息进一步定位。3. 完整的 GitHub 认证配置清单本节完整复现 认证配置教程 的实操步骤它是登录功能能够运行的前提。3.1 在 GitHub 上创建 OAuth App打开 GitHub 的 开发者设置 页面创建 OAuth App本地开发环境的推荐参数如下配置项取值Application nameBackstage或你的自定义名称Homepage URLhttp://localhost:3000指向 Backstage 前端Authorization callback URLhttp://localhost:7007/api/auth/github/handler/frame指向 auth 后端如果你使用的是 GitHub App 而非 OAuth App需要注意两者的差异GitHub App 在应用安装层面管理 OAuth scope前端调用getAccessToken时传入的scope参数不会生效。详见 GitHub 认证 Provider 文档。创建完成后记录Client ID和Client Secret点击 Generate a new client secret 获取后者。3.2 在 app-config.yaml 中写入凭据打开应用根目录的app-config.yaml在auth配置块下添加 provider 配置auth: # see https://backstage.io/docs/auth/ to learn about auth providers environment: development providers: # See https://backstage.io/docs/auth/guest/provider guest: {} github: development: clientId: YOUR CLIENT ID clientSecret: YOUR CLIENT SECRETGitHub provider 支持的关键配置项如下详见 GitHub 认证 Provider 文档clientIdGitHub 生成的客户端 ID例如b59241722e3c3b4816e2clientSecret与该 Client ID 绑定的客户端密钥enterpriseInstanceUrl可选GitHub Enterprise 实例的 base URL如https://ghe.company.com仅 GitHub Enterprise 需要callbackUrl可选当 Backstage 不是 OAuth 流程的直接接收方时例如多个 Backstage 实例共用同一个 OAuth App需要设置sessionDuration可选用户会话的生命周期支持ms库格式如24h、ISO 时长等写法signIn登录流程配置包含用于将外部身份映射到 Catalog User 实体的resolvers。需要说明的是providers下可以配置多个认证提供商同一个 provider 也可以按环境development、production 等分别配置系统会根据auth.environment的值选择匹配的配置块。3.3 前端接入登录页新前端系统接下来需要在packages/app中添加依赖并改造packages/app/src/App.tsx。首先安装所需包在仓库根目录执行yarn --cwd packages/app add backstage/core-plugin-api backstage/plugin-app-react然后在packages/app/src/App.tsx中紧接最后一个 import 之后添加import { githubAuthApiRef } 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;使用SignInPageBlueprint创建登录页扩展const signInPage SignInPageBlueprint.make({ params: { loader: async () props ( SignInPage {...props} provider{{ id: github-auth-provider, title: GitHub, message: Sign in using GitHub, apiRef: githubAuthApiRef, }} / ), }, });最后找到createApp()调用将原本的export default createApp({ features: [catalogPlugin, navModule], });替换为export default createApp({ features: [ catalogPlugin, navModule, createFrontendModule({ pluginId: app, extensions: [signInPage], }), ], });如果你希望同时提供多种登录方式可以把provider换成providers数组例如[guest, {...github 配置...}]还可以借助configApi读取auth.environment在开发环境开放 guest、生产环境仅保留 GitHub。更完整的写法参见 Authentication in Backstage。此外如果希望登录改为无弹窗的重定向流程可在app-config.yaml根级添加enableExperimentalRedirectFlow: true。3.4 后端添加 GitHub Provider后端需要安装并注册对应的 provider 模块在仓库根目录执行# from your Backstage root directory yarn --cwd packages/backend add backstage/plugin-auth-backend-module-github-provider然后在packages/backend/src/index.ts中注册backend.add(import(backstage/plugin-auth-backend)); backend.add(import(backstage/plugin-auth-backend-module-github-provider));注册的核心逻辑在仓库源码 plugins/auth-backend-module-github-provider/src/module.ts 中authModuleGithubProvider是一个针对auth插件的后端模块它通过authProvidersExtensionPoint注册githubprovider并使用createOAuthProviderFactory组合了githubAuthenticator负责与 GitHub 通信的认证器见 authenticator.ts以及来自githubSignInResolvers与commonSignInResolvers的解析器集合。完成后在终端用CtrlC停掉 Backstage再执行yarn start重启登录提示就会出现了。此时直接登录会报 Failed to sign-in, unable to resolve user identity因为还没有配置身份解析——这正是下一节要解决的问题。注意有时前端会比后端先启动完成导致登录页短暂报错。等待后端启动完毕后刷新页面即可。4. 配置 Sign-in Resolver建立外部身份到 Backstage 身份的映射4.1 Backstage 用户身份由什么构成在 Backstage 中用户身份主要由两部分构成详见 Backstage User Identity用户实体引用user entity reference唯一标识登录用户例如user:default/jane。它通常对应 Software Catalog 中的 User 实体Catalog 中存在对应实体并非强制但强烈推荐许多插件依赖它所有权引用ownership references一组实体引用用于判断用户拥有什么。例如用户 Janeuser:default/jane可以拥有user:default/jane、group:default/team-a、group:default/admins等所有权声明任何被标记为属于这些实体之一的条目都视为归 Jane 所有。登录成功后生成的后端令牌是一个 JWT用户实体引用存放在sub声明中所有权引用存放在ent声明中新后端系统中通过 auth 后端的 user info API 提供。这就是登录在数据层面的产物。4.2 可用的内置 ResolverGitHub provider 提供了两个 provider 专属的 resolver源码位于 plugins/auth-backend-module-github-provider/src/resolvers.tsResolver匹配逻辑说明usernameMatchingUserEntityNameGitHub 用户名 ↔ User 实体的metadata.name最常用见githubSignInResolvers.usernameMatchingUserEntityNameresolvers.ts取fullProfile.username后调用ctx.signInWithCatalogUseruserIdMatchingUserEntityAnnotationGitHub 用户 ID ↔ User 实体的github.com/user-id注解见 resolvers.ts取fullProfile.nodeId后按注解查找此外所有 provider 共享两个通用 resolveremailMatchingUserEntityProfileEmail用邮箱匹配 User 实体的spec.profile.emailemailLocalPartMatchingUserEntityName用邮箱的 local part 匹配 User 实体的name。使用该 resolver 时强烈建议设置allowedDomains白名单防止未授权用户登录auth: providers: github: development: ... signIn: resolvers: - resolver: emailLocalPartMatchingUserEntityName allowedDomains: - acme.org多个 resolver 会按顺序尝试但只有抛出NotFoundError时才会跳过并尝试下一个匹配失败会抛出NotFoundError。详见 GitHub Provider 文档的 Resolvers 一节。4.3 在配置中启用 Resolver 并添加 User 实体在app-config.yaml的 GitHub provider 配置下增加signIn.resolversauth: # see https://backstage.io/docs/auth/ to learn about auth providers environment: development providers: # See https://backstage.io/docs/auth/guest/provider guest: {} github: development: clientId: YOUR CLIENT ID clientSecret: YOUR CLIENT SECRET signIn: resolvers: # Matches the GitHub username with the Backstage user entity name. # See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers. - resolver: usernameMatchingUserEntityName其作用是把 GitHub 提供的用户信息与 Catalog 中的 User 实体进行匹配。为了让解析成功需要在 Catalog 中准备对应的 User 实体。新创建的应用自带examples/org.yamlCatalog 的默认数据源之一在文件末尾追加--- apiVersion: backstage.io/v1alpha1 kind: User metadata: name: YOUR GITHUB USERNAME spec: memberOf: [guests]把YOUR GITHUB USERNAME替换为你的真实 GitHub 用户名。再次CtrlC停止、yarn start启动后即可用 GitHub 账号登录并看到 Catalog 中的内容。对于生产环境推荐使用现成的 Org Entity Provider 从组织数据源导入 User 与 Group例如 GitHub Org 集成、GitLab Org、Azure Org 等没有合适现成方案的可自行创建 自定义 Entity Provider。4.4 自定义 Resolver当内置 resolver 不满足需求时可以完全用代码编写自定义 sign-in resolver移除packages/backend/src/index.ts中 provider 模块的 import改为通过createBackendModule与createOAuthProviderFactory自行构造 provider并在signInResolver回调中实现映射逻辑。一个典型的实现会校验 profile 中的邮箱、调用ctx.signInWithCatalogUser完成 Catalog 查找与令牌签发也可以改用ctx.findCatalogUserctx.resolveOwnershipEntityRefsctx.issueToken进行更底层的所有权解析控制甚至跳过 Catalog 直接签发令牌此时必须自己限制可登录用户例如校验邮箱域名。完整示例代码见 Building Custom Resolvers。如果只是想放宽Catalog 中必须存在该用户的限制还有一个配置层面的捷径为 resolver 开启dangerouslyAllowSignInWithoutUserInCatalog: true。这会跳过 Catalog 检查直接基于 resolver 层可用的身份信息签发令牌。该选项在生产环境存在明显安全风险未纳入 Backstage 的用户也可能获得访问权且由于没有关联的 User 实体权限系统可能无法按预期生效其权限将与 guest 用户相同。请谨慎评估后再决定是否启用。5. 登录问题排查指南登录文档同时定位为一份调试指南。以下是两个最常见的登录报错及其解法详细说明见 Common Sign-In Resolver Errors。5.1 报错The GitHub provider is not configured to support sign-in可能的原因与解决办法signIn.resolvers未添加到 provider 配置中按 4.3 节补上即可解决provider 配置存在语法错误运行yarn backstage-cli config:check --strict可帮助定位语法问题。5.2 报错Failed to sign-in, unable to resolve user identity这个错误意味着你配置的 Sign-in Resolver 无法在 Catalog 中找到匹配的 User 实体。解决办法是把组织内 User及 Group数据从权威来源导入 Catalog可参考 Entra IDAzure AD/MS Graph、GitHub、GitLab 等 Org 数据 provider或按需创建 自定义 Entity Provider。5.3 其他常见注意点前端先于后端启动登录页可能出现临时错误等待后端就绪后刷新页面即可修改配置后需要重启后端认证与集成相关配置变更通常不会热加载用CtrlC停止后用yarn start重启再重试观察令牌签发日志启动日志中componenttoken-factory相关的信息如Created new signing key、Issuing token for user:...可用于确认 auth 后端确实完成了令牌签发参见 独立安装指南的启动日志示例。6. 进阶配置 GitHub Integration供其他插件使用完成登录后若要打通 Scaffolder软件模板、Catalog Import 等插件与 GitHub 的交互还需要配置 GitHub Integration。推荐在本教程场景下使用 Personal Access Token并写入app-config.local.yaml该文件位于项目根目录、默认被.gitignore排除避免误提交integrations: github: - host: github.com token: ghp_urtokendeinfewinfiwebfweb # this should be the token from GitHub更安全的做法是把 token 放入环境变量GITHUB_TOKEN后再引用integrations: github: - host: github.com token: ${GITHUB_TOKEN} # this will use the environment variable GITHUB_TOKEN本教程中创建 token 时建议勾选repo与workflow两个 scope因为后续的脚手架任务会为新项目配置 GitHub Actions 工作流。关于静态配置文件的更多细节见 Static Configuration 文档关于其他集成方式GitHub Apps 等见 Integrations 总览 与 GitHub Apps。延伸阅读Authentication in Backstage认证体系总览、内置 provider 列表、代理型 provider 登录等Sign-in Identities and Resolvers用户身份构成、内置/自定义 resolver、常见错误详解GitHub Authentication ProviderGitHub provider 完整配置项与 resolver 列表Using organizational data from GitHub从 GitHub 组织导入用户与分组Independent Installation Guide创建并启动独立 Backstage 应用【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Backstage 登录实战：从 GitHub OAuth 配置到登录验证与问题排查
Backstage 登录实战从 GitHub OAuth 配置到登录验证与问题排查【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南以 docs/getting-started/logging-in.md 为主线系统讲解如何在本地 Backstage 实例中完成登录从基于 GitHub OAuth App 的认证配置、前端登录页接入、后端 provider 注册到 Sign-in Resolver 的用户身份映射以及登录失败的常见报错排查。读完本文你将能够在自己的 Backstage 应用中启用真实的 GitHub 登录、通过 Catalog 中的 User 实体完成身份解析并具备独立诊断登录链路问题的能力。前置条件在开始之前你需要先完成两件事拥有一个可运行的独立 Backstage 应用使用npx backstage/create-applatest创建并启动完整步骤见 独立安装指南。安装完成后在应用根目录执行yarn start即可同时拉起前端http://localhost:3000与后端http://localhost:7007。完成 GitHub OAuth App 的创建与配置这一步的详细操作见 认证配置教程。注意该教程面向新前端系统编写如果你仍在使用旧前端系统请参考 旧版认证配置。默认创建的应用自带一个 guest Sign In Resolver所有用户共享同一个 guest 身份仅用于快速跑通流程生产环境必须替换为真实身份提供商。关于 guest provider 与身份解析的更多说明可阅读 Sign-in Identities and Resolvers。1. 登录 Backstage在应用根目录运行yarn start然后访问http://localhost:3000。如果当前尚未登录你会看到如下登录界面登录步骤在登录页选择GitHubprovider点击Sign in按钮浏览器将重定向到 GitHub 的 OAuth 授权页面核对授权页面上展示的scopes是否与你之前在 认证配置教程 中的设置一致点击Confirm授权后浏览器会跳回 Backstage 界面此时你已成功登录。如果你此前已经登录过会话仍然有效打开http://localhost:3000会被自动带入 Backstage 实例不再显示登录页。从链路角度看这个登录过程实际发生的是前端登录页通过githubAuthApiRef发起 OAuth 流程 → 用户被重定向到 GitHub → GitHub 回调到 auth 后端的http://localhost:7007/api/auth/github/handler/frame→ 后端完成令牌签发后回到前端。回调地址的7007端口正是后端服务默认监听端口这也是为什么创建 OAuth App 时必须把 Authorization callback URL 指向该地址。2. 验证登录状态登录成功后在左侧导航栏找到Settings并点击进入你将看到自己的用户档案Profile。如果这里显示了来自 GitHub 的头像和用户名恭喜你——GitHub 认证集成已完全生效。如果看不到头像和用户名请按以下顺序排查回查 认证配置教程 中的每一步是否全部完成尤其是app-config.yaml中clientId/clientSecret的拼写、缩进与取值确认 Sign-in Resolver 已经配置且能在 Catalog 中匹配到对应的 User 实体见下文第 4 节若仍然无解可结合第 5 节的报错信息进一步定位。3. 完整的 GitHub 认证配置清单本节完整复现 认证配置教程 的实操步骤它是登录功能能够运行的前提。3.1 在 GitHub 上创建 OAuth App打开 GitHub 的 开发者设置 页面创建 OAuth App本地开发环境的推荐参数如下配置项取值Application nameBackstage或你的自定义名称Homepage URLhttp://localhost:3000指向 Backstage 前端Authorization callback URLhttp://localhost:7007/api/auth/github/handler/frame指向 auth 后端如果你使用的是 GitHub App 而非 OAuth App需要注意两者的差异GitHub App 在应用安装层面管理 OAuth scope前端调用getAccessToken时传入的scope参数不会生效。详见 GitHub 认证 Provider 文档。创建完成后记录Client ID和Client Secret点击 Generate a new client secret 获取后者。3.2 在 app-config.yaml 中写入凭据打开应用根目录的app-config.yaml在auth配置块下添加 provider 配置auth: # see https://backstage.io/docs/auth/ to learn about auth providers environment: development providers: # See https://backstage.io/docs/auth/guest/provider guest: {} github: development: clientId: YOUR CLIENT ID clientSecret: YOUR CLIENT SECRETGitHub provider 支持的关键配置项如下详见 GitHub 认证 Provider 文档clientIdGitHub 生成的客户端 ID例如b59241722e3c3b4816e2clientSecret与该 Client ID 绑定的客户端密钥enterpriseInstanceUrl可选GitHub Enterprise 实例的 base URL如https://ghe.company.com仅 GitHub Enterprise 需要callbackUrl可选当 Backstage 不是 OAuth 流程的直接接收方时例如多个 Backstage 实例共用同一个 OAuth App需要设置sessionDuration可选用户会话的生命周期支持ms库格式如24h、ISO 时长等写法signIn登录流程配置包含用于将外部身份映射到 Catalog User 实体的resolvers。需要说明的是providers下可以配置多个认证提供商同一个 provider 也可以按环境development、production 等分别配置系统会根据auth.environment的值选择匹配的配置块。3.3 前端接入登录页新前端系统接下来需要在packages/app中添加依赖并改造packages/app/src/App.tsx。首先安装所需包在仓库根目录执行yarn --cwd packages/app add backstage/core-plugin-api backstage/plugin-app-react然后在packages/app/src/App.tsx中紧接最后一个 import 之后添加import { githubAuthApiRef } 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;使用SignInPageBlueprint创建登录页扩展const signInPage SignInPageBlueprint.make({ params: { loader: async () props ( SignInPage {...props} provider{{ id: github-auth-provider, title: GitHub, message: Sign in using GitHub, apiRef: githubAuthApiRef, }} / ), }, });最后找到createApp()调用将原本的export default createApp({ features: [catalogPlugin, navModule], });替换为export default createApp({ features: [ catalogPlugin, navModule, createFrontendModule({ pluginId: app, extensions: [signInPage], }), ], });如果你希望同时提供多种登录方式可以把provider换成providers数组例如[guest, {...github 配置...}]还可以借助configApi读取auth.environment在开发环境开放 guest、生产环境仅保留 GitHub。更完整的写法参见 Authentication in Backstage。此外如果希望登录改为无弹窗的重定向流程可在app-config.yaml根级添加enableExperimentalRedirectFlow: true。3.4 后端添加 GitHub Provider后端需要安装并注册对应的 provider 模块在仓库根目录执行# from your Backstage root directory yarn --cwd packages/backend add backstage/plugin-auth-backend-module-github-provider然后在packages/backend/src/index.ts中注册backend.add(import(backstage/plugin-auth-backend)); backend.add(import(backstage/plugin-auth-backend-module-github-provider));注册的核心逻辑在仓库源码 plugins/auth-backend-module-github-provider/src/module.ts 中authModuleGithubProvider是一个针对auth插件的后端模块它通过authProvidersExtensionPoint注册githubprovider并使用createOAuthProviderFactory组合了githubAuthenticator负责与 GitHub 通信的认证器见 authenticator.ts以及来自githubSignInResolvers与commonSignInResolvers的解析器集合。完成后在终端用CtrlC停掉 Backstage再执行yarn start重启登录提示就会出现了。此时直接登录会报 Failed to sign-in, unable to resolve user identity因为还没有配置身份解析——这正是下一节要解决的问题。注意有时前端会比后端先启动完成导致登录页短暂报错。等待后端启动完毕后刷新页面即可。4. 配置 Sign-in Resolver建立外部身份到 Backstage 身份的映射4.1 Backstage 用户身份由什么构成在 Backstage 中用户身份主要由两部分构成详见 Backstage User Identity用户实体引用user entity reference唯一标识登录用户例如user:default/jane。它通常对应 Software Catalog 中的 User 实体Catalog 中存在对应实体并非强制但强烈推荐许多插件依赖它所有权引用ownership references一组实体引用用于判断用户拥有什么。例如用户 Janeuser:default/jane可以拥有user:default/jane、group:default/team-a、group:default/admins等所有权声明任何被标记为属于这些实体之一的条目都视为归 Jane 所有。登录成功后生成的后端令牌是一个 JWT用户实体引用存放在sub声明中所有权引用存放在ent声明中新后端系统中通过 auth 后端的 user info API 提供。这就是登录在数据层面的产物。4.2 可用的内置 ResolverGitHub provider 提供了两个 provider 专属的 resolver源码位于 plugins/auth-backend-module-github-provider/src/resolvers.tsResolver匹配逻辑说明usernameMatchingUserEntityNameGitHub 用户名 ↔ User 实体的metadata.name最常用见githubSignInResolvers.usernameMatchingUserEntityNameresolvers.ts取fullProfile.username后调用ctx.signInWithCatalogUseruserIdMatchingUserEntityAnnotationGitHub 用户 ID ↔ User 实体的github.com/user-id注解见 resolvers.ts取fullProfile.nodeId后按注解查找此外所有 provider 共享两个通用 resolveremailMatchingUserEntityProfileEmail用邮箱匹配 User 实体的spec.profile.emailemailLocalPartMatchingUserEntityName用邮箱的 local part 匹配 User 实体的name。使用该 resolver 时强烈建议设置allowedDomains白名单防止未授权用户登录auth: providers: github: development: ... signIn: resolvers: - resolver: emailLocalPartMatchingUserEntityName allowedDomains: - acme.org多个 resolver 会按顺序尝试但只有抛出NotFoundError时才会跳过并尝试下一个匹配失败会抛出NotFoundError。详见 GitHub Provider 文档的 Resolvers 一节。4.3 在配置中启用 Resolver 并添加 User 实体在app-config.yaml的 GitHub provider 配置下增加signIn.resolversauth: # see https://backstage.io/docs/auth/ to learn about auth providers environment: development providers: # See https://backstage.io/docs/auth/guest/provider guest: {} github: development: clientId: YOUR CLIENT ID clientSecret: YOUR CLIENT SECRET signIn: resolvers: # Matches the GitHub username with the Backstage user entity name. # See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers. - resolver: usernameMatchingUserEntityName其作用是把 GitHub 提供的用户信息与 Catalog 中的 User 实体进行匹配。为了让解析成功需要在 Catalog 中准备对应的 User 实体。新创建的应用自带examples/org.yamlCatalog 的默认数据源之一在文件末尾追加--- apiVersion: backstage.io/v1alpha1 kind: User metadata: name: YOUR GITHUB USERNAME spec: memberOf: [guests]把YOUR GITHUB USERNAME替换为你的真实 GitHub 用户名。再次CtrlC停止、yarn start启动后即可用 GitHub 账号登录并看到 Catalog 中的内容。对于生产环境推荐使用现成的 Org Entity Provider 从组织数据源导入 User 与 Group例如 GitHub Org 集成、GitLab Org、Azure Org 等没有合适现成方案的可自行创建 自定义 Entity Provider。4.4 自定义 Resolver当内置 resolver 不满足需求时可以完全用代码编写自定义 sign-in resolver移除packages/backend/src/index.ts中 provider 模块的 import改为通过createBackendModule与createOAuthProviderFactory自行构造 provider并在signInResolver回调中实现映射逻辑。一个典型的实现会校验 profile 中的邮箱、调用ctx.signInWithCatalogUser完成 Catalog 查找与令牌签发也可以改用ctx.findCatalogUserctx.resolveOwnershipEntityRefsctx.issueToken进行更底层的所有权解析控制甚至跳过 Catalog 直接签发令牌此时必须自己限制可登录用户例如校验邮箱域名。完整示例代码见 Building Custom Resolvers。如果只是想放宽Catalog 中必须存在该用户的限制还有一个配置层面的捷径为 resolver 开启dangerouslyAllowSignInWithoutUserInCatalog: true。这会跳过 Catalog 检查直接基于 resolver 层可用的身份信息签发令牌。该选项在生产环境存在明显安全风险未纳入 Backstage 的用户也可能获得访问权且由于没有关联的 User 实体权限系统可能无法按预期生效其权限将与 guest 用户相同。请谨慎评估后再决定是否启用。5. 登录问题排查指南登录文档同时定位为一份调试指南。以下是两个最常见的登录报错及其解法详细说明见 Common Sign-In Resolver Errors。5.1 报错The GitHub provider is not configured to support sign-in可能的原因与解决办法signIn.resolvers未添加到 provider 配置中按 4.3 节补上即可解决provider 配置存在语法错误运行yarn backstage-cli config:check --strict可帮助定位语法问题。5.2 报错Failed to sign-in, unable to resolve user identity这个错误意味着你配置的 Sign-in Resolver 无法在 Catalog 中找到匹配的 User 实体。解决办法是把组织内 User及 Group数据从权威来源导入 Catalog可参考 Entra IDAzure AD/MS Graph、GitHub、GitLab 等 Org 数据 provider或按需创建 自定义 Entity Provider。5.3 其他常见注意点前端先于后端启动登录页可能出现临时错误等待后端就绪后刷新页面即可修改配置后需要重启后端认证与集成相关配置变更通常不会热加载用CtrlC停止后用yarn start重启再重试观察令牌签发日志启动日志中componenttoken-factory相关的信息如Created new signing key、Issuing token for user:...可用于确认 auth 后端确实完成了令牌签发参见 独立安装指南的启动日志示例。6. 进阶配置 GitHub Integration供其他插件使用完成登录后若要打通 Scaffolder软件模板、Catalog Import 等插件与 GitHub 的交互还需要配置 GitHub Integration。推荐在本教程场景下使用 Personal Access Token并写入app-config.local.yaml该文件位于项目根目录、默认被.gitignore排除避免误提交integrations: github: - host: github.com token: ghp_urtokendeinfewinfiwebfweb # this should be the token from GitHub更安全的做法是把 token 放入环境变量GITHUB_TOKEN后再引用integrations: github: - host: github.com token: ${GITHUB_TOKEN} # this will use the environment variable GITHUB_TOKEN本教程中创建 token 时建议勾选repo与workflow两个 scope因为后续的脚手架任务会为新项目配置 GitHub Actions 工作流。关于静态配置文件的更多细节见 Static Configuration 文档关于其他集成方式GitHub Apps 等见 Integrations 总览 与 GitHub Apps。延伸阅读Authentication in Backstage认证体系总览、内置 provider 列表、代理型 provider 登录等Sign-in Identities and Resolvers用户身份构成、内置/自定义 resolver、常见错误详解GitHub Authentication ProviderGitHub provider 完整配置项与 resolver 列表Using organizational data from GitHub从 GitHub 组织导入用户与分组Independent Installation Guide创建并启动独立 Backstage 应用【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考