Add refresh token mapper #45431

mdahm · 2026-01-14T12:57:41Z

mdahm
Jan 14, 2026

Description

Currently Keycloak supports only the possibility to transform an access or ID token using OIDCIDTokenMapper. Using the UI you may configure token mappers that allow to set claims, etc. in the generated access token. However, this is not possible for refresh tokens.

Our current project's specification mandates us to influence the way a refresh token is created upon a token exchange request (to set some claims, e.g.).
Thus, we suggest to provide an analogous mechanism to OIDCIDTokenMapper by introducing a OIDCRefreshTokenMapper.

The concrete reason is that currently there is no way to influence the claims of a refresh token generated by the TokenManager.AccessTokenResponseBuilder class.

To give an example:

I know that you can configure global values for a realm for expiration dates of tokens. But what we need to do is to set the expiration (i.e. "exp") on-the-fly to a dynamic value which is defined by some rule engine.

Goals

We suggest to introduce a new interface OIDCRefreshTokenMapper:

public interface OIDCRefreshTokenMapper {
  RefreshToken transformRefreshToken(
      RefreshToken token, ProtocolMapperModel mappingModel, KeycloakSession session,
      UserSessionModel userSession, ClientSessionContext clientSession
  );
}

and use it in the TokenManager class:

public AccessTokenResponseBuilder generateRefreshToken(...) {
      ...

            transformRefreshToken();

            return this;
        }

private void transformRefreshToken() {
      ProtocolMapperUtils.getSortedProtocolMappers(session, clientSessionCtx)
          .filter(entry -> entry.getValue() instanceof OIDCRefreshTokenMapper)
          .forEach(entry -> {
                var mapper = (OIDCRefreshTokenMapper) entry.getValue();

                refreshToken = mapper.transformRefreshToken(refreshToken, entry.getKey(), session, userSession, clientSessionCtx);
              }
          );
    }

Value Proposition

The feature wold close a logical gap that exists for some time. This will give us the necessary flexibility and allow for future extensions, such as custom claims in refresh tokens.

Alternate solution

Another, yet similar solution would be to apply any given OIDCIDTokenMapper to refresh tokens, too. But I'd rather distinguish the use cases clearly.

Links

In anticipatory obedience I already created an issue and a pull request 😊

gitreelike · 2026-02-20T07:45:41Z

gitreelike
Feb 20, 2026

I think a dynamic expiry for refresh tokens is necessary in some regulated environments. And since those 8000 requirements may vary quite a bit in how that expiry is determined, I don't think there would be a "one size fits all" solution to be implemented in keycloak. A simple mapper interface would be very helpful though.

I understand that refresh tokens are basically a keycloak internal matter but this would enable keycloak to be used in more cases.

Maybe this could be a private api? That would IMHO communicate the concept that messing with refresh tokens is dangerous.

0 replies

Navigation Menu

Repository navigation

Add refresh token mapper #45431

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Add refresh token mapper #45431

Uh oh!

Uh oh!

mdahm Jan 14, 2026

Description

Goals

Value Proposition

Alternate solution

Links

Replies: 1 comment

Uh oh!

gitreelike Feb 20, 2026

mdahm
Jan 14, 2026

gitreelike
Feb 20, 2026