oauth2-proxy 接入 Gitea 身份认证：复用 GitHub Provider 的完整配置指南-迪斯科星球

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 项目文档（docs/versioned_docs/version-7.9.x/configuration/providers/gitea.md）编写。Gitea 并没有独立的 provider 实现，而是通过复用 GitHub Provider，并把登录、换取令牌、校验邮箱等端点指向自建 Gitea 实例来完成 OAuth2 认证。读完本文，你将掌握：在 Gitea 后台创建 OAuth2 应用、用--provider="github"加三个自定义端点参数接入 oauth2-proxy、以及如何用组织（Organization）/ 团队（Team）做细粒度访问控制，还能拿到一份可落地的配置示例与本地联调方案。

为什么 Gitea 要复用 GitHub Provider

oauth2-proxy 的 provider 体系中并没有名为gitea的实现。官方文档开篇便明确说明：

This is not actually its own provider. For more details and options please refer to the GitHub Provider Options.

Gitea 自带的 OAuth2 接口在端点形态上与 GitHub 高度相似，因此接入方式是把 provider 指定为github，再通过--login-url、--redeem-url、--validate-url三个参数把 OAuth 流程中的三个关键端点指到自己的 Gitea 主机上。

从源码看，这一复用关系清晰可见：providers/github.go 中GitHubProvider是唯一的实现类，Gitea 场景直接复用它；providers/gitea_test.go 的测试辅助函数testGiteaProvider也直接调用NewGitHubProvider构造 provider，并把ProviderName设为"Gitea"。在 GitHub provider 的会话富化逻辑里，代码也对 Gitea 的组织 API 做了兼容：getOrgs同时解析 GitHub 的login字段与 Gitea 的name字段（见 providers/github.go）。

需要注意的版本差异

当前主分支文档（docs/docs/configuration/providers/gitea.md）标题为 “Gitea / Forgejo”，即该方案同样适用于 Forgejo 这类 Gitea 的分支/衍生项目；
7.9.x 版本的文档标题仅为 “Gitea”，正文无其他差异，核心配置步骤完全一致。

接入前置条件

接入前请确认：

已部署并可通过 HTTPS（或本机 HTTP）访问的 Gitea 实例，假设主机名为gitea.example.com；
有权限在 Gitea 中创建 OAuth2 应用；
已部署 oauth2-proxy，并有一个将被保护的站点（下称 “proxied host”），假设为app.example.com。

配置步骤（官方四步流程）

1. 创建 Gitea OAuth2 应用

在 Gitea 中登录管理员或目标用户账号，进入个人设置的应用管理页面：

https://< your gitea host >/user/settings/applications

例如https://gitea.example.com/user/settings/applications。

点击 “Create a new OAuth2 Application”，填写应用名称后，最关键的一步是设置回调地址。

2. 填写 Redirect URI（回调地址）

在Redirect URI一栏填入 oauth2-proxy 的回调端点，格式为：

https://<proxied host>/oauth2/callback

例如https://app.example.com/oauth2/callback。

注意：该地址必须与后续传给 oauth2-proxy 的--redirect-url完全一致，否则 OAuth 授权码流程会因回调地址不匹配而失败。

3. 记录 Client ID 与 Client Secret

创建完成后，Gitea 会生成Client ID与Client Secret。将二者妥善保存（Secret 只在创建时完整展示一次），随后传入 oauth2-proxy。

4. 将以下参数传给 oauth2-proxy

--provider="github" --redirect-url="https://<proxied host>/oauth2/callback" --provider-display-name="Gitea" --client-id="< client_id as generated by Gitea >" --client-secret="< client_secret as generated by Gitea >" --login-url="https://< your gitea host >/login/oauth/authorize" --redeem-url="https://< your gitea host >/login/oauth/access_token" --validate-url="https://< your gitea host >/api/v1/user/emails"

各参数含义与底层作用

参数	作用
`--provider="github"`	指定复用 GitHub Provider 实现，是 Gitea 接入的关键
`--redirect-url`	oauth2-proxy 的`/oauth2/callback`回调地址，须与 Gitea 应用中的 Redirect URI 一致
`--provider-display-name="Gitea"`	登录页、错误页上展示的 provider 名称，可自定义（如中文环境可填`Gitea`）
`--client-id`/`--client-secret`	Gitea 生成的 OAuth2 应用凭证
`--login-url`	授权页地址，即 OAuth2 的 authorize 端点，用户在此登录并授权
`--redeem-url`	用授权码换取 Access Token 的 token 端点
`--validate-url`	会话校验时用于验证 Token 有效性、并读取用户邮箱的 API 地址

从源码看，这些端点最终被解析进ProviderData的LoginURL、RedeemURL、ValidateURL字段（见 pkg/apis/options/legacy_options.go 与 providers/provider_data.go），GitHub provider 在 providers/github.go 的NewGitHubProvider中通过setProviderDefaults设置默认端点，但用户显式指定的 URL 会覆盖默认值（defaultURL逻辑见 providers/provider_data.go）。

为什么 validate-url 指向`/api/v1/user/emails`

GitHub provider 的默认validate-url是https://api.github.com/，其校验动作依赖 makeGitHubAPIEndpoint 拼接的/user/emails等路径。而 Gitea 的 API 基路径与 GitHub 不同（Gitea 为/api/v1），因此官方文档明确要求把校验地址直接写为：

