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-proxyoauth2-proxy 是一个基于 OAuth2 的反向代理认证网关可以为上游服务统一接入身份提供商IdP。本文聚焦于 oauth2-proxy 对自托管 Git 服务 Gitea以及其分支 Forgejo的接入方式Gitea 在 oauth2-proxy 中并非独立的 Provider而是完整复用 GitHub Provider 的实现与配置项只需将授权、换取令牌、校验等端点指向你自己的 Gitea 实例。读完本文你将掌握从 Gitea 后台创建 OAuth2 应用、到配置 oauth2-proxy 完成登录认证的全流程并能进一步利用 GitHub Provider 的组织/团队/仓库级访问控制能力同时理解其底层实现原理。一、为什么 Gitea 不是独立 Provider在 oauth2-proxy 的文档中Gitea / Forgejo 章节开头就有一句关键说明见 gitea.mdThis is not actually a fully separate provider. For more details and options please refer to the GitHub Provider Options.也就是说Gitea 的 OAuth2 流程在协议层面与 GitHub 高度兼容都是标准的授权码模式Authorization Code Flow端点为/login/oauth/authorize授权与/login/oauth/access_token换令牌用户信息与校验则走 REST API。因此 oauth2-proxy 直接复用 GitHub Provider 的实现通过覆盖端点地址来适配 Gitea。从源码结构看这一点体现得十分明确providers/目录下没有gitea.goGitea 相关的逻辑全部由 providers/github.go 中的GitHubProvider承载其 ProviderType 枚举也仅包含github见 pkg/apis/options/providers.go 中的GitHubProvider ProviderType github。这正是配置时--provider必须写github的原因。二、第一步在 Gitea 中创建 OAuth2 应用在开始配置 oauth2-proxy 之前需要先让 Gitea 颁发一组 OAuth 客户端凭证。步骤如下使用 Gitea 管理员或具有应用管理权限的账号登录你的 Gitea 实例进入应用管理页面https://你的 gitea 主机/user/settings/applications点击生成新令牌 / 创建 OAuth2 应用Generate New Client Credentials / OAuth2 Application在Redirect URI重定向 URI一栏填入 oauth2-proxy 的回调地址格式必须是https://被代理的主机/oauth2/callback。例如你的网关域名为oauth.yourcompany.com则填写https://oauth.yourcompany.com/oauth2/callback创建成功后Gitea 会展示Client ID和Client Secret请将它们复制并妥善保存后续配置会用到。注意回调路径/oauth2/callback是 oauth2-proxy 的固定回调端点不可随意更改这里的被代理的主机指最终对外提供服务的网关地址而不是 Gitea 自身地址。三、第二步为 oauth2-proxy 传入 Provider 配置获取到客户端凭证后将下列参数传给 oauth2-proxy以命令行标志为例--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各参数含义与注意事项如下参数说明本例取值--provider声明使用的 Provider 类型Gitea 必须复用githubgithub--redirect-urloauth2-proxy 暴露给外部的回调地址须与 Gitea 应用里填写的 Redirect URI 完全一致https://proxied host/oauth2/callback--provider-display-name登录页上显示的名称填Gitea或Forgejo后登录按钮将显示Sign in with GiteaGitea--client-idGitea 生成的 Client ID来自 Gitea 后台--client-secretGitea 生成的 Client Secret来自 Gitea 后台--login-urlGitea 的 OAuth 授权端点https://gitea host/login/oauth/authorize--redeem-urlGitea 的令牌兑换端点换取 access tokenhttps://gitea host/login/oauth/access_token--validate-url会话校验端点Gitea 使用用户邮箱列表 APIhttps://gitea host/api/v1/user/emails3.1 也可以改用配置文件命令行参数一一对应地写在配置文件里同样有效。仓库在 contrib/local-environment/oauth2-proxy-gitea.cfg 中提供了一份完整的 Gitea 接入示例配置可直接参考http_address0.0.0.0:4180 cookie_secretOQINaROshtE9TcZkNAm-5Zs2Pv3xaWytBmc5W7sPX7w email_domains[localhost] cookie_securefalse upstreamshttp://httpbin cookie_domains[.localtest.me] # Required so cookie can be read on all subdomains. whitelist_domains[.localtest.me] # Required to allow redirection back to original requested target. client_idef0c2b91-2e38-4fa8-908d-067a35dbb71c client_secretgto_qdppomn2p26su5x46tyixj7bcny5m5er2s67xhrponq2qtp66f3a redirect_urlhttp://oauth2-proxy.localtest.me:4180/oauth2/callback # gitea provider 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注意两点实践细节配置文件中除 Provider 相关参数外还需自行指定cookie_secret会话加密密钥应使用足够随机的值、upstreams被代理的上游服务以及邮件域/回调相关配置。示例中email_domains[localhost]用于限制允许登录的邮箱域当 oauth2-proxy 与 Gitea 部署在同一台机器如本地联调时login_url/redeem_url/validate_url可以使用http://而非https://并在前面配合--cookie-securefalse生产环境则必须使用 HTTPS 并开启安全 Cookie。四、进阶继承 GitHub Provider 的访问控制能力由于 Gitea 复用的是 GitHub ProviderGitHub Provider 的全部专属选项在 Gitea 场景下同样可用。官方 GitHub Provider 选项详见 github.md关键参数如下FlagToml Field类型说明--github-orggithub_orgstring仅允许指定组织的成员登录--github-teamgithub_teamstring仅允许这些团队slug或org:team格式的成员登录逗号分隔--github-repogithub_repostring仅允许该仓库的协作者登录格式为orgname/repo--github-tokengithub_tokenstring校验仓库协作者时使用的令牌须对该仓库有 push 权限--github-usergithub_usersstring | list允许这些用户名直接登录即使其不属于上述 org/team/协作者范围从底层实现看这些选项对应 pkg/apis/options/providers.go 中的GitHubOptions结构体YAML 字段为org、team、repo、token、users。它们的作用逻辑集中在 providers/github.go 的checkRestrictions方法中Org与Team均配置时调用hasOrgAndTeam要求用户同时属于指定组织且位于指定团队仅配置Org时调用hasOrg只校验组织成员身份仅配置Team时调用hasTeam此时要求团队名必须写成完整的org:team形式如octo:cat源码中会对此进行校验并给出team name is invalid提示Repo配置且未提供 Token 时调用hasRepoAccess检查仓库权限用户必须对该仓库有 push 权限或仓库为私有且用户可 pullUsers配置后命中用户名的用户会跳过上述所有限制直接放行。这些限制手段通常配合--email-domain*使用即不依赖邮箱域过滤。此外用户所属的全部组织与团队会写入X-Forwarded-Groups请求头格式形如org1:team1,org1:team2,org2:team1上游服务可据此做二次授权。局限说明这些 API 调用依赖 Gitea 与 GitHub 兼容的 REST 接口组织列表、团队列表、用户信息等。Gitea 的 API 路径以/api/v1开头与 GitHub 的/api/v3不同但 providers/github.go 中的makeGitHubAPIEndpoint会自动识别validate_url路径中的/api/vN前缀并作为 API 基础路径因此只需把validate_url指向 Gitea如https://gitea host/api/v1/user/emails组织、团队等接口调用就会自动落在/api/v1/user/orgs、/api/v1/user/teams上。五、源码级原理解析会话如何被校验与充实理解 Gitea 场景下 oauth2-proxy 的认证闭环核心看 providers/github.go 中GitHubProvider的两个生命周期方法1.EnrichSession令牌兑换后充实会话Redeem成功后oauth2-proxy 会依次执行getOrgAndTeam分页每页 100 条调用/user/orgs与/user/teams把组织与团队写入会话的Groups。值得注意该方法的结构体同时兼容 GitHub 的login字段与 Gitea 的name字段源码注释明确标注了 Gitea API 的对应链接团队部分 GitHub 使用slug、Gitea 使用name代码中做了分支处理checkRestrictions执行上文所述的 org/team/repo/user 访问控制getEmail调用/user/emails取第一个verified已验证且primary主邮箱的邮箱写入会话 EmailgetUser调用/user获取登录名并据此完成协作者检查。2.ValidateSession后续请求的会话校验每次请求进入时oauth2-proxy 会携带 access token 调用validate_url指向的端点来确认会话仍然有效。Gitea 场景下该端点即https://gitea host/api/v1/user/emails。providers/gitea_test.go 中的测试用例恰好印证了这套行为TestGiteaProvider_ValidateSessionWithUserEmails模拟 Gitea 后端返回[{email: michael.blandgsa.gov, verified: true, primary: true}]后ValidateSession返回true说明会话校验依赖/api/v1/user/emails返回合法的已验证邮箱TestGiteaProvider_ValidateSessionWithBaseUrl当该接口无有效返回时校验结果为false。测试中还构造了/api/v1/user、/api/v1/user/orgs含page/per_page分页参数、/api/v1/repos/...、/api/v1/repos/.../collaborators/...等模拟端点全面覆盖了 Gitea 场景下组织、团队、仓库协作者等各类校验路径。六、本地快速联调一键拉起 Gitea oauth2-proxy仓库的 contrib/local-environment 目录提供了现成的本地联调环境让读者无需真实域名即可完整走通登录流程。docker-compose-gitea.yaml会同时启动三个容器oauth2-proxy镜像quay.io/oauth2-proxy/oauth2-proxy加载 oauth2-proxy-gitea.cfg 配置监听4180端口gitea镜像gitea/gitea:1.26.2作为身份提供商监听3000端口并在 Docker 网络内别名解析为gitea.localtest.mehttpbin作为示例上游服务用于验证认证通过后的代理转发效果。启动方式见 contrib/local-environment/Makefile 与 docker-compose-gitea.yaml 文件头注释docker-compose -f docker-compose-gitea.yaml up -d # 或使用 Makefile 封装的目标 make gitea-up环境启动后访问http://oauth2-proxy.localtest.me:4180触发登录流程可用示例账号adminexample.com/password登录访问http://gitea.localtest.me:3000同一账号可查看 Gitea 后台与已创建的 OAuth2 应用停止环境使用make gitea-down。这份本地环境使用的正是本文第三节的配置内容providergithub、provider_display_nameGitea、三个端点均指向gitea.localtest.me:3000并配合cookie_domains[.localtest.me]与whitelist_domains[.localtest.me]解决本地多子域下的 Cookie 与回跳问题是理解整套接入配置的最佳参考实现。七、注意事项与常见问题--provider必须为githubGitea 没有独立的 provider 类型把--provider写成gitea会被判定为无效 provider合法取值仅限 pkg/apis/options/providers.go 中枚举的adfs、azure、github、gitlab、google、oidc等validate_url指向邮箱接口Gitea 场景官方推荐的校验端点是/api/v1/user/emails这与 GitHub 默认的 API 根路径不同务必显式配置组织/团队字段兼容性GitHub 组织使用login、团队使用slugGitea 组织使用name、团队使用nameproviders/github.go 已做兼容处理但--github-team单独使用时必须采用org:team完整格式Forgejo 兼容文档标题明确将 Forgejo 一并涵盖gitea.md。由于 Forgejo 是 Gitea 的分支其 OAuth2 端点与 API 路径基本一致因此上述配置思路同样适用只需把各 URL 中的主机与 API 前缀替换为 Forgejo 实例的实际地址生产安全生产环境务必使用 HTTPS 端点、设置强随机cookie_secret并按需配合--cookie-securetrue与--email-domain域名白名单。通过本文的配置你可以在完全自托管的 Gitea / Forgejo 之上快速搭建一套带 OAuth2 认证的反向代理网关并复用 oauth2-proxy 成熟的组织、团队与仓库级访问控制能力。【免费下载链接】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），仅供参考