JSON Web Token (JWT) Response for OAuth Token Introspection
Extracted elements (27)
Introspection response members are encapsulated in a dedicated 'token_introspection' JWT claim rather than placed at the top level to prevent conflict and confusion with top-level JWT claims that may bear the same name (e.g., sub, exp, scope), thereby also preventing misuse of the JWT as an access token.
RFC 7662 introspection responses are plain JSON objects, providing no cryptographic assurance. This specification adds a signed JWT response for use cases where the resource server requires stronger assurance that the authorization server issued the introspection response, including cases where the AS assumes liability for the response content.
One way to manage RS credentials is to use dynamic client registration (RFC 7591), treating each RS as an OAuth client. The AS should maintain at minimum a client_id and token_endpoint_auth_method, plus complementary authentication metadata such as jwks or client_secret.
An AS compliant with this specification MUST refuse to serve introspection requests that don't authenticate the caller and return an HTTP status code 400, to prevent downgrading to plain RFC 7662 behavior and ensure token data is released only to legitimate recipients.
An RS requests a JWT introspection response by sending an introspection request with an Accept HTTP header field set to 'application/token-introspection+jwt'. The AS MUST authenticate the caller at the token introspection endpoint.
If the access token is invalid, expired, revoked, or not intended for the calling RS, the AS MUST set the active member in token_introspection to false and MUST NOT include other members.
If the introspection response is both signed and encrypted, it MUST be a Nested JWT as defined in RFC 7519.
The AS MUST be able to determine whether an RS is the audience for a particular access token and what data it is entitled to receive; otherwise the RS is not authorized to obtain data for the access token.
The AS MUST ensure the release of any privacy-sensitive data within the token_introspection claim is legally based, with RS-specific policy determining what identity claims to return when the AS acts as a provider of resource owner identity claims.
The AS MUST restrict the use of client credentials by an RS to the calls it requires; for example, the AS MAY restrict such a client to call only the token introspection endpoint.
The AS MUST retain the scope of the legal basis with the access token (e.g., in the scope value), MUST authenticate the RS, and MUST determine the data an RS is allowed to receive based on the RS's identity and suitable token data.
The authorization server MUST be able to identify, authenticate, and authorize resource servers in order to process introspection requests in a secure and privacy-preserving manner.
The introspection_encrypted_response_enc parameter MUST NOT be specified without also setting introspection_encrypted_response_alg.
The JWT SHOULD NOT include the sub and exp claims at the top level, as an additional measure to prevent misuse of the JWT as an access token (cross-JWT confusion).
Token introspection response parameter names intended for use across domains MUST be registered in the 'OAuth Token Introspection Response' registry defined by RFC 7662.
A token introspection request reveals to the AS when the client (and potentially the user) is accessing the RS. If this timing disclosure is not acceptable, implementers MUST use other means to relay access token data, such as embedding the needed data directly within the access token.
The introspection response may transfer personal identifiable information (PII) from the AS to the RS. The AS MUST conform to legal and jurisdictional constraints before releasing data to a particular RS, typically established via explicit user consent, out-of-band contracts, or 1st-party service terms.
The JWT introspection response MUST include four top-level claims: 'iss' (AS issuer URL), 'aud' (the RS receiving the response), 'iat' (response creation time), and 'token_introspection' (a JSON object containing the RFC 7662 introspection response members).
Three optional AS metadata parameters are introduced: 'introspection_signing_alg_values_supported', 'introspection_encryption_alg_values_supported', and 'introspection_encryption_enc_values_supported', each as JSON arrays of supported algorithm identifiers, published via RFC 8414 AS metadata.
Three optional client metadata parameters are introduced for RS registration: 'introspection_signed_response_alg' (JWS algorithm, default RS256), 'introspection_encrypted_response_alg' (JWE key encryption algorithm, default no encryption), and 'introspection_encrypted_response_enc' (JWE content encryption algorithm, default A128CBC-HS256 when encryption is used).
The JWT claim name 'token_introspection' registered in the IANA 'JSON Web Token (JWT)' registry with description 'Token introspection response', per Section 5 of RFC 9701.
The media type 'application/token-introspection+jwt' registered in the IANA 'Media Types' registry to indicate that content is a token introspection response in JWT format (binary encoding, base64url-encoded values separated by '.' characters).
Three entries registered in the IANA 'OAuth Authorization Server Metadata' registry: introspection_signing_alg_values_supported, introspection_encryption_alg_values_supported, and introspection_encryption_enc_values_supported (Section 7 of RFC 9701).
Three entries registered in the IANA 'OAuth Dynamic Client Registration Metadata' registry: introspection_signed_response_alg, introspection_encrypted_response_alg, and introspection_encrypted_response_enc (Section 6 of RFC 9701).
Cross-JWT confusion: an attacker could pass a JWT introspection response as an access token to the RS, since iss and aud may resemble those of a JWT access token. Countermeasures are the 'token-introspection+jwt' typ header and encapsulation of introspection claims inside token_introspection; RS MUST check the typ header and verify all minimally required access token claims are present.
To prevent token data leakage, the AS MUST use TLS 1.2 or higher per BCP 195 (RFC 9325), and MUST require all requests to the introspection endpoint to be authenticated, preventing introspection by parties that are not the intended consumer.
The introspection endpoint responds with Content-Type 'application/token-introspection+jwt' and the JWT typ header parameter set to 'token-introspection+jwt'. The JWT is a base64url-encoded structure per RFC 7519.