OmniAuth

用户可以使用 Google、GitHub 等流行服务的凭据登录 GitLab。 OmniAuth 是 GitLab 用于提供此身份认证的 Rack 框架。

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

支持的提供商

GitLab 支持以下 OmniAuth 提供商。

配置通用设置

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

配置初始设置

要更改 OmniAuth 设置：

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

每提供商配置

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

• username。
• nickname。
• email。

您可以按提供商创建 GitLab 配置，通过 args 提供给 提供商。如果您为提供商在 args 中设置 gitlab_username_claim 变量，可以选择其他声明用于 GitLab 用户名。所选声明必须唯一以避免冲突。

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"
  },
]

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

通过 OmniAuth 创建用户的密码

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

为现有用户启用 OmniAuth

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

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 子系统。

gitlab_rails['omniauth_enabled'] = false

omniauth:
  enabled: false

将现有用户链接到 OmniAuth 用户

如果用户邮箱匹配，您可以将 OmniAuth 用户自动链接到现有 GitLab 用户。

以下示例为 OpenID Connect 提供商和 Google OAuth 提供商启用自动链接。

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

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

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

创建外部提供商列表

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

要定义外部提供商列表，请使用提供商的全名， 例如 Google 的 google_oauth2。提供商名称请参阅 支持的提供商表格 中的 OmniAuth 提供商名称 列。

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

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。

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

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

使用提供商自动登录

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

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

gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2'

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 提供商的示例。

• 直接在配置文件中嵌入图像：此示例创建您图像的 Base64 编码版本，您可以通过 Data 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 配置。

要交换配置：

1. 在您的 gitlab.rb 文件中更改提供商配置。
2. 为在 GitLab 中具有旧提供商身份的所有用户更新 extern_uid。

要查找 extern_uid，请查看现有用户的当前 extern_uid，查找与您当前提供商中同一用户相应字段匹配的 ID。

更新 extern_uid 有两种方法：

• 使用 Users API。传递提供商名称和新的 extern_uid。

• 使用 Rails 控制台：

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

已知问题

大多数支持的 OmniAuth 提供商不支持 Git over HTTP 密码身份验证。 作为替代方案，您可以使用 个人访问令牌 进行身份验证。