使用 oauth2-proxy 对接 Gitea基于 GitHub Provider 的 OAuth2 登录配置完整指南【免费下载链接】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本文以 oauth2-proxy 官方文档中 Gitea 配置指南 为核心讲解如何让 oauth2-proxy 通过 Gitea 完成第三方登录。核心要点在于Gitea 并非一个独立的 Provider 实现而是直接复用 GitHub Provider 的协议流程只需把登录、换 token、校验三个端点指向自建 Gitea 实例即可。读完本文你将掌握从 Gitea 创建 OAuth2 应用、到编写 oauth2-proxy 命令行参数或配置文件、再到按组织/团队/仓库进行细粒度访问控制的完整实战方案。Gitea 不是独立 Provider先理解其架构定位oauth2-proxy 支持多种身份提供方Google、Azure、OpenID Connect、GitHub 等但官方文档明确说明Gitea 并没有自己专属的 Provider其 OAuth2 流程与 GitHub 高度兼容因此直接复用 GitHub Provider并通过--login-url、--redeem-url、--validate-url三个参数把请求端点指向你的 Gitea 服务器。这一点在源码中得到印证测试文件 providers/gitea_test.go 中构造的testGiteaProvider函数实际返回的类型就是*GitHubProvider其中ProviderName被显式设置为GiteaValidateURL路径指向/api/v1/user/emails——这正是 Gitea 的 API 风格GitHub 的校验路径是/api/v3。也就是说同一套 GitHub 协议实现通过端点地址的替换即可服务 Gitea。第一步在 Gitea 中创建 OAuth2 应用登录你的 Gitea 实例进入个人设置中的应用管理页面https://your gitea host/user/settings/applications点击创建新应用New Application在Redirect URI一栏填写 oauth2-proxy 的回调地址格式为https://proxied host/oauth2/callback注意proxied host是最终被 oauth2-proxy 反向代理保护的服务对外域名/oauth2/callback是 oauth2-proxy 默认的回调路径由--redirect-url决定两者必须完全一致。创建成功后Gitea 会生成一对Client ID和Client Secret将其记录下来后续配置 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各参数作用如下参数作用--providergithub指定复用 GitHub Provider 的协议实现Gitea 没有独立 provider 名--redirect-url回调地址必须与 Gitea 应用中填写的 Redirect URI 一致--provider-display-nameGitea登录页面上显示的提供方名称让用户看到的是 Gitea 而非 GitHub--client-id/--client-secretGitea 应用生成的应用凭据--login-url授权端点将用户引导至 Gitea 的 OAuth2 授权页--redeem-url令牌交换端点用授权码换取 access token--validate-url会话校验端点用于验证 token 并获取邮箱信息第三步使用配置文件的方式推荐oauth2-proxy 同时支持命令行参数与配置文件两种方式配置项一一对应蛇形命名。仓库自带的本地示例 contrib/local-environment/oauth2-proxy-gitea.cfg 给出了完整可运行的配置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配置说明providergithub与provider_display_nameGitea配合让底层走 GitHub 协议、界面显示 Gitealogin_url/redeem_url/validate_url三个地址都指向 Gitea 服务示例中为gitea.localtest.me:3000email_domains声明允许的邮箱域名用于基本的邮箱域过滤本地测试时需将cookie_secure设为false生产环境必须启用 HTTPS 并保持true该文件配合 contrib/local-environment/docker-compose-gitea.yaml 使用一条命令即可拉起完整的 oauth2-proxy Gitea HTTPBin 测试环境。源码级原理GitHub Provider 如何兼容 Gitea从源码看兼容性并非巧合而是 GitHub Provider 实现中针对 Gitea 做了显式支持。核心实现在 providers/github.go默认端点providers/github.go#L40-L65Provider 内置了 GitHub 的默认授权、换 token、API 校验地址对接 Gitea 时这些默认值全部被--login-url、--redeem-url、--validate-url覆盖为 Gitea 的地址。API 基础路径自适应providers/github.go#L94-L113makeGitHubAPIEndpoint会从ValidateURL.Path中正则匹配/api/v\d段作为 API 基础路径。因此validate_url既可以填https://gitea.example.com/api/v1/user/emails也能填 GitHub Enterprise 风格的https://host/api/v3后续的/user、/user/orgs、/user/teams、/user/emails、/repos/...等请求都会自动拼接在这个基础路径之下。组织/团队字段双兼容providers/github.go#L462-L512getOrgs解析的组织 JSON 结构同时支持 GitHub 的login字段与 Gitea 的name字段日志分别输出 Member of Github Organization 与 Member of Gitea OrganizationgetTeams同样兼容两者providers/github.go#L514-L568。邮箱验证getEmail调用/user/emails端点选取verified且primary的邮箱写入会话状态providers/github.go#L337-L367这正对应 Gitea 的validate_url指向/api/v1/user/emails的原因。会话校验逻辑在 providers/gitea_test.go 中有对应的单元测试TestGiteaProvider_ValidateSessionWithBaseUrl模拟 Gitea 后端不返回任何邮箱数据时ValidateSession返回false校验失败TestGiteaProvider_ValidateSessionWithUserEmails模拟 Gitea 返回[{email: ..., verified: true, primary: true}]时校验通过。这两条测试清晰地展示了用 Gitea 的 /api/v1/user/emails 响应验证会话有效性这一核心链路。进阶按组织、团队、仓库与用户限制访问由于底层是 GitHub ProviderGitHub Provider 配置选项 中全部访问控制能力对 Gitea 同样生效FlagToml Field类型说明--github-orggithub_orgstring仅允许指定组织的成员登录--github-teamgithub_teamstring仅允许指定团队slug或org:team的成员登录逗号分隔--github-repogithub_repostring仅允许某仓库的协作者登录格式orgname/repo--github-tokengithub_tokenstring用于校验仓库协作者的 token需对该仓库有 push 权限--github-usergithub_usersstring | list按用户名放行即使不属于上述 org/team/协作者范围也可登录典型用法示例# 仅允许组织成员 --github-orgyour-org # 仅允许组织内指定团队slug逗号分隔 --github-orgyour-org --github-teamteam1,team2,team3 # 跨组织限制团队时org 置空、团队使用 org:slug 全限定名 --github-org --github-teamorg1:team1,org2:team1,org3:team42,octo:cat # 限制为仓库协作者公共仓库需 push 权限私有仓库任意访问权限即可 --github-repoyour-org/your-repo # 按用户名放行 --github-useralice,bob实现层面providers/github.go#L407-L433checkRestrictions根据Org/Team的组合调用hasOrg、hasOrgAndTeam或hasTeam进行分组校验组织与团队信息在EnrichSession阶段通过/user/orgs与/user/teams拉取并写入会话的Groups字段最终以X-Forwarded-Groups请求头转发给上游服务格式形如org1:team1,org1:team2,org2:team1仓库协作者校验通过/repos/{repo}与/repos/{repo}/collaborators/{username}完成公共仓库要求用户有 push 权限私有仓库要求有 pull 权限providers/github.go#L255-L288--github-user配置的用户会被优先放行跳过后续所有限制checkUserRestrictionproviders/github.go#L435-L451注意Gitea 的团队校验基于组织中的name字段而 GitHub 使用 slug团队配置请以 Gitea 组织中的实际团队名为准。本地快速验证一键拉起 Gitea 测试环境仓库在 contrib/local-environment 提供了开箱即用的本地联调环境通过 docker-compose-gitea.yaml 同时启动三个容器oauth2-proxy加载上面提到的 oauth2-proxy-gitea.cfg 配置gitea/gitea充当身份提供方映射端口 3000httpbin作为被保护的上游示例服务。启动方式在contrib/local-environment目录下docker compose -f docker-compose-gitea.yaml up -d环境就绪后访问http://oauth2-proxy.localtest.me:4180触发完整登录流程默认测试账号为adminexample.com密码password访问http://gitea.localtest.me:3000可用同一账号登录 Gitea 后台查看应用与授权设置该 Makefile 还提供了便捷指令make gitea-up、make gitea-down等见 contrib/local-environment/Makefile。小结与注意事项没有 Gitea provider只有 GitHub provider对接 Gitea 的全部奥义就是--providergithub加上指向 Gitea 的三个端点 URLredirect-url必须与 Gitea 应用内填写的 Redirect URI逐字符一致生产环境务必启用 HTTPS并将cookie_secure设为true如需跨子域共享 Cookie可参考示例配置中的cookie_domains与whitelist_domains访问控制能力组织/团队/仓库/用户与 GitHub Provider 完全通用可结合--email-domain做邮箱域过滤多层限制可叠加使用想从零复现本文流程直接使用contrib/local-environment中的 compose 环境即可无需自行部署 Gitea。【免费下载链接】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），仅供参考