How to properly inject custom claims from dynamic scopes into Keycloak JWT using a custom Protocol Mapper SPI? #40109

apolope · 2025-05-30T18:33:52Z

apolope
May 30, 2025

I need to have a Springboot service — an orchestrator — perform login with an injection of information that will be embedded into the Keycloak JWT.

The login request will arrive at this orchestrator, which will query a database for some information and then pass it to another microservice to perform authentication with the enriched data.

Example:
The microservice-authenticate has an endpoint that receives:

{
    "username": "estoquista",
    "password": "estoquista"
}

It forwards this to the microservice-orchestrator, which queries the database and injects additional information for the next microservice:

{
    "username": "estoquista",
    "password": "estoquista",
    "empresaId": "2",
    "licenses": [
        "stock",
        "pos"
    ]
}

The microservice-authorization will be responsible for authenticating against Keycloak and injecting this data into the JWT.

I tried the following approach:

private AccessTokenResponse getAccessTokenResponse(
            String username,
            String password,
            String realm,
            String clientId,
            boolean publicClient,
            String clientSecret,
            List<String> licencas
    ) {
        KeycloakBuilder builder = KeycloakBuilder.builder()
                .serverUrl(authServerUrl)
                .realm(realm)
                .clientId(clientId)
                .username(username)
                .password(password)
                .grantType(OAuth2Constants.PASSWORD);

        if (!publicClient) {
            builder.clientSecret(clientSecret);
        }

        String scopeParam = "openid"; 
        if (licencas != null && !licencas.isEmpty()) {
            String licencasScope = licencas.stream()
                    .map(lic -> "licenca:" + lic.trim().replace(" ", "_"))
                    .collect(Collectors.joining(" "));
            scopeParam += " " + licencasScope;
        }
        builder.scope(scopeParam);

        AccessTokenResponse tokenResponse;
        try (Keycloak keycloak = builder.build()) {
            tokenResponse = keycloak.tokenManager().getAccessToken();
        }
        return tokenResponse;
    }

I also created a SPI (Service Provider Interface) to organize this information but was not successful.

public class LicencasScopeMapper extends AbstractOIDCProtocolMapper implements OIDCAccessTokenMapper, OIDCIDTokenMapper, UserInfoTokenMapper {

    private static final List<ProviderConfigProperty> configProperties = new ArrayList<>();
    static {
        OIDCAttributeMapperHelper.addTokenClaimNameConfig(configProperties);
        OIDCAttributeMapperHelper.addIncludeInTokensConfig(configProperties, LicencasScopeMapper.class);
    }

    public static final String PROVIDER_ID = "oidc-licencas-scope-mapper";
    private static final String LICENCE_SCOPE_PREFIX = "licenca:";
    private static final String TOKEN_CLAIM_NAME = "licencas";

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

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

    @Override
    public String getDisplayType() {
        return "Licenças from Scope Mapper";
    }

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

    @Override
    public String getHelpText() {
        return "Maps custom 'licenca:*' scopes to a token claim.";
    }

    @Override
    protected void setClaim(IDToken token, ProtocolMapperModel mappingModel, UserSessionModel userSession, KeycloakSession keycloakSession,
                            ClientSessionContext clientSessionCtx) {

        String claimName = TOKEN_CLAIM_NAME;

        String scopeParam = clientSessionCtx.getClientSession().getNote(OIDCLoginProtocol.SCOPE_PARAM);
        if (scopeParam == null) {
            scopeParam = keycloakSession.getContext().getUri().getQueryParameters().getFirst(OIDCLoginProtocol.SCOPE_PARAM);
        }


        List<String> licencas = new ArrayList<>();
        if (scopeParam != null && !scopeParam.isEmpty()) {
            licencas = Arrays.stream(scopeParam.split(" "))
                    .filter(s -> s.startsWith(LICENCE_SCOPE_PREFIX))
                    .map(s -> s.substring(LICENCE_SCOPE_PREFIX.length()))
                    .filter(s -> !s.isEmpty())
                    .collect(Collectors.toList());
        }

        if (!licencas.isEmpty()) {
            token.getOtherClaims().put(claimName, licencas);
        }
    }

    public static ProtocolMapperModel create(String name, String tokenClaimName,
                                             boolean consentRequired, String consentText,
                                             boolean accessToken, boolean idToken, boolean userInfo) {
        ProtocolMapperModel mapper = new ProtocolMapperModel();
        mapper.setName(name);
        mapper.setProtocolMapper(PROVIDER_ID);
        mapper.setProtocol(OIDCLoginProtocol.LOGIN_PROTOCOL);
        mapper.setConfig(mapper.getConfig() == null ? new java.util.HashMap<>() : mapper.getConfig()); // Inicializa se nulo
        mapper.getConfig().put(OIDCAttributeMapperHelper.INCLUDE_IN_ACCESS_TOKEN, Boolean.toString(accessToken));
        mapper.getConfig().put(OIDCAttributeMapperHelper.INCLUDE_IN_ID_TOKEN, Boolean.toString(idToken));
        mapper.getConfig().put(OIDCAttributeMapperHelper.INCLUDE_IN_USERINFO, Boolean.toString(userInfo));
        return mapper;
    }
}

Maybe you didn't configure it correctly in keycloak.

Navigation Menu

Repository navigation

How to properly inject custom claims from dynamic scopes into Keycloak JWT using a custom Protocol Mapper SPI? #40109

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

How to properly inject custom claims from dynamic scopes into Keycloak JWT using a custom Protocol Mapper SPI? #40109

Uh oh!

Uh oh!

apolope May 30, 2025

Replies: 0 comments

apolope
May 30, 2025