oauth2-proxy GitHub 认证 Provider 配置指南组织、团队、仓库 Collaborator 与 Enterprise 集成【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxyoauth2-proxy 内置的 GitHub Provider 允许你通过 GitHub OAuth 完成登录并在此基础上实现比任何人可登录更精细的访问控制按组织Organization、团队Team、仓库协作者Repository Collaborator乃至指定用户名白名单来限制登录。读完本文你将掌握 GitHub Provider 全部 5 个专属配置项--github-org、--github-team、--github-repo、--github-token、--github-user的语义与组合用法理解它们背后的 API 调用链与判定逻辑并能完成 GitHub Enterprise 的端点覆盖配置。配置项总览GitHub Provider 的专属配置项定义在 pkg/apis/options/legacy_options.go 中同时提供命令行 Flag 与 TOML/配置文件字段两种写法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--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)--github-usergithub_usersstring | listTo allow users to login by username even if they do not belong to the specified org and team or collaborators从源码看命令行 Flag 的定义与注册位于 pkg/apis/options/legacy_options.go其中--github-user使用StringSlice类型因此可以多次指定也可以逗号分隔一次传入。在配置加载阶段这些 legacy 选项会被映射为GitHubOptions结构体字段为Org、Team、Repo、Token、Users定义见 pkg/apis/options/providers.go随后在NewGitHubProvider构造器中通过setOrgTeam、setRepo、setUsers注入到 provider 实例见 providers/github.go。说明表格与文档中的--github-team描述在不同版本文档中略有差异本文以当前仓库 docs/versioned_docs/version-7.8.x/configuration/providers/github.md 为准。它既支持与--github-org搭配使用的裸 slug也支持不指定 org 时的org:team完全限定格式详见下文。Alpha Config 下的等价写法如果使用较新的 Alpha ConfigYAML 配置同一组参数以providers数组内githubConfig的形式出现GitHubOptions的 YAML 字段为org、team、repo、token、users。两个入口最终都会汇入相同的GitHubProvider实现行为完全一致。使用前提创建 GitHub OAuth App在使用前先完成 OAuth App 的注册打开 GitHub 的 Developer settings 页面OAuth Apps 创建入口位于该页面中新建一个 OAuth App在Authorization callback URL中填入 oauth2-proxy 的回调地址格式为https://internal.yourcompany.com/oauth2/callback。回调路径由 oauth2-proxy 默认的/oauth2/callback与你的对外访问域名组成必须与--redirect-url配置保持一致否则 OAuth 授权码交换会失败。Provider 默认行为与 OAuth ScopeGitHub Provider 在初始化时会设置一组默认值见 providers/github.go默认登录端点https://github.com/login/oauth/authorize默认兑换端点redeemhttps://github.com/login/oauth/access_token默认校验/API 端点validatehttps://api.github.com/默认 OAuth Scopeuser:email read:orguser:email用于读取用户邮箱read:org用于读取用户所属的组织与团队——这正是后面组织/团队级限制能够工作的基础。以上默认值有对应的单元测试覆盖见 providers/github_test.go。登录成功后Provider 会通过多个 GitHub API 端点丰富会话EnrichSession见 providers/github.go依次拉取用户所属组织、团队、邮箱与用户名写入会话状态。其中所有组织与团队会以org:team的形式团队用 slug汇总到会话的 Groups 中。两种访问控制模型GitHub Provider 提供两类限制登录的方式二者可以独立使用组织/团队级别限制为指定组织的成员或指定组织内某些团队的成员仓库级别限制为某个仓库的协作者collaborator。配合这些限制时通常还要同时设置--email-domain*。原因在于 oauth2-proxy 默认按邮箱域名做校验--email-domain不设置时不会放行任何用户而 GitHub 的 email 并不总是企业域名放开域名校验后实际的访问范围就完全由组织/团队/仓库规则来界定。此外用户所属的全部组织与团队会随请求转发到上游以X-Forwarded-Groups头传递格式为org1:team1,org1:team2,org2:team1。从源码看该头在 pkg/apis/options/legacy_options.go 中由groupsclaim 生成getPassUserHeaders上游应用可以直接读取它做细粒度授权或审计。限制到组织仅按组织限制时使用--github-orgyour-org # restrict logins to members of this organisation判定逻辑在hasOrg见 providers/github.goProvider 会遍历会话中已收集的组织列表与Org精确匹配匹配失败则返回user is missing required organization错误并拒绝登录。限制到组织内的团队在--github-org基础上叠加团队限制--github-orgyour-org --github-teamteam1,team2,team3 # restrict logins to members of any of these teams (slug), comma separated此时使用hasOrgAndTeam判定见 providers/github.go首先确认用户属于指定组织然后在该组织下检查用户所属团队 slug 是否命中列表中的任意一个。注意团队名需要是 slug 形式即 URL 中使用的团队标识而非显示名称。跨组织多团队限制如果不指定组织、只按团队限制可以将--github-org留空并用org:slug完全限定格式指定跨组织的团队--github-org --github-teamorg1:team1,org2:team1,org3:team42,octo:cat # 格式 org:slug逗号分隔这种用法由hasTeam实现见 providers/github.go。源码中还有一个值得注意的细节如果省略--github-org却在--github-team里写了不含冒号的裸 slughasTeam会直接报错team name is invalid并提示请使用完全限定的团队名org:team-slug。因此跨组织场景下必须写全org:slug。对应的测试用例见 providers/github_test.go。限制到仓库协作者如果希望限制为某个仓库的协作者使用--github-repo # restrict logins to collaborators of this repository formatted as orgname/repo例如--github-repooauth2-proxy/oauth2-proxy。仓库级别的准入规则是公开仓库用户必须对该仓库有 push 权限私有仓库用户拥有任意访问权限包括只读 pull即可。该规则在hasRepoAccess中硬编码见 providers/github.go它请求GET /repos/{org}/{repo}读取响应中的permissions.push与private字段只有pushtrue或privatetrue 且 pulltrue时放行。让只读协作者也能访问公开仓库一个明显的边界情况是公开仓库中只有 push 权限的协作者才能通过默认校验只读协作者会被拒之门外。若要放行只读协作者需要提供一个对该仓库有写权限的用户生成的 token并且该 token 至少要有public_reposcope--github-token # the token to use when verifying repository collaborators这个 token 不用于用户本人的身份而是作为管理员凭证由 oauth2-proxy 在调用 GitHub API 检查协作者身份时代替用户 token 使用。具体调用链在getUser中见 providers/github.go当Org为空、Repo与Token均非空且用户不在用户名白名单时会请求GET /repos/{org}/{repo}/collaborators/{username}以 HTTP 204 作为是协作者的判定依据isCollaborator见 providers/github.go。另外需要明确--github-token与--github-repo的组合行为见checkRestrictionsproviders/github.go只有--github-repo、没有 token 时使用用户自己的 access token调用hasRepoAccess做仓库权限检查即前面说的 push/私有规则同时设置--github-repo与--github-token时改为走isCollaborator协作者检查token 即管理员凭证。这两种路径在测试中都有覆盖TestGitHubProvider_checkRestrictionsWithNoAccessToPrivateRepo验证了无 token 时用户 token 调用仓库接口失败即拒绝TestGitHubProvider_getUserWithRepoAndToken验证了带 token 时通过协作者接口返回 204 放行见 providers/github_test.go 与 providers/github_test.go。按用户名白名单放行--github-user # allow logins by username, separated by a comma当设置了--github-user时指定的用户名即使在组织、团队、协作者规则之外也一律允许登录。注意该选项是加法性质的例外规则它只用于放行不能替代组织/团队/仓库规则来缩小范围。其判定逻辑为checkUserRestriction见 providers/github.go只要Users列表非空就调用GET /user获取当前登录用户的login字段并与白名单比对hasUser与isVerifiedUser。命中则跳过后续所有限制检查checkRestrictions第一步即返回未命中时如果同时没有配置 org 和 repo则直接拒绝missing github user。组合规则与判定优先级把所有规则放在一起看checkRestrictions见 providers/github.go的执行顺序是若配置了用户名白名单且用户命中直接放行跳过其余所有检查否则按orgteam 同时设置 → 仅 org → 仅 team的优先级执行对应校验若以上校验通过、且只配置了 repo 而没有 token再用用户 token 做仓库访问检查。这说明各限制条件之间是并集与叠加的关系用户名白名单是最高优先级的例外org 与 team 的组合是单条校验repo 校验独立于 org/team 校验执行。实际配置时应结合这些规则设计权限模型例如内部成员org 少数外部协作者repo/token 特批人员user的多层放行结构。集成 GitHub Enterprise如果使用 GitHub Enterpriseoauth2-proxy 不会自动探测企业实例的端点必须手动覆盖以下三个 URL当前仓库 7.8.x 版本的默认端点均指向github.com/api.github.com见 providers/github.go--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是整个 GitHub API 的 Base URL。从源码makeGitHubAPIEndpoint见 providers/github.go可以看到构建具体 API 路径时会识别/api/v3前缀并以此为基准拼接后续路径如/user/orgs、/user/teams、/repos/...。测试中的 mock 后端也覆盖了 Enterprise 的/api/v3/user/emails路径见 providers/github_test.go说明 Enterprise 场景下组织、团队、邮箱等数据拉取同样走企业 API。一个完整的实战配置示例综合以上内容一个仅允许某组织下特定团队成员登录的完整启动命令如下./oauth2-proxy \ --providergithub \ --client-idgithub-oauth-app-client-id \ --client-secretgithub-oauth-app-client-secret \ --redirect-urlhttps://internal.yourcompany.com/oauth2/callback \ --email-domain* \ --upstreamhttp://127.0.0.1:8080/ \ --cookie-secret32-byte-random-secret \ --github-orgyour-org \ --github-teamplatform,infra若改用仓库协作者模型./oauth2-proxy \ --providergithub \ --client-id... \ --client-secret... \ --redirect-urlhttps://internal.yourcompany.com/oauth2/callback \ --email-domain* \ --upstreamhttp://127.0.0.1:8080/ \ --cookie-secret... \ --github-repoyour-org/your-private-repo对于需要放行公开仓库只读协作者的场景追加--github-token具有public_reposcope 的管理员 token即可。对应配置的等价 TOML 写法为provider github client_id ... client_secret ... redirect_url https://internal.yourcompany.com/oauth2/callback email_domains [*] upstreams [http://127.0.0.1:8080/] github_org your-org github_team platform,infra参考实现与测试入口如需深入源码验证上述行为建议重点阅读以下文件Provider 核心实现providers/github.go重点看NewGitHubProvider、EnrichSession、checkRestrictions、hasOrgAndTeam、hasRepoAccess、isCollaborator配置结构体pkg/apis/options/providers.goGitHubOptions与 pkg/apis/options/legacy_options.golegacy Flag 定义行为测试providers/github_test.go覆盖组织、组织团队、跨组织团队、仓库权限、token 协作者检查、Enterprise API 路径等全部场景。测试代码中的 mock GitHub 后端testGitHubBackend见 providers/github_test.go几乎一比一复刻了真实 GitHub API 的路径与分页查询/user/orgs、/user/teams、/user/emails、/repos/.../collaborators/...是理解 Provider 与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
oauth2-proxy GitHub 认证 Provider 配置指南：组织、团队、仓库 Collaborator 与 Enterprise 集成
oauth2-proxy GitHub 认证 Provider 配置指南组织、团队、仓库 Collaborator 与 Enterprise 集成【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxyoauth2-proxy 内置的 GitHub Provider 允许你通过 GitHub OAuth 完成登录并在此基础上实现比任何人可登录更精细的访问控制按组织Organization、团队Team、仓库协作者Repository Collaborator乃至指定用户名白名单来限制登录。读完本文你将掌握 GitHub Provider 全部 5 个专属配置项--github-org、--github-team、--github-repo、--github-token、--github-user的语义与组合用法理解它们背后的 API 调用链与判定逻辑并能完成 GitHub Enterprise 的端点覆盖配置。配置项总览GitHub Provider 的专属配置项定义在 pkg/apis/options/legacy_options.go 中同时提供命令行 Flag 与 TOML/配置文件字段两种写法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--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)--github-usergithub_usersstring | listTo allow users to login by username even if they do not belong to the specified org and team or collaborators从源码看命令行 Flag 的定义与注册位于 pkg/apis/options/legacy_options.go其中--github-user使用StringSlice类型因此可以多次指定也可以逗号分隔一次传入。在配置加载阶段这些 legacy 选项会被映射为GitHubOptions结构体字段为Org、Team、Repo、Token、Users定义见 pkg/apis/options/providers.go随后在NewGitHubProvider构造器中通过setOrgTeam、setRepo、setUsers注入到 provider 实例见 providers/github.go。说明表格与文档中的--github-team描述在不同版本文档中略有差异本文以当前仓库 docs/versioned_docs/version-7.8.x/configuration/providers/github.md 为准。它既支持与--github-org搭配使用的裸 slug也支持不指定 org 时的org:team完全限定格式详见下文。Alpha Config 下的等价写法如果使用较新的 Alpha ConfigYAML 配置同一组参数以providers数组内githubConfig的形式出现GitHubOptions的 YAML 字段为org、team、repo、token、users。两个入口最终都会汇入相同的GitHubProvider实现行为完全一致。使用前提创建 GitHub OAuth App在使用前先完成 OAuth App 的注册打开 GitHub 的 Developer settings 页面OAuth Apps 创建入口位于该页面中新建一个 OAuth App在Authorization callback URL中填入 oauth2-proxy 的回调地址格式为https://internal.yourcompany.com/oauth2/callback。回调路径由 oauth2-proxy 默认的/oauth2/callback与你的对外访问域名组成必须与--redirect-url配置保持一致否则 OAuth 授权码交换会失败。Provider 默认行为与 OAuth ScopeGitHub Provider 在初始化时会设置一组默认值见 providers/github.go默认登录端点https://github.com/login/oauth/authorize默认兑换端点redeemhttps://github.com/login/oauth/access_token默认校验/API 端点validatehttps://api.github.com/默认 OAuth Scopeuser:email read:orguser:email用于读取用户邮箱read:org用于读取用户所属的组织与团队——这正是后面组织/团队级限制能够工作的基础。以上默认值有对应的单元测试覆盖见 providers/github_test.go。登录成功后Provider 会通过多个 GitHub API 端点丰富会话EnrichSession见 providers/github.go依次拉取用户所属组织、团队、邮箱与用户名写入会话状态。其中所有组织与团队会以org:team的形式团队用 slug汇总到会话的 Groups 中。两种访问控制模型GitHub Provider 提供两类限制登录的方式二者可以独立使用组织/团队级别限制为指定组织的成员或指定组织内某些团队的成员仓库级别限制为某个仓库的协作者collaborator。配合这些限制时通常还要同时设置--email-domain*。原因在于 oauth2-proxy 默认按邮箱域名做校验--email-domain不设置时不会放行任何用户而 GitHub 的 email 并不总是企业域名放开域名校验后实际的访问范围就完全由组织/团队/仓库规则来界定。此外用户所属的全部组织与团队会随请求转发到上游以X-Forwarded-Groups头传递格式为org1:team1,org1:team2,org2:team1。从源码看该头在 pkg/apis/options/legacy_options.go 中由groupsclaim 生成getPassUserHeaders上游应用可以直接读取它做细粒度授权或审计。限制到组织仅按组织限制时使用--github-orgyour-org # restrict logins to members of this organisation判定逻辑在hasOrg见 providers/github.goProvider 会遍历会话中已收集的组织列表与Org精确匹配匹配失败则返回user is missing required organization错误并拒绝登录。限制到组织内的团队在--github-org基础上叠加团队限制--github-orgyour-org --github-teamteam1,team2,team3 # restrict logins to members of any of these teams (slug), comma separated此时使用hasOrgAndTeam判定见 providers/github.go首先确认用户属于指定组织然后在该组织下检查用户所属团队 slug 是否命中列表中的任意一个。注意团队名需要是 slug 形式即 URL 中使用的团队标识而非显示名称。跨组织多团队限制如果不指定组织、只按团队限制可以将--github-org留空并用org:slug完全限定格式指定跨组织的团队--github-org --github-teamorg1:team1,org2:team1,org3:team42,octo:cat # 格式 org:slug逗号分隔这种用法由hasTeam实现见 providers/github.go。源码中还有一个值得注意的细节如果省略--github-org却在--github-team里写了不含冒号的裸 slughasTeam会直接报错team name is invalid并提示请使用完全限定的团队名org:team-slug。因此跨组织场景下必须写全org:slug。对应的测试用例见 providers/github_test.go。限制到仓库协作者如果希望限制为某个仓库的协作者使用--github-repo # restrict logins to collaborators of this repository formatted as orgname/repo例如--github-repooauth2-proxy/oauth2-proxy。仓库级别的准入规则是公开仓库用户必须对该仓库有 push 权限私有仓库用户拥有任意访问权限包括只读 pull即可。该规则在hasRepoAccess中硬编码见 providers/github.go它请求GET /repos/{org}/{repo}读取响应中的permissions.push与private字段只有pushtrue或privatetrue 且 pulltrue时放行。让只读协作者也能访问公开仓库一个明显的边界情况是公开仓库中只有 push 权限的协作者才能通过默认校验只读协作者会被拒之门外。若要放行只读协作者需要提供一个对该仓库有写权限的用户生成的 token并且该 token 至少要有public_reposcope--github-token # the token to use when verifying repository collaborators这个 token 不用于用户本人的身份而是作为管理员凭证由 oauth2-proxy 在调用 GitHub API 检查协作者身份时代替用户 token 使用。具体调用链在getUser中见 providers/github.go当Org为空、Repo与Token均非空且用户不在用户名白名单时会请求GET /repos/{org}/{repo}/collaborators/{username}以 HTTP 204 作为是协作者的判定依据isCollaborator见 providers/github.go。另外需要明确--github-token与--github-repo的组合行为见checkRestrictionsproviders/github.go只有--github-repo、没有 token 时使用用户自己的 access token调用hasRepoAccess做仓库权限检查即前面说的 push/私有规则同时设置--github-repo与--github-token时改为走isCollaborator协作者检查token 即管理员凭证。这两种路径在测试中都有覆盖TestGitHubProvider_checkRestrictionsWithNoAccessToPrivateRepo验证了无 token 时用户 token 调用仓库接口失败即拒绝TestGitHubProvider_getUserWithRepoAndToken验证了带 token 时通过协作者接口返回 204 放行见 providers/github_test.go 与 providers/github_test.go。按用户名白名单放行--github-user # allow logins by username, separated by a comma当设置了--github-user时指定的用户名即使在组织、团队、协作者规则之外也一律允许登录。注意该选项是加法性质的例外规则它只用于放行不能替代组织/团队/仓库规则来缩小范围。其判定逻辑为checkUserRestriction见 providers/github.go只要Users列表非空就调用GET /user获取当前登录用户的login字段并与白名单比对hasUser与isVerifiedUser。命中则跳过后续所有限制检查checkRestrictions第一步即返回未命中时如果同时没有配置 org 和 repo则直接拒绝missing github user。组合规则与判定优先级把所有规则放在一起看checkRestrictions见 providers/github.go的执行顺序是若配置了用户名白名单且用户命中直接放行跳过其余所有检查否则按orgteam 同时设置 → 仅 org → 仅 team的优先级执行对应校验若以上校验通过、且只配置了 repo 而没有 token再用用户 token 做仓库访问检查。这说明各限制条件之间是并集与叠加的关系用户名白名单是最高优先级的例外org 与 team 的组合是单条校验repo 校验独立于 org/team 校验执行。实际配置时应结合这些规则设计权限模型例如内部成员org 少数外部协作者repo/token 特批人员user的多层放行结构。集成 GitHub Enterprise如果使用 GitHub Enterpriseoauth2-proxy 不会自动探测企业实例的端点必须手动覆盖以下三个 URL当前仓库 7.8.x 版本的默认端点均指向github.com/api.github.com见 providers/github.go--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是整个 GitHub API 的 Base URL。从源码makeGitHubAPIEndpoint见 providers/github.go可以看到构建具体 API 路径时会识别/api/v3前缀并以此为基准拼接后续路径如/user/orgs、/user/teams、/repos/...。测试中的 mock 后端也覆盖了 Enterprise 的/api/v3/user/emails路径见 providers/github_test.go说明 Enterprise 场景下组织、团队、邮箱等数据拉取同样走企业 API。一个完整的实战配置示例综合以上内容一个仅允许某组织下特定团队成员登录的完整启动命令如下./oauth2-proxy \ --providergithub \ --client-idgithub-oauth-app-client-id \ --client-secretgithub-oauth-app-client-secret \ --redirect-urlhttps://internal.yourcompany.com/oauth2/callback \ --email-domain* \ --upstreamhttp://127.0.0.1:8080/ \ --cookie-secret32-byte-random-secret \ --github-orgyour-org \ --github-teamplatform,infra若改用仓库协作者模型./oauth2-proxy \ --providergithub \ --client-id... \ --client-secret... \ --redirect-urlhttps://internal.yourcompany.com/oauth2/callback \ --email-domain* \ --upstreamhttp://127.0.0.1:8080/ \ --cookie-secret... \ --github-repoyour-org/your-private-repo对于需要放行公开仓库只读协作者的场景追加--github-token具有public_reposcope 的管理员 token即可。对应配置的等价 TOML 写法为provider github client_id ... client_secret ... redirect_url https://internal.yourcompany.com/oauth2/callback email_domains [*] upstreams [http://127.0.0.1:8080/] github_org your-org github_team platform,infra参考实现与测试入口如需深入源码验证上述行为建议重点阅读以下文件Provider 核心实现providers/github.go重点看NewGitHubProvider、EnrichSession、checkRestrictions、hasOrgAndTeam、hasRepoAccess、isCollaborator配置结构体pkg/apis/options/providers.goGitHubOptions与 pkg/apis/options/legacy_options.golegacy Flag 定义行为测试providers/github_test.go覆盖组织、组织团队、跨组织团队、仓库权限、token 协作者检查、Enterprise API 路径等全部场景。测试代码中的 mock GitHub 后端testGitHubBackend见 providers/github_test.go几乎一比一复刻了真实 GitHub API 的路径与分页查询/user/orgs、/user/teams、/user/emails、/repos/.../collaborators/...是理解 Provider 与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
