- 支持的提供商
- 初始化配置
- 为现有用户启用 OmniAuth
- 在不禁用导入源的情况下启用或禁用 OmniAuth 提供商登录
- 禁用 OmniAuth
- 将现有用户关联到 OmniAuth 用户
- 创建外部提供商列表
- 使用自定义 OmniAuth 提供商
- 使 OmniAuth 用户配置文件保持最新
- 绕过双重身份验证
- 自动使用提供商登录
- 使用自定义 OmniAuth 提供商图标
- 更改应用程序或配置
- 限制
OmniAuth
支持的提供商
这是当前支持的 OmniAuth 提供商的列表。在继续阅读每个提供商的文档之前,请务必先阅读本文档,因为它包含所有提供商通用的一些设置。
提供商 | OmniAuth 提供商名称 |
---|---|
Alicloud | alicloud
|
Bitbucket Cloud | bitbucket
|
DingTalk | dingtalk
|
GitHub | github
|
GitLab.com | gitlab
|
SAML | saml
|
初始化配置
在配置 OmniAuth provider 之前,请配置所有提供商通用的设置。
设置 | 描述 | 默认值 |
---|---|---|
allow_single_sign_on
| 使您能够列出自动创建极狐GitLab 帐户的提供程序。提供者名称在支持的提供商列表的 OmniAuth 提供商名称 列中可用。 | 默认值为false 。 如果为false ,则必须手动创建用户,否则他们无法使用 OmniAuth 登录。
|
auto_link_ldap_user
| 如果启用,则在极狐GitLab 中为通过 OmniAuth 提供商创建的用户创建 LDAP 身份。如果您启用了 LDAP (ActiveDirectory) 集成,则可以启用此设置。 要求用户的 uid 在 LDAP 和 OmniAuth 提供商中都相同。
| 默认值为 false .
|
block_auto_created_users
| 如果启用,将阻止自动创建的用户登录,直到他们获得管理员批准。 | 默认值为 true 。如果您将该值设置为 false ,请确保只为您可以控制的 allow_single_sign_on 定义 provider。否则,互联网上的任何用户都可以在未经管理员批准的情况下登录极狐GitLab。
|
要更改这些设置:
-
对于 Omnibus 安装实例
-
打开配置文件:
sudo editor /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, ["github", "gitlab"], 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'] = ['github', 'gitlab'] gitlab_rails['omniauth_auto_link_ldap_user'] = true gitlab_rails['omniauth_block_auto_created_users'] = true
-
保存文件并重新配置极狐GitLab:
sudo gitlab-ctl reconfigure
-
-
对于 Helm Chart 实例
-
导出 Helm 值:
helm get values gitlab > gitlab_values.yaml
-
编辑
gitlab_values.yaml
,并更新globals.appConfig
下的omniauth
部分:global: appConfig: omniauth: enabled: true allowSingleSignOn: ['saml', 'twitter'] autoLinkLdapUser: false blockAutoCreatedUsers: true
获取更多信息,查看文档。
-
-
对于源安装实例
-
打开配置文件:
cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml
-
更新以下部分:
## OmniAuth settings omniauth: # Allow sign-in by using Twitter, Google, 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, ["github", "gitlab"], or as true/false to allow all providers or none. # User accounts will be created automatically when authentication was successful. allow_single_sign_on: ["github", "gitlab"] 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
-
配置完这些设置后,您可以配置您选择的提供商。
每个提供商的配置
引入于 15.3 版本。
如果设置了 allow_single_sign_on
,极狐GitLab 使用 OmniAuth 的 auth_hash
中返回的以下字段之一,在极狐GitLab 中为用户登录建立用户名,选择第一个存在的用户名:
username
nickname
email
您可以在每个提供商的基础上创建极狐GitLab 配置,使用 args
将其提供给提供商。如果您在 args
中为提供商设置 gitlab_username_claim
变量,您可以选择另一个声明用于极狐GitLab 用户名。所选择的声明必须是唯一的,以避免冲突。
-
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 }, ]
-
源安装实例
- { 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 登录,则可以启用 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 子系统:
-
Omnibus 安装实例
gitlab_rails['omniauth_enabled'] = false
-
源安装实例
omniauth: enabled: false
将现有用户关联到 OmniAuth 用户
引入于 13.4 版本。
如果电子邮件地址匹配,您可以自动将 OmniAuth 用户与现有的极狐GitLab 用户关联起来。
以下示例为 OpenID Connect 提供商和 Twitter OAuth 提供商启用自动关联。
-
Omnibus 安装实例
gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "twitter"]
-
源安装实例
omniauth: auto_link_user: ["openid_connect", "twitter"]
这种启用自动关联的方法适用于除 SAML 之外的所有提供商。 要为 SAML 启用自动链接,请参阅 SAML 设置说明。
创建外部提供商列表
您可以定义一个外部 OmniAuth 提供商列表。 通过列出的提供商创建帐户或登录极狐GitLab 的用户,无法访问内部项目。
要定义外部提供商列表,请使用提供商的全名。有关提供商名称,请参阅支持的提供商列表中的 OmniAuth 提供商名称列。
-
Omnibus 安装实例
gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2']
-
源安装实例
omniauth: external_providers: ['twitter', 'google_oauth2']
使用自定义 OmniAuth 提供商
如果您必须与极狐GitLab 随附的 OmniAuth 提供商以外的身份验证解决方案集成,您可以使用自定义 OmniAuth 提供商。
以下步骤是通用的。阅读 OmniAuth 提供商的文档以了解具体的实施细节。
-
停止极狐GitLab:
sudo service gitlab stop
-
将 gem 添加到您的
Gemfile
:gem "omniauth-your-auth-provider"
-
安装新的 OmniAuth 提供商 gem:
sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment
这些命令与在初始安装期间安装 gems 的命令相同,使用
--path vendor/bundle --no-deployment
而不是--deployment
。 -
启动极狐GitLab:
sudo service gitlab start
使 OmniAuth 用户配置文件保持最新
您可以从选定的 OmniAuth 提供商启用配置文件同步。您可以同步所有或特定的用户信息。
使用 LDAP 进行身份验证时,用户名和电子邮件始终同步。
-
Omnibus 安装实例
gitlab_rails['omniauth_sync_profile_from_provider'] = ['twitter', 'google_oauth2'] gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'location']
-
源安装实例
omniauth: sync_profile_from_provider: ['twitter', 'google_oauth2'] sync_profile_attributes: ['email', 'location']
绕过双重身份验证
通过某些 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']
自动使用提供商登录
您可以将 auto_sign_in_with_provider
设置添加到您的极狐GitLab 配置中,将登录请求重定向到您的 OmniAuth 提供商,来进行身份验证。这样就无需在登录前选择提供商。
例如,为 Azure v2 集成启用自动登录:
-
Omnibus 安装实例
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 像素的渲染进行了优化,然后通过以下两种方式之一覆盖该图标:
-
提供自定义图像路径:
- 如果您在极狐GitLab 服务器域之外托管图像,请确保您的内容安全策略配置为允许访问图像文件。
- 根据您安装极狐GitLab 的方法,将自定义
icon
参数添加到极狐GitLab 配置文件中。
-
直接在配置文件中嵌入图像:此示例创建图像的 Base64 编码版本,您可以通过数据 URL 提供服务:
- 使用 GNU
base64
命令(例如base64 -w 0 <logo.png>
)对图像文件进行编码,该命令返回单行<base64-data>
字符串。 -
将 Base64 编码的数据添加到极狐GitLab 配置文件中的自定义
icon
参数:omniauth: providers: - { name: '...' icon: 'data:image/png;base64,<base64-data>' ... }
- 使用 GNU
更改应用程序或配置
由于极狐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 密码身份验证。 作为解决方法,您可以使用个人访问令牌进行身份验证。