oauth2-proxy GitHub 身份提供方详解:组织、团队与仓库协作者访问控制【免费下载链接】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 v7.10.x 官方文档中 GitHub 提供方页面为主体,系统讲解如何通过--github-org、--github-team、--github-repo、--github-token、--github-user五个配置项将登录范围收窄到指定 GitHub 组织、组织内团队、跨组织团队或仓库协作者,并结合 providers/github.go 的源码实现说明每次登录背后的 API 调用链、判定规则与日志行为,帮助读者既能直接照抄配置上线,也能在出问题时从原理层面定位原因。1. GitHub 提供方在 oauth2-proxy 中的定位oauth2-proxy 作为反向代理,负责把未登录请求重定向到身份提供方完成 OAuth 认证,再把用户身份通过请求头透传给上游应用。GitHub 提供方(--providergithub)是其中的核心选项之一,其默认端点在 providers/github.go 中硬编码:项默认值说明LoginURLhttps://github.com/login/oauth/authorizeOAuth2 授权入口RedeemURLhttps://github.com/login/oauth/access_token用授权码换取 access tokenValidateURLhttps://api.github.com/API 基地址,后续所有用户/组织/团队/仓库请求都基于它拼接Scopeuser:email read:org请求用户邮箱与组织读取权限上述默认值可以在单元测试 TestNewGitHubProvider 中直接得到验证:不传任何选项时,Scope为user:email read:org,ValidateURL为https://api.github.com/。每个 API 请求都会附带Accept: application/vnd.github.v3json头和Authorization: token access_token头,见 makeGitHubHeader。2. 配置选项总览官方文档为 GitHub 提供方定义了如下完整参数表(flag 为命令行参数,TOML Field 为配置文件字段,两者一一对应,字段定义见 pkg/apis/options/legacy_options.go):FlagToml FieldTypeDescriptionDefault--github-orggithub_orgstringrestrict logins to members of this organisation(限制为某组织的成员)空--github-teamgithub_teamstringrestrict logins to members of any of these teams (slug) or (org:team), comma separated(限制为任意一个团队,支持 slug 或 org:team 两种写法,逗号分隔)空--github-repogithub_repostringrestrict logins to collaborators of this repository formatted asorgname/repo(限制为该仓库的协作者)空--github-tokengithub_tokenstringthe token to use when verifying repository collaborators (must have push access to the repository)(校验仓库协作者时使用的 token,必须对仓库有 push 权限)空--github-usergithub_usersstring | listTo allow users to login by username even if they do not belong to the specified org and team or collaborators(允许指定用户名即使不属于上述组织/团队/协作者也能登录)空这些限制类配置通常与--email-domain*搭配使用,避免与按邮箱域名的默认过滤规则叠加产生意外。此外,用户所属的全部组织与团队会被写入上游请求的X-Forwarded-Groups头,格式如org1:team1,org1:team2,org2:team1(oauth2-proxy 默认开启--pass-user-headers,会同时透传X-Forwarded-User、X-Forwarded-Email等)。需要注意文档中的 NOTE:当设置了--github-user时,列出的用户即使不属于所配置的组织和团队、也不是仓库协作者,同样被允许登录。3. 快速接入:创建 GitHub OAuth 应用在 GitHub 账号的设置页中找到 OAuth Apps 管理界面(Settings → Developer settings → OAuth Apps)创建一个新应用(Repository OAuth App);在Authorization callback URL中填写 oauth2-proxy 的回调地址,例如https://internal.yourcompany.com/oauth2/callback,该地址必须与部署时的--redirect-url一致。创建完成后的最小启动配置形如:oauth2-proxy \ --providergithub \ --client-idYOUR_CLIENT_ID \ --client-secretYOUR_CLIENT_SECRET \ --cookie-secretBASE64_COOKIE_SECRET \ --email-domain*4. 按组织与团队限制访问4.1 限制为某个组织的成员# restrict logins to members of this organisation --github-orgyour-org源码中对应 hasOrg:oauth2-proxy 会先通过/user/orgs接口分页拉取该用户所属的全部组织,逐一与p.Org比较,命中即放行,否则记录Missing Organization:... in [...]日志并返回错误user is missing required organization。4.2 限制为组织内指定的团队--github-orgyour-org # restrict logins to members of any of these teams (slug), comma separated --github-teamteam1,team2,team3此时走 hasOrgAndTeam 分支。它解析会话中的org:team形式分组,对组织名与团队名都使用大小写不敏感比较(strings.EqualFold),并且对--github-team中的每一项做了TrimSpace,因此--github-teamteam1, team2这类写法中的空格是安全的。未命中时错误信息为user is missing required team。4.3 跨组织限制团队要跨多个组织限制团队,应保持组织参数为空,改用org:team的全限定写法:# keep empty --github-org # restrict logins to members to any of the following teams (format org:slug, like octo:team1), comma separated --github-teamorg1:team1,org2:team1,org3:team42,octo:cat这里有一个文档未展开、但源码明确强制的规则:走 hasTeam 分支(即只配--github-team不配--github-org)时,每一项都必须包含:分隔符,否则直接报错team name is invalid并提示 Please use fully qualified team names (org:team-slug) if you omit the organisation。这是跨组织限制最容易踩的坑。判定优先级汇总见 checkRestrictions:switch { case p.Org ! p.Team ! : err p.hasOrgAndTeam(s) case p.Org ! : err p.hasOrg(s) case p.Team ! : err p.hasTeam(s) }即:同时配置 orgteam → 组织内团队校验;只配 org → 组织成员校验;只配 team → 全限定团队名校验。5. 按仓库协作者限制访问5.1 限制为仓库协作者# restrict logins to collaborators of this repository formatted as orgname/repo --github-repo当仅配置--github-repo且未配置 token 时,oauth2-proxy 会调用 hasRepoAccess:使用用户自己的 access token请求GET /repos/{org}/{repo},解析返回的permissions与private字段,判定规则为:// Every user can implicitly pull from a public repo, so only grant access // if they have push access or the repo is private and they can pull if repo.Permissions.Push || (repo.Private repo.Permissions.Pull) { return nil }也就是说:对公开仓库需要 push 权限才放行(因为公开仓库人人可 pull,pull 权限不构成有效区分);对私有仓库,只要用户有 pull 权限(即任意访问权)就放行。不满足时返回user doesnt have repository access。5.2 使用--github-token放行只读协作者如果希望允许仅具有只读权限访问公开仓库的用户登录,需要提供一个拥有写权限用户的 token(创建时至少勾选public_reposcope):# the token to use when verifying repository collaborators --github-token配置 token 后,校验路径切换为 isCollaborator:oauth2-proxy 改用这个 token调用GET /repos/{org}/{repo}/collaborators/{username},只有当返回状态码为204时才视为该用户是协作者,否则返回got code from endpoint错误。注意 getUser 中的触发条件:if !p.isVerifiedUser(user.Login) p.Org p.Repo ! p.Token ! {即 token 协作者校验只在未配置组织、配置了仓库、配置了 token、且用户名不在--github-user白名单中时才会执行。该路径在测试后端 testGitHubBackend 中同样有/repos/oauth2-proxy/oauth2-proxy/collaborators/mbland端点的模拟覆盖。5.3 用户名白名单--github-user# allow logins by username, comma separated --github-user当用户名命中--github-user列表时(isVerifiedUser 做精确匹配),checkRestrictions会在 checkUserRestriction 中直接跳过组织、团队、仓库的全部限制,这是文档 NOTE 所述行为的实现依据。反过来说,如果只配置了--github-user而没有配置 org/repo,用户名不在列表中的登录会返回missing github user错误——即--github-user本身也可以作为独立的登录白名单使用。6. GitHub Enterprise 部署如果使用 GitHub Enterprise,需要将三个 URL 参数指到企业实例:--login-urlhttp(s)://enterprise github host/login/oauth/authorize --redeem-urlhttp(s)://enterprise github host/login/oauth/access_token --validate-urlhttp(s)://enterprise github host/api/v3--validate-url指向企业 API 基地址(通常带/api/v3前缀)是关键。源码中的 makeGitHubAPIEndpoint 专门处理了这一点:它用正则^/api/v\d从ValidateURL.Path中提取版本前缀再拼接子路径,因此/user、/user/orgs、/repos/...等请求最终都会落在https://enterprise host/api/v3/...下,而不是把ValidateURL.Path原样拼在最前面造成路径重复。测试文件 providers/github_test.go 中的/api/v3、/api/v3/user/emails端点正是对企业 Server API 形态的模拟。7. 登录时的底层调用链与 X-Forwarded-Groups 的来源以--providergithub完成 token 交换后,每次登录(以及会话刷新)会执行 EnrichSession,调用顺序固定为四步:getOrgAndTeam:先 getOrgs 分页(per_page100)拉取/user/orgs,再把组织名逐条追加进s.Groups;随后 getTeams 分页拉取/user/teams,以org:team-slug形式追加进s.Groups。这两步的结果最终就是透传给上游的X-Forwarded-Groups内容。值得注意的是,结构体同时解析了login(GitHub)与name(Gitea)两种字段,因此 Gitea 也能复用同一套 provider 逻辑——gitea 提供方文档 也明确说明 Gitea 并非独立 provider,需参照 GitHub 提供方配置并使用--providergithub配合自定义 URL。checkRestrictions:按第 4、5 节描述的优先级执行 org/team/repo 校验,任何一步失败都会直接拒绝登录;getEmail:getEmail 请求/user/emails,优先选取verified primary的邮箱写入会话,这也是默认 scope 中包含user:email的原因;getUser:请求/user拿到 login 名作为s.User,并在满足 5.2 节条件时追加 token 协作者校验。会话存活期间,ValidateSession 会周期性用同一套 GitHub 头校验 access token 是否仍然有效。8. Alpha 配置(YAML)中的等价写法从 7.10.x 起,oauth2-proxy 支持 alpha 版 YAML 配置,上述五个参数收敛为providers.githubConfig块,结构定义见 pkg/apis/options/providers.go,字段说明与 alpha_config.md 中的GitHubOptions一致:providers: githubConfig: org: your-org team: team1,team2 repo: orgname/repo token: REPO_TOKEN_WITH_PUSH users: - alice - boblegacy flag/TOML 与 alpha 结构的映射在 pkg/apis/options/legacy_options.go 中完成:provider.GitHubConfig GitHubOptions{ Org: l.GitHubOrg, Team: l.GitHubTeam, Repo: l.GitHubRepo, Token: l.GitHubToken, Users: l.GitHubUsers, }两种写法语义完全等价,可按部署方式选择其一。9. 常见问题排查现象源码依据排查方向日志出现Missing Team:... in teams: [...],错误user is missing required teamhasOrgAndTeam确认用户确属该组织下的任一目标团队;注意大小写不敏感、逗号分隔只配--github-team时报team name is invalidhasTeam未配--github-org时,团队必须写org:team全限定形式user is missing required organizationhasOrg用户不属于--github-org指定组织,或/user/orgs分页拉取失败user doesnt have repository accesshasRepoAccess公开仓库用户需 push 权限;若需放行只读用户,改用--github-token方案Enterprise 环境所有 API 调用 404makeGitHubAPIEndpoint--validate-url是否指向https://host/api/v310. 小结oauth2-proxy 的 GitHub 提供方提供了一套组织 → 组织内团队 → 跨组织团队 → 仓库协作者逐级收窄的登录控制模型:--github-org、--github-team基于/user/orgs与/user/teams的组成员判定,--github-repo基于仓库权限位或 token 协作者接口判定,--github-user则提供一条绕过全部限制的白名单通道;所有用户所属组信息最终汇入X-Forwarded-Groups供上游做二次授权。配置时建议按先选限制维度(org/team/repo),再决定是否叠加 token 与用户名白名单的顺序组合参数,并留意跨组织团队必须使用org:team全限定名、企业部署必须改写三个 URL 这两个源码级硬性约束。相关源码与文档入口:GitHub 提供方实现、提供方单元测试、legacy 参数定义、alpha 配置参考、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 身份提供方详解:组织、团队与仓库协作者访问控制
oauth2-proxy GitHub 身份提供方详解:组织、团队与仓库协作者访问控制【免费下载链接】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 v7.10.x 官方文档中 GitHub 提供方页面为主体,系统讲解如何通过--github-org、--github-team、--github-repo、--github-token、--github-user五个配置项将登录范围收窄到指定 GitHub 组织、组织内团队、跨组织团队或仓库协作者,并结合 providers/github.go 的源码实现说明每次登录背后的 API 调用链、判定规则与日志行为,帮助读者既能直接照抄配置上线,也能在出问题时从原理层面定位原因。1. GitHub 提供方在 oauth2-proxy 中的定位oauth2-proxy 作为反向代理,负责把未登录请求重定向到身份提供方完成 OAuth 认证,再把用户身份通过请求头透传给上游应用。GitHub 提供方(--providergithub)是其中的核心选项之一,其默认端点在 providers/github.go 中硬编码:项默认值说明LoginURLhttps://github.com/login/oauth/authorizeOAuth2 授权入口RedeemURLhttps://github.com/login/oauth/access_token用授权码换取 access tokenValidateURLhttps://api.github.com/API 基地址,后续所有用户/组织/团队/仓库请求都基于它拼接Scopeuser:email read:org请求用户邮箱与组织读取权限上述默认值可以在单元测试 TestNewGitHubProvider 中直接得到验证:不传任何选项时,Scope为user:email read:org,ValidateURL为https://api.github.com/。每个 API 请求都会附带Accept: application/vnd.github.v3json头和Authorization: token access_token头,见 makeGitHubHeader。2. 配置选项总览官方文档为 GitHub 提供方定义了如下完整参数表(flag 为命令行参数,TOML Field 为配置文件字段,两者一一对应,字段定义见 pkg/apis/options/legacy_options.go):FlagToml FieldTypeDescriptionDefault--github-orggithub_orgstringrestrict logins to members of this organisation(限制为某组织的成员)空--github-teamgithub_teamstringrestrict logins to members of any of these teams (slug) or (org:team), comma separated(限制为任意一个团队,支持 slug 或 org:team 两种写法,逗号分隔)空--github-repogithub_repostringrestrict logins to collaborators of this repository formatted asorgname/repo(限制为该仓库的协作者)空--github-tokengithub_tokenstringthe token to use when verifying repository collaborators (must have push access to the repository)(校验仓库协作者时使用的 token,必须对仓库有 push 权限)空--github-usergithub_usersstring | listTo allow users to login by username even if they do not belong to the specified org and team or collaborators(允许指定用户名即使不属于上述组织/团队/协作者也能登录)空这些限制类配置通常与--email-domain*搭配使用,避免与按邮箱域名的默认过滤规则叠加产生意外。此外,用户所属的全部组织与团队会被写入上游请求的X-Forwarded-Groups头,格式如org1:team1,org1:team2,org2:team1(oauth2-proxy 默认开启--pass-user-headers,会同时透传X-Forwarded-User、X-Forwarded-Email等)。需要注意文档中的 NOTE:当设置了--github-user时,列出的用户即使不属于所配置的组织和团队、也不是仓库协作者,同样被允许登录。3. 快速接入:创建 GitHub OAuth 应用在 GitHub 账号的设置页中找到 OAuth Apps 管理界面(Settings → Developer settings → OAuth Apps)创建一个新应用(Repository OAuth App);在Authorization callback URL中填写 oauth2-proxy 的回调地址,例如https://internal.yourcompany.com/oauth2/callback,该地址必须与部署时的--redirect-url一致。创建完成后的最小启动配置形如:oauth2-proxy \ --providergithub \ --client-idYOUR_CLIENT_ID \ --client-secretYOUR_CLIENT_SECRET \ --cookie-secretBASE64_COOKIE_SECRET \ --email-domain*4. 按组织与团队限制访问4.1 限制为某个组织的成员# restrict logins to members of this organisation --github-orgyour-org源码中对应 hasOrg:oauth2-proxy 会先通过/user/orgs接口分页拉取该用户所属的全部组织,逐一与p.Org比较,命中即放行,否则记录Missing Organization:... in [...]日志并返回错误user is missing required organization。4.2 限制为组织内指定的团队--github-orgyour-org # restrict logins to members of any of these teams (slug), comma separated --github-teamteam1,team2,team3此时走 hasOrgAndTeam 分支。它解析会话中的org:team形式分组,对组织名与团队名都使用大小写不敏感比较(strings.EqualFold),并且对--github-team中的每一项做了TrimSpace,因此--github-teamteam1, team2这类写法中的空格是安全的。未命中时错误信息为user is missing required team。4.3 跨组织限制团队要跨多个组织限制团队,应保持组织参数为空,改用org:team的全限定写法:# keep empty --github-org # restrict logins to members to any of the following teams (format org:slug, like octo:team1), comma separated --github-teamorg1:team1,org2:team1,org3:team42,octo:cat这里有一个文档未展开、但源码明确强制的规则:走 hasTeam 分支(即只配--github-team不配--github-org)时,每一项都必须包含:分隔符,否则直接报错team name is invalid并提示 Please use fully qualified team names (org:team-slug) if you omit the organisation。这是跨组织限制最容易踩的坑。判定优先级汇总见 checkRestrictions:switch { case p.Org ! p.Team ! : err p.hasOrgAndTeam(s) case p.Org ! : err p.hasOrg(s) case p.Team ! : err p.hasTeam(s) }即:同时配置 orgteam → 组织内团队校验;只配 org → 组织成员校验;只配 team → 全限定团队名校验。5. 按仓库协作者限制访问5.1 限制为仓库协作者# restrict logins to collaborators of this repository formatted as orgname/repo --github-repo当仅配置--github-repo且未配置 token 时,oauth2-proxy 会调用 hasRepoAccess:使用用户自己的 access token请求GET /repos/{org}/{repo},解析返回的permissions与private字段,判定规则为:// Every user can implicitly pull from a public repo, so only grant access // if they have push access or the repo is private and they can pull if repo.Permissions.Push || (repo.Private repo.Permissions.Pull) { return nil }也就是说:对公开仓库需要 push 权限才放行(因为公开仓库人人可 pull,pull 权限不构成有效区分);对私有仓库,只要用户有 pull 权限(即任意访问权)就放行。不满足时返回user doesnt have repository access。5.2 使用--github-token放行只读协作者如果希望允许仅具有只读权限访问公开仓库的用户登录,需要提供一个拥有写权限用户的 token(创建时至少勾选public_reposcope):# the token to use when verifying repository collaborators --github-token配置 token 后,校验路径切换为 isCollaborator:oauth2-proxy 改用这个 token调用GET /repos/{org}/{repo}/collaborators/{username},只有当返回状态码为204时才视为该用户是协作者,否则返回got code from endpoint错误。注意 getUser 中的触发条件:if !p.isVerifiedUser(user.Login) p.Org p.Repo ! p.Token ! {即 token 协作者校验只在未配置组织、配置了仓库、配置了 token、且用户名不在--github-user白名单中时才会执行。该路径在测试后端 testGitHubBackend 中同样有/repos/oauth2-proxy/oauth2-proxy/collaborators/mbland端点的模拟覆盖。5.3 用户名白名单--github-user# allow logins by username, comma separated --github-user当用户名命中--github-user列表时(isVerifiedUser 做精确匹配),checkRestrictions会在 checkUserRestriction 中直接跳过组织、团队、仓库的全部限制,这是文档 NOTE 所述行为的实现依据。反过来说,如果只配置了--github-user而没有配置 org/repo,用户名不在列表中的登录会返回missing github user错误——即--github-user本身也可以作为独立的登录白名单使用。6. GitHub Enterprise 部署如果使用 GitHub Enterprise,需要将三个 URL 参数指到企业实例:--login-urlhttp(s)://enterprise github host/login/oauth/authorize --redeem-urlhttp(s)://enterprise github host/login/oauth/access_token --validate-urlhttp(s)://enterprise github host/api/v3--validate-url指向企业 API 基地址(通常带/api/v3前缀)是关键。源码中的 makeGitHubAPIEndpoint 专门处理了这一点:它用正则^/api/v\d从ValidateURL.Path中提取版本前缀再拼接子路径,因此/user、/user/orgs、/repos/...等请求最终都会落在https://enterprise host/api/v3/...下,而不是把ValidateURL.Path原样拼在最前面造成路径重复。测试文件 providers/github_test.go 中的/api/v3、/api/v3/user/emails端点正是对企业 Server API 形态的模拟。7. 登录时的底层调用链与 X-Forwarded-Groups 的来源以--providergithub完成 token 交换后,每次登录(以及会话刷新)会执行 EnrichSession,调用顺序固定为四步:getOrgAndTeam:先 getOrgs 分页(per_page100)拉取/user/orgs,再把组织名逐条追加进s.Groups;随后 getTeams 分页拉取/user/teams,以org:team-slug形式追加进s.Groups。这两步的结果最终就是透传给上游的X-Forwarded-Groups内容。值得注意的是,结构体同时解析了login(GitHub)与name(Gitea)两种字段,因此 Gitea 也能复用同一套 provider 逻辑——gitea 提供方文档 也明确说明 Gitea 并非独立 provider,需参照 GitHub 提供方配置并使用--providergithub配合自定义 URL。checkRestrictions:按第 4、5 节描述的优先级执行 org/team/repo 校验,任何一步失败都会直接拒绝登录;getEmail:getEmail 请求/user/emails,优先选取verified primary的邮箱写入会话,这也是默认 scope 中包含user:email的原因;getUser:请求/user拿到 login 名作为s.User,并在满足 5.2 节条件时追加 token 协作者校验。会话存活期间,ValidateSession 会周期性用同一套 GitHub 头校验 access token 是否仍然有效。8. Alpha 配置(YAML)中的等价写法从 7.10.x 起,oauth2-proxy 支持 alpha 版 YAML 配置,上述五个参数收敛为providers.githubConfig块,结构定义见 pkg/apis/options/providers.go,字段说明与 alpha_config.md 中的GitHubOptions一致:providers: githubConfig: org: your-org team: team1,team2 repo: orgname/repo token: REPO_TOKEN_WITH_PUSH users: - alice - boblegacy flag/TOML 与 alpha 结构的映射在 pkg/apis/options/legacy_options.go 中完成:provider.GitHubConfig GitHubOptions{ Org: l.GitHubOrg, Team: l.GitHubTeam, Repo: l.GitHubRepo, Token: l.GitHubToken, Users: l.GitHubUsers, }两种写法语义完全等价,可按部署方式选择其一。9. 常见问题排查现象源码依据排查方向日志出现Missing Team:... in teams: [...],错误user is missing required teamhasOrgAndTeam确认用户确属该组织下的任一目标团队;注意大小写不敏感、逗号分隔只配--github-team时报team name is invalidhasTeam未配--github-org时,团队必须写org:team全限定形式user is missing required organizationhasOrg用户不属于--github-org指定组织,或/user/orgs分页拉取失败user doesnt have repository accesshasRepoAccess公开仓库用户需 push 权限;若需放行只读用户,改用--github-token方案Enterprise 环境所有 API 调用 404makeGitHubAPIEndpoint--validate-url是否指向https://host/api/v310. 小结oauth2-proxy 的 GitHub 提供方提供了一套组织 → 组织内团队 → 跨组织团队 → 仓库协作者逐级收窄的登录控制模型:--github-org、--github-team基于/user/orgs与/user/teams的组成员判定,--github-repo基于仓库权限位或 token 协作者接口判定,--github-user则提供一条绕过全部限制的白名单通道;所有用户所属组信息最终汇入X-Forwarded-Groups供上游做二次授权。配置时建议按先选限制维度(org/team/repo),再决定是否叠加 token 与用户名白名单的顺序组合参数,并留意跨组织团队必须使用org:team全限定名、企业部署必须改写三个 URL 这两个源码级硬性约束。相关源码与文档入口:GitHub 提供方实现、提供方单元测试、legacy 参数定义、alpha 配置参考、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），仅供参考