尧图网站建设 
oauth2-proxy 使用 GitHub 提供商接入 Gitea / Forgejo 身份验证的完整配置与源码解析【免费下载链接】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 / Forgejo 提供商配置指南展开说明如何通过复用内置的github提供商将自建 Gitea 实例作为身份提供商接入反向代理读完本文你将掌握 Gitea 侧 OAuth2 应用的创建步骤、oauth2-proxy 全部必需参数的含义与取值依据以及底层GitHubProvider如何针对 Gitea 的 API 差异做适配的源码级细节并能用仓库自带的 docker-compose 环境在本地完整复现一次登录闭环。Gitea 不是独立 Provider为什么要复用github提供商oauth2-proxy 的 Gitea 文档开篇就明确指出Gitea 实际上并不是一个完全独立的 provider它复用的是 GitHub 提供商的实现因此文档同时建议读者参考 GitHub Provider 选项说明。这一设计源于 Gitea 对 GitHub OAuth 流程的高度兼容Gitea 完整实现了 OAuth2 Authorization Code 流程授权、令牌兑换端点路径与 GitHub 一致只是域名换成你的 Gitea 主机Gitea 提供了兼容 GitHub v3 风格的/api/v1/*REST APIoauth2-proxy 可以用同一套客户端逻辑拉取用户信息、邮箱、组织与团队。在源码层面Gitea 登录走的就是 providers/github.go 中定义的GitHubProvider它预置了 GitHub 官方的默认端点https://github.com/login/oauth/authorize、https://github.com/login/oauth/access_token、https://api.github.com/和默认 scopeuser:email read:org接入 Gitea 时通过命令行/配置文件把这三类 URL 覆盖为 Gitea 主机上的对应端点即可。providers/gitea_test.go 中的测试辅助函数testGiteaProvider正是这样构造的——它直接调用NewGitHubProvider把ProviderName改写为Gitea并把ValidateURL指向/api/v1/user/emails。第一步在 Gitea 中创建 OAuth2 应用按照官方文档的操作步骤在 Gitea 实例上完成以下准备创建新应用访问https://your gitea host/user/settings/applications需以具有应用管理权限的账号登录填写 Redirect URI填入代理的回调地址即https://proxied host/oauth2/callback。该地址必须与 oauth2-proxy 的--redirect-url完全一致否则 Gitea 会拒绝回调记录凭据保存 Gitea 生成的 Client ID 和 Client Secret后续传给代理。适用前提Gitea 已启用 OAuth2社区版默认开启若部署在 HTTPS 之后redirect_url与三个 Gitea 端点都应使用与浏览器访问一致的协议避免 Cookie 安全属性与重定向循环问题。第二步向代理传递 8 个关键参数文档要求将以下选项传给 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 提供商实现不要写成gitea仓库中不存在名为 gitea 的 provider 常量--redirect-urlOAuth2 回调地址必须与 Gitea 应用的 Redirect URI 逐字一致--provider-display-name登录页展示名仅影响/oauth2/start页面显示不影响流程--client-id/--client-secretGitea 应用的凭据用于兑换 access token--login-url覆盖默认授权端点替换 GitHub 默认的github.com/login/oauth/authorize--redeem-url覆盖默认令牌兑换端点替换默认的github.com/login/oauth/access_token--validate-url覆盖默认校验端点指向 Gitea 的/api/v1/user/emails它同时是会话校验与后续 API 请求的基础地址--validate-url是 Gitea 接入中最关键也最容易被误解的一个参数。从源码结构看它的职责有两层会话周期性校验GitHubProvider.ValidateSession直接委托给 providers/internal_util.go 中的validateToken该函数携带访问令牌请求ValidateURL请求成功即视为会话有效API 基础地址推导providers/github.go 中的makeGitHubAPIEndpoint会用正则^/api/v\d从ValidateURL.Path中提取出/api/v1作为 basePath再拼接/user、/user/emails、/user/orgs、/user/teams等端点。因此把--validate-url设为https://your gitea host/api/v1/user/emails是刻意为之——既给出了一个真实可请求的校验端点又让代理能正确推导出 Gitea 的 API 版本前缀。同样值得注意的是鉴权头的构造makeGitHubHeader会附加Accept: application/vnd.github.v3json头并以 Bearer 方式携带 access token。Gitea 对这一 GitHub 风格 Accept 头是兼容的这也是复用该提供商能够工作的原因之一。会话生命周期登录成功后代理做了什么用户授权回调、令牌兑换完成后GitHubProvider.EnrichSession会按固定顺序执行四个步骤见 providers/github.gogetOrgAndTeam—— 分页调用/user/orgs与/user/teams把组织/团队写入会话的GroupscheckRestrictions—— 若配置了 org / team / repo 限制则执行准入判断getEmail—— 调用/user/emails优先取verified且primary的邮箱写入会话getUser—— 调用/user取得登录名写入会话User字段。其中getOrgs/getTeams对 Gitea 做了显式兼容GitHub 的组织对象返回login字段而 Gitea 的 API 返回name字段Organization结构体同时声明了Login与Name两个字段并分别记录日志“Member of Gitea Organization / Member of Gitea Organization-Team”。从源码结构看这意味着--github-org/--github-team之类的限制参数在 Gitea 环境下同样可被解析为org:team形式的分组进行匹配。上述 GitHub 特有的限制参数在 pkg/apis/options/providers.go 的GitHubOptions结构体中定义type GitHubOptions struct { // Org sets restrict logins to members of this organisation Org string // Team sets restrict logins to members of this team Team string // Repo sets restrict logins to collaborators of this repository Repo string // Token is the token to use when verifying repository collaborators // it must have push access to the repository Token string // Users allows users with these usernames to login // even if they do not belong to the specified org and team or collaborators Users []string }需要说明的限制Repo的 collaborator 校验走的是/repos/owner/repo/collaborators/user端点并依赖一个具有 push 权限的 token这一路径针对 GitHub API 语义编写若在你的 Gitea 版本上启用 repo 级限制建议先用测试账号验证其兼容性org / team 限制则因有上面提到的字段兼容处理而相对稳妥。完整可复现的配置示例仓库在contrib/local-environment/下提供了一份与 Gitea 联动的真实代理配置 contrib/local-environment/oauth2-proxy-gitea.cfg在文档 8 个核心参数之外补充了本地调试常用项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/login/../api/v1/user/emails注意cookie_secret必须是你自行生成的 32 字节 base64 随机串上文件中的值仅用于本地示例环境生产环境请替换并配合cookie_securetrue与 HTTPS。配套的 contrib/local-environment/docker-compose-gitea.yaml 会同时拉起三个服务oauth2-proxy镜像quay.io/oauth2-proxy/oauth2-proxy:v7.15.3、gitea/gitea:1.26.2作为身份提供商、以及 httpbin 作为示例上游。启动后可通过文档注释中的地址验证登录闭环访问http://oauth2-proxy.localtest.me:4180触发登录流程使用测试账号adminexample.com/ 密码password访问http://gitea.localtest.me:3000同凭据查看应用设置。该 compose 文件也提供了两种启动方式docker-compose -f docker-compose-gitea.yaml command或使用同级 contrib/local-environment/Makefile 的make gitea-up/make gitea-down目标。测试用例如何验证这套集成providers/gitea_test.go 用一个httptest.Server模拟 Gitea 后端其路由表直接对应了上面梳理的 API 端点/api/v1/user/emails—— 校验端点返回邮箱列表时ValidateSession判定会话有效TestGiteaProvider_ValidateSessionWithUserEmails端点不可达或返回 404 时判定无效TestGiteaProvider_ValidateSessionWithBaseUrl/api/v1/user、/api/v1/user/orgs带page1per_page100分页参数、/api/v1/repos/.../collaborators/...—— 对应EnrichSession各步骤的请求形态。这套测试恰好印证了两件事校验端点返回 2xx 是会话保活的最小条件请求 Gitea API 时必须带上 Bearer 鉴权头且分页查询参数为per_pagepage。小结Gitea / Forgejo 接入 oauth2-proxy 的正确姿势是--providergithub加三个 URL 覆盖login-url、redeem-url、validate-url而非寻找一个不存在的giteaprovider--validate-url指向/api/v1/user/emails不仅承担会话校验还是代理推导 Gitea API 基础前缀的依据org / team 分组匹配已通过name字段的兼容解析适配 Gitea 的 API 返回格式可用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），仅供参考 oauth2-proxy 使用 GitHub 提供商接入 Gitea / Forgejo 身份验证的完整配置与源码解析
oauth2-proxy 使用 GitHub 提供商接入 Gitea / Forgejo 身份验证的完整配置与源码解析【免费下载链接】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 / Forgejo 提供商配置指南展开说明如何通过复用内置的github提供商将自建 Gitea 实例作为身份提供商接入反向代理读完本文你将掌握 Gitea 侧 OAuth2 应用的创建步骤、oauth2-proxy 全部必需参数的含义与取值依据以及底层GitHubProvider如何针对 Gitea 的 API 差异做适配的源码级细节并能用仓库自带的 docker-compose 环境在本地完整复现一次登录闭环。Gitea 不是独立 Provider为什么要复用github提供商oauth2-proxy 的 Gitea 文档开篇就明确指出Gitea 实际上并不是一个完全独立的 provider它复用的是 GitHub 提供商的实现因此文档同时建议读者参考 GitHub Provider 选项说明。这一设计源于 Gitea 对 GitHub OAuth 流程的高度兼容Gitea 完整实现了 OAuth2 Authorization Code 流程授权、令牌兑换端点路径与 GitHub 一致只是域名换成你的 Gitea 主机Gitea 提供了兼容 GitHub v3 风格的/api/v1/*REST APIoauth2-proxy 可以用同一套客户端逻辑拉取用户信息、邮箱、组织与团队。在源码层面Gitea 登录走的就是 providers/github.go 中定义的GitHubProvider它预置了 GitHub 官方的默认端点https://github.com/login/oauth/authorize、https://github.com/login/oauth/access_token、https://api.github.com/和默认 scopeuser:email read:org接入 Gitea 时通过命令行/配置文件把这三类 URL 覆盖为 Gitea 主机上的对应端点即可。providers/gitea_test.go 中的测试辅助函数testGiteaProvider正是这样构造的——它直接调用NewGitHubProvider把ProviderName改写为Gitea并把ValidateURL指向/api/v1/user/emails。第一步在 Gitea 中创建 OAuth2 应用按照官方文档的操作步骤在 Gitea 实例上完成以下准备创建新应用访问https://your gitea host/user/settings/applications需以具有应用管理权限的账号登录填写 Redirect URI填入代理的回调地址即https://proxied host/oauth2/callback。该地址必须与 oauth2-proxy 的--redirect-url完全一致否则 Gitea 会拒绝回调记录凭据保存 Gitea 生成的 Client ID 和 Client Secret后续传给代理。适用前提Gitea 已启用 OAuth2社区版默认开启若部署在 HTTPS 之后redirect_url与三个 Gitea 端点都应使用与浏览器访问一致的协议避免 Cookie 安全属性与重定向循环问题。第二步向代理传递 8 个关键参数文档要求将以下选项传给 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 提供商实现不要写成gitea仓库中不存在名为 gitea 的 provider 常量--redirect-urlOAuth2 回调地址必须与 Gitea 应用的 Redirect URI 逐字一致--provider-display-name登录页展示名仅影响/oauth2/start页面显示不影响流程--client-id/--client-secretGitea 应用的凭据用于兑换 access token--login-url覆盖默认授权端点替换 GitHub 默认的github.com/login/oauth/authorize--redeem-url覆盖默认令牌兑换端点替换默认的github.com/login/oauth/access_token--validate-url覆盖默认校验端点指向 Gitea 的/api/v1/user/emails它同时是会话校验与后续 API 请求的基础地址--validate-url是 Gitea 接入中最关键也最容易被误解的一个参数。从源码结构看它的职责有两层会话周期性校验GitHubProvider.ValidateSession直接委托给 providers/internal_util.go 中的validateToken该函数携带访问令牌请求ValidateURL请求成功即视为会话有效API 基础地址推导providers/github.go 中的makeGitHubAPIEndpoint会用正则^/api/v\d从ValidateURL.Path中提取出/api/v1作为 basePath再拼接/user、/user/emails、/user/orgs、/user/teams等端点。因此把--validate-url设为https://your gitea host/api/v1/user/emails是刻意为之——既给出了一个真实可请求的校验端点又让代理能正确推导出 Gitea 的 API 版本前缀。同样值得注意的是鉴权头的构造makeGitHubHeader会附加Accept: application/vnd.github.v3json头并以 Bearer 方式携带 access token。Gitea 对这一 GitHub 风格 Accept 头是兼容的这也是复用该提供商能够工作的原因之一。会话生命周期登录成功后代理做了什么用户授权回调、令牌兑换完成后GitHubProvider.EnrichSession会按固定顺序执行四个步骤见 providers/github.gogetOrgAndTeam—— 分页调用/user/orgs与/user/teams把组织/团队写入会话的GroupscheckRestrictions—— 若配置了 org / team / repo 限制则执行准入判断getEmail—— 调用/user/emails优先取verified且primary的邮箱写入会话getUser—— 调用/user取得登录名写入会话User字段。其中getOrgs/getTeams对 Gitea 做了显式兼容GitHub 的组织对象返回login字段而 Gitea 的 API 返回name字段Organization结构体同时声明了Login与Name两个字段并分别记录日志“Member of Gitea Organization / Member of Gitea Organization-Team”。从源码结构看这意味着--github-org/--github-team之类的限制参数在 Gitea 环境下同样可被解析为org:team形式的分组进行匹配。上述 GitHub 特有的限制参数在 pkg/apis/options/providers.go 的GitHubOptions结构体中定义type GitHubOptions struct { // Org sets restrict logins to members of this organisation Org string // Team sets restrict logins to members of this team Team string // Repo sets restrict logins to collaborators of this repository Repo string // Token is the token to use when verifying repository collaborators // it must have push access to the repository Token string // Users allows users with these usernames to login // even if they do not belong to the specified org and team or collaborators Users []string }需要说明的限制Repo的 collaborator 校验走的是/repos/owner/repo/collaborators/user端点并依赖一个具有 push 权限的 token这一路径针对 GitHub API 语义编写若在你的 Gitea 版本上启用 repo 级限制建议先用测试账号验证其兼容性org / team 限制则因有上面提到的字段兼容处理而相对稳妥。完整可复现的配置示例仓库在contrib/local-environment/下提供了一份与 Gitea 联动的真实代理配置 contrib/local-environment/oauth2-proxy-gitea.cfg在文档 8 个核心参数之外补充了本地调试常用项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/login/../api/v1/user/emails注意cookie_secret必须是你自行生成的 32 字节 base64 随机串上文件中的值仅用于本地示例环境生产环境请替换并配合cookie_securetrue与 HTTPS。配套的 contrib/local-environment/docker-compose-gitea.yaml 会同时拉起三个服务oauth2-proxy镜像quay.io/oauth2-proxy/oauth2-proxy:v7.15.3、gitea/gitea:1.26.2作为身份提供商、以及 httpbin 作为示例上游。启动后可通过文档注释中的地址验证登录闭环访问http://oauth2-proxy.localtest.me:4180触发登录流程使用测试账号adminexample.com/ 密码password访问http://gitea.localtest.me:3000同凭据查看应用设置。该 compose 文件也提供了两种启动方式docker-compose -f docker-compose-gitea.yaml command或使用同级 contrib/local-environment/Makefile 的make gitea-up/make gitea-down目标。测试用例如何验证这套集成providers/gitea_test.go 用一个httptest.Server模拟 Gitea 后端其路由表直接对应了上面梳理的 API 端点/api/v1/user/emails—— 校验端点返回邮箱列表时ValidateSession判定会话有效TestGiteaProvider_ValidateSessionWithUserEmails端点不可达或返回 404 时判定无效TestGiteaProvider_ValidateSessionWithBaseUrl/api/v1/user、/api/v1/user/orgs带page1per_page100分页参数、/api/v1/repos/.../collaborators/...—— 对应EnrichSession各步骤的请求形态。这套测试恰好印证了两件事校验端点返回 2xx 是会话保活的最小条件请求 Gitea API 时必须带上 Bearer 鉴权头且分页查询参数为per_pagepage。小结Gitea / Forgejo 接入 oauth2-proxy 的正确姿势是--providergithub加三个 URL 覆盖login-url、redeem-url、validate-url而非寻找一个不存在的giteaprovider--validate-url指向/api/v1/user/emails不仅承担会话校验还是代理推导 Gitea API 基础前缀的依据org / team 分组匹配已通过name字段的兼容解析适配 Gitea 的 API 返回格式可用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），仅供参考