OmniAuth

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

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

支持的提供者#

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

配置通用设置#

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

配置初始设置#

要更改 OmniAuth 设置：

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

每个提供者的配置#

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

• username。
• nickname。
• email。

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

ruby
复制
1gitlab_rails['omniauth_providers'] = [
2
3  # 使用名称 PROVIDER_NAME 配置提供者的通用模式
4
5  gitlab_rails['omniauth_providers'] = {
6    name: "PROVIDER_NAME"
7    ...
8    args: { gitlab_username_claim: 'sub' } # 对于使用您配置的提供者登录的用户，极狐GitLab 用户名将设置为从提供者收到的 "sub"
9  },
10
11  # 这里是使用 GitHub 和 Kerberos 的示例
12
13  gitlab_rails['omniauth_providers'] = {
14    name: "github"
15    ...
16    args: { gitlab_username_claim: 'name' } # 对于使用 GitHub 登录的用户，极狐GitLab 用户名将设置为从 GitHub 收到的 "name"
17  },
18  {
19    name: "kerberos"
20    ...
21    args: { gitlab_username_claim: 'uid' } # 对于使用 Kerberos 登录的用户，极狐GitLab 用户名将设置为从 Kerberos 收到的 "uid"
22  },
23]

yaml
复制
1- { name: 'PROVIDER_NAME',
2  # ...
3  args: { gitlab_username_claim: 'sub' }
4}
5- { name: 'github',
6  # ...
7  args: { gitlab_username_claim: 'name' }
8}
9- { name: 'kerberos',
10  # ...
11  args: { gitlab_username_claim: 'uid' }
12}

通过 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 提供者的登录。

要启用或禁用 OmniAuth 提供者：

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

禁用 OmniAuth#

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

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

ruby
复制
gitlab_rails['omniauth_enabled'] = false

yaml
复制
omniauth:
  enabled: false

将现有用户链接到 OmniAuth 用户#

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

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

ruby
复制
gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "google_oauth2"]

yaml
复制
omniauth:
  auto_link_user: ["openid_connect", "google_oauth2"]

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

创建外部提供者列表#

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

ruby
复制
gitlab_rails['omniauth_external_providers'] = ['saml', 'google_oauth2']

yaml
复制
omniauth:
  external_providers: ['saml', 'google_oauth2']

保持 OmniAuth 用户资料的最新#

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

• name
• email
• job_title
• location
• organization

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

绕过双因素认证#

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

要绕过 2FA，您可以：

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

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

此配置不适用于 SAML。

ruby
复制
gitlab_rails['omniauth_allow_bypass_two_factor'] = ['saml', 'google_oauth2']

yaml
复制
omniauth:
  allow_bypass_two_factor: ['saml', 'google_oauth2']

自动使用提供者登录#

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

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

ruby
复制
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2'

yaml
复制
omniauth:
  auto_sign_in_with_provider: azure_activedirectory_v2

请记住，每次登录尝试都会重定向到 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 参数中：

     yaml
     复制
     1omniauth:
     2  providers:
     3    - { name: '...'
     4        icon: 'data:image/png;base64,<base64-data>'
     5        # 为了可读性删除了其他参数
     6      }

更改应用程序或配置#

由于极狐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 控制台：

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

已知问题#

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