rfc9701.original   rfc9701.txt 
Open Authentication Protocol T. Lodderstedt, Ed. Internet Engineering Task Force (IETF) T. Lodderstedt, Ed.
Internet-Draft yes.com AG Request for Comments: 9701 yes.com AG
Intended status: Standards Track V. Dzhuvinov Category: Standards Track V. Dzhuvinov
Expires: 8 March 2022 Connect2id Ltd. ISSN: 2070-1721 Connect2id Ltd.
4 September 2021 December 2024
JWT Response for OAuth Token Introspection JSON Web Token (JWT) Response for OAuth Token Introspection
draft-ietf-oauth-jwt-introspection-response-12
Abstract Abstract
This specification proposes an additional JSON Web Token (JWT) This specification proposes an additional response secured by JSON
secured response for OAuth 2.0 Token Introspection. Web Token (JWT) for OAuth 2.0 Token Introspection.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 8 March 2022. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9701.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Simplified BSD License text to this document. Code Components extracted from this document must
as described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Simplified BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction
2. Requirements Notation and Conventions . . . . . . . . . . . . 3 2. Requirements Notation
3. Resource Server Management . . . . . . . . . . . . . . . . . 3 3. Resource Server Management
4. Requesting a JWT Response . . . . . . . . . . . . . . . . . . 4 4. Requesting a JWT Response
5. JWT Response . . . . . . . . . . . . . . . . . . . . . . . . 4 5. JWT Response
6. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 7 6. Client Metadata
7. Authorization Server Metadata . . . . . . . . . . . . . . . . 8 7. Authorization Server Metadata
8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 8. Security Considerations
8.1. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 9 8.1. Cross-JWT Confusion
8.2. Token Data Leakage . . . . . . . . . . . . . . . . . . . 9 8.2. Token Data Leakage
9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 9 9. Privacy Considerations
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 10. IANA Considerations
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 10.1. OAuth Dynamic Client Registration Metadata Registration
11.1. OAuth Dynamic Client Registration Metadata 10.1.1. Registry Contents
Registration . . . . . . . . . . . . . . . . . . . . . . 10 10.2. OAuth Authorization Server Metadata Registration
11.1.1. Registry Contents . . . . . . . . . . . . . . . . . 10 10.2.1. Registry Contents
11.2. OAuth Authorization Server Metadata Registration . . . . 11 10.3. Media Type Registration
11.2.1. Registry Contents . . . . . . . . . . . . . . . . . 11 10.3.1. Registry Contents
11.3. Media Type Registration . . . . . . . . . . . . . . . . 12 10.4. JWT Claim Registration
11.3.1. Registry Contents . . . . . . . . . . . . . . . . . 12 10.4.1. Registry Contents
11.4. JWT Claim Registration . . . . . . . . . . . . . . . . . 13 11. References
11.4.1. Registry Contents . . . . . . . . . . . . . . . . . 13 11.1. Normative References
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 11.2. Informative References
12.1. Normative References . . . . . . . . . . . . . . . . . . 13 Acknowledgements
12.2. Informative References . . . . . . . . . . . . . . . . . 15 Authors' Addresses
Appendix A. Document History . . . . . . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction 1. Introduction
OAuth 2.0 Token Introspection [RFC7662] specifies a method for a "OAuth 2.0 Token Introspection" [RFC7662] specifies a method for a
protected resource to query an OAuth 2.0 authorization server to protected resource to query an OAuth 2.0 authorization server to
determine the state of an access token and obtain data associated determine the state of an access token and obtain data associated
with the access token. This enables deployments to implement opaque with the access token. This enables deployments to implement opaque
access tokens in an interoperable way. access tokens in an interoperable way.
The introspection response, as specified in OAuth 2.0 Token The introspection response, as specified in "OAuth 2.0 Token
Introspection [RFC7662], is a plain JSON object. However, there are Introspection" [RFC7662], is a plain JSON object. However, there are
use cases where the resource server requires stronger assurance that use cases where the resource server requires stronger assurance that
the authorization server issued the token introspection response for the authorization server issued the token introspection response for
an access token, including cases where the authorization server an access token, including cases where the authorization server
assumes liability for the content of the token introspection assumes liability for the content of the token introspection
response. An example is a resource server using verified person data response. An example is a resource server using verified personal
to create certificates, which in turn are used to create qualified data to create certificates, which in turn are used to create
electronic signatures. qualified electronic signatures.
In such use cases it may be useful or even required to return a In such use cases, it may be useful or even required to return a
signed JWT [RFC7519] as the introspection response. This signed JWT [RFC7519] as the introspection response. This
specification extends the token introspection endpoint with the specification extends the token introspection endpoint with the
capability to return responses as JWTs. capability to return responses as JWTs.
2. Requirements Notation and Conventions 2. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
3. Resource Server Management 3. Resource Server Management
The authorization server (AS) and the resource server (RS) maintain a The authorization server (AS) and the resource server (RS) maintain a
strong two-way trust relationship. The resource server relies on the strong, two-way trust relationship. The resource server relies on
authorization server to obtain authorization, user and other data as the authorization server to obtain authorization, user, and other
input to its access control decisions and service delivery. The data as input to its access control decisions and service delivery.
authorization server relies on the resource server to handle the The authorization server relies on the resource server to handle the
provided data appropriately. provided data appropriately.
In the context of this specification, the token introspection In the context of this specification, the token introspection
endpoint is used to convey such security data and potentially also endpoint is used to convey such security data and potentially also
privacy sensitive data related to an access token. privacy-sensitive data related to an access token.
In order to process the introspection requests in a secure and In order to process the introspection requests in a secure and
privacy-preserving manner, the authorization server MUST be able to privacy-preserving manner, the authorization server MUST be able to
identify, authenticate and authorize resource servers. identify, authenticate, and authorize resource servers.
The authorization server MAY additionally encrypt the token The AS MAY additionally encrypt the token introspection response
introspection response JWTs. If encryption is used the authorization JWTs. If encryption is used, the AS is provisioned with encryption
server is provisioned with encryption keys and algorithms for the RS. keys and algorithms for the RS.
The authorization server MUST be able to determine whether an RS is The AS MUST be able to determine whether an RS is the audience for a
the audience for a particular access token and what data it is particular access token and what data it is entitled to receive;
entitled to receive, otherwise the RS is not authorized to obtain otherwise, the RS is not authorized to obtain data for the access
data for the access token. The AS has the discretion how to fulfil token. The AS has the discretion of how to fulfill this requirement.
this requirement. The AS could, for example, maintain a mapping The AS could, for example, maintain a mapping between scope values
between scope values and resource servers. and RSs.
The requirements given above imply that the authorization server The requirements given above imply that the AS maintains credentials
maintains credentials and other configuration data for each RS. and other configuration data for each RS.
One way is by utilizing dynamic client registration [RFC7591] and One way is by utilizing dynamic client registration [RFC7591] and
treating every RS as an OAuth client. In this case, the treating every RS as an OAuth client. In this case, the AS is
authorization server is assumed to at least maintain a "client_id" assumed to at least maintain a "client_id" and a
and a "token_endpoint_auth_method" with complementary authentication "token_endpoint_auth_method" with complementary authentication method
method metadata, such as "jwks" or "client_secret". In cases where metadata, such as "jwks" or "client_secret". In cases where the AS
the AS needs to acquire consent to transmit data to a RS, the needs to acquire consent to transmit data to an RS, the following
following client metadata fields are recommended: "client_name", client metadata fields are recommended: "client_name", "client_uri",
"client_uri", "contacts", "tos_uri", "policy_uri". "contacts", "tos_uri", and "policy_uri".
The AS MUST restrict the use of client credentials by a RS to the The AS MUST restrict the use of client credentials by an RS to the
calls it requires, e.g. the AS MAY restrict such a client to call the calls it requires, e.g., the AS MAY restrict such a client to call
token introspection endpoint only. How the AS implements this the token introspection endpoint only. How the AS implements this
restriction is beyond the scope of this specification. restriction is beyond the scope of this specification.
This specification further introduces client metadata to manage the This specification further introduces client metadata to manage the
configuration options required to sign and encrypt token configuration options required to sign and encrypt token
introspection response JWTs. introspection response JWTs.
4. Requesting a JWT Response 4. Requesting a JWT Response
A resource server requests a JWT introspection response by sending an An RS requests a JWT introspection response by sending an
introspection request with an "Accept" HTTP header field set to introspection request with an Accept HTTP header field set to
"application/token-introspection+jwt". "application/token-introspection+jwt".
The AS MUST authenticate the caller at the token introspection The AS MUST authenticate the caller at the token introspection
endpoint. Authentication can utilize client authentication methods endpoint. Authentication can utilize client authentication methods
or a separate access token issued to the resource server and or a separate access token that is issued to the RS and identifies
identifying it as subject. the RS as the subject.
The following is a non-normative example request, with the resource The following is a non-normative example request, with the RS
server authenticating with a private key JWT: authenticating with a private key JWT:
POST /introspect HTTP/1.1 POST /introspect HTTP/1.1
Host: as.example.com Host: as.example.com
Accept: application/token-introspection+jwt Accept: application/token-introspection+jwt
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
token=2YotnFZFEjr1zCsicMWpAA& token=2YotnFZFEjr1zCsicMWpAA&
client_assertion_type= client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=PHNhbWxwOl[...omitted for brevity...]ZT client_assertion=PHNhbWxwOl[...omitted for brevity...]ZT
5. JWT Response 5. JWT Response
The introspection endpoint responds with a JWT, setting the "Content- The introspection endpoint responds with a JWT, setting the Content-
Type" HTTP header field to "application/token-introspection+jwt" and Type HTTP header field to "application/token-introspection+jwt" and
the JWT "typ" ("type") header parameter to "token-introspection+jwt". the JWT typ ("type") header parameter to "token-introspection+jwt".
The JWT MUST include the following top-level claims: The JWT MUST include the following top-level claims:
iss MUST be set to the issuer URL of the authorization server. iss
MUST be set to the issuer URL of the authorization server.
aud MUST identify the resource server receiving the token aud
introspection response. MUST identify the resource server receiving the token
introspection response.
iat MUST be set to the time when the introspection response was iat
created by the authorization server. MUST be set to the time when the introspection response was
created by the authorization server
token_introspection A JSON object containing the members of the token_introspection
token introspection response as specified in [RFC7662], A JSON object containing the members of the token introspection
section 2.2. The separation of the introspection response response, as specified in [RFC7662], Section 2.2. The separation
members into a dedicated containing JWT claim is intended to of the introspection response members into a dedicated JSON object
prevent conflict and confusion with top-level JWT claims that containing a JWT claim is intended to prevent conflict and
may bear the same name. confusion with top-level JWT claims that may bear the same name.
If the access token is invalid, expired, revoked, or not If the access token is invalid, expired, revoked, or not intended
intended for the calling resource server (audience), the for the calling resource server (audience), the authorization
authorization server MUST set the value of the "active" server MUST set the value of the active member in the
member in the "token_introspection" claim to "false" and MUST token_introspection claim to false and MUST NOT include other
NOT include other members. Otherwise, the "active" member is members. Otherwise, the active member is set to true.
set to "true".
The AS SHOULD narrow down the "scope" value to the scopes The AS SHOULD narrow down the scope value to the scopes relevant
relevant to the particular RS. to the particular RS.
As specified in section 2.2 of [RFC7662], implementations MAY As specified in Section 2.2 of [RFC7662], implementations MAY
extend the token introspection response with service-specific extend the token introspection response with service-specific
claims. In the context of this specification, such claims claims. In the context of this specification, such claims will be
will be added as top-level members of the added as top-level members of the token_introspection claim.
"token_introspection" claim.
Token introspection response parameter names intended to be Token introspection response parameter names intended to be used
used across domains MUST be registered in the OAuth Token across domains MUST be registered in the "OAuth Token
Introspection Response registry Introspection Response" registry [IANA.OAuth.Token.Introspection]
[IANA.OAuth.Token.Introspection] defined by [RFC7662]. defined by [RFC7662].
When the AS acts as a provider of resource owner identity When the AS acts as a provider of resource owner identity claims
claims to the RS, the AS determines based on its RS-specific to the RS, the AS determines, based on its RS-specific policy,
policy what identity claims to return in the token what identity claims to return in the token introspection
introspection response. The AS MUST ensure the release of response. The AS MUST ensure the release of any privacy-sensitive
any privacy-sensitive data is legally based (see Section 9). data is legally based (see Section 9).
Further content of the introspection response is determined Further content of the introspection response is determined by the
by the RS-specific policy at the AS. RS-specific policy at the AS.
The JWT MAY include other claims, including those from the "JSON Web The JWT MAY include other claims, including those from the "JSON Web
Token Claims" registry established by [RFC7519]. The JWT SHOULD NOT Token Claims" registry established by [RFC7519]. The JWT SHOULD NOT
include the "sub" and "exp" claims, as an additional prevention include the sub and exp claims, as an additional measure to prevent
against misuse of the JWT as an access token (see Section 8.1). misuse of the JWT as an access token (see Section 8.1).
Note: Although the JWT format is widely used as an access token Note: Although the JWT format is widely used as an access token
format, the JWT returned in the introspection response is not an format, the JWT returned in the introspection response is not an
alternative representation of the introspected access token and is alternative representation of the introspected access token and is
not intended to be used as an access token. not intended to be used as an access token.
This specification registers the "application/token- This specification registers the "application/token-
introspection+jwt" media type, which is used as value of the "typ" introspection+jwt" media type, which is used as the value of the typ
("type") header parameter of the JWT to indicate that the payload is ("type") header parameter of the JWT to indicate that the payload is
a token introspection response. a token introspection response.
The JWT is cryptographically secured as specified in [RFC7519]. The JWT is cryptographically secured as specified in [RFC7519].
Depending on the specific resource server policy the JWT is either Depending on the specific resource server policy, the JWT is either
signed, or signed and encrypted. If the JWT is signed and encrypted signed or signed and encrypted. If the JWT is signed and encrypted,
it MUST be a Nested JWT, as defined in JWT [RFC7519]. it MUST be a Nested JWT, as defined in JWT [RFC7519].
Note: An AS compliant with this specification MUST refuse to serve Note: An AS compliant with this specification MUST refuse to serve
introspection requests that don't authenticate the caller, and return introspection requests that don't authenticate the caller and return
an HTTP status code 400. This is done to ensure token data is an HTTP status code 400. This is done to ensure token data is
released to legitimate recipients only and prevent downgrading to released to legitimate recipients only and prevent downgrading to
[RFC7662] behavior (see Section 8.2). [RFC7662] behavior (see Section 8.2).
The following is a non-normative example response (with line breaks The following is a non-normative example response (with line breaks
for display purposes only): for display purposes only):
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/token-introspection+jwt Content-Type: application/token-introspection+jwt
skipping to change at page 7, line 51 skipping to change at line 327
acting as a client, as specified below. acting as a client, as specified below.
The parameter names follow the pattern established by OpenID Connect The parameter names follow the pattern established by OpenID Connect
Dynamic Client Registration [OpenID.Registration] for configuring Dynamic Client Registration [OpenID.Registration] for configuring
signing and encryption algorithms for JWT responses at the UserInfo signing and encryption algorithms for JWT responses at the UserInfo
endpoint. endpoint.
The following client metadata parameters are introduced by this The following client metadata parameters are introduced by this
specification: specification:
introspection_signed_response_alg OPTIONAL. JWS [RFC7515] algorithm introspection_signed_response_alg
("alg" value) as defined in JWA [RFC7518] for signing OPTIONAL. "JSON Web Signature (JWS)" [RFC7515] algorithm (alg
introspection responses. If this is specified, the response value), as defined in "JSON Web Algorithms (JWA)" [RFC7518], for
will be signed using JWS and the configured algorithm. The signing introspection responses. If this is specified, the
default, if omitted, is "RS256". response will be signed using JWS and the configured algorithm.
The default, if omitted, is RS256.
introspection_encrypted_response_alg OPTIONAL. JWE [RFC7516] introspection_encrypted_response_alg
algorithm ("alg" value) as defined in JWA [RFC7518] for OPTIONAL. "JSON Web Encryption (JWE)" [RFC7516] algorithm (alg
content key encryption. If this is specified, the response value), as defined in JWA [RFC7518], for content key encryption.
will be encrypted using JWE and the configured content If this is specified, the response will be encrypted using JWE and
encryption algorithm the configured content encryption algorithm
("introspection_encrypted_response_enc"). The default, if (introspection_encrypted_response_enc). The default, if omitted,
omitted, is that no encryption is performed. If both signing is that no encryption is performed. If both signing and
and encryption are requested, the response will be signed encryption are requested, the response will be signed then
then encrypted, with the result being a Nested JWT, as encrypted, with the result being a Nested JWT, as defined in JWT
defined in JWT [RFC7519]. [RFC7519].
introspection_encrypted_response_enc OPTIONAL. JWE [RFC7516] introspection_encrypted_response_enc
algorithm ("enc" value) as defined in JWA [RFC7518] for OPTIONAL. JWE [RFC7516] algorithm (enc value), as defined in JWA
content encryption of introspection responses. The default, [RFC7518], for content encryption of introspection responses. The
if omitted, is "A128CBC-HS256". Note: This parameter MUST default, if omitted, is A128CBC-HS256. Note: This parameter MUST
NOT be specified without setting NOT be specified without setting
"introspection_encrypted_response_alg". introspection_encrypted_response_alg.
Resource servers may register their public encryption keys using the Resource servers may register their public encryption keys using the
"jwks_uri" or "jwks" metadata parameters. jwks_uri or jwks metadata parameters.
7. Authorization Server Metadata 7. Authorization Server Metadata
Authorization servers SHOULD publish the supported algorithms for Authorization servers SHOULD publish the supported algorithms for
signing and encrypting the JWT of an introspection response by signing and encrypting the JWT of an introspection response by
utilizing OAuth 2.0 Authorization Server Metadata [RFC8414] utilizing "OAuth 2.0 Authorization Server Metadata" [RFC8414]
parameters. Resource servers use this data to parametrize their parameters. Resource servers use this data to parametrize their
client registration requests. client registration requests.
The following parameters are introduced by this specification: The following parameters are introduced by this specification:
introspection_signing_alg_values_supported OPTIONAL. JSON array introspection_signing_alg_values_supported
containing a list of the JWS [RFC7515] signing algorithms OPTIONAL. JSON array containing a list of the JWS [RFC7515]
("alg" values) as defined in JWA [RFC7518] supported by the signing algorithms (alg values), as defined in JWA [RFC7518],
introspection endpoint to sign the response. supported by the introspection endpoint to sign the response.
introspection_encryption_alg_values_supported OPTIONAL. JSON array introspection_encryption_alg_values_supported
containing a list of the JWE [RFC7516] encryption algorithms OPTIONAL. JSON array containing a list of the JWE [RFC7516]
("alg" values) as defined in JWA [RFC7518] supported by the encryption algorithms (alg values), as defined in JWA [RFC7518],
introspection endpoint to encrypt the content encryption key supported by the introspection endpoint to encrypt the content
for introspection responses (content key encryption). encryption key for introspection responses (content key
encryption).
introspection_encryption_enc_values_supported OPTIONAL. JSON array introspection_encryption_enc_values_supported
containing a list of the JWE [RFC7516] encryption algorithms OPTIONAL. JSON array containing a list of the JWE [RFC7516]
("enc" values) as defined in JWA [RFC7518] supported by the encryption algorithms (enc values), as defined in JWA [RFC7518],
introspection endpoint to encrypt the response (content supported by the introspection endpoint to encrypt the response
encryption). (content encryption).
8. Security Considerations 8. Security Considerations
8.1. Cross-JWT Confusion 8.1. Cross-JWT Confusion
The "iss" and potentially the "aud" claim of a token introspection The iss and potentially the aud claim of a token introspection JWT
JWT can resemble those of a JWT-encoded access token. An attacker can resemble those of a JWT-encoded access token. An attacker could
could try to exploit this and pass a JWT token introspection response try to exploit this and pass a JWT token introspection response as an
as an access token to the resource server. The "typ" ("type") JWT access token to the resource server. The typ ("type") JWT header
header "token-introspection+jwt" and the encapsulation of the token "token-introspection+jwt" and the encapsulation of the token
introspection members such as "sub" and "scope" in the introspection members, such as sub and scope in the
"token_introspection" claim is intended to prevent such substitution token_introspection claim, are intended to prevent such substitution
attacks. Resource servers MUST therefore check the "typ" JWT header attacks. Resource servers MUST therefore check the typ JWT header
value of received JWT-encoded access tokens and ensure all minimally value of received JWT-encoded access tokens and ensure all minimally
required claims for a valid access token are present. required claims for a valid access token are present.
Resource servers MUST additionally apply the countermeasures against Resource servers MUST additionally apply the countermeasures against
replay as described in [I-D.ietf-oauth-security-topics], section 3.2. access token replay, as described in [RFC9700].
JWT Confusion and other attacks involving JWTs are discussed in JWT confusion and other attacks involving JWTs are discussed in
[I-D.ietf-oauth-jwt-bcp]. [RFC8725].
8.2. Token Data Leakage 8.2. Token Data Leakage
The authorization server MUST use Transport Layer Security (TLS) 1.2 The authorization server MUST use Transport Layer Security (TLS) 1.2
(or higher) per BCP 195 [RFC7525] in order to prevent token data (or higher), per BCP 195 [RFC9325], in order to prevent token data
leakage. leakage.
Section 2.1 of [RFC7662] permits requests to the introspection Section 2.1 of [RFC7662] permits requests to the introspection
endpoint to be authorized with an access token which doesn't identify endpoint to be authorized with an access token that doesn't identify
the caller. To prevent introspection of tokens by parties that are the caller. To prevent introspection of tokens by parties that are
not the intended consumer the authorization server MUST require all not the intended consumer, the authorization server MUST require all
requests to the token introspection endpoint to be authenticated. requests to the token introspection endpoint to be authenticated.
9. Privacy Considerations 9. Privacy Considerations
The token introspection response can be used to transfer personal The token introspection response can be used to transfer personal
identifiable information (PII) from the AS to the RS. The AS MUST identifiable information (PII) from the AS to the RS. The AS MUST
conform to legal and jurisdictional constraints for the data transfer conform to legal and jurisdictional constraints for the data transfer
before any data is released to a particular RS. The details and before any data is released to a particular RS. The details and
determining of these constraints varies by jurisdiction and is determining of these constraints vary by jurisdiction and are outside
outside the scope of this document. the scope of this document.
A commonly found way to establish the legal basis for releasing PII A commonly found way to establish the legal basis for releasing PII
is by explicit user consent gathered from the resource owner by the is by explicit user consent gathered from the resource owner by the
AS during the authorization flow. AS during the authorization flow.
It is also possible that the legal basis is established out of band, It is also possible that the legal basis is established out of band,
for example in an explicit contract or by the client gathering the for example, in an explicit contract or by the client gathering the
resource owner's consent. resource owner's consent.
If the AS and the RS belong to the same legal entity (1st party If the AS and the RS belong to the same legal entity (1st party
scenario), there is potentially no need for an explicit user consent scenario), there is potentially no need for an explicit user consent,
but the terms of service and policy of the respective service but the terms of service and policy of the respective service
provider MUST be enforced at all times. provider MUST be enforced at all times.
In any case, the AS MUST ensure that the scope of the legal basis is In any case, the AS MUST ensure that the scope of the legal basis is
enforced throughout the whole process. The AS MUST retain the scope enforced throughout the whole process. The AS MUST retain the scope
of the legal basis with the access token, e.g. in the scope value, it of the legal basis with the access token, e.g., in the scope value,
MUST authenticate the RS, and the AS MUST determine the data a it MUST authenticate the RS, and the AS MUST determine the data an RS
resource server is allowed to receive based on the resource server's is allowed to receive based on the RS's identity and suitable token
identity and suitable token data, e.g. the scope value. data, e.g., the scope value.
Implementers should be aware that a token introspection request lets Implementers should be aware that a token introspection request lets
the AS know when the client (and potentially the user) is accessing the AS know when the client (and potentially the user) is accessing
the RS, which is also an indication of when the user is using the the RS, which is also an indication of when the user is using the
client. If this implication is not acceptable, implementers MUST use client. If this implication is not acceptable, implementers MUST use
other means to relay access token data, for example by directly other means to relay access token data, for example, by directly
transferring the data needed by the RS within the access token. transferring the data needed by the RS within the access token.
10. Acknowledgements 10. IANA Considerations
We would like to thank Petteri Stenius, Neil Madden, Filip Skokan,
Tony Nadalin, Remco Schaar, Justin Richer, Takahiko Kawasaki,
Benjamin Kaduk, Robert Wilton and Roman Danyliw for their valuable
feedback.
11. IANA Considerations
11.1. OAuth Dynamic Client Registration Metadata Registration
This specification requests registration of the following client
metadata definitions in the IANA "OAuth Dynamic Client Registration
Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]:
11.1.1. Registry Contents
* Client Metadata Name: "introspection_signed_response_alg"
* Client Metadata Description: String value indicating the client's 10.1. OAuth Dynamic Client Registration Metadata Registration
desired introspection response signing algorithm.
* Change Controller: IESG The following client metadata definitions have been registered in the
IANA "OAuth Dynamic Client Registration Metadata" registry
[IANA.OAuth.Parameters] established by [RFC7591]:
* Specification Document(s): Section 6 of [[ this specification ]] 10.1.1. Registry Contents
* Client Metadata Name: "introspection_encrypted_response_alg" Client Metadata Name: introspection_signed_response_alg
Client Metadata Description: String value indicating the client's
desired introspection response signing algorithm
Change Controller: IETF
Reference: Section 6 of RFC 9701
* Client Metadata Description: String value specifying the desired Client Metadata Name: introspection_encrypted_response_alg
Client Metadata Description: String value specifying the desired
introspection response content key encryption algorithm (alg introspection response content key encryption algorithm (alg
value). value)
Change Controller: IETF
* Change Controller: IESG Reference: Section 6 of RFC 9701
* Specification Document(s): Section 6 of [[ this specification ]]
* Client Metadata Name: "introspection_encrypted_response_enc"
* Client Metadata Description: String value specifying the desired
introspection response content encryption algorithm (enc value).
* Change Controller: IESG
* Specification Document(s): Section 6 of [[ this specification ]]
11.2. OAuth Authorization Server Metadata Registration Client Metadata Name: introspection_encrypted_response_enc
Client Metadata Description: String value specifying the desired
introspection response content encryption algorithm (enc value)
Change Controller: IETF
Reference: Section 6 of RFC 9701
This specification requests registration of the following values in 10.2. OAuth Authorization Server Metadata Registration
the IANA "OAuth Authorization Server Metadata" registry
[IANA.OAuth.Parameters] established by [RFC8414].
11.2.1. Registry Contents The following values have been registered in the IANA "OAuth
Authorization Server Metadata" registry [IANA.OAuth.Parameters]
established by [RFC8414].
* Metadata Name: "introspection_signing_alg_values_supported" 10.2.1. Registry Contents
* Metadata Description: JSON array containing a list of algorithms Metadata Name: introspection_signing_alg_values_supported
Metadata Description: JSON array containing a list of algorithms
supported by the authorization server for introspection response supported by the authorization server for introspection response
signing. signing
Change Controller: IETF
* Change Controller: IESG Reference: Section 7 of RFC 9701
* Specification Document(s): Section 7 of [[ this specification ]]
* Metadata Name: "introspection_encryption_alg_values_supported"
* Metadata Description: JSON array containing a list of algorithms Metadata Name: introspection_encryption_alg_values_supported
Metadata Description: JSON array containing a list of algorithms
supported by the authorization server for introspection response supported by the authorization server for introspection response
content key encryption (alg value). content key encryption (alg value)
Change Controller: IETF
* Change Controller: IESG Reference: Section 7 of RFC 9701
* Specification Document(s): Section 7 of [[ this specification ]]
* Metadata Name: "introspection_encryption_enc_values_supported"
* Metadata Description: JSON array containing a list of algorithms Metadata Name: introspection_encryption_enc_values_supported
Metadata Description: JSON array containing a list of algorithms
supported by the authorization server for introspection response supported by the authorization server for introspection response
content encryption (enc value). content encryption (enc value)
Change Controller: IETF
* Change Controller: IESG Reference: Section 7 of RFC 9701
* Specification Document(s): Section 7 of [[ this specification ]]
11.3. Media Type Registration 10.3. Media Type Registration
This section registers the "application/token-introspection+jwt" The "application/token-introspection+jwt" media type has been
media type in the "Media Types" registry [IANA.MediaTypes] in the registered in the "Media Types" registry [IANA.MediaTypes] in the
manner described in [RFC6838], which can be used to indicate that the manner described in [RFC6838]. It can be used to indicate that the
content is a token introspection response in JWT format. content is a token introspection response in JWT format.
11.3.1. Registry Contents 10.3.1. Registry Contents
* Type name: application Type name: application
* Subtype name: token-introspection+jwt Subtype name: token-introspection+jwt
* Required parameters: N/A Required parameters: N/A
* Optional parameters: N/A Optional parameters: N/A
* Encoding considerations: binary; A token introspection response is Encoding considerations: binary. A token introspection response is
a JWT; JWT values are encoded as a series of base64url-encoded a JWT; JWT values are encoded as a series of base64url-encoded
values (with trailing '=' characters removed), some of which may values (with trailing '=' characters removed), some of which may
be the empty string, separated by period ('.') characters. be the empty string, separated by period ('.') characters.
* Security considerations: See Section 7 of this specification Security considerations: see Section 8 of RFC 9701
* Interoperability considerations: N/A
* Published specification: Section 4 of this specification
* Applications that use this media type: Applications that produce Interoperability considerations: N/A
and consume OAuth Token Introspection Responses in JWT format
* Fragment identifier considerations: N/A Published specification: Section 4 of RFC 9701
* Additional information: Applications that use this media type: applications that produce and
consume OAuth Token Introspection Responses in JWT format
- Magic number(s): N/A Fragment identifier considerations: N/A
- File extension(s): N/A
- Macintosh file type code(s): N/A Additional information:
Magic number(s): N/A
File extension(s): N/A
Macintosh file type code(s): N/A
* Person & email address to contact for further information: Torsten Person & email address to contact for further information:
Lodderstedt, torsten@lodderstedt.net Torsten Lodderstedt (torsten@lodderstedt.net)
* Intended usage: COMMON Intended usage: COMMON
* Restrictions on usage: none Restrictions on usage: none
* Author: Torsten Lodderstedt, torsten@lodderstedt.net Author: Torsten Lodderstedt (torsten@lodderstedt.net)
* Change controller: IESG Change controller: IETF
* Provisional registration? No Provisional registration? No
11.4. JWT Claim Registration 10.4. JWT Claim Registration
This section registers the "token_introspection" claim in the JSON The "token_introspection" claim has been registered in the "JSON Web
Web Token (JWT) IANA registry [IANA.JWT] in the manner described in Token (JWT)" registry [IANA.JWT] in the manner described in
[RFC7519]. [RFC7519].
11.4.1. Registry Contents 10.4.1. Registry Contents
* Claim name: token_introspection
* Claim description: Token introspection response
* Change Controller: IESG
* Specification Document(s): Section 5 of [[this specification]]
12. References
12.1. Normative References Claim Name: token_introspection
Claim Description: Token introspection response
Change Controller: IETF
Reference: Section 5 of RFC 9701
[I-D.ietf-oauth-jwt-bcp] 11. References
Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best
Current Practices", Work in Progress, Internet-Draft,
draft-ietf-oauth-jwt-bcp-06, 7 June 2019,
<http://www.ietf.org/internet-drafts/draft-ietf-oauth-jwt-
bcp-06.txt>.
[I-D.ietf-oauth-security-topics] 11.1. Normative References
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett,
"OAuth 2.0 Security Best Current Practice", Work in
Progress, Internet-Draft, draft-ietf-oauth-security-
topics-13, 8 July 2019, <http://www.ietf.org/internet-
drafts/draft-ietf-oauth-security-topics-13.txt>.
[IANA.JWT] IANA, "JSON Web Token (JWT) claims registry", [IANA.JWT] IANA, "JSON Web Token (JWT) Claims",
<https://www.iana.org/assignments/jwt/jwt.xhtml#claims>. <https://www.iana.org/assignments/jwt>.
[IANA.MediaTypes] [IANA.MediaTypes]
IANA, "Media Types", IANA, "Media Types",
<http://www.iana.org/assignments/media-types>. <http://www.iana.org/assignments/media-types>.
[IANA.OAuth.Token.Introspection] [IANA.OAuth.Token.Introspection]
IANA, "OAuth Token Introspection Response registry", IANA, "OAuth Token Introspection Response",
<https://www.iana.org/assignments/oauth-parameters/oauth- <https://www.iana.org/assignments/oauth-parameters>.
parameters.xhtml#token-introspection-response>.
[OpenID.Registration] [OpenID.Registration]
Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect
Dynamic Client Registration 1.0 incorporating errata set Dynamic Client Registration 1.0 incorporating errata set
1", 8 November 2014, <https://openid.net/specs/openid- 1", November 2014, <https://openid.net/specs/openid-
connect-registration-1_0.html>. connect-registration-1_0.html>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13, Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013, RFC 6838, DOI 10.17487/RFC6838, January 2013,
skipping to change at page 15, line 9 skipping to change at line 621
<https://www.rfc-editor.org/info/rfc7516>. <https://www.rfc-editor.org/info/rfc7516>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015, DOI 10.17487/RFC7518, May 2015,
<https://www.rfc-editor.org/info/rfc7518>. <https://www.rfc-editor.org/info/rfc7518>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>. <https://www.rfc-editor.org/info/rfc7519>.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
2015, <https://www.rfc-editor.org/info/rfc7525>.
[RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and
P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
RFC 7591, DOI 10.17487/RFC7591, July 2015, RFC 7591, DOI 10.17487/RFC7591, July 2015,
<https://www.rfc-editor.org/info/rfc7591>. <https://www.rfc-editor.org/info/rfc7591>.
[RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection",
RFC 7662, DOI 10.17487/RFC7662, October 2015, RFC 7662, DOI 10.17487/RFC7662, October 2015,
<https://www.rfc-editor.org/info/rfc7662>. <https://www.rfc-editor.org/info/rfc7662>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", RFC 8414, Authorization Server Metadata", RFC 8414,
DOI 10.17487/RFC8414, June 2018, DOI 10.17487/RFC8414, June 2018,
<https://www.rfc-editor.org/info/rfc8414>. <https://www.rfc-editor.org/info/rfc8414>.
12.2. Informative References [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best
Current Practices", BCP 225, RFC 8725,
[IANA.OAuth.Parameters] DOI 10.17487/RFC8725, February 2020,
IANA, "OAuth Parameters", <https://www.rfc-editor.org/info/rfc8725>.
<http://www.iana.org/assignments/oauth-parameters>.
Appendix A. Document History
[[ To be removed from the final specification ]]
-12
* made registration of response parameters intended for cross domain
use a MUST ( in RFC 7662)
-11
* consistent normative language that the AS must authenticate all
callers to the token introspection endpoint when complying with
this specification
* removes text that claims from the JSON Web Token Claims registry
may be included in the token_introspection claim
* updates the privacy considerations section
* fixes the example BASE64URL encoded JWT payload
-10
* added requirement to authenticate RS if privacy sensitive data is
released
* reworked text on claims from different registries
* added forward reference to privacy considerations to section 5
* added text in privacy considerations regarding client/user
tracking
-09
* changes the Accept and Content-Type HTTP headers from
"application/json" to "application/token-introspection+jwt" so
they match the registered media type
* moves the token introspection response members into a JSON object
claim named "token_introspection" to provide isolation from the
top-level JWT-specific claims
* "iss", "aud" and "iat" MUST be present as top-level JWT claims
* the "sub" and "exp" claims SHOULD NOT be used as top-level JWT
claims as additional prevention against JWT access token
substitution attacks
-08
* made difference between introspected access token and
introspection response clearer
* defined semantics of JWT claims overlapping between introspected
access token and introspection response as JWT
* added section about RS management
* added text about user claims including a privacy considerations
section
* removed registration of OpenID Connect claims to "Token
Introspection Response" registry and refer to "JWT Claims"
registry instead
* added registration of "application/token-introspection+jwt" media
type as type identifier of token introspection responses in JWT
format
* more changed to incorporate IESG review feedback
-07
* fixed wrong description of "locale"
* added references for ISO and ITU specifications
-06
* replaced reference to RFC 7159 with reference to RFC 8259
-05
* improved wording for TLS requirement
* added RFC 2119 boilerplate
* fixed and updated some references
-04
* reworked definition of parameters in section 4
* added text on data minimization to security considerations section
* added statement regarding TLS to security considerations section
-03
* added registration for OpenID Connect Standard Claims to OAuth
Token Introspection Response registry
-02
* updated references
-01
* adapted wording to preclude any accept header except "application/
jwt" if encrypted responses are required
* use registered alg value RS256 for default signing algorithm
* added text on claims in the token introspection response
-00
* initial version of the WG draft
* defined default signing algorithm
* changed behavior in case resource server is set up for encryption
* Added text on token data leakage prevention to the security
considerations
* moved Security Considerations section forward
WG draft
-01
* fixed typos in client meta data field names
* added OAuth Server Metadata parameters to publish algorithms
supported for signing and encrypting the introspection response
* added registration of new parameters for OAuth Server Metadata and [RFC9325] Sheffer, Y., Saint-Andre, P., and T. Fossati,
Client Registration "Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 9325, DOI 10.17487/RFC9325, November
2022, <https://www.rfc-editor.org/info/rfc9325>.
* added explicit request for JWT introspection response [RFC9700] Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett,
"Best Current Practice for OAuth 2.0 Security", BCP 240,
RFC 9700, DOI 10.17487/RFC9700, December 2024,
<https://www.rfc-editor.org/info/rfc9700>.
* made iss and aud claims mandatory in introspection response 11.2. Informative References
* Stylistic and clarifying edits, updates references [IANA.OAuth.Parameters]
IANA, "OAuth Parameters",
<http://www.iana.org/assignments/oauth-parameters>.
-00 Acknowledgements
* initial version We would like to thank Petteri Stenius, Neil Madden, Filip Skokan,
Tony Nadalin, Remco Schaar, Justin Richer, Takahiko Kawasaki,
Benjamin Kaduk, Robert Wilton, and Roman Danyliw for their valuable
feedback.
Authors' Addresses Authors' Addresses
Torsten Lodderstedt (editor) Torsten Lodderstedt (editor)
yes.com AG yes.com AG
Email: torsten@lodderstedt.net Email: torsten@lodderstedt.net
Vladimir Dzhuvinov Vladimir Dzhuvinov
Connect2id Ltd. Connect2id Ltd.
Email: vladimir@connect2id.com Email: vladimir@connect2id.com
 End of changes. 118 change blocks. 
489 lines changed or deleted 308 lines changed or added

This html diff was produced by rfcdiff 1.48.