5.11. 定义用户配置集
在 Red Hat Single Sign-On 中,用户与一组属性关联。这些属性用于更好地描述和识别 Red Hat Single Sign-On 中的用户,以及传递给应用程序的附加信息。
用户配置集定义了一条明确的 schema,用于代表用户属性以及如何在域中管理。通过提供对用户信息的一致视图,管理员可以控制管理属性的不同方面,并更容易扩展红帽单点登录以支持附加属性。
除其他功能外,用户配置集使管理员能够:
- 为用户属性定义 schema
- 根据上下文信息(例如,仅要求用户或管理员)或同时定义属性是否需要属性,或根据所请求的范围。)
- 定义特定权限以查看和编辑用户属性,从而遵循强大的隐私要求,其中第三方(包括管理员)无法看到或更改某些属性。
- 动态强制实施用户配置集合规性,以便始终更新用户信息并与属性相关的元数据和规则
- 利用内置的验证器或编写自定义的验证规则,以每个attribute 为基础定义验证规则
- 根据属性定义,用户可以动态呈现与帐户控制台中的注册、更新配置文件、代理和个人信息等交互,而无需手动更改它们。
User Profile 功能由 User Profile SPI 支持。默认情况下,这些功能被禁用,域被配置为使用默认配置,以便向后兼容旧行为。
旧行为是在管理用户 root 属性(如用户名、电子邮件、第一和姓氏)时使用的默认限制,而不考虑如何管理自定义属性的任何限制。有关用户流(如注册、配置集更新、代理)并通过帐户控制台管理帐户,用户将限制为使用前所述属性来更改主题模板以支持附加属性。
如果您已经使用 Red Hat Single Sign-On,旧的行为是您目前正在使用的行为。
与传统行为不同,声明性提供程序为您提供了很多灵活性,以通过管理控制台和明确定义的 JSON 模式将用户配置文件配置定义为域。
在下一部分中,我们将了解如何使用声明性提供程序定义您自己的用户配置文件配置。
在未来,红帽单点登录将不再支持传统行为。理想情况下,您应该开始关注 User Profile 提供的新功能,并相应地迁移您的域。
5.11.1. 启用用户配置集 复制链接链接已复制到粘贴板!
声明性用户配置集 是技术预览,不被完全支持。此功能默认为禁用。
要使用 -Dkeycloak.profile=preview 或 -Dkeycloak.profile.feature.feature.declarative_user_profile=enabled 来启用 服务器。如需了解更多详细信息,请参阅 配置文件。
除了启用 declarative_user_profile 功能外,您应该为域启用用户配置文件。为此,可单击左侧菜单中的 Realm Settings 链接,再打开 User Profile Enabled switch。
启用并单击 Save 按钮后,您可以从中访问 User Profile 选项卡,从中可以管理用户属性的配置。
通过为域启用用户配置文件,Red Hat Single Sign-On 将会根据用户配置集配置来施加额外的限制如何管理属性。总之,以下列出了在启用该功能时应该期望的内容:
-
从管理的角度看,用户详情页面上的
Attributes选项卡将仅显示用户配置文件配置中定义的属性。根据每个属性定义的条件也会在管理属性时考虑。 - 用户面临的表单,如帐户控制台中的注册、更新配置文件、代理和个人信息,将根据用户配置文件配置动态呈现。为此,Red Hat Single Sign-On 将依赖于不同的模板来动态呈现这些表单。
在下一个主题中,我们将探索如何管理用户配置文件配置以及它对域的影响。
5.11.2. 管理用户配置集 复制链接链接已复制到粘贴板!
用户配置集配置以每个域为基础进行管理。为此,请单击左侧菜单上的 Realm Settings 链接,然后单击 User Profile 选项卡。
User Profile 选项卡
在 Attributes 子选项卡中,您有一个当前与用户配置文件关联的属性列表。默认情况下,配置基于用户 root 属性创建,每个属性在验证和权限方面都会配置一些默认值。
在 "属性 组"子选项卡中,您可以管理属性组。属性组允许您关联属性,以便在呈现用户面向形式时一起显示它们。
现在,属性组仅用于渲染目的,而在将来,它们还应启用与它们链接的属性定义的顶级配置。
在 JSON Editor 子选项卡中,您可以使用定义的 JSON 模式查看和编辑配置。在其他任何标签页中反映到此选项卡中的 JSON 配置时,您所做的任何更改都会反映出来。
在下一部分中,您将了解如何从 属性 子选项卡中管理配置。
5.11.3. 管理属性 复制链接链接已复制到粘贴板!
在 Attributes 子选项卡中,您可以创建、编辑和删除与用户配置文件关联的属性。
要定义新属性并将其与用户配置文件关联,请点属性列表右上角的 Create 按钮。
属性配置
在配置属性时,您可以定义以下设置:
- Name
- 属性的名称。
- 显示名称
- 属性的用户友好的名称,主要在呈现面向用户表单时使用。它支持国际化,以便可以从消息捆绑包加载值。
- 属性组
- 属性组(若有)。
- 在范围时启用
- 允许您定义范围列表来动态启用属性。如果没有设置,则 属性总是被启用,在管理用户配置集以及渲染面向用户的表单时始终强制执行其限制。否则,只有在客户端请求列表中任何范围时,同样的限制才会应用。
- 必需
- 根据需要设置 属性。如果没有启用,则属性是可选的。否则,用户必须和管理员提供属性才能使用户或管理员仅根据客户端所请求的范围而必要的属性。
- 权限
- 在本节中,您可以为用户和管理员定义读取和写入权限。
- 验证
- 在本节中,您可以定义管理属性值时要执行的验证。Red Hat Single Sign-On 提供了一组内置验证器,您可以选择它自行添加。
- 注解
- 在此部分中,您可以将注解与属性关联。注解主要用于将额外元数据传递给 frontend 以便进行渲染。
5.11.3.1. 管理权限 复制链接链接已复制到粘贴板!
在 Permission 部分中,您可以定义访问权限用户级别,管理员必须读取和写入属性。
属性权限
因此,您可以使用以下设置:
- 用户是否可以查看?
- 如果启用,用户可以查看 属性。否则,用户无法访问 属性。
- 用户是否可以编辑?
- 如果启用,用户可以查看和编辑 属性。否则,用户无权写入属性。
- 管理可以查看吗?
- 如果启用,管理员可以查看 属性。否则,管理员无法访问 属性。
- 管理员是否可以编辑?
- 如果启用,管理员可以查看和编辑 属性。否则,管理员无权写入属性。
当您创建属性时,没有权限设置为 属性。有效地,用户或管理员无法访问该属性。创建属性后,请确保相应地设置该属性仅对目标受众可见的权限。
权限会对如何管理属性以及属性呈现方式直接影响。
例如,通过将属性标记为只能查看属性,则管理员在通过管理控制台管理用户时无法访问 属性(从用户 API 中)。另外,用户在更新其配置集时无法更改属性。如果从现有的身份存储(解码)获取用户属性,并且您希望使属性对用户可见,而无需通过源身份存储更新其他属性,则比较有趣的配置。
同样,您还可以将属性标记为只针对用户具有只读访问权限的管理员可写属性。在这种情况下,只有管理员才可以管理属性。
根据您的隐私要求,您可能还希望管理员无法访问属性,但用户具有读写权限。
每次向用户配置文件配置添加新属性时,务必设置正确的权限。
5.11.3.2. 管理验证 复制链接链接已复制到粘贴板!
在 Validation 部分中,您可以从不同类型的验证中选择,以确保属性值符合特定的规则。
属性验证
Red Hat Single Sign-On 提供了不同的验证程序:
| Name | 描述 | Configuration |
|---|---|---|
| 长度 | 根据最小和最大长度检查字符串值的长度。 | min :一个整数来定义允许的最短长度。 max :一个整数来定义允许的最大长度。 trim-disabled :一个布尔值,用于定义在验证前是否修剪该值。 |
| 整数 | 检查该值是否为整数,并在较低和/或高范围内。如果没有定义范围,则验证器将仅检查该值是否有效。 | min :一个整数来定义较低范围。 max :一个整数来定义上限。 |
| double | 检查该值是否是双,在较低和/或高范围内。如果没有定义范围,则验证器将仅检查该值是否有效。 | min :一个整数来定义较低范围。 max :一个整数来定义上限。 |
| uri | 检查该值是否为有效的 URI。 | None |
| pattern | 检查值是否与特定 RegEx 模式匹配。 | Pattern :验证值时要使用的 RegEx 模式。 error-message :i18n bundle 中错误消息的密钥。如果未设置通用消息。 |
| | 检查该值是否具有有效的电子邮件格式。 | None |
| local-date | 根据 realm 和/或用户区域设置,检查该值是否具有有效的格式。 | None |
| person-name-prohibited-characters | 检查该值是否为用于攻击的额外障碍,如脚本注入。验证基于一个默认的 RegEx 模式,它阻断了不常在人名称中的字符。 | error-message :i18n bundle 中错误消息的密钥。如果未设置通用消息。 |
| username-prohibited-characters | 检查该值是否为用于攻击的额外栏方,如脚本注入。验证基于一个默认 RegEx 模式,它阻断了在用户名中不常见的字符。 | error-message :i18n bundle 中错误消息的密钥。如果未设置通用消息。 |
| 选项 | 检查值是否来自定义的允许值集合。用于验证通过 select 和 multiselect 字段输入的值很有用。 | 选项 :包含允许值的字符串数组。 |
5.11.3.2.1. 管理注解 复制链接链接已复制到粘贴板!
要将额外信息传递给 frontends,可以使用注解来解码属性来指示属性是如何呈现的。此功能在扩展 Red Hat Single Sign-On themes 时,根据与属性关联的注解动态呈现页面时,此功能很有用。此机制 用于为属性 配置 Form 输入文件。
属性注解
5.11.4. 管理属性组 复制链接链接已复制到粘贴板!
在 Attribute Groups 子选项卡中,您可以创建、编辑和删除属性组。属性组允许您为关联属性定义容器,以便在面向用户的表单时将它们呈现在一起。
闲置组列表
您不能删除绑定到属性的属性组。为此,您应该首先更新属性以删除绑定。
要创建新组,请单击属性组列表右上角的 Create 按钮。
属性组配置
在配置组时,您可以定义以下设置:
- Name
- 组名称。
- 显示名称
- 对组的用户友好名称,在呈现面向用户的表单时主要使用。它支持国际化,以便可以从消息捆绑包加载值。
- 显示描述
- 用户友好的文本,在呈现面向用户的表单时将显示为工具提示。
- 注解
- 在此部分中,您可以将注解与属性关联。注解主要用于将额外元数据传递给 frontend 以便进行渲染。
5.11.5. 使用 JSON 配置 复制链接链接已复制到粘贴板!
用户配置集配置使用定义良好的 JSON 模式存储。您可以通过点击 JSON Editor sub-tab 直接从编辑用户配置集配置中选择。
JSON 配置
JSON 模式定义如下:
架构支持尽可能多的属性。
对于每个属性,您应定义一个 名称,以及可选的 所需、权限 和注解 设置。
5.11.5.1. 所需的属性 复制链接链接已复制到粘贴板!
required 设置定义属性是否是必需的。Red Hat Single Sign-On 允许您根据不同条件设置属性。
当 required 设置定义为空对象时,则始终需要。
另一方面,您可以选择为用户或管理员做出所需的属性。另外,只有在 Red Hat Single Sign-On 中用户进行身份验证时,才要求将 属性标记为必需属性。
要标记用户和/或管理员所需的属性,请按如下所示设置 roles 属性:
roles 属性需要一个数组,其值可以是 user 或 admin,具体取决于用户还是管理员所需要的属性。
同样,您可以选择在验证用户时,选择为客户端请求一个或多个范围时所需的属性。为此,您可以使用 scopes 属性,如下所示:
scopes 属性是一个数组,其值可以是代表客户端范围的任何字符串。
5.11.5.2. 权限属性 复制链接链接已复制到粘贴板!
属性级 权限 属性可用于定义属性的读取和写入权限。权限会根据用户或管理员是否能够对属性来执行这些操作。
view 和 edit 属性都要求一个数组,其值可以是 用户或 admin,具体取决于属性是否可以被分别查看或管理员编辑。
当授予edit权限时,而会获得 view 权限。
5.11.5.3. annotations 属性 复制链接链接已复制到粘贴板!
属性级 注解 属性可用于将额外元数据与属性关联。注解主要用于根据用户配置集配置传递属性到 frontends rendering 用户属性的额外信息。每个注解都是键/值对。
5.11.6. 使用动态表单 复制链接链接已复制到粘贴板!
User Profile 的主要功能之一是可以根据属性元数据动态呈现面向用户表单。当您为域启用了该功能时,会使用特定的主题模板根据用户配置集配置来动态显示页面,如注册和更新配置文件。
也就是说,如果默认渲染机制根据您的需要,则应该不需要自定义模板。如果您仍然需要将自定义自定义到它们,请参考以下模板:
| 模板 | 描述 |
|---|---|
| base/login/update-user-profile.ftl | 呈现更新配置集页面的模板。 |
| base/login/register-user-profile.ftl | 呈现注册页面的模板。 |
| base/login/idp-review-user-profile.ftl | 在生成用户通过代理时,渲染查看/更新用户配置集的页面的模板。 |
| base/login/user-profile-commons.ftl | 基于属性配置以表单形式呈现输入字段的模板。在上述所有三个页面模板中使用。此处可实施新的输入类型。 |
默认渲染机制提供以下功能:
- 根据设置为属性的权限动态显示字段。
- 根据设置为属性的约束,为必填字段动态呈现标记。
- 动态呈现字段输入类型(文本、日期、数字、选择、多选)设置为属性。
- 根据设置为属性的权限,动态呈现只读字段。
- 根据分配给属性的顺序设置动态订购字段。
- 属于同一属性组的动态组字段。
5.11.6.1. 排序属性 复制链接链接已复制到粘贴板!
在属性列表页面中时,单击上下箭头和下箭头即可设置属性顺序。
排序属性
当字段以动态形式呈现时,会遵循您在本页中设置的顺序。
5.11.6.2. 分组属性 复制链接链接已复制到粘贴板!
呈现动态表单时,它们将尝试将属于同一属性组的属性分组在一起。
动态更新配置文件表单
当属性链接到属性组时,属性顺序也很重要,以确保同一组中的属性在相同的组标题中关闭。否则,如果组中的属性没有连续顺序,则可能会以动态的形式呈现同一组标头多次。
5.11.6.3. 为属性配置表单输入文件 复制链接链接已复制到粘贴板!
Red Hat Single Sign-On 提供了内置注解,以配置哪些输入类型用于动态形式的属性及其视觉化的其他方面。
可用注解:
| Name | 描述 |
|---|---|
| inputType | 表单输入字段的类型。下表描述了可用类型。 |
| inputHelperTextBefore |
在输入字段之前呈现的帮助文本(再次)输入字段。此处可以使用直接文本或国际化模式(如 |
| inputHelperTextAfter |
在输入字段后(在下面)呈现帮助文本。此处可以使用直接文本或国际化模式(如 |
| inputOptionsFromValidation | 选择和多选类型的注解。用于获取输入选项的自定义属性验证的可选名称。请参阅以下 详细说明。 |
| inputOptionLabelsI18nPrefix | 选择和多选类型的注解。在 UI 中呈现选项的国际化密钥前缀。请参阅以下 详细说明。 |
| inputOptionLabels | 选择和多选类型的注解。可选映射来为选项定义 UI 标签(直接或使用国际化)。请参阅以下 详细说明。 |
| inputTypePlaceholder |
应用于字段的 HTML 输入 |
| inputTypeSize |
应用于字段的 HTML 输入 |
| inputTypeCols |
应用于字段的 HTML 输入 |
| inputTypeRows |
应用于字段的 HTML 输入 |
| inputTypePattern |
HTML 输入 |
| inputTypeMaxLength |
应用于提供客户端验证的字段 HTML 输入 |
| inputTypeMinLength |
HTML 输入 |
| inputTypeMax |
HTML 输入 |
| inputTypeMin |
HTML 输入 |
| inputTypeStep |
应用到字段的 HTML 输入 |
字段类型使用 HTML 表单字段标签和应用到它们的属性 - 它们基于 HTML 规格和浏览器支持。
视觉化呈现还取决于使用主题中应用的 cs 风格。
可用的 inputType 注解值:
| Name | 描述 | 使用的 HTML 标签 |
|---|---|---|
| text | 单行文本输入。 | 输入 |
| 文本区域 | 多行文本输入. | 文本区域 |
| select | 常见单选输入。请参考 如何在下面配置选项的说明。 | select |
| select-radiobuttons | 单个选择通过一组单选按钮的输入。请参考 如何在下面配置选项的说明。 | 输入组 |
| multiselect | 常见多选输入.请参考 如何在下面配置选项的说明。 | select |
| multiselect-checkboxes | 通过组复选框进行多选择输入。请参考 如何在下面配置选项的说明。 | 输入组 |
| html5-email | 基于 HTML 5 规格的电子邮件地址的单行文本输入。 | 输入 |
| html5-tel | 基于 HTML 5 规格的电话号码的单行文本输入。 | 输入 |
| html5-url | 基于 HTML 5 规格的 URL 的单行文本输入。 | 输入 |
| html5-number |
基于 HTML 5 规格的单行输入(整数或浮点,取决于 | 输入 |
| html5-range | 基于 HTML 5 规格输入的数字幻灯片。 | 输入 |
| html5-datetime-local | 基于 HTML 5 规格的日期时间输入。 | 输入 |
| html5-date | 基于 HTML 5 规格的日期输入。 | 输入 |
| html5-month | 基于 HTML 5 规格的每月输入。 | 输入 |
| html5-week | 基于 HTML 5 规格的星期一输入。 | 输入 |
| html5-time | 基于 HTML 5 规格的时间输入。 | 输入 |
5.11.6.3.1. 定义选择和多选字段的选项 复制链接链接已复制到粘贴板!
选择和多选择字段的选项从验证应用到属性,以确保 UI 中提供的验证和字段选项始终一致。默认情况下,选项取自内置 选项 验证。
您可以使用各种方法为选择和多选选项提供 nice 人类可读标签。最简单的情况是,属性值与 UI 标签相同。本例中不需要任何额外的配置。
选项值与 UI 标签相同
如果属性值是不适合 UI 的 ID,您可以使用 inputOptionLabelsI18nPrefix 注解提供的简单国际化支持。它定义了国际化键的前缀,选项值是附加到这个前缀的点。
使用 i18n 键前缀进行 UI 标签的简单国际化
选项值的本地化 UI 标签文本必须由 userprofile.jobtitle.sweng 和 userprofile.jobtitle.swarch 键提供,然后使用常见的本地化机制。
您还可以使用 inputOptionLabels 注解为单个选项提供标签。它包含映射中选项 - 键的标签映射(在验证中定义),映射中的值是 UI 标签文本自身或其国际化模式(如 ${i18n.key})用于该选项。
您必须使用 User Profile JSON Editor 输入 map 作为 inputOptionLabels 注解值。
没有国际化的单个选项直接输入标签示例:
独立选项的国际化标签示例:
本地化文本必须由 jobtitle.swengineer 和 jobtitle.swarchitect 键提供,使用常见的本地化机制。
自定义验证器可用于提供选项,因为 inputOptionsFromValidation attribute 注解。此验证必须具有提供 选项的 config 数组的选项。国际化的方式与内置 选项验证的选项相同。
自定义验证器提供的选项
5.11.7. 强制用户配置文件合规性 复制链接链接已复制到粘贴板!
为确保用户配置集符合配置,管理员可以使用 VerifyProfile required 操作来最终强制用户在向 Red Hat Single Sign-On 进行身份验证时更新其配置集。
VerifyProfile 操作与 UpdateProfile 操作类似。但是,它会利用用户配置集提供的所有功能来自动强制实施与用户配置文件配置的合规性。
启用后,VerifyProfile 操作会在用户进行身份验证时执行以下步骤:
- 检查用户配置集是否与用户配置集配置完全符合该域。
- 如果没有,请在身份验证过程中执行额外的步骤,以便用户可以更新任何缺失或无效属性。
- 如果用户配置集与配置兼容,则不会执行额外的步骤,用户继续进行身份验证过程。
默认情况下,VerifyProfile 操作被禁用。要启用它,请单击左侧菜单中的 Authentication 链接,然后单击 Required Actions 选项卡。在这个标签页中,点 Register 按钮并选择 VerifyProfile action。
Registring VerifyProfile Required Action
5.11.8. 迁移到用户配置集 复制链接链接已复制到粘贴板!
在为域启用用户配置文件功能前,您需要了解一些重要的注意事项。通过提供单一位置来管理属性元数据,该功能对可设置为用户的属性以及管理方式而言非常严格。
在用户管理方面,管理员只能管理用户配置文件配置中定义的属性。将任何其他属性设置为用户,在用户配置文件配置中尚未定义的任何属性都无法访问。建议您使用您要向用户或管理员公开的所有用户属性更新用户配置集配置。
同样的建议适用于访问用户 REST API 来查询用户信息。
关于 Red Hat Single Sign-On 内部用户属性,例如 LDAP_ID、LDAP_ENTRY_DN 或 KERBEROS_PRINCIPAL,如果您要访问这些属性,应在用户配置集配置中具有属性。建议将这些属性标记为只能供管理员查看,因此当通过管理控制台管理用户属性或通过用户 API 查询用户属性时,您可以查看它们。
就它们而言,如果您已经对旧模板进行了自定义(使用 root 属性进行硬编码),则您的自定义模板在呈现用户表单时不会被使用,但呈现这些表单的新模板会动态呈现这些表单。理想情况下,您应该避免对模板进行任何自定义,并尝试使用这些新模板提供的行为来动态呈现形式。如果它们仍不足以满足您的要求,您可以对其进行自定义,或提供任何反馈意见,以便我们讨论是否对新模板进行增强。