1 基础知识

1.1 前言

一个问题，一篇文章，一出故事。
本章将Keycloak与PrivacyIDEA集成，要实现的工作流程如下，

• Nextcloud用户在Keycloak输入用户名和密码之后，由Keycloak弹出输入OPT令牌的页面。
• 用户输入OPT令牌后，Keycloak将令牌送到后端的PrivacyIDEA验证并返回接收验证结果后做出是否登陆成功的断言。

1.2 配置身份验证

1.2.1 Keycloak的身份验证主题

• 执行严格的密码和一次性密码（OTP）策略
• 管理不同的凭证类型
• 使用Kerberos登陆
• 禁用和启用内置凭证类型

1.2.2 密码策略

菜单位置【Authentication】->【Policies】->【Add policy】

• Keycloak创建域时，不会将密码策略与该域关联
• 设置的简单密码，不受长度、安全性或浮渣型限制
• 生产环境中，Keycloak通过启用密码策略来管理控制台访问

密码策略的类型

• 哈希算法，密码非明文存储，存储前Keycloak会使用标准的哈希算法进行哈希加密
• 哈希迭代，指定Keycloak存储或验证密码之前进行哈希处理的次数，默认值为“-1”
• 最大认证年龄，指定用户身份验证的最大有效期，期间，用户无需重新验证即可更新密码，值为0即始终验证才能更新密码

1.2.3 OTP策略

菜单位置【Authentication】->【Policies】->【OTP policy】

• Keycloak支持设置FreeOTP或Google Authenticator一次性密码生成器的策略
• Keycloak根据OTP策略选项卡的配置信息在OTP设置页面上生成二维码

OTP的类型

• 基于时间的算法（TOTP），令牌生成器会对当前时间和共享密码进行哈希处理，通过对比一段时间内哈希值与提交的值来验证
• 基于计数器的算法（HOTP），使用共享计数器而非时间，成功登陆OTP后服务器会递增计数器，即OTP会变化（TOTP更安全）

OTP的配置选项

• OTP哈希算法（OTP hash algorithm），默认是SHA1,更安全的是SHA256和SHA512
• 位数（Number of digits），长度越长约安全，短的用户容易记忆。
• 环顾窗口（Look around window），服务器尝试匹配哈希值的间隔数。
• 如果TOTP生成器和验证服务器时钟不同步，Keycloak中会显示此选项，默认1足够。
• 设令牌时间间隔30秒，1个环顾窗口时间为90秒（时间间隔30秒+前间隔30秒+后间隔30秒）
• OTP令牌周期（OTP token period），服务器匹配哈希值时隔（秒为单位），每次经过该时隔，令牌生成器创建一个TOTP
• 可重用代码（Reusable code），定义OTP令牌是否支持身份验证过程中重复使用，或者等待下一个令牌。

1.2.4 身份验证流程

• 身份验证流程是登录、注册和其他Keycloak工作流期间的身份验证、屏幕和操作的容器
• Keycloak内置多个流程，流程无法修改，但是支持根据需求调整流程需求。

菜单位置【Authentication】

如上图所示，上面的身份验证流程能如下，

• 选项“Cookie”,用户首次成功登陆，Keycloak会设置会话Cookie。
• 选项“Kerberos”,此身份验证器默认处于禁用状态，并且浏览器流程会被跳过。
• 选项“Identity Provider Redirector”即身份提供者重定向器，将验证重定向到另外一个IdP进行身份代理。
• 选项“Forms”表格，如果Cookie身份验证通过，则直接跳过，其子流程包含需要执行的附加身份验证类型。
• 选项“Username Password Form”用户名和密码表单，向用户呈现用户名和密码页面（必须）
• 选项“Browser – Conditional 2FA”浏览器式的条件2FA，将根据条件和用户配置执行的结果执行
• 选项“Condition – User Configured”条件式用户配置身份验证，检查Keycloak是否已为用户配置流程中的其他执行
• 选项“OTP Form”OTP表单，需要前面条目判断用户拥有已配置OTP凭证是才执行，否则跳过。
• 选项“WebAuthn Authenticator”Webauthn身份验证器（禁用），如果为用户配置相应凭证，可改为“requirement”
• 选项“Recovery Authentication Code Form”恢复身份验证表单（禁用），如为用户配相应凭证，可改为“requirement”

需要注意的是，

• 身份验证的名称或要执行的操作
• 如果身份验证已经缩进，则表示它位于子流程中，是否执行取决于父流程

创建顶级流程

如上图所示，你需要定义如下选项，

• 选项“Name”，定义流程的名称
• 选项“Description”，定义流程的描述
• 选项“Flow type”，定义流程的类型，“Client”仅用于客户端的身份验证，其他选择“basic”

创建子流程

创建“顶级流程”后，紧接着提示创建“子流程”，以下三个因素确定流和子流程的行为，

• 流和子流的结构
• 流程中的执行（例如发送重置邮件或一次性验证码，即OTP）
• 自流程和执行中设置的条件

关于添加具体的执行，具体如下图，

身份验证执行支持配置身份验证器的参考值，范例如下图，

关于以上参数，

• 身份验证方法参考（AMR）协议映射器，利用该值来填充OIDC访问令牌和ID令牌中的amr声明（参阅RFC-8176）
• 当客户端配置身份验证方法参考（AMR）协议映射器时，他会将用户在身份验证流程中成功完成的任何身份验证器的参考值填充到amr声明中。

