Angular应用向Keycloak传递登录额外参数的实现方法

1. login方法传入自定义参数的写法 #

调用Keycloak实例的login方法时，将所有自定义参数放在配置对象的extras字段中即可，keycloak-js会自动将这些参数拼接为授权请求的查询参数发送到服务端，示例代码如下：

this._keycloakInstance.login({
  redirectUri: 'http://localhost:4200/callback',
  scope: 'openid',
  // 自定义参数统一放在extras对象下
  extras: {
    tempId: 'abc'
  }
});

注意：不要将自定义参数平级写在login配置的最外层，非OIDC标准的平级属性会被keycloak-js过滤，不会携带到请求中。如果使用v12以下的老旧版本keycloak-js没有extras字段，可以通过as any类型断言绕过校验直接传参，但优先推荐升级版本使用标准extras写法。

2. Keycloak端Script Mapper获取参数的方式 #

根据请求场景不同，取值方式有区别：

• 直接请求token端点场景（如Postman测试）
  这类场景下参数直接放在token请求的x-www-form-urlencoded表单中，在Script Mapper脚本中可以直接通过上下文读取请求表单参数：

  // 从请求表单中读取自定义参数
  var tempId = keycloakSession.getContext().getHttpRequest().getDecodedFormParameters().getFirst("tempId");
  

• 前端正常走授权码流程登录场景
  这种场景下自定义参数是携带在授权（/authorize）请求中的，Keycloak默认不会将非标准参数从授权请求透传到token端点上下文，需要先在管理后台做简单配置：
  • 打开对应客户端的详情页，切换到「客户端范围」标签
  • 找到该客户端对应的专用范围（命名格式为{客户端ID}-dedicated），进入范围配置页
  • 切换到「Mappers」标签，选择添加Mapper类型为「用户会话注释（User Session Note）」
  • 配置项填写：
    • 名称：自定义即可，比如tempId参数映射
    • 用户会话注释：填写你传入的参数名tempId
    • 令牌声明名称：可和参数名保持一致填tempId
    • 不需要将参数直接写入令牌的话，取消勾选所有「添加到XX令牌」的选项即可
      配置完成后Keycloak会自动把授权请求中的tempId存入用户会话注释，在Script Mapper中可以直接通过下面的代码取值：

  // 从用户会话中读取前端传入的自定义参数
  var tempId = userSession.getNote("tempId");
  

之前尝试通过acr字段传参不符合预期，是因为acr是OIDC协议标准字段，Keycloak会对它做格式校验和特殊的认证上下文处理，不适合用来传递业务自定义参数。

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