5.12. 定义用户配置文件

在红帽构建的 Keycloak 中，用户与一组属性关联。这些属性用于更好地描述和识别红帽构建的 Keycloak 中的用户，以及将有关它们的额外信息传递给应用程序。

用户配置文件定义了定义良好的模式，用于代表用户属性以及如何在域中管理它们。通过对用户信息提供一致的视图，管理员可以控制管理属性的不同方面，并更轻松地扩展红帽构建的 Keycloak 以支持其他属性。

除了其他功能外，用户配置文件使管理员能够：

为用户属性定义模式
根据上下文信息（例如：仅对用户或管理员（或者管理员）或两者都需要，或者取决于请求的范围，定义属性是否是必需的。
定义用于查看和编辑用户属性的特定权限，可以遵守强隐私要求，因为第三方无法看到或更改某些属性（包括管理员）
动态强制实施用户配置文件合规性，以便始终更新用户信息，并遵守与属性关联的元数据和规则
使用内置验证器或编写自定义验证器来基于每个属性定义验证规则
根据属性定义，动态呈现用户与帐户控制台中的注册、更新配置集、代理和个人信息交互的表单，而无需手动更改它们。

用户配置文件功能由 User Profile SPI 支持。默认情况下，这些功能被禁用，域配置为使用与旧行为向后兼容的默认配置。

注意

旧行为是保留红帽构建 Keycloak 的默认约束，在管理用户根属性（如用户名、电子邮件、名字和姓氏）时，而无需对管理自定义属性的任何限制。关于通过帐户控制台完成用户流，如注册、配置集更新、代理和管理帐户，用户会被限制为使用上述属性，并可能更改主题模板来支持其他属性。

如果您已使用红帽构建的 Keycloak，旧的行为是您目前为止。

与旧行为不同，声明性提供程序为您提供了通过管理控制台和明确定义的 JSON 模式向域定义用户配置文件配置的灵活性。

在下一小节中，我们将了解如何使用声明性供应商定义您自己的用户配置文件配置。

注意

未来，红帽构建的 Keycloak 不再支持旧的行为。理想情况下，您应该开始查看用户配置文件提供的新功能，并相应地迁移您的域。

5.12.1. 启用用户配置文件

注意

声明性用户配置文件 是技术预览，且不被支持。此功能默认为禁用。

使用 --features=preview 或 --features=declarative-user-profile启用启动服务器

除了启用 declarative_user_profile 功能外，您应该为域启用 User Profile。为此，请单击左侧菜单中的 Realm Settings 链接，再打开 User Profile Enabled 开关。

启用它并点击 Save 按钮后，您可以从中访问 User Profile 选项卡，您可以在其中管理用户属性的配置。

通过为域启用用户配置集，红帽构建的 Keycloak 将对如何根据用户配置集配置管理属性施加额外的限制。在概述中，以下是启用该功能时应该预期的列表：

从管理的角度来看，用户详细信息页面上的 Attributes 选项卡将仅显示用户配置文件配置中定义的属性。在管理属性时，根据每个属性定义的条件也会考虑。
在帐户控制台中，面向用户的注册、更新配置文件、代理和个人信息等面向用户的表单将根据用户配置文件配置动态呈现。为此，红帽构建的 Keycloak 将依赖不同的模板来动态呈现这些表单。

在下一个主题中，我们将探索如何管理用户配置文件配置以及如何影响您的域。

5.12.2. 管理用户配置文件

用户配置文件配置基于每个域管理。为此，请单击左侧菜单中的 Realm Settings 链接，然后单击 User Profile 选项卡。

用户配置文件 Tab

在 Attributes 子选项卡中，您拥有与用户配置文件当前关联的属性的列表。默认情况下，配置会根据用户 root 属性创建，每个属性在验证和权限方面都配置了一些默认值。

在 Attribute Groups 子选项卡中，您可以管理属性组。属性组允许您关联属性，以便在呈现面向用户的表单时显示它们。

注意

现在，属性组仅用于渲染目的，但将来也应该启用为它们链接到的属性定义顶级配置。

