GitLab 对接 EAuth OIDC 认证

介绍

本次记录范围：

1. GitLab 接入 EAuth OIDC，实现统一登录。
2. 梳理 EAuth 与 GitLab 两侧的关键配置。
3. 输出上线验证项和常见排障路径。

建议先在测试环境验证完成后，再切换生产登录入口。

GitLab 简介

GitLab 是覆盖代码托管、代码评审、CI/CD、制品与安全扫描的一体化 DevOps 平台。

在企业场景中，GitLab 通常需要与统一身份系统打通，避免多套账号并支持组织级访问治理。

对接原因

在该方案中，职责拆分如下：

1. EAuth 负责身份认证与账号来源。
2. GitLab 负责仓库、流水线、权限模型与审计记录。

引入 OIDC 的直接收益：

1. 统一登录入口，减少账号运维成本。
2. 新用户可按策略自动创建并接入组织。
3. 认证策略与审计统一收敛到身份层。

前置条件

开始前请确认：

1. GitLab 实例可访问（示例：https://gitlab.efucloud.com）。
2. EAuth 已部署并可提供 OIDC（issuer、client_id、client_secret 已就绪）。
3. GitLab 与 EAuth 网络互通，可访问 /.well-known/openid-configuration。
4. 已规划回调地址与登出跳转策略。

OIDC 关键设计点

正式配置前建议先确认以下策略：

1. 登录标识映射：使用 preferred_username / email / sub 哪个 claim。
2. 自动创建用户：是否允许首次登录自动开通（allow_single_sign_on）。
3. 自动绑定方式：是否按邮箱自动关联已有账号（auto_link_user）。
4. 组织权限同步：是否基于 groups claim 做角色治理。

EAuth 端配置清单

在 EAuth 中创建 OIDC 应用，建议至少包含：

1. 应用名称：gitlab。
2. 回调地址：https://gitlab.efucloud.com/users/auth/openid_connect/callback。
3. 授权范围：openid profile email（如需组信息再增加对应 scope/claim）。
4. 授权方式：Authorization Code。

GitLab 端配置框架

以下为 GitLab Omnibus 的配置框架，可直接作为 gitlab.rb 的基础模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_auto_link_user'] = ['openid_connect']

gitlab_rails['omniauth_providers'] = [
  {
    name: 'openid_connect',
    label: 'EAuth',
    args: {
      name: 'openid_connect',
      scope: ['openid', 'profile', 'email'],
      response_type: 'code',
      issuer: 'https://eauth.efucloud.com',
      discovery: true,
      client_auth_method: 'query',
      uid_field: 'preferred_username',
      pkce: true,
      client_options: {
        identifier: 'your_client_id',
        secret: 'your_client_secret',
        redirect_uri: 'https://gitlab.efucloud.com/users/auth/openid_connect/callback'
      }
    }
  }
]

配置完成后执行：

1
2

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

如果你使用 Helm 部署 GitLab，可按同样字段映射到 global.appConfig.omniauth。

部署步骤

1. 在 EAuth 创建应用并拿到 client_id、client_secret、issuer。
2. 在 GitLab 写入 OIDC Provider 配置。
3. 重载 GitLab 配置并重启相关组件。
4. 浏览器无痕模式验证登录链路。
5. 完成后收敛本地账号登录策略（按组织策略决定是否保留）。

验证

建议按以下顺序验证：

1. 登录页出现 EAuth 登录按钮。
2. 点击后正常跳转到 EAuth 登录页。
3. 认证成功后回调到 GitLab，并自动进入目标账号。
4. 首次登录用户按预期被创建或被拦截。
5. 邮箱、用户名、显示名映射符合预期。

常见问题与排障

1) 登录页没有 EAuth 按钮

1. 检查 omniauth_enabled 是否生效。
2. 检查 gitlab.rb 语法与重载是否成功。
3. 检查浏览器缓存，使用无痕窗口重试。

2) 回调报错或重定向循环

1. 核对 EAuth 配置的回调地址与 GitLab 完全一致。
2. 检查 GitLab 外部访问地址与 redirect_uri 是否一致。
3. 检查反向代理头（X-Forwarded-Proto）是否正确。

3) 用户创建成功但信息映射错误

1. 调整 uid_field（如 preferred_username / email）。
2. 检查 EAuth 实际下发 claim 与 GitLab 配置是否一致。
3. 必要时开启 GitLab 日志定位 claim 解析结果。

4) 已有账号无法自动关联

1. 确认 omniauth_auto_link_user 已包含 openid_connect。
2. 确认 GitLab 现有账号邮箱与 EAuth 返回邮箱一致。

注意事项

1. client_secret 建议使用密钥管理，不要长期明文保存。
2. 上线前先保留管理员应急登录方式，避免 SSO 配置错误导致锁死。
3. 生产切换建议分阶段：先灰度团队，再全员切换。
4. 若涉及外包或临时账号，建议结合 EAuth 生命周期策略统一治理。

结果记录

完成对接后可确认：

1. GitLab 登录入口统一到 EAuth。
2. 用户身份来源统一，账号治理更清晰。
3. 认证审计链路可与组织身份体系打通。

参考链接

1. GitLab OmniAuth 文档: https://docs.gitlab.com/administration/auth/oidc/
2. GitLab 通用身份认证文档: https://docs.gitlab.com/integration/omniauth/
3. OpenID Connect Core: https://openid.net/specs/openid-connect-core-1_0.html
4. 智易付官网: https://efucloud.com