Release notes for lightweight access tokens and group together relate… (#28622)

closes #28460

Signed-off-by: mposolda <mposolda@gmail.com>


Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>

docs/documentation/release_notes/topics/25_0_0.adoc

@@ -53,6 +53,17 @@ expired. Now for the case when user is already logged-in in one browser tab and
 application with an OIDC/SAML error, so the client application can immediately retry authentication, which should usually automatically log in the application because of the SSO session. For more
 details, see link:{adminguide_link}#_authentication-sessions[{adminguide_name} authentication sessions].
 
+= Lightweight access token to be even more lightweight
+
+In previous releases, the support for lightweight access token was added. In this release, we managed to remove even more built-in claims from the lightweight access token. The claims are added
+by protocol mappers. Some of them affect even the regular access tokens or ID tokens as they were not strictly required by the OIDC specification.
+
+* Claims `sub` and `auth_time` are added by protocol mappers now, which are configured by default on the new client scope `basic`, which is added automatically to all the clients. The claims are still added to the ID token and access token as before, but not to lightweight access token.
+* Claim `nonce` is added only to the ID token now.  It is not added to a regular access token or lightweight access token. For backwards compatibility, you can add this claim to an access token by protocol mapper, which needs to be explicitly configured.
+* Claim `session_state` is not added to any token now. It is still possible to add it by protocol mapper if needed. There is still the other dedicated claim `sid` supported by the specification, which was available in previous versions as well and which has exactly the same value.
+
+For more details, see the link:{upgradingguide_link}[{upgradingguide_name}]..
+
 = Password policy for check if password contains Username
 
 Keycloak supports a new password policy that allows you to deny user passwords which contains the user username.

docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc

@@ -18,12 +18,6 @@ http_server_requests_seconds_sum{method="GET",outcome="SUCCESS",status="200",uri
 Use the new options `http-metrics-histograms-enabled` and `http-metrics-slos` to enable default histogram buckets or specific buckets for service level objectives (SLOs).
 Read more about histograms in the https://prometheus.io/docs/concepts/metric_types/#histogram[Prometheus documentation about histograms] on how to use the additional metrics series provided in `http_server_requests_seconds_bucket`.
 
-= Nonce claim is only added to the ID token
-
-The nonce claim is now only added to the ID token strictly following the OpenID Connect Core 1.0 specification. As indicated in the specification, the claim is compulsory inside the https://openid.net/specs/openid-connect-core-1_0.html#IDToken[ID token] when the same parameter was sent in the authorization request. The specification also recommends to not add the `nonce` after a https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokenResponse[refresh request]. Previously, the claim was set to all the tokens (Access, Refresh and ID) in all the responses (refresh included).
-
-A new `Nonce backwards compatible` mapper is also included in the software that can be assigned to client scopes to revert to the old behavior. For example, the JS adapter checked the returned `nonce` claim in all the tokens before fixing issue https://github.com/keycloak/keycloak/issues/26651[#26651] in version 24.0.0. Therefore, if an old version of the JS adapter is used, the mapper should be added to the required clients by using client scopes.
-
 = Limiting memory usage when consuming HTTP responses
 
 In some scenarios like brokering Keycloak uses HTTP to talk to external servers.
@@ -83,6 +77,7 @@ The new client scope named `basic` is added as a realm "default" client scope an
 
 This scope contains preconfigured protocol mappers for the following claims:
 
+ * `sub` (See the details below in the dedicated section)
  * `auth_time`
 
 This provides additional help to reduce the number of claims in a lightweight access token, but also gives the chance to configure claims that were always added automatically.
@@ -107,7 +102,13 @@ Only in the case you are using `Pairwise subject identifier` mapper to map `sub`
 
 You can use the `Subject (sub)` mapper to configure the `sub` claim only for access token, lightweight access token, and introspection response. IDToken and Userinfo always contain `sub` claim.
 
-The mapper has no effects for service accounts, because no user session exists, and the`sub` claim is always added to the access token.
+The mapper has no effects for service accounts, because no user session exists, and the `sub` claim is always added to the access token.
+
+= Nonce claim is only added to the ID token
+
+The nonce claim is now only added to the ID token strictly following the OpenID Connect Core 1.0 specification. As indicated in the specification, the claim is compulsory inside the https://openid.net/specs/openid-connect-core-1_0.html#IDToken[ID token] when the same parameter was sent in the authorization request. The specification also recommends to not add the `nonce` after a https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokenResponse[refresh request]. Previously, the claim was set to all the tokens (Access, Refresh and ID) in all the responses (refresh included).
+
+A new `Nonce backwards compatible` mapper is also included in the software that can be assigned to client scopes to revert to the old behavior. For example, the JS adapter checked the returned `nonce` claim in all the tokens before fixing issue https://github.com/keycloak/keycloak/issues/26651[#26651] in version 24.0.0. Therefore, if an old version of the JS adapter is used, the mapper should be added to the required clients by using client scopes.
 
 = Changed `userId` for events related to refresh token
 
@@ -116,6 +117,17 @@ The reason for this change is that the value of the `sub` claim in the refresh t
 
 However a `refresh_token_sub` detail is now added as backwards compatibility to have info about the user in the case of missing userId in the `REFRESH_TOKEN_ERROR` event.
 
+= Using older javascript adapter
+
+If you use the latest {project_name} server with older versions of the javascript adapter in your applications, you may be affected by the token changes mentioned above as previous
+versions of javascript adapter rely on the claims, which were added by {project_name}, but not supported by the OIDC specification. This includes:
+
+* Adding the `Session State (session_state)` mapper in case of using the Keycloak Javascript adapter 24.0.3 or older
+* Adding the `Nonce backwards compatible` mapper in case of using a Keycloak Javascript adapter that is older than Keycloak 24
+
+You can add the protocol mappers directly to the corresponding client or to some client scope, which can be used by your client applications relying on older versions of the Keycloak Javascript adapter.
+Some more details are in the previous sections dedicated to `session_state` and `nonce` claims.
+
 = Default `http-pool-max-threads` reduced
 
 `http-pool-max-threads` if left unset will default to the greater of 50 or 4 x (available processors). Previously it defaulted to the greater of 200 or 8 x (available processors). Reducing the number or task threads for most usage scenarios will result in slightly higher performance due to less context switching among active threads.

services/src/main/java/org/keycloak/protocol/oidc/mappers/SHA256PairwiseSubMapper.java

@@ -58,7 +58,8 @@ public class SHA256PairwiseSubMapper extends AbstractPairwiseSubMapper {
 
     @Override
     public String getHelpText() {
-        return "Calculates a pairwise subject identifier using a salted sha-256 hash. See OpenID Connect specification for more info about pairwise subject identifiers.";
+        return "Calculates a pairwise subject identifier using a salted sha-256 hash and adds it to the 'sub' claim. It is recommended to remove built-in 'sub' mapper when this one is used. " +
+                "See OpenID Connect specification for more info about pairwise subject identifiers.";
     }
 
     @Override