在 JSON Editor 子选项卡中，您可以使用定义良好的 JSON 模式查看和编辑配置。您在任何其他标签页中反映在此标签页中显示的 JSON 配置时所做的任何更改。

在下一部分中，您将了解如何从 Attributes 子选项卡管理配置。

5.12.3. 管理属性

在 Attributes 子选项卡中，您可以创建、编辑和删除与用户配置文件关联的属性。

要定义新属性并将其与用户配置文件关联，请单击 属性列表顶部的 Create 属性按钮。

属性配置

在配置属性时，您可以定义以下设置：

Name: 属性的名称。
显示名称: 属性的用户友好名称，主要用于呈现面向用户的表单。它支持国际化，以便从消息捆绑包加载值。
属性组: 属性所属的属性组（若有）。
在范围时启用: 允许您定义范围列表来动态启用属性。如果没有设置，则属性总是被启用，在管理用户配置集以及呈现面向用户的表单时始终强制执行其限制。否则，只有当客户端请求列表中的任何范围时，才会应用相同的限制。
必需: 根据需要设置属性。如果没有启用，则属性是可选的。否则，属性必须由用户和管理员提供，也可以使用户或管理员以及客户端请求的范围也需要的属性。
权限: 在本节中，您可以为用户和管理员定义读写权限。
验证: 在本小节中，您可以定义在管理属性值时要执行的验证。Red Hat build of Keycloak 提供了一组内置验证器，您可以选择它们可能会自行添加。
注解: 在本节中，您可以将注解与属性关联。注解主要用于将其他元数据传递给前端，以满足呈现的目的。

5.12.3.1. 管理权限

在 Permission 部分中，您可以定义访问用户和管理员必须读取和写入属性。

属性权限

为此，您可以使用以下设置：

用户能否查看？: 如果启用，用户可以查看属性。否则，用户无法访问该属性。
用户是否可以编辑？: 如果启用，用户可以查看和编辑属性。否则，用户无法访问写入属性。
管理员视图吗？: 如果启用，管理员可以查看属性。否则，管理员无法访问该属性。
管理员是否可以编辑？: 如果启用，管理员可以查看和编辑属性。否则，管理员没有写入属性的访问权限。

注意

当您创建属性时，不会将权限设置为属性。实际上，属性不能被用户或管理员访问。创建属性后，请确保将权限相应地设置为该属性仅由目标使用者可见。

权限对如何和谁管理属性以及属性是如何以面向用户的形式呈现的直接影响。

例如，通过将属性标记为只能被用户查看，管理员在通过管理控制台（而不是从用户 API）管理用户时无法访问该属性。另外，用户在更新其配置集时无法更改属性。如果用户属性从现有的身份存储(federation)获取，并且您只想使属性对用户可见，而无需通过源身份存储更新其他属性，则值得注意的配置。

同样，您也可以为具有只读访问权限的管理员将属性标记为可写。在这种情况下，只有管理员才可以管理属性。

根据您的隐私要求，您可能还需要管理员无法访问的属性，但用户具有读写权限。

每当您向用户配置文件配置添加新属性时，请确保设置正确的权限。

5.12.3.2. 管理验证

在 Validation 部分中，您可以从不同类型的验证中选择，以确保属性值符合特定规则。

属性验证

Red Hat build of Keycloak 提供不同的验证器：

