如何配置Keycloak用AES-128-GCM替代AES-128-CBC加密SAML断言

一、创建AES-128-GCM专用密钥 #

• 登录Keycloak控制台，进入目标领域（比如你使用的master领域）
• 左侧菜单选择「Realm Settings」→「Keys」标签页
• 点击「Add Provider」按钮，选择「AES」作为密钥类型
• 在配置表单中填写以下内容：
  • Key Name：自定义名称（例如aes-128-gcm-key）
  • Algorithm：选择AES（Keycloak下拉选项仅显示基础算法，后续通过客户端配置指定GCM模式）
  • Key Size：设置为128，确保是AES-128规格
  • Provider ID：自定义标识（例如aes-gcm-provider）
  • Priority：设为高于默认AES密钥的数值（比如100），确保Keycloak优先使用该密钥
  • 勾选「Active」和「Enabled」选项
  • 点击「Save」完成密钥创建

二、配置SAML客户端的加密算法 #

这是切换到GCM模式的核心步骤：

• 左侧菜单选择「Clients」，找到你的SAML服务提供商客户端
• 进入客户端的「Settings」标签页，滚动到「Fine Grain SAML Configuration」区域，点击「Edit」
• 在弹出的配置界面中，修改以下字段：
  • Assertion Encryption Algorithm：直接选择AES_128_GCM（若下拉列表无此选项，手动输入URI：http://www.w3.org/2009/xmlenc11#aes128-gcm）
  • Key Transport Algorithm：保持默认或根据需求选择（例如RSA-OAEP）
• 同时确认「Settings」标签页的「SAML Settings」区域中，「Encrypt Assertions」选项已开启
• 保存客户端配置

三、验证配置效果 #

• 重新发起SSO流程，用SAML-Tracer捕获SAML响应
• 查看加密断言的<xenc:EncryptionMethod>节点，确认其Algorithm属性值为http://www.w3.org/2009/xmlenc11#aes128-gcm，即为配置成功

常见问题排查 #

• 若下拉无AES-128-GCM选项，手动输入上述URI即可，Keycloak可直接识别该加密算法
• 确保新创建的AES密钥优先级高于其他AES密钥，避免Keycloak fallback到默认的CBC模式密钥
• 确认你的服务提供商应用支持AES-GCM解密：GCM模式需要处理额外的认证标签（Tag），需在解密逻辑中包含该验证步骤

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