Ubuntu GitLab如何配置单点登录

Ubuntu 上 GitLab 单点登录配置指南

一 方案总览与前置条件

• 常见方案包括：SAML 2.0（企业级 IdP 如 Okta/OneLogin）、OAuth2/OpenID Connect（自建或云厂商）、以及 CAS。GitLab 可作为 Service Provider（SP） 接入。前置要求：实例启用 HTTPS（生产环境必须），域名与证书就绪；准备 IdP 的 SAML ACS URL、EntityID/Issuer、NameID、证书指纹/证书 或 OAuth 的 Client ID/Secret、回调地址、Scope 等。为便于对接，GitLab 提供 SAML 元数据 URL：https:///users/auth/saml/metadata。

二 方案一 SAML 2.0 集成步骤

• 修改配置文件 /etc/gitlab/gitlab.rb（Omnibus 包）：启用 OmniAuth、允许 SSO 自动创建账户、可选自动关联同邮箱用户，并配置 SAML 提供方参数（ACS、IdP SSO 地址、Issuer、证书指纹、NameID 格式等）。示例：

  gitlab_rails['omniauth_enabled'] = true
  gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
  gitlab_rails['omniauth_block_auto_created_users'] = false
  gitlab_rails['omniauth_auto_link_saml_user'] = true
  
  gitlab_rails['omniauth_providers'] = [
    {
      name: "saml",
      label: "Company SAML",   # 登录按钮显示名
      args: {
        assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
        idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",  # SHA-1 指纹
        idp_sso_target_url: "https://login.example.com/idp",
        issuer: "https://gitlab.example.com",
        name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
      }
    }
  ]
  

  关键要点：
  • ACS URL 固定为 https:///users/auth/saml/callback；Issuer 需与 IdP 中注册的应用标识一致；NameID 建议使用 Persistent，确保用户标识稳定；证书指纹为 SHA-1。
• 在 IdP 中注册 GitLab SP：使用上面的 Issuer 与 ACS URL；多数 IdP 支持直接导入 GitLab 的 元数据 URL（/users/auth/saml/metadata）；至少提供 email/mail 声明，建议同时提供 name/first_name/last_name。
• 使配置生效并测试：执行 sudo gitlab-ctl reconfigure；访问登录页应出现 SAML 按钮，完成跳转后自动登录；如提示邮箱已被占用，可先以本地账号登录，在 Profile → Account 中绑定第三方身份。

三 方案二 OAuth2/OpenID Connect 集成步骤

• 修改 /etc/gitlab/gitlab.rb：启用 OmniAuth、允许 SSO、按需锁定自动创建账户，并配置具体提供方。示例（以通用 OAuth2 为例）：

  gitlab_rails['omniauth_enabled'] = true
  gitlab_rails['omniauth_allow_single_sign_on'] = ['oauth2_generic']
  gitlab_rails['omniauth_block_auto_created_users'] = false
  
  gitlab_rails['omniauth_providers'] = [
    {
      name: 'oauth2_generic',
      app_id: 'YOUR_CLIENT_ID',
      app_secret: 'YOUR_CLIENT_SECRET',
      args: {
        client_options: {
          site: 'https://idp.example.com',
          authorize_url: '/oauth2/authorize',
          token_url: '/oauth2/token',
          user_info_url: '/oauth2/userinfo'
        },
        user_response_structure: {
          root_path: [],  # 依据 IdP 返回结构调整
          attributes: { name: 'username', nickname: 'nickName' }
        },
        name: 'Company OAuth',
        strategy_class: "OmniAuth::Strategies::OAuth2Generic"
      }
    }
  ]
  

  关键要点：
  • 回调地址通常为 https:///users/auth/oauth2_generic/callback；按需申请 openid profile email 等 Scope；确保返回 email 唯一且稳定。
• 使配置生效并测试：执行 sudo gitlab-ctl reconfigure；登录页出现 Company OAuth 按钮，完成授权后自动登录；若邮箱已存在，先本地登录后在 Profile → Account 绑定第三方账号。

四 多 IdP 与常见问题处理

• 多 IdP 配置（GitLab 14.6+）：为每个提供方设置唯一 name，且 assertion_consumer_service_url 与之匹配（如 /users/auth/saml_1/callback 与 /users/auth/saml_2/callback），必要时显式指定 strategy_class，并为每个按钮设置不同 label。
• 常见报错与处理：
  • 登录时报 422 且提示 Email has already been taken：说明该邮箱已在 GitLab 存在，先用本地账号登录，在 Profile → Account 中绑定第三方身份后再使用 SSO。
  • 账户被锁定或限制：若设置了 omniauth_block_auto_created_users = true，自动创建账户会被锁定，需管理员解锁或改为 false 并配合 auto_link_saml_user 使用。
  • 安全与合规：确保 NameID 固定（避免被冒用登录他人账号）；SAML 响应需签名，证书指纹使用 SHA-1；必要时开启 断言/响应加密 与 签名校验。