Name	描述	Configuration
length	根据最小和最大长度检查字符串值的长度。	Min ：用来定义最小允许长度的整数。最大：用于定义允许的最大长度的整数。 trim-disabled ：一个布尔值，用于定义在验证前是否修剪该值。
整数	检查该值是否为整数，并在较低和/或大写范围内。如果没有定义范围，验证器只检查该值是否为有效数字。	Min: 定义较低范围的整数。最大：用来定义上限的整数。
double	检查该值是否为两倍，并在较低和/或上范围内。如果没有定义范围，验证器只检查该值是否为有效数字。	Min: 定义较低范围的整数。最大：用来定义上限的整数。
uri	检查该值是否为有效的 URI。	None
pattern	检查该值是否与特定的 RegEx 模式匹配。	Pattern ：验证值时要使用的 RegEx 模式。 error-message ： i18n 捆绑包中的错误消息的键。如果没有设置通用消息。
email	检查该值是否具有有效的电子邮件格式。	None
local-date	检查该值是否具有基于 realm 和/或用户区域设置的有效格式。	None
person-name-prohibited-characters	检查该值是否为有效的人员名称，作为攻击的额外障碍，如脚本注入。验证基于默认的 RegEx 模式，它会阻止个人名称中不常见的字符。	error-message ： i18n 捆绑包中的错误消息的键。如果没有设置通用消息。
username-prohibited-characters	检查该值是否为有效用户名，作为安全攻击（如脚本注入）的额外障碍。验证基于默认的 RegEx 模式，它会阻止用户名中不常见的字符。	error-message ： i18n 捆绑包中的错误消息的键。如果没有设置通用消息。
选项	检查该值是否来自定义的允许值集合。有助于验证通过选择和多选字段输入的值。	选项：包含允许值的字符串数组。

5.12.3.2.1. 管理注解

要将额外信息传递给前端，可以通过注解来解码属性，以指定如何呈现属性。当扩展红帽构建的 Keycloak 主题时，此功能主要有用，以根据与属性关联的注解动态呈现页面。此机制用于为属性配置 Form input filed。

属性注解

5.12.4. 管理属性组

在 Attribute Groups 子选项卡中，您可以创建、编辑和删除属性组。属性组允许您为关联属性定义容器，以便在面向用户的表单下呈现它们。

属性组列表

注意

您不能删除绑定到属性的属性组。为此，您应该首先更新属性以删除绑定。

若要创建新组，请单击属性组列表顶部的 Create attributes group 按钮。

属性组配置

在配置组时，您可以定义以下设置：

Name: 组的名称。
显示名称: 组群的用户友好名称，主要用于呈现面向用户的表单。它支持国际化，以便从消息捆绑包加载值。
显示描述: 在呈现面向用户的表单时，用户友好的文本将显示为工具提示。
注解: 在本节中，您可以将注解与属性关联。注解主要用于将其他元数据传递给前端，以满足呈现的目的。

5.12.5. 使用 JSON 配置

用户配置文件配置使用定义良好的 JSON 模式存储。您可以通过单击 JSON Editor 子选项卡来选择直接编辑用户配置文件配置。

JSON 配置

JSON 模式定义如下：

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {
        "roles": [ "user", "admin" ],
        "scopes": [ "foo", "bar" ]
      },
      "permissions": {
        "view": [ "admin", "user" ],
        "edit": [ "admin", "user" ]
      },
      "validations": {
        "email": {},
        "length": {
          "max": 255
        }
      },
      "annotations": {
        "myannotation": "myannotation-value"
      }
    }
  ],
  "groups": [
    {
      "name": "personalInfo",
      "displayHeader": "Personal Information"
    }
  ]
}

模式根据需要支持多个属性。

对于每个属性，您应该定义一个 name，以及可选的、权限 和注解 设置。

5.12.5.1. 所需属性

所需的设置 定义是否需要属性。红帽构建的 Keycloak 允许您根据不同的条件设置属性。

当将 所需的设置 定义为空对象时，属性始终是必需的。

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {}
  ]
}

另一方面，您可以选择只为用户提供或管理员所需的属性。以及仅在 Red Hat build of Keycloak 进行身份验证时请求特定范围时，才需要标记属性。

要将属性标记为用户和/或管理员所需的属性，请设置 roles 属性，如下所示：

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {
        "roles": ["user"]
      }
  ]
}

roles 属性需要一个数组，其值可以是用户或 admin，具体取决于用户还是管理员需要属性。

同样，您可以选择在验证用户时让客户端请求一个或多个范围时所需的属性。为此，您可以使用 scopes 属性，如下所示：

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {
        "scopes": ["foo"]
      }
  ]
}

