Release notes for support application/jwt response in token introspec… (#30105)

closes #30104

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

@@ -119,6 +119,12 @@ by protocol mappers. Some of them affect even the regular access tokens or ID to
 
 For more details, see the link:{upgradingguide_link}[{upgradingguide_name}]..
 
+= Support for application/jwt media-type in token introspection endpoint
+
+You can use the HTTP Header `Accept: application/jwt` when invoking a token introspection endpoint. When enabled for a particular client, it returns a claim `jwt` from the
+token introspection endpoint with the full JWT access token, which can be useful especially for the use-cases when the client calling introspection endpoint used lightweight access
+token. Thanks to https://github.com/thomasdarimont[Thomas Darimont] for the contribution.
+
 = 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/securing_apps/topics/oidc/available-endpoints.adoc

@@ -78,6 +78,12 @@ This endpoint can only be invoked by confidential clients.
 
 For more details on how to invoke on this endpoint, see https://datatracker.ietf.org/doc/html/rfc7662[OAuth 2.0 Token Introspection specification].
 
+====== Introspection endpoint triggered with application/jwt header
+
+You can invoke an introspection endpoint with the HTTP header `Accept: application/jwt` instead of `Accept: application/json`. In case of `application/jwt`, the response
+may contain the additional claim `jwt` with the full JWT access token, which can be useful especially if the token to be introspected was a link:{adminguide_link}#_using_lightweight_access_token[lightweight access token]. This requires that you enable `Support JWT claim in Introspection Response`
+on the client advanced settings, which triggers the token introspection.
+
 ===== Dynamic Client Registration endpoint
 ....
 /realms/{realm-name}/clients-registrations/openid-connect

docs/documentation/server_admin/topics/clients/con-protocol-mappers.adoc

@@ -4,7 +4,7 @@
 = OIDC token and SAML assertion mappings
 
 [role="_abstract"]
-Applications receiving ID tokens, access tokens, or SAML assertions may require different roles and user metadata. 
+Applications receiving ID tokens, access tokens, or SAML assertions may require different roles and user metadata.
 
 You can use {project_name} to:
 
@@ -17,7 +17,7 @@ You perform these actions in the *Mappers* tab in the Admin Console.
 .Mappers tab
 image:images/mappers-oidc.png[]
 
-New clients do not have built-in mappers but they can inherit some mappers from client scopes. See the <<_client_scopes, client scopes section>> for more details. 
+New clients do not have built-in mappers, but they can inherit some mappers from client scopes. See the <<_client_scopes, client scopes section>> for more details.
 
 Protocol mappers map items (such as an email address, for example) to
 a specific claim in the identity and access token. The function of a mapper should be self-explanatory from its name. You  add pre-configured mappers by clicking *Add Builtin*.
@@ -89,3 +89,6 @@ Information that cannot be removed from a lightweight access token::
 
 Using a lightweight access token in {project_name}::
   By applying `use-lightweight-access-token` executor of <<_client_policies, client policies>> to a client, the client can receive a lightweight access token instead of an access token. The lightweight access token contains a claim controlled by a protocol mapper where its setting `Add to lightweight access token`(default OFF) is turned ON. Also, by turning ON its setting `Add to token introspection` of the protocol mapper, the client can obtain the claim by sending the access token to {project_name}'s token introspection endpoint.
+
+Introspection endpoint::
+  In some cases, it might be useful to trigger the token introspection endpoint with the HTTP header `Accept: application/jwt` instead of `Accept: application/json`, which can be useful especially for lightweight access tokens. See the details in the link:{adapterguide_link}#_token_introspection_endpoint[Token Introspection endpoint] section.