• 支持的提供者
• 配置通用设置
  • 配置初始设置
  • 每个提供者的配置
  • 通过 OmniAuth 创建的用户密码
• 为现有用户启用 OmniAuth
• 启用或禁用使用 OmniAuth 提供者登录而不禁用导入源
• 禁用 OmniAuth
• 将现有用户链接到 OmniAuth 用户
• 创建外部提供者列表
• 保持 OmniAuth 用户资料的最新
• 绕过双因素认证
• 自动使用提供者登录
• 使用自定义 OmniAuth 提供者图标
• 更改应用程序或配置
• 已知问题

{{< details >}}

• Tier: 基础版，专业版，旗舰版
• Offering: 私有化部署

{{< /details >}}

用户可以通过使用来自 Google、GitHub 和其他流行服务的凭据登录极狐GitLab。 OmniAuth 是极狐GitLab 用来提供此身份验证的 Rack 框架。

配置完成后，登录页面上会显示额外的登录选项。

支持的提供者

极狐GitLab 支持以下 OmniAuth 提供者。

配置通用设置

在配置 OmniAuth 提供者之前，先配置所有提供者通用的设置。

配置初始设置

要更改 OmniAuth 设置：

{{< tabs >}}

{{< tab title=”Linux package (Omnibus)” >}}

1. 编辑 /etc/gitlab/gitlab.rb：

   # 小心！
   # 这允许用户在没有用户账户的情况下登录。使用数组定义允许的提供者，例如 ["saml", "google_oauth2"]，或作为 true/false 以允许所有或不允许任何提供者。
   # 当身份验证成功时，用户账户将自动创建。
   gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'google_oauth2']
   gitlab_rails['omniauth_auto_link_ldap_user'] = true
   gitlab_rails['omniauth_block_auto_created_users'] = true
   

2. 保存文件并重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

{{< /tab >}}

{{< tab title=”Helm chart (Kubernetes)” >}}

1. 导出 Helm 值：

   helm get values gitlab > gitlab_values.yaml
   

2. 编辑 gitlab_values.yaml，并更新 globals.appConfig 下的 omniauth 部分：

   global:
     appConfig:
       omniauth:
         enabled: true
         allowSingleSignOn: ['saml', 'google_oauth2']
         autoLinkLdapUser: false
         blockAutoCreatedUsers: true
   

3. 保存文件并应用新的值：

   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
   

{{< /tab >}}

{{< tab title=”Docker” >}}

1. 编辑 docker-compose.yml：

   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'google_oauth2']
           gitlab_rails['omniauth_auto_link_ldap_user'] = true
           gitlab_rails['omniauth_block_auto_created_users'] = true
   

2. 保存文件并重启极狐GitLab：

   docker compose up -d
   

{{< /tab >}}

{{< tab title=”Self-compiled (source)” >}}

1. 编辑 /home/git/gitlab/config/gitlab.yml：

   ## OmniAuth 设置
   omniauth:
     # 允许通过 Google、极狐GitLab 等使用 OmniAuth 提供者登录
     # 版本 11.4 之前需要将其设置为 true
     # enabled: true
   
     # 小心！
     # 这允许用户在没有用户账户的情况下登录。使用数组定义允许的提供者，例如 ["saml", "google_oauth2"]，或作为 true/false 以允许所有或不允许任何提供者。
     # 当身份验证成功时，用户账户将自动创建。
     allow_single_sign_on: ["saml", "google_oauth2"]
   
     auto_link_ldap_user: true
   
     # 锁定这些用户，直到管理员清除他们（默认：true）。
     block_auto_created_users: true
   

2. 保存文件并重启极狐GitLab：

   # 对于运行 systemd 的系统
   sudo systemctl restart gitlab.target
   
   # 对于运行 SysV init 的系统
   sudo service gitlab restart
   

{{< /tab >}}

{{< /tabs >}}

配置这些设置后，您可以配置您选择的 提供者。

每个提供者的配置

{{< history >}}

• 引入于极狐GitLab 15.3。

{{< /history >}}