scopes 属性是一个数组，其值可以是代表客户端范围的任何字符串。

5.12.5.2. 权限属性

属性级 权限 属性可用于定义属性的读写权限。权限根据用户或管理员是否可以对属性或管理员执行这些操作来设置。

{
  "attributes": [
    {
      "name": "myattribute",
      "permissions": {
        "view": ["admin"],
        "edit": ["user"]
      }
  ]
}

查看和编辑 属性都希望其值可以是用户或 admin 的数组，具体取决于属性是可查看还是可由用户还是管理员编辑。

授予权限时，会隐式授予 view 权限。

5.12.5.3. annotations 属性

property-level 注解 属性可用于将额外的元数据与属性关联。注解主要用于传递有关属性的额外信息，以根据用户配置文件配置呈现用户属性。每个注解都是键/值对。

{
  "attributes": [
    {
      "name": "myattribute",
      "annotations": {
        "foo": ["foo-value"],
        "bar": ["bar-value"]
      }
  ]
}

5.12.6. 使用动态表单

用户配置文件的主要功能之一是根据属性元数据动态呈现面向用户的表单。当您为域启用了功能时，将使用特定的主题模板渲染表单，以根据用户配置文件配置动态呈现页面。

这意味着，如果默认渲染机制满足您的需要，则应该不需要所有自定义模板。如果您仍然需要对主题进行自定义，您应该查看以下模板：

模板	描述
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	根据属性配置以表单呈现输入字段的模板。在上述所有三个页面模板中使用。这里可以实施新的输入类型。

默认渲染机制提供以下功能：

根据将权限设置为属性，动态显示字段。
根据设置为属性的限制，动态呈现必填字段的标记。
动态呈现字段输入类型(text、date、number、选择、multiselect)设置为属性。
根据设置为属性的权限，动态呈现只读字段。
根据设置为属性的顺序，动态顺序字段。
动态组属于同一属性组的字段。

5.12.6.1. 排序属性

属性顺序通过将属性行拖放到属性列表页面中来设置。

排序属性

当字段以动态格式呈现时，会考虑您在此页面中设置的顺序。

5.12.6.2. 分组属性

在呈现动态表单时，它们将尝试对属于同一属性组的属性进行分组。

动态更新配置文件表单

注意

当属性链接到属性组时，属性顺序也很重要，确保同一组中的属性在同一组标头中关闭。否则，如果组中的属性没有顺序顺序，您可能有相同的组标头以动态形式呈现多次。

5.12.6.3. 为属性配置表单输入文件

红帽构建的 Keycloak 提供内置注解，来配置将哪些输入类型用于动态形式及其视觉化的其他方面。

可用的注解有：

Name	描述
inputType	表单输入字段的类型。下表描述了可用类型。
inputHelperTextBefore	在(above)输入字段之前呈现的帮助文本。可以在此处使用直接文本或国际化模式（如 `${i18n.key}`）。在呈现到页面时，文本不会被转义，因此您可以使用此处的 HTML 标签格式化文本，但您必须正确转义 html 控制字符。
inputHelperTextAfter	输入字段后（在）输入字段后呈现的帮助程序文本。可以在此处使用直接文本或国际化模式（如 `${i18n.key}`）。在呈现到页面时，文本不会被转义，因此您可以使用此处的 HTML 标签格式化文本，但您必须正确转义 html 控制字符。
inputOptionsFromValidation	选择和多选类型的注解。自定义属性验证的可选名称，以便从中获取输入选项。请参见以下详细描述。
inputOptionLabelsI18nPrefix	选择和多选类型的注解。国际化密钥前缀，以在 UI 中呈现选项。请参见以下详细描述。
inputOptionLabels	选择和多选类型的注解。可选映射，为选项（直接或使用国际化）定义 UI 标签。请参见以下详细描述。
inputTypePlaceholder	应用到字段的 HTML 输入 `占位符` 属性 - 指定简短提示，用于描述输入字段的预期值（例如，示例值或预期格式的简短描述）。在用户输入值前，输入字段中会显示简短提示。
inputTypeSize	应用到字段的 HTML 输入 `大小` 属性 - 指定单行输入字段的宽度、字符表示。对于基于 HTML `选择类型的字段`，它指定了带有选项的行数。可能无法正常工作，具体取决于使用的主题中的 cs!
inputTypeCols	应用到字段的 HTML 输入并置属性 - 指定 `文本area` 类型的宽度（以字符为单位）。可能无法正常工作，具体取决于使用的主题中的 cs!
inputTypeRows	应用到字段的 HTML 输入 `行` 属性 - 为 `文本area` 类型指定 height、以字符为单位。对于选择字段，它指定了带有选项的行数。可能无法正常工作，具体取决于使用的主题中的 cs!
inputTypePattern	应用到提供客户端侧验证的字段的 HTML 输入 `模式` 属性 - 指定检查输入字段值的正则表达式。对于单行输入非常有用。
inputTypeMaxLength	HTML 输入 `maxlength` 属性应用到提供客户端侧验证的字段 - 可在输入字段中输入的文本的最大长度。对于文本字段非常有用。
inputTypeMinLength	适用于提供客户端侧验证的字段的 HTML 输入 `minlength` 属性 - 可在输入字段中输入的文本的最小长度。对于文本字段非常有用。
inputTypeMax	HTML 输入 `max` 属性应用到提供客户端侧验证的字段 - 最大值，可输入输入字段。对于数字字段很有用。
inputTypeMin	HTML 输入 `min` 属性应用到提供客户端侧验证的字段 - 可在输入字段中输入最小值。对于数字字段很有用。
inputTypeStep	应用到字段的 HTML 输入 `step` 属性 - 指定输入字段中的法律号码之间的间隔。对于数字字段很有用。

注意

字段类型使用 HTML 表单字段标签和属性 - 它们的行为取决于 HTML 规格和浏览器支持。

视觉渲染还取决于使用的主题中应用的 css 风格。

可用的 inputType 注解值：

Name	描述	使用的 HTML 标签
text	单行文本输入。	输入
文本area	多行文本输入。	文本area
select	常见单选输入。请参见以下方法配置选项。	select
select-radiobuttons	通过一组单选按钮选择输入。请参见以下方法配置选项。	输入组
多选	常见多选输入。请参见以下方法配置选项。	select
multiselect-checkboxes	通过多组复选框进行多选输入。请参见以下方法配置选项。	输入组
html5-email	基于 HTML 5 spec 的电子邮件地址的单行文本输入。	输入
html5-tel	基于 HTML 5 spec 的电话号码输入单行文本。	输入
html5-url	基于 HTML 5 spec 的单行文本输入 URL。	输入
html5-number	根据 `步骤`根据 HTML 5 spec，单行输入数字（整数或浮点）。	输入
html5-range	根据 HTML 5 spec 输入的数字滑块。	输入
html5-datetime-local	基于 HTML 5 规范的日期时间输入。	输入
html5-date	基于 HTML 5 规格的日期输入。	输入
html5-month	基于 HTML 5 规格的月份输入。	输入
html5-week	基于 HTML 5 规格的每周输入。	输入
html5-time	基于 HTML 5 规格的时间输入。	输入

5.12.6.3.1. 为选择和多选字段定义选项

选择和多选字段的选项从应用于属性的验证中获取，以确保 UI 中显示的验证和字段选项始终一致。默认情况下，从内置选项验证中获取 选项。

您可以使用各种方法为选择和多选选项提供人类可读的标签。最简单的情况是属性值与 UI 标签相同时。在这种情况下不需要额外的配置。

选项值与 UI 标签相同

当属性值是不适用于 UI 的 ID 类型时，您可以使用 输入OptionLabelsI18nPrefix 注解提供的简单国际化支持。它为国际化键定义前缀，选项值会附加到这个前缀中。

使用 i18n 键前缀简单的 UI 标签国际化

选项值的本地化 UI 标签文本必须由 userprofile.jobtitle.sweng 和 userprofile.jobtitle.swarch 键提供，然后使用常见的本地化机制。

您还可以使用 inputOptionLabels 注解为单个选项提供标签。它包含选项的标签映射 - 映射中的键是 options 值（在验证中定义），映射中的值是 UI 标签文本本身，或者其国际化模式（如 ${i18n.key}）用于该选项。

注意

您必须使用 User Profile JSON Editor 将 map 输入为 inputOptionLabels 注解值。

在没有国际化的情况下，为单个选项直接输入标签示例：

"attributes": [
<...
{
  "name": "jobTitle",
  "validations": {
    "options": {
      "options":[
        "sweng",
        "swarch"
      ]
    }
  },
  "annotations": {
    "inputType": "select",
    "inputOptionLabels": {
      "sweng": "Software Engineer",
      "swarch": "Software Architect"
    }
  }
}
...
]

单个选项的国际化标签示例：

"attributes": [
...
{
  "name": "jobTitle",
  "validations": {
    "options": {
      "options":[
        "sweng",
        "swarch"
      ]
    }
  },
  "annotations": {
    "inputType": "select-radiobuttons",
    "inputOptionLabels": {
      "sweng": "${jobtitle.swengineer}",
      "swarch": "${jobtitle.swarchitect}"
    }
  }
}
...
]

本地化文本必须由 jobtitle.swengineer 和 jobtitle.swarchitect 键提供，然后使用常见的本地化机制。

由于 inputOptionsFromValidation 属性注解，可以使用自定义验证器来提供选项。此验证必须具有提供选项数组 的选项 配置选项。国际化的工作方式与内置选项验证 提供的选项 相同。

自定义验证器提供的选项

5.12.7. 强制用户配置文件合规性

为确保用户配置集符合配置，管理员可以使用 VerifyProfile 所需的操作最终强制用户在向 Keycloak 进行身份验证时更新其配置集。

注意

VerifyProfile 操作类似于 UpdateProfile 操作。但是，它会利用用户配置文件提供的所有功能来自动强制符合用户配置文件配置。

启用后，当用户验证时，VerifyProfile 操作将执行以下步骤：

检查用户配置文件是否与设置为 realm 的用户配置文件配置完全兼容。
如果没有，请在身份验证过程中执行额外的步骤，以便用户可以更新任何缺少的或无效属性。
如果用户配置文件符合配置，则不会执行额外的步骤，用户将继续使用身份验证过程。

默认情况下禁用 VerifyProfile 操作。要启用它，请点击左侧菜单中的 Authentication 链接，然后单击 Required Actions 选项卡。在此选项卡中，选择 VerifyProfile 操作的 Enabled 开关。

注册 VerifyProfile 必需的操作

5.12.8. 迁移到用户配置文件

在为域启用用户配置文件功能前，您应该了解一些重要的注意事项。通过提供单一位置来管理属性元数据，这个功能对于可以将其设置为用户的属性及其管理方式非常严格。

就用户管理而言，管理员只能管理用户配置文件配置中定义的属性。任何设置为用户，并且尚未在用户配置文件配置中定义的其他属性都无法访问。建议您使用您要向用户或管理员公开的所有用户属性更新您的用户配置文件配置。

同样适用于访问 User REST API 的建议，以查询用户信息。

对于红帽构建的 Keycloak 内部用户属性，如 LDAP_ID、LDAP_ENTRY_DN 或 KERBEROS_PRINCIPAL，如果您要访问这些属性，您应该将其作为用户配置集配置中的属性。建议将这些属性标记为只能向管理员查看，以便您可以在通过管理控制台管理用户属性时查看它们，或通过 User API 查询用户。

值得注意的是，如果您已自定义旧模板（使用用户 root 属性硬编码）您的自定义模板，则在呈现面向用户的表单时不会被使用，但动态呈现这些表单的新模板。理想情况下，您应该避免对模板进行任何自定义，并尝试使用这些新模板提供的行为来动态为您呈现表单。如果他们仍不足以满足您的要求，您可以对其进行自定义或向我们提供任何反馈，以便我们讨论是否对新模板有意义。