In Keycloak, there are features that rely on modifying token contents. We have MTLS-HoK that adds cnf section to access + refresh tokens and introspection response; we will soon have DPoP that does the same plus ID tokens and token response (token_type=DPoP); we might have HTTPSig one day that would do something similar. For example, DPoP does the following for token response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
 "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IkJlQUxrYiJ9...",
 "token_type": "DPoP", // modified by DPoP
 "expires_in": 2677,
 "refresh_token": "Q..Zkm29lexi8VnWg2zPW1x-tgGad0Ibc3s3EwM_Ni4-g"
}

and the following for access token:

{
  "sub": "...",
  ...,
  "cnf": {"jkt":"0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"} // added by DPoP
}

Currently, all the token manipulations are hardcoded into TokenEndpoint / TokenManager. On the other hand, there is an existing mechanism that is suited for the same, namely protocol mappers (OIDCAccessTokenMapper, OIDCAccessTokenResponseMapper, OIDCIDTokenMapper, and eventually OIDCIntrospectionResponseMapper).

It would be nice if features like MTLS and DPoP could use protocol mappers as helpers. However, mappers need to be configured by the admin beforehand. Even if MTLS and DPoP manage to add their respective mappers programmatically, the admin could remove them by mistake. The proposal is to introduce the concept of system (implicit?) mappers, that would be different from the traditional mappers in the following aspects:

• system mappers will be implicitly active for every realm and every client;
• system mappers won't be visible in the admin UI;
• system mappers won't have dedicated configuration, but will rather obtain it from the client and/or system config, and will retrieve their runtime data from KeycloakSession.

This way, system mappers won't have corresponding entries in PROTOCOL_MAPPER / PROTOCOL_MAPPER_CONFIG. Alternatively, we can keep just number 2 (invisibility) and let the software components like MTLS and DPoP set up the mappers programmatically. In this case, database entries will be created as usual.

The rationale behind this proposal is to allow reuse of the existing mechanisms and decouple token binding from TokenEndpoint / TokenManager (which already contain a fair amount of code), thus making the codebase more manageable.

@tnorimat @mposolda