keycloak~scope客户端模板的使用

scope为何物?

scope在oauth2中表示授权的范围,另外也可以理解为,根据认证时scope的参数,在构建jwt时,返回更多的信息;比如在keycloak中,你的可选scope(optional scope)中添加了address这个模板,当你通过/auth/realms/{realmId}/protocol/openid-connect/token进行认证时,你的参数scope中出现address,那么在生成的jwt token中,就会出现address这个内容,如图:

这种按需求构建jwt的方法就是client scope最大的作用,下面我们具体来说一下步骤。

客户端模板功能汇总

  1. 在客户端模板中,可以看到所有的模板列表
  2. 可直接为所有新加的客户端添加默认模板(Default Client Scopes)
  3. 可以在模板配置中,选择可选模板,这个功能与认证参数scope配合使用,根据scope参数来扩展jwt token的内容
  4. 通过继承AbstractOIDCProtocolMapper来扩展客户端模板

配置客户端模板

模板列表,如图:

默认客户端模板,添加可选的scope,如图:

认证请求时,添加scope参数,如openid,address等

  • openid:在jwt中添加id_token相关信息,即存放用户的基本信息的token。
  • address:在jwt中添加address属性,通过解析user_attribute中的street,locality,region等信息,来扩展jwt token。

自定义客户端模板

例如,希望写一个扩展,在token中输出用户昵称,但这个昵称是有业务逻辑的,通过复杂的逻辑计算出一个用户昵称,这时,需要你自定义一个模板

  1. 定义一个ExtensionNicknameMapper
public class ExtensionNicknameMapper
    extends AbstractOIDCProtocolMapper
    implements OIDCAccessTokenMapper, OIDCIDTokenMapper, UserInfoTokenMapper {

  public static final String CONFIG_NAME = "extensionNickname";//配置里的名称
  public static final String PROVIDER_ID = "oidc-extension-nick-name-mapper";
  private static final List<ProviderConfigProperty> configProperties = new ArrayList<ProviderConfigProperty>();
  private static final String NICKNAME = "nickname";

  static {
    configProperties.add(createConfigProperty(CONFIG_NAME, "Token申请名", "在jwt中的属性名称,默认nickname"));
    OIDCAttributeMapperHelper.addIncludeInTokensConfig(configProperties, ExtensionNicknameMapper.class);
  }

  protected static ProviderConfigProperty createConfigProperty(String claimName, String label, String help) {
    ProviderConfigProperty property = new ProviderConfigProperty();
    property.setName(claimName);
    property.setLabel(label);
    property.setHelpText(help);
    property.setType(ProviderConfigProperty.STRING_TYPE);
    return property;
  }

  @Override
  protected void setClaim(IDToken token, ProtocolMapperModel mappingModel, UserSessionModel userSession,
                          KeycloakSession keycloakSession, ClientSessionContext clientSessionCtx) {
  
      String nickname="";
       // 复杂的业务方法,计算出nickname变量的值
      token.setOtherClaims(tokenAttribute, nickname);
  }

  public List<ProviderConfigProperty> getConfigProperties() {
    return configProperties;
  }

  @Override
  public String getId() {
    return PROVIDER_ID;
  }

  @Override
  public String getDisplayType() {
    return "Extension Nickname";
  }

  @Override
  public String getDisplayCategory() {
    return TOKEN_MAPPER_CATEGORY;
  }

  @Override
  public String getHelpText() {
    return "Maps Extension Nickname claim.";
  }

}

  1. 将ExtensionNicknameMapper添加到Jboss的SPI中
  • /resources/META-INF/services/org.keycloak.protocol.ProtocolMapper文件
your.package.ExtensionNicknameMapper
  1. 在keycloak管理后台,添加一个新的模板,然后在模板里的mapper选项卡中,添加一个新的mapper中选你的ExtensionNicknameMapper

好了,到这里,keycloak的client scope(客户端模板)就介绍完了,希望对各位有所帮助。