https://< your gitea host >/api/v1/user/emails

会话校验时，oauth2-proxy 会向该端点发起带 Access Token 的请求；Gitea 返回的邮箱 JSON 数组（含email、primary、verified字段）用于校验用户身份。测试用例 providers/gitea_test.go 正是模拟了返回{"email": "...", "verified": true, "primary": true}的场景来验证校验通过。

使用 Gitea 组织 / 团队做访问控制

由于复用的是 GitHub provider，所有 GitHub 专属的授权参数都可以直接用于 Gitea 场景，参数定义见 pkg/apis/options/legacy_options.go：

--github-org="your-org"：仅允许指定组织的成员登录。Gitea 的组织成员通过/api/v1/user/orgs接口获取（见 providers/github.go，代码同时兼容 GitHub 的login字段和 Gitea 的name字段）；
--github-team="team1,team2"：进一步限定组织内特定团队（slug），可逗号分隔多个；若跨多个组织使用，可写成org:team全限定格式（见 providers/github.go 的hasOrgAndTeam）；
--github-user="alice,bob"：白名单用户名，即使不属于指定组织/团队也可登录（见 providers/github.go 的isVerifiedUser）。

这些限制通常搭配--email-domain="*"一起使用，表示不限制邮箱域名、仅按组织/团队/用户白名单放行。用户所属的 Gitea 组织与团队会以org:team的形式写入X-Forwarded-Groups请求头（见 docs/docs/configuration/providers/github.md 与 providers/github.go 的getTeams），可供上游应用继续做细粒度鉴权。

完整配置示例（配置文件写法）

上面的命令行参数同样可以在配置文件中以 TOML/INI 风格书写。参考仓库自带的本地联调配置 contrib/local-environment/oauth2-proxy-gitea.cfg：

http_address="0.0.0.0:4180" cookie_secret="OQINaROshtE9TcZkNAm-5Zs2Pv3xaWytBmc5W7sPX7w=" email_domains=["localhost"] cookie_secure="false" upstreams="http://httpbin" cookie_domains=[".localtest.me"] # 使 cookie 可在所有子域名读取 whitelist_domains=[".localtest.me"] # 允许跳转回原请求目标 client_id="ef0c2b91-2e38-4fa8-908d-067a35dbb71c" client_secret="gto_qdppomn2p26su5x46tyixj7bcny5m5er2s67xhrponq2qtp66f3a" redirect_url="http://oauth2-proxy.localtest.me:4180/oauth2/callback" # gitea provider provider="github" provider_display_name="Gitea" login_url="http://gitea.localtest.me:3000/login/oauth/authorize" redeem_url="http://gitea.localtest.me:3000/login/oauth/access_token" validate_url="http://gitea.localtest.me:3000/api/v1/user/emails"

注意配置文件中的键名与命令行参数的对应关系（蛇形命名），例如provider_display_name对应--provider-display-name、login_url对应--login-url（映射定义见 pkg/apis/options/legacy_options.go）。

本地快速联调（docker-compose 方案）

仓库提供了开箱即用的本地验证环境 contrib/local-environment/docker-compose-gitea.yaml，同时拉起 oauth2-proxy、Gitea 与 httpbin 三个服务：

oauth2-proxy 使用 contrib/local-environment/oauth2-proxy-gitea.cfg 作为配置；
Gitea 监听gitea.localtest.me:3000，与配置中的三个端点地址一一对应；
httpbin 作为示例上游应用。

启动方式（二选一）：

# 方式一：docker-compose docker-compose -f contrib/local-environment/docker-compose-gitea.yaml up # 方式二：Makefile（仓库根目录执行） make gitea-up

启动后：

访问http://oauth2-proxy.localtest.me:4180触发一次完整登录流程（默认测试账号admin@example.com/password）；
访问http://gitea.localtest.me:3000使用同一账号登录，可查看 OAuth2 应用设置。

该示例使用的 Gitea 镜像为gitea/gitea:1.26.2，对应的 Gitea OAuth2 API 与上文所述的/api/v1/user/emails、/api/v1/user/orgs端点兼容。

常见问题与排查要点

回调地址不匹配：Gitea 应用里的 Redirect URI 与 oauth2-proxy 的--redirect-url必须逐字符一致（包括协议、端口、路径），否则授权码回调会被拒绝。
validate-url 拼错：Gitea 的 API 基路径是/api/v1，务必按文档写https://<gitea host>/api/v1/user/emails，不要沿用 GitHub 的默认校验端点。
邮箱校验失败：Gitea 用户需有已验证的邮箱（verified: true），因为会话富化依赖邮箱列表中的 primary + verified 邮箱（见 providers/github.go 的getEmail）。
组织限制不生效：确认账号确实是目标组织的成员，且使用了正确的组织名；Gitea 场景下组织名取自name字段（见 providers/github.go）。

参考文档

Gitea Provider 官方文档（当前主分支）
GitHub Provider 选项（Gitea 复用的完整参数说明）
GitHub Provider 实现源码
Gitea Provider 测试用例
本地联调配置文件
本地联调 docker-compose 编排

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析