如果设置了 allow_single_sign_on，极狐GitLab 使用 OmniAuth auth_hash 中返回的以下字段之一来为登录的用户在极狐GitLab 中建立用户名，选择第一个存在的字段：

• username。
• nickname。
• email。

您可以为提供者提供的 提供者 使用 args 创建极狐GitLab 配置。如果您在提供者的 args 中设置了 gitlab_username_claim 变量，则可以选择另一个声明来作为极狐GitLab 用户名。选择的声明必须是唯一的，以避免冲突。

{{< tabs >}}

{{< tab title=”Linux package (Omnibus)” >}}

gitlab_rails['omniauth_providers'] = [

  # 使用名称 PROVIDER_NAME 配置提供者的通用模式

  gitlab_rails['omniauth_providers'] = {
    name: "PROVIDER_NAME"
    ...
    args: { gitlab_username_claim: 'sub' } # 对于使用您配置的提供者登录的用户，极狐GitLab 用户名将设置为从提供者收到的 "sub"
  },

  # 这里是使用 GitHub 和 Kerberos 的示例

  gitlab_rails['omniauth_providers'] = {
    name: "github"
    ...
    args: { gitlab_username_claim: 'name' } # 对于使用 GitHub 登录的用户，极狐GitLab 用户名将设置为从 GitHub 收到的 "name"
  },
  {
    name: "kerberos"
    ...
    args: { gitlab_username_claim: 'uid' } # 对于使用 Kerberos 登录的用户，极狐GitLab 用户名将设置为从 Kerberos 收到的 "uid"
  },
]

{{< /tab >}}

{{< tab title=”Self-compiled (source)” >}}

- { name: 'PROVIDER_NAME',
  # ...
  args: { gitlab_username_claim: 'sub' }
}
- { name: 'github',
  # ...
  args: { gitlab_username_claim: 'name' }
}
- { name: 'kerberos',
  # ...
  args: { gitlab_username_claim: 'uid' }
}

{{< /tab >}}

{{< /tabs >}}

通过 OmniAuth 创建的用户密码

通过集成身份验证方法创建用户的生成密码 指南提供了关于极狐GitLab 如何生成和设置使用 OmniAuth 创建的用户密码的概述。

为现有用户启用 OmniAuth

如果您是现有用户，在极狐GitLab 账户创建后，您可以激活一个 OmniAuth 提供者。例如，如果您最初使用 LDAP 登录，您可以启用一个 OmniAuth 提供者，例如 Google。

1. 使用您的极狐GitLab 凭据、LDAP 或其他 OmniAuth 提供者登录极狐GitLab。
2. 在左侧边栏中，选择您的头像。
3. 选择 编辑个人资料。
4. 在左侧边栏中，选择 账户。
5. 在 连接的账户 部分，选择 OmniAuth 提供者，例如 Google。
6. 您将被重定向到提供者。在您授权极狐GitLab 后，您将被重定向回极狐GitLab。

现在您可以使用您选择的 OmniAuth 提供者登录极狐GitLab。

启用或禁用使用 OmniAuth 提供者登录而不禁用导入源

管理员可以启用或禁用某些 OmniAuth 提供者的登录。

{{< alert type=”note” >}}

默认情况下，配置在 config/gitlab.yml 中的所有 OAuth 提供者都启用了登录。

{{< /alert >}}

要启用或禁用 OmniAuth 提供者：

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 常规。
3. 展开 登录限制。
4. 在 启用的 OAuth 身份验证源 部分，选择或清除要启用或禁用的每个提供者的复选框。

禁用 OmniAuth

OmniAuth 默认启用。但是，OmniAuth 仅在提供者配置并 启用 时才有效。

如果 OmniAuth 提供者即使在单独禁用时也导致问题，您可以通过修改配置文件禁用整个 OmniAuth 子系统。

{{< tabs >}}

{{< tab title=”Linux package (Omnibus)” >}}

gitlab_rails['omniauth_enabled'] = false

{{< /tab >}}

{{< tab title=”Self-compiled (source)” >}}

omniauth:
  enabled: false

{{< /tab >}}

{{< /tabs >}}

将现有用户链接到 OmniAuth 用户

