如何在Keycloak中限制WebAuthn仅使用指定YubiKey？

需求合理性 #

这个需求完全合理，属于设备级强身份管控的范畴——既然是团队内部专用设备，限制仅允许预先分发的YubiKey注册/认证，能彻底杜绝外部同品牌设备的非法接入，比单纯的AAGUID白名单安全性更高，非常适合内部协作场景。

可行性与实现方法 #

完全可以实现，核心思路是通过YubiKey硬件唯一序列号或WebAuthn注册生成的凭证ID做精准校验，结合Keycloak的扩展能力完成限制。以下是具体落地步骤：

1. 收集授权YubiKey的唯一标识

优先采用YubiKey硬件序列号（每个YubiKey的硬件唯一ID，不随注册操作改变）：

• 用YubiKey Manager工具连接每个分发的YubiKey，直接查看并导出序列号（格式通常为数字串）
• 将这些序列号整理成白名单，可存储在Keycloak的Realm配置属性中，或单独的数据库表内

2. 通过Keycloak扩展实现校验

根据技术能力选择两种扩展方式：

方式一：编写自定义WebAuthn Authenticator（Java代码）

这是最稳定的方案：

• 创建Java项目，引入Keycloak核心依赖（keycloak-core、keycloak-server-spi等）
• 继承Keycloak原生的WebAuthnAuthenticator，重写认证/注册逻辑：
  • 注册流程：解析WebAuthn的Attestation Object，提取YubiKey序列号，检查是否在白名单内，不在则拒绝注册
  • 认证流程：解析WebAuthn断言（Assertion）中的设备信息，提取序列号做白名单校验，不匹配则返回认证失败
• 打包为JAR包，放入Keycloak的providers目录，重启后在Realm的认证流程中启用自定义WebAuthn认证器

方式二：用Keycloak脚本扩展快速实现（无需编译代码）

若不想编写Java代码，可使用Keycloak的脚本Authenticator：

• 先开启Keycloak脚本功能：在配置文件（keycloak.conf或standalone.xml）中设置spi-scripting-enabled=true
• 在Realm的认证流程中添加「Script Authenticator」，编写Groovy/JavaScript脚本：
  • 脚本中获取WebAuthn凭证数据，调用Yubico的WebAuthn解析库提取YubiKey序列号
  • 对比预定义白名单（可直接写在脚本里，或从Realm属性读取），不匹配则抛出认证异常

3. 关键注意点

• 序列号提取：不同型号的YubiKey在WebAuthn数据中携带序列号的位置可能有差异，需测试验证提取逻辑的准确性
• 白名单维护：建议将白名单存储在可动态修改的位置（如Realm属性或数据库），避免每次更新都修改代码或重启Keycloak
• 兼容性：测试主流浏览器（Chrome、Firefox等）和不同版本YubiKey的适配情况，确保校验逻辑不影响正常流程

内容的提问来源于stack exchange，提问作者Ottobus