oauth2-proxy GitLab 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 的 GitLab 身份提供方Provider展开介绍如何通过--gitlab-group与--gitlab-project两个核心参数实现登录成员的组/项目级过滤以及 GitLab.com 与自托管 GitLab 两种场景下的完整接入步骤。读完本文你将掌握 GitLab OAuth 应用的创建、回调地址配置、访问级别校验原理并能结合仓库源码理解登录会话如何被“充实”与刷新。核心配置参数一览GitLab Provider 的全部专属配置仅有两个参数在 version-7.14.x 的 GitLab 文档 中以参数表形式给出FlagTOML 字段类型说明默认值--gitlab-groupgitlab_groupsstring | list将登录限制为任意一个指定组slug的成员多个组用逗号分隔空--gitlab-projectgitlab_projectsstring | list将登录限制为任意一个指定项目的成员可多次指定格式为orgname/repoaccesslevel。访问级别取值需符合 GitLab access levels缺省时为 20空在旧版命令行Legacy配置体系中这两个 flag 定义于 pkg/apis/options/legacy_options.go并在legacyToProvider转换时映射到新的 Provider 结构case gitlab: provider.GitLabConfig GitLabOptions{ Group: l.GitLabGroup, Projects: l.GitLabProjects, }而在新版 Alpha 配置TOML中对应字段位于gitlabConfig下结构体定义见 pkg/apis/options/providers.gotype GitLabOptions struct { // Group sets restrict logins to members of this group Group []string yaml:group,omitempty // Projects restricts logins to members of these projects Projects []string yaml:projects,omitempty }即 Alpha 配置写法为[providers[0]] provider gitlab clientID GITLAB_CLIENT_ID clientSecret GITLAB_CLIENT_SECRET [providers[0].gitlabConfig] group [mygroup, myothergroup] projects [myorg/myproject30]在 GitLab 中创建 OAuth 应用无论你使用 GitLab.com 还是自托管 GitLab接入流程一致进入 GitLab 的 OAuth Provider 应用注册页面添加一个 Application并注意以下三点至少启用openid、profile、email三个 scope——这是 oauth2-proxy 正常读取用户身份所必需的最低范围将回调地址Redirect URI设置为你的应用地址例如https://myapp.com/oauth2/callback如果要用到项目过滤--gitlab-project需要额外添加read_apiscope——oauth2-proxy 需要以此调用 GitLab API 查询用户的真实访问级别。需要说明的是即使你忘了手动加read_api源码也会自动补上在 providers/gitlab.go 的setProjectScope中只要配置了允许项目就会检查并追加read_api到 scope 末尾func (p *GitLabProvider) setProjectScope() { for _, val : range strings.Split(p.Scope, ) { if val read_api { return } } p.Scope read_api }默认 scope 为openid email见 providers/gitlab.go 中的gitlabDefaultScope因此最终会变成openid email read_api。版本兼容性说明该 Provider 已在 GitLab 12.X 上完成测试由于 GitLab API 的变更低于 12.X 的版本可能无法正常工作见 oauth2-proxy 的 issue #994。如果你仍在使用旧版自托管 GitLab请先升级到 12.X 及以上再接入。最小可用配置完成应用注册后以下命令行参数即可让 oauth2-proxy 以 GitLab 作为唯一身份源工作--providergitlab --redirect-urlhttps://myapp.com/oauth2/callback // 必须与 GitLab 应用中填写的回调地址一致 --client-idGITLAB_CLIENT_ID --client-secretGITLAB_CLIENT_SECRET --cookie-secretCOOKIE_SECRET--redirect-url必须与你在 GitLab Application 里登记的回调地址完全一致否则 GitLab 会拒绝回调--cookie-secret用于加密会话 Cookie生成方式见 overview 文档中的 cookie secret 生成章节注意 GitLab Provider 基于 OIDC 实现GitLabProvider内嵌*OIDCProvider见 providers/gitlab.go因此 GitLab.com 场景下 issuer 相关默认值即可工作。按组Group限制登录只允许特定 GitLab 组的成员登录使用--gitlab-group多个组用逗号分隔--gitlab-groupmygroup,myothergroup # restrict logins to members of any of these groups (slug), separated by a comma含义是“这些组中任意一个的成员即可通过认证”逻辑为 OR。组名使用 slug即 URL 中的短横线形式。底层实现中provider.setAllowedGroups(opts.GitLabConfig.Group)会在NewGitLabProvider时把组写入AllowedGroups集合见 providers/gitlab.go之后会话中的组列表会与该集合比对。按项目Project限制登录项目级过滤使用--gitlab-project格式为orgname/repoaccesslevel--gitlab-projectmyorg/myproject30访问级别的取值与 GitLab 文档定义的访问级别一致。oauth2-proxy 源码中有效级别白名单为[10, 20, 30, 40]见 providers/gitlab.go对应关系如下值GitLab 角色10Guest访客20Reporter报告者默认值30Developer开发者40Maintainer维护者要点省略accesslevel时默认按 20Reporter处理级别是“最低门槛”语义——用户的真实访问级别配置级别即视为通过见下文校验逻辑传入非法级别如 50/Owner 或非数字会在启动时直接报错invalid gitlab project access level specified阻止 oauth2-proxy 启动。项目过滤的底层校验流程这是 GitLab Provider 与其它 OIDC Provider 差异最大的地方值得深入理解。在 providers/gitlab.go 的EnrichSession中登录时会依次完成拉取 userinfo调用GET {GitLab 地址}/oauth/userinfo携带Authorization: Bearer access_token解析出nickname、email、email_verified、groups见 providers/gitlab.go校验邮箱如果--insecure-allow-unverified-email未开启且email_verified为 false直接拒绝登录user email is not verified填充会话把 nickname/email/groups 写入SessionState校验项目对每个配置的允许项目调用 GitLab APIGET /api/v4/projects/urlencode(项目名)见 providers/gitlab.go然后逐项检查项目已归档archived true→ 拒绝并跳过优先取permissions.project_access为空则回退到permissions.group_access即用户通过所属组继承的访问权限两者都为空 → 拒绝用户的access_level低于要求的最低级别 → 拒绝。通过校验的项目会以project:项目名的形式追加进会话组列表formatProject加上project:前缀见 providers/gitlab.go因此项目约束在会话数据里表现为一种特殊的“组”。会话刷新时项目信息不丢失GitLab 项目信息是登录时通过 API 查询得到的并不存在于 ID Token 的 claims 里因此普通 OIDC 刷新会把它冲掉。GitLabProvider重写了RefreshSession见 providers/gitlab.go刷新前先把project:前缀的组暂存下来刷新完成后再合并回去并去重从而保证长期会话期间项目约束依然生效。自托管 GitLab 的特殊配置如果你使用的是自托管 GitLab需要额外指定 issuer 地址--oidc-issuer-urlyour gitlab url例如--oidc-issuer-urlhttps://gitlab.example.com。oauth2-proxy 会基于该地址解析 OIDC 发现文档、验证 ID Token 签名并在用户信息与项目查询时拼接{issuer}/oauth/userinfo与{issuer}/api/v4/projects/...注意源码中 userinfo 与项目 API 的 Host/Scheme 均取自LoginURL即由 issuer 推导而来。部署在子目录subdirectory时的回调注意如果自托管 GitLab 挂在子目录下例如domain.tld/gitlab而非独立子域例如gitlab.domain.tldGitLab 自身的 OAuth 端点位于子目录之下此时你可能需要在反向代理层面加一条跳转把domain.tld/oauth重定向到domain.tld/gitlab/oauth以确保 OAuth 授权流程中的回调路径能正确命中 GitLab 的端点。测试验证行为与源码一致仓库的单元测试直接验证了上述行为可作为排障参考。providers/gitlab_test.go 中构造了模拟 GitLab 后端userInfo返回nickname/email/email_verified/groupsprojectInfo返回archived与permissions.project_access/group_access其中还专门构造了group_access.access_level 30以及project_access与group_access均为 null 的“无权限”用例用于验证通过组继承获得项目访问权限时group_access非空可以放行完全没有项目/组级访问权限时被拒绝配置的访问级别高于用户实际级别时被拒绝。完整实战示例自托管 项目过滤综合以上内容一个自托管 GitLab 场景的完整命令行配置如下--providergitlab --oidc-issuer-urlhttps://gitlab.example.com --redirect-urlhttps://myapp.com/oauth2/callback --client-idGITLAB_CLIENT_ID --client-secretGITLAB_CLIENT_SECRET --cookie-secretCOOKIE_SECRET --gitlab-groupplatform --gitlab-projectplatform/backend30,platform/frontend20该配置的效果是仅允许platform组的成员登录同时必须是platform/backend项目 30 级Developer以上、或platform/frontend项目 20 级Reporter以上成员组与项目约束同时生效取交集。对应 Alpha TOML 写法即前文给出的gitlabConfig.group与gitlabConfig.projects字段。小结GitLab Provider 是 oauth2-proxy 中功能最丰富的 OIDC 型 Provider 之一它既有标准的 OIDC 授权码流程又通过 GitLab 专属 API 实现了组过滤与精细的项目访问级别控制。掌握--gitlab-group与--gitlab-project的语义OR 关系、默认级别 20、有效级别 10/20/30/40、自托管时--oidc-issuer-url的必要性以及项目校验的“API 查询 级别比较”原理即可在生产环境中精确管控谁能登录你的应用。【免费下载链接】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），仅供参考