如果他们的电子邮件地址匹配，您可以自动链接 OmniAuth 用户和现有的极狐GitLab 用户。

以下示例启用了对 OpenID Connect 提供者和 Google OAuth 提供者的自动链接。

{{< tabs >}}

{{< tab title=”Linux package (Omnibus)” >}}

gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "google_oauth2"]

{{< /tab >}}

{{< tab title=”Self-compiled (source)” >}}

omniauth:
  auto_link_user: ["openid_connect", "google_oauth2"]

{{< /tab >}}

{{< /tabs >}}

启用自动链接的方法适用于所有提供者（除了 SAML）。要为 SAML 启用自动链接，请参阅 SAML 设置说明。

创建外部提供者列表

您可以定义一个外部 OmniAuth 提供者列表。通过列出的提供者在极狐GitLab 上创建账户或登录的用户无法访问 内部项目，并被标记为 外部用户。

{{< alert type=”note” >}}

如果您从外部提供者列表中移除 OmniAuth 提供者，您必须手动更新使用此登录方法的用户，以便他们的账户升级为完整的内部账户。

{{< /alert >}}

{{< tabs >}}

{{< tab title=”Linux package (Omnibus)” >}}

gitlab_rails['omniauth_external_providers'] = ['saml', 'google_oauth2']

{{< /tab >}}

{{< tab title=”Self-compiled (source)” >}}

omniauth:
  external_providers: ['saml', 'google_oauth2']

{{< /tab >}}

{{< /tabs >}}

保持 OmniAuth 用户资料的最新

{{< history >}}

• 在极狐GitLab 17.9 中引入 job_title 和 organization 属性。

{{< /history >}}

{{< alert type=”note” >}}

某些提供者需要额外配置以同步这些属性。例如，SAML 提供者需要 映射个人资料属性。

{{< /alert >}}

您可以启用从选定的 OmniAuth 提供者同步个人资料。您可以同步以下用户属性的任意组合：

• name
• email
• job_title
• location
• organization

使用 LDAP 进行身份验证时，用户的姓名和电子邮件始终同步。

{{< tabs >}}

{{< tab title=”Linux package (Omnibus)” >}}

1. 编辑 /etc/gitlab/gitlab.rb：

   gitlab_rails['omniauth_sync_profile_from_provider'] = ['saml', 'google_oauth2']
   gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'job_title', 'location', 'organization']
   

2. 保存文件并重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

{{< /tab >}}

{{< tab title=”Helm chart (Kubernetes)” >}}

1. 导出 Helm 值：

   helm get values gitlab > values.yaml
   

2. 编辑 values.yaml：

   global:
     appConfig:
       omniauth:
         syncProfileFromProvider: ['saml', 'google_oauth2']
         syncProfileAttributes: ['name', 'email', 'job_title', 'location', 'organization']
   

3. 保存文件并应用新的值：

   helm upgrade -f values.yaml gitlab gitlab/gitlab
   

{{< /tab >}}

{{< tab title=”Docker” >}}

1. 编辑 docker-compose.yml：

   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           gitlab_rails['omniauth_sync_profile_from_provider'] = ['saml', 'google_oauth2']
           gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'job_title', 'location', 'organization']
   

2. 保存文件并重启极狐GitLab：

   docker compose up -d
   

{{< /tab >}}

{{< tab title=”Self-compiled (source)” >}}

1. 编辑 /home/git/gitlab/config/gitlab.yml：

   production: &base
     omniauth:
       sync_profile_from_provider: ['saml', 'google_oauth2']
       sync_profile_attributes: ['name', 'email', 'job_title', 'location', 'organization']
   

2. 保存文件并重启极狐GitLab：

   # 对于运行 systemd 的系统
   sudo systemctl restart gitlab.target
   
   # 对于运行 SysV init 的系统
   sudo service gitlab restart
   

{{< /tab >}}

{{< /tabs >}}

绕过双因素认证

对于某些 OmniAuth 提供者，用户可以在不使用双因素认证 (2FA) 的情况下登录。

要绕过 2FA，您可以：

• 使用数组定义允许的提供者（例如 ['saml', 'google_oauth2']）。
• 指定 true 以允许所有提供者，或 false 以不允许任何提供者。

