From 193439788efcb2e719d07958bde571b3aca3c857 Mon Sep 17 00:00:00 2001
From: Marek Posolda <mposolda@gmail.com>
Date: Tue, 4 Jun 2024 06:49:13 +0200
Subject: [PATCH] =?UTF-8?q?Release=20notes=20for=20support=20application/j?=
 =?UTF-8?q?wt=20response=20in=20token=20introspec=E2=80=A6=20(#30105)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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        | 6 ++++++
 .../securing_apps/topics/oidc/available-endpoints.adoc     | 6 ++++++
 .../server_admin/topics/clients/con-protocol-mappers.adoc  | 7 +++++--
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/docs/documentation/release_notes/topics/25_0_0.adoc b/docs/documentation/release_notes/topics/25_0_0.adoc
index 57539307c0c1..8aa6e6b3603d 100644
--- a/docs/documentation/release_notes/topics/25_0_0.adoc
+++ b/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.
diff --git a/docs/documentation/securing_apps/topics/oidc/available-endpoints.adoc b/docs/documentation/securing_apps/topics/oidc/available-endpoints.adoc
index 333c1ef25cb2..51a287c8973b 100644
--- a/docs/documentation/securing_apps/topics/oidc/available-endpoints.adoc
+++ b/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
diff --git a/docs/documentation/server_admin/topics/clients/con-protocol-mappers.adoc b/docs/documentation/server_admin/topics/clients/con-protocol-mappers.adoc
index 7e910a4fd5df..af6fc83320a0 100644
--- a/docs/documentation/server_admin/topics/clients/con-protocol-mappers.adoc
+++ b/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.