ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

基于 oauth2-proxy 的 GitHub 登录认证与细粒度访问控制配置指南

基于 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 中接入 GitHub 身份提供商的开发者系统讲解 GitHub OAuth App 的创建、--github-org/--github-team/--github-repo/--github-token/--github-user五个核心参数的语义与组合方式并结合 providers/github.go 源码剖析其背后基于 GitHub REST API 的组织、团队、仓库协作者校验流程以及 GitHub Enterprise 环境下的端点定制。阅读完本文你将能够按组织、团队、仓库协作者或用户名白名单四类策略精确控制哪些 GitHub 用户可以访问你的受保护应用。本文基于仓库内 docs/versioned_docs/version-7.15.x/configuration/providers/github.md 整理扩展所有行为描述均可在当前仓库源码与测试中找到对应实现依据。一、GitHub Provider 配置选项总览oauth2-proxy 的 GitHub provider 提供了五个专属配置项用于在通过 GitHub 账号认证的基础上叠加额外的授权限制。它们既可以作为命令行 Flag 使用也可以在 TOML/YAML 配置文件中通过对应字段配置FlagToml 字段类型描述默认值--github-orggithub_orgstring将登录限制为该组织的成员空--github-teamgithub_teamstring将登录限制为这些团队的成员支持 slug 或org:team格式逗号分隔空--github-repogithub_repostring将登录限制为该仓库的协作者格式为orgname/repo空--github-tokengithub_tokenstring用于校验仓库协作者身份的 token必须对仓库具有 push 权限空--github-usergithub_usersstring | list允许指定用户名的用户登录即使他们不属于上述组织、团队或协作者范围空命令行 Flag 的定义位于 pkg/apis/options/legacy_options.goGitHubOrg string flag:github-org cfg:github_org GitHubTeam string flag:github-team cfg:github_team GitHubRepo string flag:github-repo cfg:github_repo GitHubToken string flag:github-token cfg:github_token GitHubUsers []string flag:github-user cfg:github_users在 alpha 配置格式下这些参数被聚合到GitHubOptions结构体中YAML 字段名为org、team、repo、token、users对应定义见 pkg/apis/options/providers.goproviders: - id: github provider: github clientID: 你的 Client ID clientSecret: 你的 Client Secret githubConfig: org: your-org team: team1,team2 repo: your-org/your-repo token: ghp_xxx users: - alice - boblegacy 配置在加载时会被转换为上述结构体转换逻辑见 pkg/apis/options/legacy_options.go。二、快速上手创建 GitHub OAuth App使用 GitHub provider 前需要先在 GitHub 上注册一个 OAuth Application登录 GitHub 后进入「Settings → Developer settings → OAuth Apps → New OAuth App」创建新应用在Authorization callback URL授权回调地址中填入 oauth2-proxy 的完整回调地址形如https://internal.yourcompany.com/oauth2/callback注意回调路径固定为/oauth2/callback必须与 oauth2-proxy 实际对外暴露的地址保持一致创建完成后将生成的 Client ID 与 Client Secret 分别配置到--client-id与--client-secret或在配置文件中设置clientID/clientSecret。最简启动示例oauth2-proxy \ --providergithub \ --client-id你的 Client ID \ --client-secret你的 Client Secret \ --cookie-secret32字节随机字符串 \ --email-domain* \ --upstreamhttp://127.0.0.1:8080三、两种访问控制模型与 X-Forwarded-GroupsGitHub provider 在邮箱/账号认证之外额外支持两种访问限制方式组织 / 团队级限制限定为某个组织的成员或进一步限定为组织内一个或多个团队的成员仓库协作者级限制限定为某个仓库的协作者collaborators。使用这两种限制时通常需要同时配置--email-domain*表示不通过邮箱域名做限制因为访问控制完全交由上述策略决定而不是邮箱。此外无论是否配置限制用户所属的全部组织和团队都会被写入会话的 groups 列表并在后续请求中以X-Forwarded-Groups请求头透传给上游应用例如org1:team1,org1:team2,org2:team1该头是 oauth2-proxy 默认注入的请求头之一配置来源见 pkg/apis/options/legacy_options.go它从会话的groupsclaim 取值。上游应用可以基于该头实现自己的二次授权逻辑例如 Nginx、服务网格内的基于组的路由。四、按组织Organization限制登录只允许指定 GitHub 组织的成员登录# 将登录限制为这个组织的成员 --github-orgyour-org源码层面该限制由 providers/github.go 中的hasOrg实现遍历会话中的 groups凡是不含:分隔符的 group 均视为组织名与p.Org精确匹配即放行匹配失败则返回错误user is missing required organization并拒绝登录。五、按团队Team限制登录5.1 限定同一组织下的多个团队与--github-org搭配将登录限制为指定组织内若干团队的成员使用团队 slug逗号分隔--github-orgyour-org # 将登录限制为以下任一团队的成员团队 slug逗号分隔 --github-teamteam1,team2,team35.2 跨组织的团队限制如果团队分布在不同的组织中则必须将--github-org留空并在--github-team中使用org:slug全限定格式# 保持为空 --github-org # 将登录限制为以下任一团队的成员格式 org:slug如 octo:team1逗号分隔 --github-teamorg1:team1,org2:team1,org3:team42,octo:cat源码中的校验逻辑清晰地区分了这两种模式当Org与Team同时配置时走 hasOrgAndTeam先从 groups 中解析出org:team对要求用户所属组织命中p.Org大小写不敏感且该组织下命中的团队 slug 出现在p.Team逗号分隔列表中当仅配置TeamOrg 为空时走 hasTeam要求配置的每个团队名都必须包含:分隔符否则直接报错team name is invalid并提示省略组织时必须使用全限定团队名 org:team-slug随后与用户实际所属的org:team做大小写不敏感匹配。六、按仓库协作者Collaborator限制登录如果不按组织/团队限制而希望只允许某个仓库的协作者登录则使用--github-repo# 将登录限制为这个仓库的协作者格式为 orgname/repo --github-repoyour-org/your-repo协作者权限判定规则如下公开仓库用户必须对该仓库具有push写入权限私有仓库用户对该仓库具有任意访问权限包括只读 pull即可。上述判定逻辑位于 hasRepoAccess它调用 GitHub APIGET /repos/{org}/{repo}读取返回的permissions与private字段只有当permissions.push true或者仓库为私有且permissions.pull true时才放行——因为公开仓库对所有人隐式可读所以只读权限不构成授权依据。6.1 使用--github-token支持公开仓库的只读协作者如果希望允许对公开仓库只有**只读read only**权限的用户登录则需要提供一个对该仓库具有write 权限的账号所创建的 GitHub Personal Access Token在 GitHub 的 Developer settings → Personal access tokens 中创建。该 token 至少需要具备public_reposcope# 用于校验仓库协作者身份的 token --github-tokenghp_xxxxxxxxxxxxxxxx从源码看token 有两种用途当Org为空、Repo非空且Token非空时checkRestrictions 不再用用户自己的 token 做仓库访问检查因为只读用户可能没有可用 token而是跳过 repo 校验真正的协作者校验发生在 getUser 中——通过 isCollaborator 以管理 token调用GET /repos/{org}/{repo}/collaborators/{username}返回 HTTP 204 表示该用户确实是协作者。6.2 不带 token 时的行为如果只配置--github-repo而未配置--github-token则使用用户自身登录后获得的 AccessToken 调用仓库 API 校验见 checkRestrictions此时遵循上文公开仓库需 push 权限、私有仓库任意权限的规则。七、按用户名白名单放行--github-user--github-user提供了一条例外通道列出的用户名可以直接登录即使他们不属于上面配置的组织、团队也不是仓库协作者。# 允许按用户名登录逗号分隔该 Flag 也可重复指定多次 --github-useralice,bob其判断链路为checkUserRestriction 首先通过GET /userhasUser获取当前登录用户名与白名单精确比对isVerifiedUser命中白名单后checkRestrictions 会直接跳过 org/team/repo 校验特别地如果用户不在白名单、且Org 与 Repo 均未配置则直接返回错误missing github user——此时白名单就是唯一的授权依据。八、底层原理EnrichSession 会话丰富流程GitHub provider 在完成 OAuth 换码redeem拿到 AccessToken 之后会通过 EnrichSession 用 GitHub REST API 丰富会话状态这是上述所有访问控制得以实施的基础EnrichSession ├── 1. getOrgAndTeam → GET /user/orgs GET /user/teams分页拉取per_page100 │ ├── 组织写入 session.Groups如 org1、org2 │ └── 团队写入 session.Groups如 org1:team1、org1:team2 ├── 2. checkRestrictions → 根据 Org/Team/Repo/Users 配置执行授权校验失败则拒绝 ├── 3. getEmail → GET /user/emails取 primary 且 verified 的邮箱写入 session.Email └── 4. getUser → GET /user取 login 写入 session.User必要时做协作者校验值得注意的实现细节组织和团队列表通过分页接口获取每页per_page100并递增page参数直至返回空列表见 getOrgs 与 getTeams团队写入格式为orgName:teamSlug这正是X-Forwarded-Groups头中org1:team1形式的来源会话校验阶段 ValidateSession 使用带Accept: application/vnd.github.v3json头makeGitHubHeader的请求验证 AccessToken 有效性。以上行为在 providers/github_test.go 中有完整覆盖例如TestNewGitHubProvider验证了默认端点与默认 scopetestGitHubBackend中模拟了/user/orgs、/user/teams的多页响应、/user/emails、/user以及协作者检查端点还专门为 GitHub Enterprise 准备了/api/v3前缀的端点。九、默认端点与默认 ScopeGitHub provider 内置以下默认值见 providers/github.go 与 NewGitHubProvider项默认值说明Login URLhttps://github.com/login/oauth/authorize授权跳转端点Redeem URLhttps://github.com/login/oauth/access_token换取 AccessToken 端点Validate URLhttps://api.github.com/API 基础地址组织/团队/仓库等 API 请求均基于它拼接Profile URL无GitHub provider 不使用 profile URL用户信息由 API 获取Scopeuser:email read:org请求的 OAuth scoperead:org是组织/团队信息获取所必需的 scope——没有它/user/orgs与/user/teams将无法返回数据组织/团队限制也就无法生效。这些默认值同样由测试TestNewGitHubProvider断言。十、GitHub Enterprise企业版适配如果使用 GitHub Enterprise含 GitHub Enterprise Server需要将以下三个端点替换为企业实例的地址见 TestGitHubProviderOverrides测试验证了覆盖行为--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 中有一条专门处理若 ValidateURL 的路径以/api/v\d开头如/api/v3则将其作为后续 API 请求的 base path从而正确拼出/api/v3/user/orgs、/api/v3/repos/...等企业版端点测试后端也对/api/v3/user/emails等路径做了模拟支持。十一、验证配置与排障使用--config-test验证配置oauth2-proxy 提供--config-test参数只做配置校验不启动代理可用来确认 provider 类型、client 信息、Cookie 密钥等是否配置合法观察日志关键词授权被拒时日志会给出明确原因例如Missing Organization:... in [...]、Missing Team:... from Org:... in teams: ...、user doesnt have repository access、missing github user等见上文各校验函数的 logger 输出核对 groups 头用curl -I或抓包检查上游收到的X-Forwarded-Groups确认组织/团队信息是否正确注入确认 scope组织/团队限制不生效时优先检查 OAuth App 授权时是否带上了read:orgscopetoken 需由用户重新授权。小结GitHub provider 的核心价值在于把认证你是谁与授权你能访问什么分离认证统一走 GitHub OAuth授权则可通过组织、团队、仓库协作者、用户名白名单四类策略自由组合同时以X-Forwarded-Groups头将组织与团队信息传递给上游应用做更精细的控制。理解 providers/github.go 中EnrichSession → checkRestrictions的校验链路是正确使用这些参数、快速定位授权失败问题的关键。【免费下载链接】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),仅供参考
返回列表