此选项应仅为已经具有 2FA 的提供者配置。默认值为 false。

此配置不适用于 SAML。

{{< tabs >}}

{{< tab title=”Linux package (Omnibus)” >}}

gitlab_rails['omniauth_allow_bypass_two_factor'] = ['saml', 'google_oauth2']

{{< /tab >}}

{{< tab title=”Self-compiled (source)” >}}

omniauth:
  allow_bypass_two_factor: ['saml', 'google_oauth2']

{{< /tab >}}

{{< /tabs >}}

自动使用提供者登录

您可以将 auto_sign_in_with_provider 设置添加到您的极狐GitLab 配置中，以将登录请求重定向到您的 OmniAuth 提供者进行身份验证。这消除了在登录前选择提供者的需要。

例如，要启用 Azure v2 集成 的自动登录：

{{< tabs >}}

{{< tab title=”Linux package (Omnibus)” >}}

gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2'

{{< /tab >}}

{{< tab title=”Self-compiled (source)” >}}

omniauth:
  auto_sign_in_with_provider: azure_activedirectory_v2

{{< /tab >}}

{{< /tabs >}}

请记住，每次登录尝试都会重定向到 OmniAuth 提供者，因此您无法使用本地凭据登录。确保至少有一个 OmniAuth 用户是管理员。

您还可以通过浏览器访问 https://gitlab.example.com/users/sign_in?auto_sign_in=false 来绕过自动登录。

使用自定义 OmniAuth 提供者图标

大多数支持的提供者都包含用于渲染登录按钮的内置图标。

要使用自己的图标，请确保您的图片经过优化以在 64 x 64 像素下渲染，然后通过以下两种方式之一覆盖图标：

• 提供自定义图片路径：

  1. 如果您在极狐GitLab 服务器域之外托管图片，请确保您的 内容安全策略 已配置为允许访问图片文件。
  2. 根据您安装极狐GitLab 的方法，将自定义 icon 参数添加到您的极狐GitLab 配置文件中。阅读 OpenID Connect OmniAuth 提供者 示例以了解 OpenID Connect 提供者的示例。

• 直接在配置文件中嵌入图片：此示例创建您可以通过 Data URL 提供的图片的 Base64 编码版本：

  1. 使用 GNU base64 命令（例如 base64 -w 0 <logo.png>）对您的图片文件进行编码，该命令返回单行的 <base64-data> 字符串。

  2. 将 Base64 编码的数据添加到您的极狐GitLab 配置文件中的自定义 icon 参数中：

     omniauth:
       providers:
         - { name: '...'
             icon: 'data:image/png;base64,<base64-data>'
             # 为了可读性删除了其他参数
           }
     

更改应用程序或配置

由于极狐GitLab 中的 OAuth 不支持将相同的外部身份验证和授权提供者设置为多个提供者，因此如果提供者或应用程序发生更改，极狐GitLab 配置和用户标识必须同时更新。 例如，您可以设置 saml 和 azure_activedirectory_v2，但不能在同一配置中添加第二个 azure_activedirectory_v2。

这些说明适用于极狐GitLab 存储 extern_uid 的所有身份验证方法，并且它是用户身份验证使用的唯一数据。

在提供者内更改应用程序时，如果用户的 extern_uid 不变，则只需更新极狐GitLab 配置。

要交换配置：

1. 在您的 gitlab.rb 文件中更改提供者配置。
2. 更新在极狐GitLab 中拥有前一个提供者身份的所有用户的 extern_uid。

要查找 extern_uid，请查看现有用户的当前 extern_uid，以获取与您当前提供者中相同用户的适当字段匹配的 ID。

有两种方法可以更新 extern_uid：

• 使用 用户 API。传递提供者名称和新的 extern_uid。

• 使用 Rails 控制台：

  Identity.where(extern_uid: 'old-id').update!(extern_uid: 'new-id')
  

已知问题

大多数支持的 OmniAuth 提供者不支持通过 HTTP 密码进行 Git 身份验证。作为一种解决方法，您可以使用 个人访问令牌 进行身份验证。