支持的提供商
配置通用设置
配置初始化设置
- 每个提供商的配置
- 通过 OmniAuth 创建的用户密码
为现有用户启用 OmniAuth
在不禁用导入源的情况下启用或禁用 OmniAuth 提供商登录
禁用 OmniAuth
将现有用户关联到 OmniAuth 用户
创建外部提供商列表
保持 OmniAuth 用户个人资料为最新
绕过双重身份验证
自动使用提供商登录
使用自定义 OmniAuth 提供商图标
更改应用程序或配置
已知问题

OmniAuth

用户可以使用他们的 GitHub、钉钉、GitLab 等主流服务的凭据来登录极狐GitLab。OmniAuth是极狐GitLab 用来提供这种身份认证的 Rack 框架。

当配置后，额外的登录选项就会在登录页面上展示出来。 <!– GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and other popular services. OmniAuth is a “generalized Rack framework for multiple-provider authentication” built on Ruby.

Configuring OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) from continuing to work. Users can choose to sign in using any of the configured mechanisms.

Initial OmniAuth Configuration
Supported Providers
Enable OmniAuth for an Existing User
OmniAuth configuration sample when using Omnibus GitLab
Enable or disable Sign In with an OmniAuth provider without disabling import sources –>

支持的提供商

极狐GitLab 支持一下 OmniAuth 提供商。

提供商	OmniAuth 提供商名称
AliCloud	`alicloud`
Atlassian	`atlassian_oauth2`
Auth0	`auth0`
Bitbucket Cloud	`bitbucket`
Generic OAuth 2.0	`oauth2_generic`
GitHub	`github`
GitLab.com	`gitlab`
JWT	`jwt`
Kerberos	`kerberos`
OpenID Connect	`openid_connect`
SAML	`saml`

配置通用设置

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

| 选项 | 描述 | | —— | ———– | | allow_bypass_two_factor | 允许用户使用没有双因素认证的特定提供商进行登录。可设为 true、false 或提供商数组。更多详情可查看绕过双因素认证。 | | allow_single_sign_on | 启用当用 OmniAuth 登录时自动创建账号功能。可设为 true、false 或提供商数组。提供商名称可查看支持的提供商表格。当为 false 时，使用没有极狐GitLab 账号的 OmniAuth 提供商进行登录时不被允许的。您必须先创建一个极狐GitLab 账号，然后通过您的个人资料设置链接到您的 OmniAuth 提供商。| | auto_link_ldap_user | 在极狐GitLab 为通过 OmniAuth 提供商创建的用户创建 LDAP 身份。要开启此设置，您必须开启了 LDAP 集成。LDAP 和 OmniAuth 提供商中的 uid 必须保持一致。 | | auto_link_saml_user | 如果邮箱匹配的话，允许通过 SAML 提供商的用户认证被自动连接到当前的极狐GitLab 账号上。要开启此设置，您必须开启 SAML 集成。 | | auto_link_user | 如果邮箱匹配的话，允许通过 OmniAuth 提供商的用户认证被自动连接到当前的极狐GitLab 账号上。可设为 true、false 或提供商数组。提供商名称可查看支持的提供商表格。 | | auto_sign_in_with_provider | 允许用户使用单个提供商名称自动登录。这必须要和提供商名称相匹配，比如 saml。为了防止出现无限登录循环，用户必须在登出极狐GitLab 之前登出他们的身份识别提供商。当前正在进行的功能增强包括SAML，以实现对支持的OmniAuth提供商的联合注销。 | | block_auto_created_users | 将自动创建的用户放置在等待审核状态（此时无法登陆），直到管理员批准。当为 false 时，请确定您定义了自己能够掌控的提供商，比如 true 时，默认会阻止自动创建的用户，而且在他们能够登录之前，必须由管理员来解除对他们的阻止。 | | enabled | 启用或禁用极狐GitLab OmniAuth 的使用。当为 false 时，OmniAuth 提供商按钮在用户界面上是不可见的。| | external_providers | 能够让您来定义您想让哪个 OmniAuth 提供商成为 external，以便让所有用户都能够创建账号、或者通过这些提供商来登录这些事情都不能够访问内部项目。您必须使用提供商的完整名称，更多详情可以查看创建一个外部提供商列表。 | | providers | 在支持的提供商表格中可用的提供商名称。 | | sync_profile_attributes |当登录的时候从提供商同步的个人资料属性列表。更多详情可查看保持 OmniAuth 用户个人资料为最新。| | sync_profile_from_provider |极狐GitLab 自动同步个人资料信息的提供商名称列表。条目必须要和提供者的名称相匹配，诸如 saml。更多详情可查阅保持 OmniAuth 用户个人资料为最新。|

配置初始化设置

要更改 OmniAuth 设置：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

# CAUTION!
# This allows users to sign in without having a user account first. Define the allowed providers
# using an array, for example, ["saml", "google_oauth2"], or as true/false to allow all providers or none.
# User accounts will be created automatically when authentication was successful.
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

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

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

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

更多详情可查看全局文档。

保存文件并应用新的 values：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 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

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

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

## OmniAuth settings
omniauth:
  # Allow sign-in by using Google, GitLab, etc. using OmniAuth providers
  # Versions prior to 11.4 require this to be set to true
  # enabled: true

  # CAUTION!
  # This allows users to sign in without having a user account first. Define the allowed providers
  # using an array, for example, ["saml", "google_oauth2"], or as true/false to allow all providers or none.
  # User accounts will be created automatically when authentication was successful.
  allow_single_sign_on: ["saml", "google_oauth2"]

  auto_link_ldap_user: true

  # Locks down those users until they have been cleared by the admin (default: true).
  block_auto_created_users: true

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

当完成这些设置后，您可以配置您选择的提供商。

