哈喽大家好！欢迎来到每天一个 Keycloak 知识点系列。
今天我们要聊的是一个超级实用、能让强迫症患者极度舒适的功能——用户属性管理 (User Profile)。
如果你用过早期的 Keycloak，你肯定有过这种痛点：系统默认只有用户名、邮箱、姓、名这几个可怜的字段。一旦老板发话：“咱们注册页面得加个‘手机号’和‘公司部门’字段！” 你就只能去改ftl模板，或者在代码里硬塞到那个毫无结构的 attributes Map 里。字段没有校验，没有权限控制，简直是野蛮生长。
但现在不同了！Keycloak 引入了强大的 Declarative User Profile。今天咱们就用大白话聊聊，这玩意儿到底怎么用。
什么是 User Profile？
简单来说，User Profile 就是给你的用户属性立规矩。
它允许你在 Keycloak 后台集中定义一个用户到底应该有哪些属性，并精确控制这些属性的“生杀大权”：
- 谁能看？谁能改？ （用户自己能改吗？还是只有管理员能改？）
- 必须填吗？ （必填项控制）
- 格式对吗？ （长度限制、正则表达式校验）
- 页面上长啥样？ （前端是渲染成文本框、下拉框还是日期选择器？）
只要你在后台配置好，Keycloak 的注册页面、用户个人中心 (Account Console) 以及管理员后台 (Admin Console) 都会自动同步生效！是不是爽歪歪？
手把手教你配置 User Profile
在较新的 Keycloak 版本（包括 26.x）中，User Profile 功能已经是默认开启的了。咱们直接去后台看看怎么玩。
第一步：找到组织的根据地
- 登录 Keycloak Admin Console。
- 在左侧菜单找到 Realm settings（Realm 设置）。
- 顶部的 Tab 栏里，找到 User Profile。
第二步：创建一个新属性 (Attribute)
点击 Create attribute，你会看到一个配置表单。这里有几个核心区域，咱们挨个扒一扒：
1. 基本信息 (General)
-
Name: 属性在数据库和代码里的名字（比如
phone_number）。 -
Display name: 显示在页面上的名字。这里支持写国际化占位符，比如
${profile.phone_number}，非常适合多语言项目。
2. 权限控制 (Permissions)
这是最精髓的地方！
- User view/edit: 用户在自己的个人中心能不能看到或修改这个字段？（比如“入职日期”用户只能看不能改，“个人签名”可以自己改）。
- Admin view/edit: 管理员在后台能不能看/改？
3. 校验规则 (Validations)
告别前端“防君子不防小人”的校验，直接在服务端卡死！点击 Add validation，你可以添加：
- length: 限制最大最小字符数。
- pattern: 祭出你的正则表达式（比如只允许输入大陆手机号）。
- person-name-prohibited-characters: 屏蔽一些奇奇怪怪的特殊符号。
4. 页面长啥样 (Annotations)
这部分主要是给 UI 界面提供线索。Keycloak 原生页面会读取这些注解来渲染组件。
- 比如你设置
inputType=html5-email，前端就会渲染成邮件输入框。 - 设置
inputType=select，还可以配合配置下拉框的选项。
一个接地气的实战场景
假设你要加一个“工号” (Employee ID) 字段：
-
Name:
employee_id -
Display name:
工号 - Permissions: User 设为不可编辑（打工人哪有权限改自己的工号），Admin 设为可编辑。
-
Validations: 加一个
pattern校验，正则写^EMP\d{4}$（必须是 EMP 开头加4位数字）。
保存之后，你去创建一个新用户，或者让用户去注册，你会发现表单里神奇地多出了一个“工号”字段，而且如果你乱填，系统会无情地提示你格式不对！
总结一下
Keycloak 的 User Profile 功能把分散在模板、代码和数据库里的“用户字段逻辑”全部统一到了配置界面。一次配置，三端（注册页、账号中心、管理后台）生效，而且自带服务端校验。这大大降低了我们定制用户系统的开发成本。
如果你还在改 FreeMarker 模板来手写表单校验，赶紧停下来，去试试 User Profile 吧！
