GitLab 验证模块

GitLab 身份验证模块是一个预配置的 OAuth2.0 认证模块，允许用户使用 GitLab 凭据登录 Hub 及所有已连接的服务。

启用 GitLab 身份验证

为允许已在 GitLab 拥有帐户的用户登录 Hub，请启用认证模块。

此过程分为三个步骤：

在 Hub 中生成重定向 URI。当您创建认证模块时，Hub 会生成一个重定向 URI 以与授权服务一起使用。此 URI 用于识别每个登录请求的来源。
在 GitLab 中生成客户端 ID 和密钥。每个从 Hub 发送的登录请求都包含唯一标识符。您在认证模块中存储的 ID 和密钥会告知 GitLab 授权服务每个登录请求均已授权。
在 Hub 中启用认证模块。在您生成 Hub 用于与 GitLab 授权服务验证身份的信息后，将这些值复制到 Hub 并启用该模块。

在 Hub 中生成重定向 URI

首先，创建 GitLab 身份验证模块。执行此操作后，Hub 会生成一个重定向 URI 以与授权服务一起使用。

在 Access Management (权限管理) 部分的 Administration (行政) 菜单中，选择 Auth Modules (身份验证模块)。
点击 New module (新模块) 按钮。
- Select an identity provider (选择身份提供商) 对话框打开。
在 Select an identity provider (选择身份提供商) 对话框中，选择 GitLab。
- Auth Modules (身份验证模块) 页面显示新建 GitLab 认证模块的设置。
- Hub 会为您生成一个重定向 URI 以供授权服务使用。
如果您的浏览器支持此功能，可使用 Copy (复制) 按钮将重定向 URI 复制到剪贴板。

当您更改 Hub 实例的基本 URL 时，请确保在授权服务中更新重定向 URI。例如，更改代理设置后。

生成客户端 ID 和密钥

下一步是在 GitLab 中为 Hub 注册授权的重定向 URI。

登录到您的 GitLab 实例，并进入 Applications (应用程序) 管理区域。
在 Add new application (添加新应用程序) 表单中，为 Hub 服务输入名称，并将生成的重定向 URL 复制到 Redirect URI (重定向 URI) 字段。
在 Scopes (范围) 选项中，选择 api 和 read_user。
点击 Save application (保存应用程序) 按钮。
- GitLab 会生成您在 Hub 中用作 Client ID (客户端 ID) 和 Client secret (客户端密钥) 的值。

在 Hub 中启用认证模块

为完成配置，请将授权服务中的客户端 ID 和密钥存储到 GitLab 身份认证模块。

从 GitLab 复制 Application ID (应用程序 ID) ，并粘贴到 Hub 中的 Client ID (客户端 ID) 输入字段。
从 GitLab 复制 Secret (私密) ，并粘贴到 Hub 中的 Client secret (客户端密钥) 输入字段。
配置该身份认证模块的可选设置。如需详细信息，请参阅其他设置。
点击 Save (保存) 按钮以应用设置。
点击 Enable module (启用模块) 按钮。
- GitLab 身份认证模块已启用。
- 存储于 Button image (按钮图像) 设置中的图标会添加到登录对话窗口。用户可点击此图标，使用其 GitLab 凭据登录 Hub。

测试连接

要验证 GitLab 身份认证模块设置是否正确，请测试连接。

点击顶部的 Test login (测试登录) 按钮。这将在新浏览器标签页验证登录流程。

如果身份认证模块设置正确，则会显示成功消息。
如果连接有问题，身份认证服务会显示错误消息。请使用错误页面上提供的信息排查问题。

设置

设置页的首部分显示身份认证模块的一般设置。在此处，您还可以找到用于在授权服务中注册 Hub 的重定向 URI，以及用于存储在授权服务中生成的 Client ID (客户端 ID) 和 Client Secret (客户端密钥) 的输入字段。

设置	描述
类型	显示在 Hub 中启用于第三方认证的授权服务类型。
名称	存储身份认证模块的名称。使用此设置可将该模块与 Auth Modules (验证模块) 列表中的其他认证模块区分开。
按钮图像	显示用于用户点击按钮，通过连接的授权服务账号登录 Hub 所使用的图像。您可以上传 JPG、GIF 或 PNG 文件。图像会自动调整为 48 x 48 像素。
重定向 URI	显示用于在授权服务中注册连接到 Hub 的授权重定向 URI。
客户端 ID	存储授权服务用于验证登录请求的标识符。在配置 Web 应用的授权设置并输入授权重定向 URI 时，您需在授权服务中生成此值。
客户端密钥	存储用于验证客户端 ID 的密钥或密码。您需在授权服务中与客户端 ID 一同生成此值。
授权延期	保存用于扩展授权时标识身份认证模块的值。如果填写了该值，Hub 会处理来自授权服务的访问令牌互换请求，为其颁发访问 Hub 的令牌。要成功互换访问令牌，必须在第三方身份认证服务中授权且在 Hub 中启用身份认证模块。要学习如何使用 Hub REST API 交换访问令牌，请参阅扩展授权。

