token_
Registry Context
A top-level JWT claim containing the OAuth token introspection response as a dedicated JSON object.
Technical Summary
RFC 9701 requires JWT token introspection responses to contain a top-level `token_introspection` claim whose value is a JSON object containing the introspection response members specified by RFC 7662, Section 2.2.
When Used
When an introspection endpoint returns a JWT token introspection response.
Normative Requirements
Authorization servers
RFC 9701 - Section 5
include other members in `token_introspection`.
Condition: If the access token is invalid, expired, revoked, or not intended for the calling resource server.
For these conditions, the authorization server MUST NOT include other members.
RFC 9701 - Section 5
include `token_introspection` as a top-level JWT claim.
Condition: When returning a JWT token introspection response.
The JWT MUST include the listed top-level claims, including `token_introspection`.
RFC 9701 - Section 5
set the `active` member in `token_introspection` to false.
Condition: If the access token is invalid, expired, revoked, or not intended for the calling resource server.
For these conditions, the authorization server MUST set `active` to false.
RFC 9701 - Section 5
ensure that the release of privacy-sensitive data has a legal basis.
Condition: When acting as a provider of resource owner identity claims to the resource server.
The AS MUST ensure the release of privacy-sensitive data is legally based.
RFC 7662 - Section 2.2
include `active` as a boolean indicator of whether the presented token is currently active.
Condition: When producing the introspection response object contained by `token_introspection`.
RFC 7662 defines `active` as REQUIRED and as a boolean indicator.
RFC 9701 - Section 5
include `sub` or `exp` as top-level JWT claims.
Condition: When returning a JWT token introspection response.
The JWT SHOULD NOT include top-level `sub` and `exp` claims to reduce misuse as an access token.
RFC 9701 - Section 5
narrow the `scope` value to scopes relevant to the particular resource server.
Condition: When returning a `scope` value in `token_introspection`.
The AS SHOULD narrow the scope value to scopes relevant to the particular RS.
RFC 9701 - Section 5
include other top-level JWT claims.
Condition: When returning a JWT token introspection response.
The JWT MAY include other claims, including registered JWT claims.
implementation
RFC 9701 - Section 5
extend the introspection response with service-specific claims as members of `token_introspection`.
Implementations MAY extend the response with service-specific claims.
registrant
RFC 9701 - Section 5
register token introspection response parameter names in the OAuth Token Introspection Response registry.
Condition: When the names are intended for use across domains.
Response parameter names intended for cross-domain use MUST be registered.
Validation Guidance
Report an error when a JWT token introspection response lacks a top-level `token_introspection` claim or its value is not a JSON object.
Require `token_introspection.active` to be a boolean.
For an invalid, expired, revoked, or wrong-audience token, verify that `active` is false and is the only member of `token_introspection`.
Warn when the returned `scope` value is not narrowed to scopes relevant to the receiving resource server.
Ensure service-specific introspection response claims are members of `token_introspection`, rather than top-level JWT claims representing introspection data.
Verify that response parameter names intended for cross-domain use are registered in the OAuth Token Introspection Response registry.
Review the release of privacy-sensitive identity claims for an applicable legal basis.
Warn when `sub` or `exp` appears as a top-level claim in the introspection JWT rather than solely within `token_introspection`.
Security Notes
RFC 9701 - Section 8.1
The dedicated `token_introspection` object, together with the `token-introspection+jwt` type header, is intended to prevent substitution of an introspection response as an access token.
Reference
Details
- Entry Id
token_introspection - Claim Name
token_introspection - Claim Description
Token introspection response- Change Controller
IETF- Reference
RFC9701 - Section 5