keycloak~scope客户端模板的使用

技术分享 1年前 (2024-09-04) 0 999+

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最大的作用，下面我们具体来说一下步骤。

客户端模板功能汇总

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

配置客户端模板

模板列表，如图：

默认客户端模板和可选客户端模板

默认客户端模板（Default Client Scopes ）
可选客户端模板（Optional Client Scopes ）
以上两种模板互斥，即，当一个模板select-user被选择为“默认客户端模板”后，它将会在“可选客户端模板”列表中消失，反之，亦然。

可选客户端模板，可以添加address,openid来对原有jwt进行扩展，如图：

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

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

自定义客户端模板

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

定义一个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.";   }  }