oauth2-proxy 接入 Gitea 身份认证基于 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导读本文聚焦 oauth2-proxy 项目一个支持 Google、Azure、OpenID Connect 及众多身份提供商的通用反向代理认证组件如何接入自建 Gitea 实例作为 OAuth2 身份提供方。Gitea 并未被实现为一个独立的认证 Provider而是通过复用githubProvider 并覆盖登录、换码、校验三个关键端点来实现。读完本文你将掌握在 Gitea 管理界面创建 OAuth2 应用、配置 oauth2-proxy 命令行与配置文件两种方式、理解 GitHub Provider 内部如何通过 Gitea API 校验邮箱与组织、以及如何用仓库自带的 docker-compose 环境快速本地验证全流程。Gitea 与 oauth2-proxy 的接入方式概述Gitea 是一个轻量级、自托管的 Git 服务提供标准的 OAuth2 授权码模式接口。oauth2-proxy 的官方配置文档gitea.md明确指出Gitea 并不是一个完全独立的 Provider它的认证流程与访问控制语义完全继承自 GitHub Provider因此更详细的选项需要参考 GitHub Provider Options。这一设计决策可以从源码中得到印证在 providers/gitea_test.go 中测试直接通过NewGitHubProvider构造 provider并以ProviderName: Gitea覆盖显示名称同时把校验端点指向 Gitea 的/api/v1/user/emails。也就是说接入 Gitea 的本质是借用 GitHub Provider 的 OAuth2 流程替换三个端点为 Gitea 的地址。第一步在 Gitea 中创建 OAuth2 应用在 Gitea 管理界面中创建新应用的入口为https:// your gitea host /user/settings/applications操作步骤如下进入上述应用管理页面点击创建新应用New Application在Redirect URI重定向 URI字段中填写正确的回调地址即https://proxied host/oauth2/callback。注意这个地址必须与 oauth2-proxy 的--redirect-url严格一致否则授权码回调会被 Gitea 拒绝创建完成后Gitea 会生成并展示Client ID与Client Secret请妥善保存 Client Secret部分版本只在创建时展示一次将这两个值分别填入 oauth2-proxy 的--client-id与--client-secret参数。第二步以命令行参数方式配置 oauth2-proxy官方文档给出了最直接的最小可用配置将所有 Provider 相关的参数以命令行标志传入--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指定复用的 Provider 实现GitHub 风格 OAuth2 流程固定为github--redirect-urloauth2-proxy 处理回调的地址必须与 Gitea 应用中的 Redirect URI 一致https://proxied host/oauth2/callback--provider-display-name登录页面上展示的 Provider 名称Gitea--client-idGitea 生成的客户端 ID由 Gitea 生成--client-secretGitea 生成的客户端密钥由 Gitea 生成--login-urlOAuth2 授权端点引导用户跳转登录https://gitea host/login/oauth/authorize--redeem-url用授权码换取 access token 的端点https://gitea host/login/oauth/access_token--validate-url校验 access token 并获取用户邮箱的 API 端点https://gitea host/api/v1/user/emails上述--login-url、--redeem-url、--validate-url三个标志定义于 pkg/apis/options/legacy_options.go对应的 Toml 配置字段分别为login_url、redeem_url、validate_url官方描述分别是Authentication endpointToken redemption endpointAccess token validation endpoint。第三步以配置文件方式配置推荐用于生产命令行标志过多时容易出错生产环境更推荐将配置写入.cfg文件再通过--config加载。仓库在 contrib/local-environment/oauth2-proxy-gitea.cfg 中提供了一个完整的 Gitea 接入示例核心部分如下# 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该示例同时还展示了与本场景配套的其他关键配置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需要特别说明示例中的client_id、client_secret、cookie_secret均为仓库自带的本地测试用值生产环境必须替换为自行生成的随机密钥。本地快速验证使用 docker-compose 一键拉起整套环境为了便于验证 Gitea 接入效果仓库提供了 contrib/local-environment/docker-compose-gitea.yaml它一次性启动三个容器oauth2-proxy以--config /oauth2-proxy.cfg启动配置文件挂载自上面的oauth2-proxy-gitea.cfg监听4180端口gitea使用gitea/gitea:1.26.2镜像作为身份提供方监听3000端口并在网络别名中注册为gitea.localtest.mehttpbin作为示例 upstream被保护的后端服务。启动方式有两种等价写法docker-compose -f docker-compose-gitea.yaml up # 或通过仓库 Makefile 封装的目标 make gitea-up启动后按文件头部注释的说明访问http://oauth2-proxy.localtest.me:4180触发完整登录流程测试账号为adminexample.com密码为password访问http://gitea.localtest.me:3000可用同一账号登录查看应用配置。整个环境的 Makefile 目标与更多部署选项可参考 contrib/local-environment/Makefile 与 contrib/local-environment/README.md。深入原理GitHub Provider 如何与 Gitea API 交互由于 Gitea 复用 GitHub Provider理解登录成功后的校验与信息补全逻辑就能明白--validate-url为什么必须指向/api/v1/user/emails。以 providers/github.go 的实现为据默认端点与 ScopeNewGitHubProviderproviders/github.go在未覆盖时会填充 GitHub 官方端点github.com与api.github.com以及默认 scopeuser:email read:org。接入 Gitea 时--login-url、--redeem-url、--validate-url三个标志将其全部替换为 Gitea 实例地址。ValidateSession校验 access token 有效性ValidateSessionproviders/github.go调用validateToken向ValidateURL发起携带Authorization: token access_token的请求。当ValidateURL为 Gitea 的/api/v1/user/emails时即对 Gitea 的 token 有效性做实时校验——这也是 providers/gitea_test.go 中TestGiteaProvider_ValidateSessionWithUserEmails所验证的行为Gitea 返回包含primary且verified的邮箱时会话校验通过。会话信息补全与访问控制EnrichSessionproviders/github.go依次执行getOrgAndTeam调用 Gitea API 的/api/v1/user/orgs与/api/v1/user/teams分页per_page100拉取用户的组织与团队写入s.GroupscheckRestrictions根据--github-org、--github-team、--github-repo、--github-user等限制条件判定授权getEmail解析/api/v1/user/emails返回的邮箱列表取verified且primary的邮箱作为会话 EmailgetUser从/api/v1/user获取用户名写入会话。值得留意的是getOrgsproviders/github.go解析的组织结构体同时兼容 GitHub 的login字段与 Gitea 的name字段getTeamsproviders/github.go同理兼容 GitHub 的slug与 Gitea 的name字段代码注释中明确引用了 Gitea API 文档说明 GitHub Provider 对 Gitea 的适配是官方刻意为之的双向兼容。进阶复用 GitHub Provider 的访问控制能力由于底层实现就是GitHubProviderGitea 接入天然继承了 GitHub Provider Options 文档中的全部访问控制能力以下选项同样适用于 GiteaFlagToml Field说明--github-orggithub_org仅允许指定组织的成员登录--github-teamgithub_team仅允许指定团队slug 或org:team成员登录逗号分隔--github-repogithub_repo仅允许指定仓库orgname/repo的协作者登录--github-tokengithub_token用于校验协作者身份的 token对目标仓库须有 push 权限--github-usergithub_users按用户名放行即使不属于上述组织/团队/协作者限制逻辑可在checkRestrictionsproviders/github.go中看到清晰的优先级先检查用户名白名单--github-user再按orgteam / org / team三种组合依次判定最后处理仓库协作者场景。例如限制为某个 Gitea 组织成员--github-orgyour-org限制为多个团队跨组织时使用org:slug格式--github-org --github-teamorg1:team1,org2:team1这些组织/团队信息会以org1:team1,org1:team2,org2:team1的形式写入X-Forwarded-Groups请求头供上游服务做更细粒度的授权。小结接入 Gitea 的关键在于理解 oauth2-proxy 复用 GitHub Provider 的设计在 Gitea 创建应用获取凭据将--login-url、--redeem-url、--validate-url指向 Gitea 的/login/oauth/authorize、/login/oauth/access_token、/api/v1/user/emails并以--provider-display-nameGitea呈现品牌名称。生产部署建议使用.cfg配置文件并替换示例密钥需要细粒度授权时可直接套用--github-*系列选项本地联调则可用仓库自带的 docker-compose 环境在几分钟内完成端到端验证。【免费下载链接】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），仅供参考