授权服务端点

本节页面的设置用于存储 GitLab 使用的 OAuth 2.0 端点。

对于预配置的 OAuth 2.0 模块，所选授权服务所用值会自动设置。

设置	描述
验证	存储 Hub 通过用户代理重定向从资源所有者取得授权所用的端点。
令牌	存储 Hub 用于将授权令牌换取访问令牌的端点。
用户数据	存储用于定位已认证用户个人资料数据的端点。
电子邮箱	存储用于定位已认证用户电子邮件地址的端点。仅当电子邮件地址未直接存储在用户个人资料中时使用。
头像	存储用于定位认证用户头像二进制文件的端点。仅当头像未直接存储在用户个人资料中时使用。

字段映射

当 GitLab 服务以对象响应返回用户资料时，指定字段路径中的值会被复制到 Hub 的用户资料中。请使用以下设置，定义用于定位已认证用户资料数据的端点，并将授权服务中存储的字段映射到 Hub 中的用户账户。

对于 GitLab 模块，值会自动设置。

要指定嵌套对象内字段的路径，请输入用斜杠（/ ）分隔的路径段序列。
如需引用可能存储在多个位置的值，可使用" Elvis 运算符"（?: ）作为多路径的分隔符。使用该选项时，Hub 会采用指定字段遇到的第一个非空值。

字段	描述
用户 ID	映射到存储要复制到 Hub 的 User ID (用户 ID) 属性的字段。
用户名	映射到存储要复制到 Hub 个人资料中 Username (用户名) 字段的值的字段。此选项适用于 Hub 2023.1.15453 及更高版本。
全名	映射到存储要复制到 Hub 个人资料中 Full name (全名) 字段的值的字段。
电子邮箱	映射到存储要复制到 Hub 个人资料中 Email (电子邮箱) 字段的值的字段。
电子邮件验证状态	映射到存储待复制至 Hub 已验证邮件属性的字段。
头像	映射到存储用作 Hub 个人资料中 Avatar (头像) 的图片字段。
图像 URL 模式	为以 ID 引用头像的情况生成头像图片 URL。请使用 <picture-id> 占位符引用存储头像的字段。
分组	映射到在连接的授权服务中存储组成员分配的属性。指定该值后，您可以将授权服务中的组成员身份与 Hub 中的对应组进行映射和同步。有关详细信息，请参阅群组映射。

其他设置

页面底部提供以下选项。这些设置允许您定义请求作用域，并选择如何与服务进行身份验证。

本节的其他选项允许您管理 Hub 账户创建、组成员关系，并降低闲置连接消耗的处理资源损失。

选项	描述
范围	设置访问请求的作用域。输入一个用空格分隔的作用域列表。
身份验证	确定如何将凭证传递到授权服务。
用户创建	启用为使用连接的授权服务账户登录的未注册用户创建 Hub 账户。 Hub 会通过电子邮件地址判断用户是否已有账户。
自动验证电子邮件	当身份认证服务未返回电子邮件验证状态时，确定 Hub 如何设置该属性的验证状态。
自动加入组	当用户使用存储在已连接授权服务中的账户登录时，自动将其添加到指定组。您可选择一个或多个组。新用户自动加入组后将继承该组的全部权限。建议您为用户至少添加一个组。否则，新用户只会被授予当前分配给 All Users (所有用户) 组的权限。
连接超时	设置等待与授权服务建立连接的时间。默认值为 5000 毫秒（5 秒）。
读取超时	设置从授权服务读取和获取用户个人资料数据的等待时间。默认值为 5000 毫秒（5 秒）。
审核	链接到 Hub 的 Audit Events (审核事件) 页面。在此可查看对此身份认证模块应用的更改列表。

群组映射

操作

页眉提供以下操作：

操作	描述
设为默认	将认证模块设为您的安装默认。任一时刻只能有一个认证模块为默认，如果有其它模块已为默认，该状态将被清除。任一时刻只能有一个认证模块被设置为默认。如果其它模块当前为默认状态，该状态将被清除。仅当当前认证模块未设为默认时，显示此选项。
清除默认	移除此身份认证模块的默认状态。如没有任何已用身份认证模块被设为默认，未认证用户将始终被引导到 Hub 登录页面。仅当当前认证模块设为默认时，显示此选项。
禁用模块	禁用身份认证模块。仅当身份认证模块当前已启用时，显示该选项。
启用模块	启用身份认证模块。仅当身份认证模块当前已禁用时，显示此选项。
测试登录	可测试与身份认证服务的连接。
删除模块	从 Hub 中移除身份认证模块。仅当您已配置其他可供用户登录 Hub 的身份认证模块时使用。

2026年 3月 16日