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 应用、用--providergithub加三个自定义端点参数接入 oauth2-proxy、以及如何用组织Organization/ 团队Team做细粒度访问控制还能拿到一份可落地的配置示例与本地联调方案。为什么 Gitea 要复用 GitHub Provideroauth2-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--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 接入的关键--redirect-urloauth2-proxy 的/oauth2/callback回调地址须与 Gitea 应用中的 Redirect URI 一致--provider-display-nameGitea登录页、错误页上展示的 provider 名称可自定义如中文环境可填Gitea--client-id/--client-secretGitea 生成的 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.goGitHub provider 在 providers/github.go 的NewGitHubProvider中通过setProviderDefaults设置默认端点但用户显式指定的 URL 会覆盖默认值defaultURL逻辑见 providers/provider_data.go。为什么 validate-url 指向/api/v1/user/emailsGitHub 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-orgyour-org仅允许指定组织的成员登录。Gitea 的组织成员通过/api/v1/user/orgs接口获取见 providers/github.go代码同时兼容 GitHub 的login字段和 Gitea 的name字段--github-teamteam1,team2进一步限定组织内特定团队slug可逗号分隔多个若跨多个组织使用可写成org:team全限定格式见 providers/github.go 的hasOrgAndTeam--github-useralice,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.cfghttp_address0.0.0.0:4180 cookie_secretOQINaROshtE9TcZkNAm-5Zs2Pv3xaWytBmc5W7sPX7w email_domains[localhost] cookie_securefalse upstreamshttp://httpbin cookie_domains[.localtest.me] # 使 cookie 可在所有子域名读取 whitelist_domains[.localtest.me] # 允许跳转回原请求目标 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_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触发一次完整登录流程默认测试账号adminexample.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 编排【免费下载链接】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），仅供参考 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 应用、用--providergithub加三个自定义端点参数接入 oauth2-proxy、以及如何用组织Organization/ 团队Team做细粒度访问控制还能拿到一份可落地的配置示例与本地联调方案。为什么 Gitea 要复用 GitHub Provideroauth2-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--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 接入的关键--redirect-urloauth2-proxy 的/oauth2/callback回调地址须与 Gitea 应用中的 Redirect URI 一致--provider-display-nameGitea登录页、错误页上展示的 provider 名称可自定义如中文环境可填Gitea--client-id/--client-secretGitea 生成的 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.goGitHub provider 在 providers/github.go 的NewGitHubProvider中通过setProviderDefaults设置默认端点但用户显式指定的 URL 会覆盖默认值defaultURL逻辑见 providers/provider_data.go。为什么 validate-url 指向/api/v1/user/emailsGitHub 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-orgyour-org仅允许指定组织的成员登录。Gitea 的组织成员通过/api/v1/user/orgs接口获取见 providers/github.go代码同时兼容 GitHub 的login字段和 Gitea 的name字段--github-teamteam1,team2进一步限定组织内特定团队slug可逗号分隔多个若跨多个组织使用可写成org:team全限定格式见 providers/github.go 的hasOrgAndTeam--github-useralice,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.cfghttp_address0.0.0.0:4180 cookie_secretOQINaROshtE9TcZkNAm-5Zs2Pv3xaWytBmc5W7sPX7w email_domains[localhost] cookie_securefalse upstreamshttp://httpbin cookie_domains[.localtest.me] # 使 cookie 可在所有子域名读取 whitelist_domains[.localtest.me] # 允许跳转回原请求目标 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_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触发一次完整登录流程默认测试账号adminexample.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 编排【免费下载链接】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），仅供参考