OAuth2-Proxy 接入 Gitea / Forgejo：基于 GitHub Provider 的完整配置指南

OAuth2-Proxy 接入 Gitea / Forgejo基于 GitHub Provider 的完整配置指南【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxy导读Gitea 与 Forgejo 是自托管场景下最常见的轻量级 Git 服务而 oauth2-proxy 提供了一款独立于具体 Identity Provider 的反向代理认证网关。本文聚焦 docs/versioned_docs/version-7.15.x/configuration/providers/gitea.md 的核心内容说明 oauth2-proxy 如何通过复用 GitHub Provider 接入自托管的 Gitea/Forgejo从在 Gitea 侧创建 OAuth2 应用、配置回调地址到使用--providergithub配合自定义登录、兑换、校验端点完成认证再到借助组织、团队、仓库、用户名等维度实现细粒度访问控制。读完本文你将能独立完成一套 Gitea 单点登录代理的搭建与访问策略配置。Gitea Provider 的本质复用 GitHub Provider 而非独立实现在 oauth2-proxy 的 Provider 生态中Gitea 并不是一个拥有独立代码实现的 Provider。原文档明确提示This is not actually a fully separate provider这并不是一个完全独立的 Provider更详细的选项需要参考 GitHub Provider。这一点可以从仓库源码得到直接印证providers/目录下只有 gitea_test.go 而没有gitea.go所有 Gitea 相关的逻辑都发生在 github.go 这一实现中。测试代码里通过NewGitHubProvider构造 Provider并显式将ProviderName设置为Giteap : NewGitHubProvider( ProviderData{ ProviderName: Gitea, LoginURL: url.URL{}, RedeemURL: url.URL{}, ProfileURL: url.URL{}, ValidateURL: url.URL{Path: /api/v1/user/emails}, Scope: }, opts) p.ProviderName Gitea这意味着凡是 GitHub Provider 支持的访问控制选项组织、团队、仓库、用户名对 Gitea/Forgejo 同样有效只需按 Gitea 的 API 语义使用即可。第一步在 Gitea 侧创建 OAuth2 应用在开始配置 oauth2-proxy 之前需要先让 Gitea 认可我们的代理身份登录你的 Gitea 实例进入用户设置 → 应用Applications地址形如https://你的 gitea 主机/user/settings/applications在重定向 URIRedirect URI一栏填写正确的回调地址即代理对外暴露的/oauth2/callback端点https://被代理主机/oauth2/callback这个地址必须与 oauth2-proxy 的--redirect-url完全一致否则 OAuth2 授权流程会失败。保存后记录 Gitea 生成的Client ID客户端 ID与Client Secret客户端密钥后续配置需要使用。第二步为代理传入 Gitea 专属参数由于 Gitea 的 OAuth2 端点与 GitHub 不同需要通过通用端点参数把 GitHub Provider 重定向到自托管的 Gitea 实例。原文档给出的完整命令行参数如下--providergithub --redirect-urlhttps://proxied host/oauth2/callback --provider-display-nameGitea --client-id client_id as generated by Gitea --client-secret client_secret as generated by Gitea --login-urlhttps:// your gitea host /login/oauth/authorize --redeem-urlhttps:// your gitea host /login/oauth/access_token --validate-urlhttps:// your gitea host /api/v1/user/emails各参数含义与配置要点如下参数说明--providergithub指定使用 GitHub Provider 逻辑来对接 Gitea/Forgejo这是本方案的核心前提--redirect-url回调地址必须与 Gitea 应用中填写的重定向 URI 完全一致--provider-display-nameGitea登录页面显示的 Provider 名称便于终端用户识别是使用 Gitea 账号登录--client-id/--client-secretGitea 应用生成的凭据--login-urlGitea 的授权端点固定为/login/oauth/authorize--redeem-urlGitea 的令牌兑换端点固定为/login/oauth/access_token--validate-url用于校验会话有效性的端点使用 Gitea API 的/api/v1/user/emails源码侧的三个端点如何被使用这三个 URL 不是摆设它们分别对应 github.go 中 ProviderData 的LoginURL、RedeemURL、ValidateURL字段。其中ValidateURL语义特殊在 GitHub 实现中它是API Base URL其他 API 请求如拉取组织、团队、邮箱都会基于它拼接路径。makeGitHubAPIEndpoint会用正则提取ValidateURL中的/api/v\d前缀作为 API 根路径re : regexp.MustCompile(^/api/v\d) match : re.FindString(p.ValidateURL.Path) if match ! { basePath match }因此在 Gitea 场景下--validate-url设置为https://gitea 主机/api/v1/user/emails时代理请求用户邮箱、组织、团队等数据时会落到/api/v1/...根路径上与 Gitea API v1 版本对应。如果配错版本号后续的邮箱/组织/团队校验请求都会 404。配置文件CFG/Alpha 配置等价写法除命令行参数外oauth2-proxy 同样支持配置文件方式。仓库自带的本地环境示例 contrib/local-environment/oauth2-proxy-gitea.cfg 展示了完整的 Gitea 对接写法其中provider与各 URL 字段与命令行一一对应providergithub provider_display_nameGitea login_urlhttp://gitea.localtest.me:3000/login/oauth/authorize redeem_urlhttp://gitea.localtest.me:3000/login/oauth/access_token validate_urlhttp://gitea.localtest.me:3000/api/v1/user/emails该示例还配套了 contrib/local-environment/docker-compose-gitea.yaml 本地编排可用于快速起一套 Gitea oauth2-proxy 的实验环境。第三步可选利用 GitHub 选项做细粒度访问控制因为 Gitea 复用 GitHub Provider因此 GitHub Provider 的所有访问控制选项都可用。这些选项在 pkg/apis/options/providers.go 的GitHubOptions结构中定义命令行与配置字段的对应关系在 pkg/apis/options/legacy_options.go 中注册FlagToml/CFG 字段类型说明--github-orggithub_orgstring仅允许指定组织的成员登录--github-teamgithub_teamstring仅允许指定团队slug成员登录可逗号分隔支持org:team全限定格式--github-repogithub_repostring仅允许某仓库协作者登录格式orgname/repo--github-tokengithub_tokenstring校验仓库协作者时使用的令牌需对该仓库有写权限--github-usergithub_usersstring | list即使不属于上述组织/团队/协作者也允许指定用户名登录在GitHubOptions中对应为type GitHubOptions struct { Org string yaml:org,omitempty Team string yaml:team,omitempty Repo string yaml:repo,omitempty Token string yaml:token,omitempty Users []string yaml:users,omitempty }组织与团队限制限定到单个组织通常搭配--email-domain*使用# 仅允许该组织成员登录 --github-orgyour-org限定到组织内的指定团队使用团队 slug逗号分隔--github-orgyour-org # 仅允许下列团队slug成员登录 --github-teamteam1,team2,team3跨多个组织限定团队时可留空--github-org改用org:team全限定格式# 留空 --github-org # 仅允许以下团队格式 org:slug逗号分隔成员登录 --github-teamorg1:team1,org2:team1,org3:team42,octo:cat仓库协作者限制如需限定到仓库协作者用户必须对公开仓库有推送权限或对私有仓库有任何访问权限# 仅允许该仓库格式 orgname/repo协作者登录 --github-repo若希望允许对公开仓库仅有只读权限的用户登录需要额外提供一个对该仓库有写权限用户的令牌且令牌至少包含public_repo权限范围# 校验仓库协作者时使用的令牌 --github-token该判断逻辑位于 github.go 的hasRepoAccess仅当repo.Permissions.Push为真或仓库为私有且用户具有Pull权限时放行。而--github-user指定的用户会跳过所有上述限制见checkRestrictions中先执行checkUserRestriction的设计用于白名单式放行# 允许指定用户名登录即使不属于组织/团队/协作者 --github-useralice,bob组织/团队信息如何写入会话启用上述限制后用户所属的组织与团队会被写入X-Forwarded-Groups请求头格式形如org1:team1,org1:team2,org2:team1可供下游应用做基于组的授权。源码中getOrgs与getTeams会分别调用/user/orgs与/user/teams接口并做分页拉取per_page100其中 Gitea 与 GitHub 的响应字段差异login与name已在代码中兼容处理// Support for Github organizations Login string json:login,omitempty // Support for Gitea organizations Name string json:name,omitempty会话校验与测试验证配置完成后oauth2-proxy 会通过ValidateSession校验用户会话其实现为调用--validate-url指向的接口并检查响应状态。针对 Gitea 场景仓库提供了 providers/gitea_test.go 中的两个典型用例TestGiteaProvider_ValidateSessionWithBaseUrl后端只返回 404 时会话校验失败TestGiteaProvider_ValidateSessionWithUserEmails/api/v1/user/emails返回[{email: michael.blandgsa.gov, verified: true, primary: true}]时会话校验成功。这印证了--validate-url指定的邮箱接口正是会话校验的判定依据Gitea 侧需确保/api/v1/user/emails可被携带用户令牌访问。常见问题与注意事项回调地址必须完全一致Gitea 应用里的重定向 URI 与--redirect-url若不一致授权回调会被 Gitea 拒绝。--validate-url版本号要匹配其路径中的/api/v1会被源码提取为后续 API 请求的根路径写错版本号将导致组织/团队/邮箱拉取失败。--provider-display-name与 Provider 逻辑无关它只影响登录页显示名称即使不设置也不影响认证流程。令牌最小权限使用--github-token校验协作者时令牌持有者需对目标仓库有写权限否则校验结果不准确。总结接入 Gitea / Forgejo 并不需要一个新的 Provideroauth2-proxy 通过--providergithub复用 GitHub Provider 的全部能力再以--login-url、--redeem-url、--validate-url三个参数将认证端点指向自托管的 Gitea 实例即可完成对接随后可借助--github-org、--github-team、--github-repo、--github-user实现组织、团队、仓库协作者与用户名四类细粒度访问控制。本文所有参数均可对照 github.go 的 Provider 实现、gitea_test.go 的测试用例以及 oauth2-proxy-gitea.cfg 的本地示例进行验证与实操。【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考