1.3 PrivacyIDEA配置流程

• Cookie（如果用户已经登陆）
• PrivacyIDEA表单（如果用户尚未登录，则流程）
• 用户名密码形式（第一因素）
• privacyIDEA（第二因素）

2 最佳实践

2.1 配置环境

2.1.1 部署Nextcloud集成Keycloak环境

如何配置Nextcloud集成Keycloak？

2.1.2 实现Google身份验证器获取TOTP令牌

如何配置PrivacyIDEA集成Google身份验证器？

请注意，

• 以上服务器地址为“https://privacyidea.cmdschool.org”，一会我们需要用到
• 上面配置手机的Google身份验证器获取TOTP令牌，一会我们也需要用到

2.2 在Keycloak安装PrivacyIDEA插件

2.2.1 下载软件包

cd ~
wget https://github.com/privacyidea/keycloak-provider/releases/download/v1.5.1/PrivacyIDEA-Keycloak-Provider-1.5.1.1.jar

以上只是下载演示，如果下载异常或需要更新的版本，请从如下连接下载，
https://github.com/privacyidea/keycloak-provider/releases

2.2.2 停止Keycloak服务

systemctl stop keycloak

2.2.3 部署软件包

cd ~
cp PrivacyIDEA-Keycloak-Provider-1.5.1.1.jar ${RHBK_HOME}/providers/PrivacyIDEA-Keycloak-Provider.jar 
chown keycloak:keycloak ${RHBK_HOME}/providers/PrivacyIDEA-Keycloak-Provider.jar

2.2.4 重新构建Keycloak

sudo -u keycloak bash -c "${RHBK_HOME}/bin/kc.sh build --db=mariadb"

正常可见如下提示，

INFO: The following run time options were found, but will be ignored during build time: kc.log, kc.log-file, kc.log-level, kc.db-url, kc.db-username, kc.db-password, kc.proxy-headers, kc.https-certificate-file, kc.https-certificate-key-file, kc.hostname, kc.hostname-admin, kc.cache, kc.cache-stack

Updating the configuration and installing your custom providers, if any. Please wait.
2025-08-27 17:18:56,348 WARN  [org.keycloak.services] (build-45) KC-SERVICES0047: privacyidea-authenticator (org.privacyidea.authenticator.PrivacyIDEAAuthenticatorFactory) is implementing the internal SPI authenticator. This SPI is internal and may change without notice
2025-08-27 17:19:01,043 INFO  [io.quarkus.deployment.QuarkusAugmentor] (main) Quarkus augmentation completed in 6818ms
Server configuration updated and persisted. Run the following command to review the configuration:

        kc.sh show-config

根据提示执行如下命令，

sudo -u keycloak bash -c "${RHBK_HOME}/bin/kc.sh show-config" | grep -i PrivacyIDEA

可见如下提示，

        kc.provider.file.PrivacyIDEA-Keycloak-Provider.jar.last-modified =  1756347457157 (PersistedConfigSource)

2.2.5 重启服务使部署生效

systemctl start keycloak

2.2.6 界面验证插件安装

如上图所示，
单击【Manage realms】->选择非【master】的域
单击【Manage realms】->选择【master】->【Provider info】
如果看到“Add providers”中包含“privacyidea-authenticator”即表示PrivacyIDEA插件被正确加载

2.2 在Keycloak配置PrivacyIDEA插件

2.2.1 复制流程

如上图所示，
单击【Manage realms】并选择你需要操作的域，本范例为“cmdschool”
单击【Authentication】->【Flows】
选择“Flow name”为“browser”的条目并单击三个点的菜单后选择【Duplicate】
窗口显示如下，

如上图所示，
选项“Name”中填写“privacyIDEA”
选项“Description”中填写“privacyIDEA authentication”
单击【Duplicate】完成复制

2.2.2 添加执行

如上图所示，
我们删除没有使用需求的选项，保留图上的三项。
在“privacyIDEA forms”上单击【+】->【Add execution】
窗口显示如下，

如上图所示，
在“Search”窗口中输入“privacyIDEA”
选中【privacyIDEA】->【Add】

如上图所示，
把“privacyIDEA”的“Requirement”从“Disable”变更为“Required”
单击齿轮图标即【Settings】
窗口显示如下，

在“privacyIDEA config”中填写如下参数，

参数“Alias”填写“privacyidea.cmdschool.org”
参数“PrivacyIDEA URL”填写“https://privacyidea.cmdschool.org”
参数“Verify SSL”选择“On”
参数“Enable Trigger Challenge”选择“On”
参数“Send Password”选择“On”
参数“Enable Logging”选择“On”

其他的参数根据需求自行选取，单击【Save】保存退出即可

2.3 测试

2.3.1 使用浏览器登陆测试

https://websso.cmdschool.org/realms/cmdschool/account

2.3.2 故障排除

tail -f /var/log/keycloak/keycloak.log

参阅文档
=====================

privacyIDEA官方文档
——————
https://community.privacyidea.org/t/how-to-use-keycloak-with-privacyidea/1132
https://github.com/privacyidea/keycloak-provider

Versatile 2FA Single Sign-On with Keycloak and privacyIDEA

keyCloak官方文档
—————-
https://www.keycloak.org/docs/latest/server_admin/index.html#configuring-authentication_server_administration_guide
https://www.keycloak.org/docs/latest/server_admin/index.html#_identity_broker_post_login_flow