每个提供商的配置

引入于 15.3 版本。

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

username
nickname
email

您可以在每个提供商的基础上创建极狐GitLab 配置，使用 args 将其提供给提供商。如果您在 args 中为提供商设置 gitlab_username_claim 变量，您可以选择另一个声明用于极狐GitLab 用户名。所选择的声明必须是唯一的，以避免冲突。

::Tabs

:::TabTitle Linux package (Omnibus)

gitlab_rails['omniauth_providers'] = [

  # The generic pattern for configuring a provider with name PROVIDER_NAME

  gitlab_rails['omniauth_providers'] = {
    name: "PROVIDER_NAME"
    ...
    args: { gitlab_username_claim: 'sub' } # For users signing in with the provider you configure, the GitLab username will be set to the "sub" received from the provider
  },

  # Here are examples using GitHub and Kerberos

  gitlab_rails['omniauth_providers'] = {
    name: "github"
    ...
    args: { gitlab_username_claim: 'name' } # For users signing in with GitHub, the GitLab username will be set to the "name" received from GitHub
  },
  {
    name: "kerberos"
    ...
    args: { gitlab_username_claim: 'uid' } # For users signing in with Kerberos, the GitLab username will be set to the "uid" received from Kerberos
  },
]

:::TabTitle 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' }
}

::EndTabs

通过 OmniAuth 创建的用户密码

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

为现有用户启用 OmniAuth

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

使用您的极狐GitLab 凭据、LDAP 或其他 OmniAuth 提供商登录极狐GitLab。
在左侧边栏的右上角，选择您的头像。
选择 编辑个人资料。
在左侧边栏中，选择账户。
在 关联账户 部分，选择 OmniAuth 提供商。
您被重定向到提供商。授权极狐GitLab 后，您将被重定向回极狐GitLab。

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

在不禁用导入源的情况下启用或禁用 OmniAuth 提供商登录

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

默认情况下，为 config/gitlab.yml 中配置的所有 OAuth provider 启用登录。

要启用或禁用 OmniAuth provider：

在左侧导航栏底部，选择 管理员。
在左侧边栏中，选择设置。
展开 登录限制。
在 启用 OAuth 身份验证源 部分，选中或清除您要启用或禁用的每个 provider 的复选框。

禁用 OmniAuth

默认情况下启用 OmniAuth。但是，OmniAuth 仅在提供商已配置且启用时才有效。

如果 OmniAuth 提供商在单独禁用时仍导致问题，您可以通过修改配置文件来禁用整个 OmniAuth 子系统：

::Tabs

:::TabTitle Linux package (Omnibus)

gitlab_rails['omniauth_enabled'] = false

:::TabTitle Self-compiled (source)

omniauth:
  enabled: false

::EndTabs

将现有用户关联到 OmniAuth 用户

引入于 13.4 版本。

如果电子邮件地址匹配，您可以自动将 OmniAuth 用户与现有的极狐GitLab 用户关联起来。

以下示例为 OpenID Connect 提供商和 Twitter OAuth 提供商启用自动关联。

::Tabs

:::TabTitle Linux package (Omnibus)

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

:::TabTitle Self-compiled (source)

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

::EndTabs

这种启用自动关联的方法适用于除 SAML 之外的所有提供商。要为 SAML 启用自动链接，请参阅 SAML 设置说明。

创建外部提供商列表

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

要定义外部提供商列表，请使用提供商的全名。有关提供商名称，请参阅支持的提供商列表中的 OmniAuth 提供商名称列。

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

::Tabs

:::TabTitle Linux package (Omnibus)

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

:::TabTitle Self-compiled (source)

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

保持 OmniAuth 用户个人资料为最新

您可以从选定的 OmniAuth 提供商启用配置文件同步。您可以同步以下任何信息的组合体：

name
email
location

当使用 LDAP 进行身份认证，用户名和电子邮件是始终同步的。

::Tabs

:::TabTitle Linux package (Omnibus)

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

:::TabTitle Self-compiled (source)

omniauth:
  sync_profile_from_provider: ['saml', 'google_oauth2']
  sync_profile_attributes: ['email', 'location']

::EndTabs

绕过双重身份验证

通过某些 OmniAuth 提供商，用户可以在不使用双重身份验证 (2FA) 的情况下登录。

由于一个已知问题，用户必须在他们的极狐GitLab 账户上设置 2FA 来绕过 2FA。否则，系统会提示他们在登录极狐GitLab 时设置 2FA。

要绕过 2FA，您可以：

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

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

此配置不适用于 SAML。

Omnibus 安装实例

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

源安装实例

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

::Tabs

:::TabTitle Linux package (Omnibus)

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

:::TabTitle Self-compiled (source)

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

::EndTabs

自动使用提供商登录

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

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

::Tabs

:::TabTitle Linux package (Omnibus)

gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2'

:::TabTitle Self-compiled (source)

omniauth:
  auto_sign_in_with_provider: azure_activedirectory_v2

::EndTabs

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

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

使用自定义 OmniAuth 提供商图标

大多数受支持的提供商都包含一个用于呈现登录按钮的内置图标。

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

提供自定义图像路径：
1. 如果您在极狐GitLab 服务器域之外托管图像，请确保您的内容安全策略配置为允许访问图像文件。
2. 根据您安装极狐GitLab 的方法，将自定义 icon 参数添加到极狐GitLab 配置文件中。
直接在配置文件中嵌入图像：此示例创建图像的 Base64 编码版本，您可以通过数据 URL 提供服务：
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 配置。

交换配置：

更改 gitlab.rb 文件中的提供商配置。
为所有在极狐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 提供商不支持 Git over HTTP 密码身份验证。作为解决方法，您可以使用个人访问令牌进行身份验证。