Keycloak 身份验证模块
Keycloak 身份验证模块是一个预配置的 OAuth2.0 身份验证模块，允许用户使用他们的 Keycloak 凭据登录 Hub 以及任何连接的服务。
启用 Keycloak 身份验证
要允许已有 Keycloak 账户的用户登录 Hub，请启用身份验证模块。
此过程分为三个步骤：
创建 Keycloak 身份验证模块。 当您创建身份验证模块时，Hub 会生成一个重定向 URI，用于授权服务。 此 URI 用于标识每次登录请求的来源。
在 Keycloak 中生成客户端 ID 和 密钥。 从 Hub 发送的每个登录请求都包含唯一标识符。 您在身份验证模块中存储的 ID 和密钥会告知 Keycloak 授权服务每个登录请求已授权。
在 Hub 中启用身份验证模块。 在您生成了 Hub 用于与 Keycloak 授权服务进行身份验证的信息后，将这些值复制到 Hub 并启用该模块。
在 Hub 中创建 Keycloak 身份验证模块
首先，创建 Keycloak 身份验证模块。 执行该操作时，Hub 会生成一个用于授权服务的重定向 URI。
要创建 Keycloak 身份验证模块：
在 Access Management (权限管理) 部分的 Administration (行政) 菜单中，选择 。
点击 New module (新模块) 按钮。
Select an identity provider (选择身份提供商) 对话框将打开。
在 Select an identity provider (选择身份提供商) 对话框中，选择 Keycloak。
New Keycloak Auth Module (新 Keycloak 验证模块) 对话框将打开。
在 New Keycloak Auth Module (新 Keycloak 验证模块) 对话框中，为以下设置输入值：
设置
描述
Keycloak 根 URL
输入 Keycloak 服务器的根 URL。
Keycloak 域
输入用于管理您希望允许访问 Hub 的用户账户的 Keycloak 域名称。
点击 Create (创建) 按钮。
Auth Modules (身份验证模块) 页面展示了新 Keycloak 身份验证模块的设置。
Hub 会为您生成一个可在授权服务中使用的重定向 URI。
生成客户端 ID 和 密钥
下一步是从 Keycloak 获取客户端 ID 和密钥。
使用您的管理员账户登录管理控制台。
从列表中选择您的域。
在 Configure (配置) 菜单中，选择 Clients (客户端)。
点击 Create (创建) 按钮。
Add Client (添加客户端) 对话框打开。
为以下设置输入值：
对于 Client ID (客户端 ID) ，请输入便于识别客户端应用的值。
对于 Client Protocol (客户端协议) ，请选择 openid-connect (openid-连接)。
对于 Root URL (根 URL) ，请输入 Hub 安装的基础 URL。
点击 Save (保存) 按钮。
新客户端应用设置页面已打开。
在客户端应用的 Settings (设置) 选项卡，将 Access Type (访问类型) 更改为 confidential (机密)。
点击 Save (保存) 按钮。
使用作为 Client ID (客户端 ID) 保存的值来在 Hub 中启用身份验证模块。
选择 Credentials (凭据) 选项卡，然后使用作为 Secret (私密) 保存的值在 Hub 中启用身份验证模块。
如需获取更多信息，请参阅 Keycloak 文档。
在 Hub 中启用身份验证模块
要完成设置，请将授权服务中的客户端 ID 和密钥存储到 Keycloak 身份验证模块中。
将 Client ID (客户端 ID) 从 Keycloak 的 Settings (设置) 选项卡复制并粘贴到 Hub 的 Client ID (客户端 ID) 输入框中。
将 Secret (私密) 从 Keycloak 的 Credentials (凭据) 选项卡复制并粘贴到 Hub 的 Client secret (客户端密钥) 输入框中。
配置身份验证模块的可选设置。 如需详细信息，请参阅 其他设置。
点击 Save (保存) 按钮以应用设置。
点击 Enable module (启用模块) 按钮。
Keycloak 身份验证模块已启用。
存储在 Button image (按钮图像) 设置中的图标会添加到登录对话窗口。 用户可以点击该图标，使用 Keycloak 凭据登录 Hub。
测试连接
要验证 Keycloak 身份验证模块是否设置正确，请测试连接。
点击标题中的 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 交换访问令牌，请参阅 扩展授权。 |
授权服务端点
该部分页面的设置存储 Keycloak 使用的 OAuth 2.0 端点。
对于预配置的 OAuth 2.0 模块，所选授权服务所用值会自动设置。
设置 | 描述 |
|---|---|
验证 | 存储 Hub 通过用户代理重定向从资源拥有者获取授权的端点。 |
令牌 | 存储 Hub 用于将授权码换取访问令牌的端点。 |
用户数据 | 存储用于定位已认证用户的个人资料数据的端点。 |
电子邮件 | 存储用于定位已认证用户电子邮件地址的端点。 仅当电子邮件地址未存储在用户资料中时使用。 |
头像 | 存储用于定位被用作已认证用户头像的二进制文件的端点。 仅当头像未直接存储在用户资料中时使用。 |
字段映射
当 Keycloak 返回用户个人资料响应对象时，从指定字段路径获取的值会复制到 Hub 的用户资料中。 可使用以下设置来定义定位已认证用户个人资料数据的端点，并将授权服务中存储的字段映射到 Hub 用户账户。
对于预定义的 Keycloak 模块， User ID (用户 ID)、 Email (电子邮箱)、 Email verification state (电子邮件验证状态)、 Full name (全名) 和 Groups (分组) 会自动设置。 如果需要修改这些值以满足需求，您可以覆盖它们。
要指定嵌套对象内的字段路径，请输入由斜杠字符（
/）分隔的段序列。要引用可能存储在多个位置的值，请使用 "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 中的相应组进行映射和同步。 有关详细信息，请参阅 群组映射。 |
其他设置
以下选项位于页面底部。 这些设置允许您定义请求范围并选择与服务的身份验证方式。
对于预定义的 Keycloak 模块， Scope (作用域) 会自动设置。 如果需要修改此值以满足需求，您可以覆盖它。
本节的其他选项允许您管理 Hub 账户创建和组成员关系，并减少因空闲连接消耗的处理资源损失。
选项 | 描述 |
|---|---|
作用域 | 为访问请求设置范围。 输入以空格分隔的范围列表。 |
身份验证 | 确定凭据如何传递给授权服务。 |
用户创建 | 启用对未注册用户使用连接的授权服务账户登录时在 Hub 中创建账户。Hub 会通过电子邮件地址判断用户是否已有账户。 Hub 会通过电子邮件地址判断用户是否已有账户。 |
自动验证电子邮件 | 当身份验证服务未返回该属性值时，决定 Hub 如何设置电子邮件地址的验证状态。 |
自动加入组 | 当用户使用连接的授权服务账户登录时，将其添加到组。 您可以选择一个或多个组。 自动加入组的新用户，将继承该组的所有权限。 建议您将用户至少添加到一个组。 否则，新用户只会获得当前分配给 All Users (所有用户) 组的权限。 |
连接超时 | 设置与授权服务建立连接的等待时间。 默认设置为 5000 毫秒（5 秒）。 |
读取超时 | 设置等待从授权服务读取和获取用户资料数据的时间。 默认设置为 5000 毫秒（5 秒）。 |
审核 | 链接至 Hub 中的 Audit Events (审核事件) 页面。 在那里，您可以查看已应用于此身份验证模块的变更列表。 |
群组映射
在 Group Mappings (群组映射) 选项卡中，您可以将授权服务中的现有用户组映射到 Hub 中的用户组。
如果您想将 Keycloak 中的用户组映射到 Hub 中的用户组，您需要在此身份验证模块的 Field Mapping (字段映射) 配置部分指定存储 Keycloak 用户组成员资格的 Groups (分组) 属性。 对于预定义的 Keycloak 模块， Groups (分组) 属性和 Scope (作用域) 会被自动设置。
配置用户组映射后，用户使用目录服务中管理的帐户登录时，Hub 会检查其 Keycloak 用户组成员资格。 对于每个已映射到 Hub 用户组的 Keycloak 用户组，Hub 会执行以下操作：
属于已映射 Keycloak 用户组但不属于已映射 Hub 用户组的用户会被添加到 Hub 中的用户组。
不属于已映射 Keycloak 用户组但属于已映射 Hub 用户组的用户会从 Hub 的该用户组中移除。
授权服务中用户组成员资格的变更，仅在用户使用他们的 Keycloak 帐户登录 Hub 时才会生效。
您可以将多个 Keycloak 用户组映射到 Hub 的同一个目标用户组。 您不能将 Keycloak 用户组映射到多个 Hub 用户组。
要将 Keycloak 的组映射到 Hub 的组：
打开您的 Keycloak 身份验证模块。
选择 Group Mappings (群组映射) 选项卡。
点击 Add mapping (添加映射) 按钮。
Add Mapping (添加映射) 对话框将打开。
在 OAuth group name (OAuth 组名) 字段中输入 Keycloak 用户组的名称。
从 Target group (目标组) 列表中选择一个用户组。
点击 Add (添加) 按钮。
映射会被添加到列表中。
操作
页眉中可用以下操作：
操作 | 描述 |
|---|---|
设为默认 | 将该身份验证模块指定为您的安装默认模块。 同一时间只能有一个身份验证模块被设为默认。 如果另一个模块当前被设为默认状态，该状态会被清除。 仅当当前身份验证模块未被设为默认时才显示此选项。 |
清除默认 | 将该身份验证模块从您的安装默认模块中移除。 如果所有可用身份验证模块都未设置为默认，未认证用户将始终跳转至 Hub 登录页面。 仅当当前身份验证模块已被设为默认时才显示此选项。 |
禁用模块 | 禁用该身份验证模块。 仅在身份验证模块已启用时显示此选项。 |
启用模块 | 启用该身份验证模块。 仅在身份验证模块已禁用时显示此选项。 |
测试登录 | 允许您测试与身份验证服务的连接。 |
删除模块 | 将身份验证模块从 Hub 移除。 仅在您已配置了允许用户登录 Hub 的其他身份验证模块时使用。 |