draft-ietf-oauth-jwt-introspection-response-08.txt   draft-ietf-oauth-jwt-introspection-response-09.txt 
Open Authentication Protocol T. Lodderstedt, Ed. Open Authentication Protocol T. Lodderstedt, Ed.
Internet-Draft yes.com AG Internet-Draft yes.com AG
Intended status: Standards Track V. Dzhuvinov Intended status: Standards Track V. Dzhuvinov
Expires: March 22, 2020 Connect2id Ltd. Expires: October 27, 2020 Connect2id Ltd.
Sep 19, 2019 April 25, 2020
JWT Response for OAuth Token Introspection JWT Response for OAuth Token Introspection
draft-ietf-oauth-jwt-introspection-response-08 draft-ietf-oauth-jwt-introspection-response-09
Abstract Abstract
This specification proposes an additional JSON Web Token (JWT) This specification proposes an additional JSON Web Token (JWT)
secured response for OAuth 2.0 Token Introspection. secured response 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 Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
skipping to change at page 1, line 32 skipping to change at page 1, line 32
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 22, 2020. This Internet-Draft will expire on October 27, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 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 Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Requirements Notation and Conventions . . . . . . . . . . . . 3 2. Requirements Notation and Conventions . . . . . . . . . . . . 3
3. Resource server management . . . . . . . . . . . . . . . . . 3 3. Resource Server Management . . . . . . . . . . . . . . . . . 3
4. Requesting a JWT Response . . . . . . . . . . . . . . . . . . 4 4. Requesting a JWT Response . . . . . . . . . . . . . . . . . . 4
5. JWT Response . . . . . . . . . . . . . . . . . . . . . . . . 4 5. JWT Response . . . . . . . . . . . . . . . . . . . . . . . . 4
6. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 7 6. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 7
7. Authorization Server Metadata . . . . . . . . . . . . . . . . 8 7. Authorization Server Metadata . . . . . . . . . . . . . . . . 8
8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
8.1. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 9 8.1. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 9
8.2. Token Data Leakage . . . . . . . . . . . . . . . . . . . 9 8.2. Token Data Leakage . . . . . . . . . . . . . . . . . . . 9
8.3. Keeping Token Data Confidential from OAuth Clients . . . 10 8.3. Keeping Token Data Confidential from OAuth Clients . . . 10
8.4. Logging and Audit of Introspection Activity . . . . . . . 10 8.4. Logging and Audit of Introspection Activity . . . . . . . 10
9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
11.1. OAuth Dynamic Client Registration Metadata Registration 11 11.1. OAuth Dynamic Client Registration Metadata Registration 11
11.1.1. Registry Contents . . . . . . . . . . . . . . . . . 11 11.1.1. Registry Contents . . . . . . . . . . . . . . . . . 11
11.2. OAuth Authorization Server Metadata Registration . . . . 12 11.2. OAuth Authorization Server Metadata Registration . . . . 11
11.2.1. Registry Contents . . . . . . . . . . . . . . . . . 12 11.2.1. Registry Contents . . . . . . . . . . . . . . . . . 12
11.3. Media Type Registration . . . . . . . . . . . . . . . . 12 11.3. Media Type Registration . . . . . . . . . . . . . . . . 12
11.3.1. Registry Contents . . . . . . . . . . . . . . . . . 13 11.3.1. Registry Contents . . . . . . . . . . . . . . . . . 12
11.4. JWT Claim Registration . . . . . . . . . . . . . . . . . 13
11.4.1. Registry Contents . . . . . . . . . . . . . . . . . 13
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
12.1. Normative References . . . . . . . . . . . . . . . . . . 14 12.1. Normative References . . . . . . . . . . . . . . . . . . 14
12.2. Informative References . . . . . . . . . . . . . . . . . 15 12.2. Informative References . . . . . . . . . . . . . . . . . 15
Appendix A. Document History . . . . . . . . . . . . . . . . . . 15 Appendix A. Document History . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 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.
skipping to change at page 3, line 18 skipping to change at page 3, line 18
capability to return responses as JWTs. capability to return responses as JWTs.
2. Requirements Notation and Conventions 2. Requirements Notation and Conventions
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 BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 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 the
authorization server to obtain authorization, user and other data as authorization server to obtain authorization, user and other data as
input to its access control decisions and service delivery. The input to its access control decisions and service delivery. The
authorization server relies on the resource server to handle 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
skipping to change at page 4, line 20 skipping to change at page 4, line 20
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 the
token introspection endpoint only. How the AS implements this 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 to receive a JWT introspection response by A resource server requests a JWT introspection response by including
including an Accept header with content type "application/jwt" in the an "Accept" HTTP header "application/token-introspection+jwt" in the
introspection request. introspection request.
Authentication at the token introspection endpoint can utilize client The AS SHOULD authenticate the caller at the token introspection
authentication methods or a separate access token issued to the endpoint. Authentication can utilize client authentication methods
resource server. Whether a resource server is required to or a separate access token issued to the resource server. Whether a
authenticate is determined by the respective RS-specific policy at resource server is required to authenticate is determined by the
the AS. respective RS-specific policy at the AS.
The following is a non-normative example request using client The following is a non-normative example request with client
authentication: authentication:
POST /introspect HTTP/1.1 POST /introspect HTTP/1.1
Host: server.example.com Host: as.example.com
Accept: application/jwt Accept: application/token-introspection+jwt
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
token=2YotnFZFEjr1zCsicMWpAA token=2YotnFZFEjr1zCsicMWpAA
If required by its policy, the authorization server MUST authenticate
the caller and check its authorization to use the token introspection
endpoint.
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" header to "application/jwt". This JWT is a cryptographically Type" HTTP header to "application/token-introspection+jwt" and the
protected representation of the token introspection response as JWT "typ" ("type") header to "token-introspection+jwt".
specified in [RFC7662].
Note: Although the JWT format is widely used as an access token The JWT MUST include the following top-level claims:
format, the JWT returned in the introspection response is not an
alternative representation of the introspected access token and is
not intended to be used as an access token.
JWT metadata values, such as "iat", might differ between the token iss MUST be set to the issuer URL of the authorization server.
introspection response in JWT format and the introspected access
token (see below).
This specification registers the "application/token- aud MUST identify the resource server receiving the token
introspection+jwt" media type, which is used as value of the "typ" introspection response.
header parameter of the JWT to indicate that the payload is a token
introspection response.
If the access token is invalid, expired, has been revoked, or is not iat MUST be set to the time when the introspection response was
intended to be consumed by the calling resource server (audience), created by the authorization server.
the authorization server MUST set the value of the response claim
"active" to "false". Otherwise, this claim is set to "true".
If the access token is considered active, it MUST contain the claims token_introspection A JSON object containing the members of the
"iss" and "aud" in order to prevent misuse of the JWT as an ID or token introspection response, as specified in the "OAuth
access token (see Section 8.1). Token Introspection Response" registry established by
[RFC7662] as well as other members. The separation of the
introspection members into a dedicated containing JWT claim
is intended to prevent conflict and confusion with top-level
JWT claims that may bear the same name.
The "iss" MUST be set to the issuer URL of the AS. If the access token is invalid, expired, revoked, or is not
intended for the calling resource server (audience), the
authorization server MUST set the value of the "active"
member in the "token_introspection" claim to "false" and
other members MUST NOT be included. Otherwise, the "active"
member is set to "true".
The value of the "aud" claims MUST identify the resource server If possible, the AS MUST narrow down the "scope" value to the
receiving the token introspection response. scopes relevant to the particular RS.
If the AS adds the following claims to the token introspection Claims from the "JSON Web Token Claims" registry that are
response their meaning is defined as follows: commonly used in [OpenID.Core] and can be applied to the
resource owner MAY be included as members in the
"token_introspection" claim. They can serve to convey the
privileges delegated to the client, to identify the resource
owner as a natural person or to provide a required contact
detail, such as an e-Mail address or phone number. When
transmitting such claims the AS acts as an identity provider
in regard to the RS. The AS determines based on its RS-
specific policy what claims about the resource owner to
return in the token introspection response.
iat The "iat" claim indicates when the introspection response was The AS MUST ensure the release of any privacy-sensitive data
issued by the AS. is legally based.
exp The "exp" claim indicates when the access token passed in the Further content of the introspection response is determined
introspection request will expire. by the RS-specific policy at the AS.
jti The "jti" claim is a unique identifier for the access token The JWT MAY include other claims, including those from the "JSON Web
passed in the introspection request. This identifier MUST be Token Claims" registry established by [RFC7519]. The JWT SHOULD NOT
stable for all introspection calls for a given access token. include the "sub" and "exp" claims as an additional prevention
against misuse of the JWT as an access token (see Section 8.1).
Further content of the introspection response is determined by the Note: Although the JWT format is widely used as an access token
RS-specific policy at the AS. format, the JWT returned in the introspection response is not an
alternative representation of the introspected access token and is
not intended to be used as an access token.
If possible, the AS MUST narrow down the "scope" value to the scopes This specification registers the "application/token-
relevant to the particular RS. introspection+jwt" media type, which is used as value of the "typ"
("type") header parameter of the JWT to indicate that the payload is
a token introspection response.
The JWT formatted introspection response MAY contain further claims, The JWT is cryptographically secured as specified in [RFC7662].
especially the claims defined in the "OAuth Token Introspection
Response" registry established by [RFC7662] and the "JSON Web Token
Claims" registry established by [RFC7519].
This includes claims from the "JSON Web Token Claims" registry that Depending on the specific resource server policy the JWT is either
are commonly used in [OpenID.Core] and can be applied to the resource signed, or signed and encrypted. If the JWT is signed and encrypted
owner. These claims can serve to identify the resource owner as a it MUST be a Nested JWT, as defined in JWT [RFC7519].
natural person or to provide a required contact detail, such as an
e-Mail address or phone number. When transmitting such claims the AS
acts as an identity provider in regard to the RS.
The AS determines based on the RS-specific policy what claims about Note: If the resource server policy requires a signed and encrypted
the resource owner to return in the token introspection response. response and the authorization server receives an unauthenticated
The AS MUST ensure that the release of any privacy-sensitive data is request containing an "Accept" header with content type other than
legally based. "application/token-introspection+jwt", it MUST refuse to serve the
request and return an HTTP status code 400. This is done to prevent
downgrading attacks to obtain token data intended for release to
legitimate recipients only (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/jwt Content-Type: application/token-introspection+jwt
eyJ0eXAiOiJ0b2tlbi1pbnRyb3NwZWN0aW9uK2p3dCIsImFsZyI6IlJTMjU2In0.eyJ eyJraWQiOiJ3RzZEIiwidHlwIjoidG9rZW4taW50cm9zcGVjdGlvbitqd3QiLCJhbGc
pc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbS8iLCJhdWQiOiJzNkJoZFJrcX iOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FzLmV4YW1wbGUuY29tLyIsImF1ZCI6I
QzIiwianRpIjoidDFGb0NDYVpkNFh2NE9SSlVXVlVlVFpmc0toVzMwQ1FDcldERGp3W mh0dHBzOi8vcnMuZXhhbXBsZS5jb20vcmVzb3VyY2UiLCJpYXQiOjE1MTQ3OTc4OTIs
Hk2dyIsImFjdGl2ZSI6dHJ1ZSwic2NvcGUiOiJyZWFkIHdyaXRlIGRvbHBoaW4iLCJl InRva2VuX2ludHJvc3BlY3Rpb24iOnsiYWN0aXZlIjp0cnVlLCJpc3MiOiJodHRwczo
eHAiOjE1MTQ3OTc5NDIwMDAsImlhdCI6MTUxNDc5NzgyMjAwMCwiY2xpZW50X2lkIjo vL2FzLmV4YW1wbGUuY29tLyIsImF1ZCI6Imh0dHBzOi8vcnMuZXhhbXBsZS5jb20vcm
iczZCaGRSa3F0MyIsInN1YiI6Ilo1TzN1cFBDODhRckFqeDAwZGlzIiwiZ2l2ZW5fbm Vzb3VyY2UiLCJpYXQiOjE1MTQ3OTc4MjIsImV4cCI6MTUxNDc5Nzk0MiwiY2xpZW50X
FtZSI6IkpvaG4iLCJmYW1pbHlfbmFtZSI6IkRvZSIsImJpcnRoZGF0ZSI6IjE5ODItM 2lkIjoicGFpQjJnb28wYSIsInNjb3BlIjoicmVhZHdyaXRlZG9scGhpbiIsInN1YiI6
DItMDEifQ.mnGNVJJwMaMR-drVHIyjOd7S5mScHT5tYC_sLdeaS9C4pkmiOgwHNGah9 Ilo1TzN1cFBDODhRckFqeDAwZGlzIiwiYmlydGhkYXRlIjoiMTk4Mi0wMi0wMSIsImd
w_15kbotjDckotJNHpNTQCcE5nRC29L_jz5hSCNTMmK62fJdEcq0QVuCL_roeHzc-s1 pdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJEb2UiLCJqdGkiOiJ0MUZvQ0
bjU2V2Qme6_2468zqcuhf1fhcieWxx9bDwFFwk3su0qdoF9RBa0HobWzy1ENU6MjiKH NhWmQ0WHY0T1JKVVdWVWVUWmZzS2hXMzBDUUNyV0REandYeTZ3In19.przJMU5GhmNz
vmrnd5PkJenn1rJEt0EQTUuVE0vh2tQGhxbaZkQ34mLLgES5TCuBK7ALDXhT4aGCzxg vwtt1Sr-xa9xTkpiAg5IshbQsRiRVP_7eGR1GHYrNwQh84kxOkHCyje2g5WSRcYosGE
3jLprs_jYTjCq2kugptseKaxsvti0TxOxmxLPcuy5xRxHDUzV2h9_VWVJRgM8y0vhLN VIiC-eoPJJ-qBwqwSlgx9JEeCDw2W5DjrblOI_N0Jvsq_dUeOyoWVMqlOydOBhKNY0s
v9XKDe4EQqaIFLA_YD4TBeyPV7Sm4xMQ-2OsSmAz0E2BY_b_s0WrFN2K8tspQhj2mnG mBrI4NZvEExucOm9WUJXMuJtvq1gBes-0go5j4TEv9sOP9uu81gqWTr_LOo6pgT0tFF
v7Zz8O3zeE2gC59JR56aU_SNspGPbt8GvTwuL5ZZTCmiWKUzQ0ev4zVthUczQmK53dx yZfWC4kbXPXiQ2YT6mxCiQRRNM-l9cBdF6Jx6IOrsfFhBuYdYQ_mlL19HgDDOFaleyq
Zl6ZxBfIRPV5k1GTPyEPbWehizbJT4JBSLlk-l8JvJcfL2USLtJgMLH1D01fww0IqN1 mru6lKlASOsaE8dmLSeKcX91FbG79FKN8un24iwIDCbKT9xlUFl54xWVShNDFA
ofHeHFUmZWB_LR7kGaJ8Kx_a9z4CaaVesW8jzgSmwA8K_pv9yJqqjnUhsh51c49OAgn
cqwAahGrUhrN0dIBrd6sRXU3AiRpaah0MMNcjR2UJbEZKwnMyHTkBQAeZAe9vO9pKV8
JOd0ziYBpAbEpYGE4p3wog4
The example response header contains the following JSON document: The example response JWT header contains the following JSON document:
{ {
"typ": "token-introspection+jwt", "typ": "token-introspection+jwt",
"alg": "RS256" "alg": "RS256"
"kid": "wG6D"
} }
The example response payload contains the following JSON document:
The example response JWT payload contains the following JSON
document:
{ {
"iss":"https://server.example.com/", "iss":"https://as.example.com/",
"aud":"s6BhdRkqt3", "aud":"https://rs.example.com/resource",
"jti": "t1FoCCaZd4Xv4ORJUWVUeTZfsKhW30CQCrWDDjwXy6w", "iat":1514797892,
"active":true, "token_introspection":
"scope":"read write dolphin", {
"exp":1514797942000, "active":true,
"iat":1514797822000, "iss":"https://as.example.com/",
"client_id":"s6BhdRkqt3", "aud":"https://rs.example.com/resource",
"sub":"Z5O3upPC88QrAjx00dis", "iat":1514797822,
"given_name":"John", "exp":1514797942,
"family_name":"Doe", "client_id":"paiB2goo0a",
"birthdate":"1982-02-01" "scope":"read write dolphin",
"sub":"Z5O3upPC88QrAjx00dis",
"birthdate":"1982-02-01",
"given_name":"John",
"family_name":"Doe",
"jti":"t1FoCCaZd4Xv4ORJUWVUeTZfsKhW30CQCrWDDjwXy6w"
}
} }
Depending on the specific resource server policy the JWT is either
signed, or signed and encrypted. If the JWT is signed and encrypted
it MUST be a Nested JWT, as defined in JWT [RFC7519].
Note: If the resource server policy requires a signed and encrypted
response and the authorization server receives an unauthenticated
request containing an Accept header with content type other than
"application/jwt", it MUST refuse to serve the request and return an
HTTP status code 400. This is done to prevent downgrading attacks to
obtain token data intended for release to legitimate recipients only
(see Section 8.2).
6. Client Metadata 6. Client Metadata
The authorization server determines what algorithm to employ to The authorization server determines the algorithm to secure the JWT
secure the JWT for a particular introspection response. This for a particular introspection response. This decision can be based
decision can be based on registered metadata parameters for the on registered metadata parameters for the resource server, supplied
resource server, supplied via dynamic client registration [RFC7591] via dynamic client registration [RFC7591] with the resource server
with the resource server 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 OPTIONAL. JWS [RFC7515] algorithm
skipping to change at page 9, line 11 skipping to change at page 9, line 12
introspection_encryption_enc_values_supported OPTIONAL. JSON array introspection_encryption_enc_values_supported OPTIONAL. JSON array
containing a list of the JWE [RFC7516] encryption algorithms containing a list of the JWE [RFC7516] encryption algorithms
("enc" values) as defined in JWA [RFC7518] supported by the ("enc" values) as defined in JWA [RFC7518] supported by the
introspection endpoint to encrypt the response (content introspection endpoint to encrypt the response (content
encryption). encryption).
8. Security Considerations 8. Security Considerations
8.1. Cross-JWT Confusion 8.1. Cross-JWT Confusion
Token introspection responses in JWT format, access tokens in JWT The "iss" and potentially the "aud" claim of a token introspection
format, and OpenID Connect ID Tokens are syntactical similar. JWT can resemble those of a JWT-encoded access token. An attacker
Attackers could try to utilize this fact and attempt to use a token could try to exploit this and pass a JWT token introspection response
introspection response as access token when invoking a resource as an access token to the resource server. The "typ" ("type") JWT
server or as ID Token when logging into at a OpenID Connect RP. header "token-introspection+jwt" and the encapsulation of the token
introspection members such as "sub" and "scope" in the
Any relying party processing the "typ" JWT header element should "token_introspection" claim is intended to prevent such substitution
detect the attack since token introspection responses in JWT format attacks. Resource servers MUST therefore check the "typ" JWT header
set this header to the value "token-introspection+jwt". value of received JWT-encoded access tokens and ensure all minimally
Unfortunately, this is not a well established practice yet. required claims for a valid access token are present.
As an alternative approach, such an attack can be prevented like any
other token substitution attack by restricting the audience of the
JWT. As specified in Section 5, the authorization server includes
the claims "iss" and "aud" in each JWT introspection response, with
the "iss" value set to the authorization server's issuer URL and the
"aud" value set to the resource server's identifier. Any recipient
of an JWT MUST check these values in order to detect substitution
attacks.
OpenID Connect RPs are additionally expected to use and check the
"nonce" parameter and claim to prevent token and code replay.
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. replay as described in [I-D.ietf-oauth-security-topics], section 3.2.
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]. [I-D.ietf-oauth-jwt-bcp].
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
skipping to change at page 10, line 8 skipping to change at page 9, line 45
To prevent introspection of leaked tokens and to present an To prevent introspection of leaked tokens and to present an
additional security layer against token guessing attacks the additional security layer against token guessing attacks the
authorization server MAY require all requests to the token authorization server MAY require all requests to the token
introspection endpoint to be authenticated. As an alternative or as introspection endpoint to be authenticated. As an alternative or as
an addition to the authentication, the intended recipients MAY be set an addition to the authentication, the intended recipients MAY be set
up for encrypted responses. up for encrypted responses.
In the latter case, confidentiality is ensured by the fact that only In the latter case, confidentiality is ensured by the fact that only
the legitimate recipient is able to decrypt the response. An the legitimate recipient is able to decrypt the response. An
attacker could try to circumvent this measure by requesting a plain attacker could try to circumvent this measure by requesting a plain
JSON response, using an Accept header with the content type set to, JSON response, using an "Accept" header with the content type set to,
for example, "application/json" instead of "application/jwt". To for example, "application/json" instead of "application/token-
prevent this attack the authorization server MUST NOT serve requests introspection+jwt". To prevent this attack the authorization server
with a content type other than "application/jwt" if the resource MUST NOT serve requests with a content type other than "application/
server is set up to receive encrypted responses (see also Section 5). token-introspection+jwt" if the resource server is set up to receive
encrypted responses (see also Section 5).
8.3. Keeping Token Data Confidential from OAuth Clients 8.3. Keeping Token Data Confidential from OAuth Clients
Authorization servers with a policy that requires token data to be Authorization servers with a policy that requires token data to be
kept confidential from OAuth clients must require all requests to the kept confidential from OAuth clients must require all requests to the
token introspection endpoint to be authenticated. As an alternative token introspection endpoint to be authenticated. As an alternative
or as an addition to the authentication, the intended recipients may or as an addition to the authentication, the intended recipients may
be set up for encrypted responses. be set up for encrypted responses.
8.4. Logging and Audit of Introspection Activity 8.4. Logging and Audit of Introspection Activity
skipping to change at page 11, line 11 skipping to change at page 10, line 51
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, of the legal basis with the access token, e.g. in the scope value,
and the AS MUST determine the data a resource server is allowed to and the AS MUST determine the data a resource server is allowed to
receive based on the resource server's identity and suitable token receive based on the resource server's identity and suitable token
data, e.g. the scope value. data, e.g. the scope value.
10. Acknowledgements 10. Acknowledgements
We would like to thank Petteri Stenius, Neil Madden, Filip Skokan, We would like to thank Petteri Stenius, Neil Madden, Filip Skokan,
Tony Nadalin, and Remco Schaar for their valuable feedback. Tony Nadalin, Remco Schaar, Justin Richer and Takahiko Kawasaki for
their valuable feedback.
11. IANA Considerations 11. IANA Considerations
11.1. OAuth Dynamic Client Registration Metadata Registration 11.1. OAuth Dynamic Client Registration Metadata Registration
This specification requests registration of the following client This specification requests registration of the following client
metadata definitions in the IANA "OAuth Dynamic Client Registration metadata definitions in the IANA "OAuth Dynamic Client Registration
Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]:
11.1.1. Registry Contents 11.1.1. Registry Contents
skipping to change at page 14, line 5 skipping to change at page 13, line 41
o Intended usage: COMMON o Intended usage: COMMON
o Restrictions on usage: none o Restrictions on usage: none
o Author: Torsten Lodderstedt, torsten@lodderstedt.net o Author: Torsten Lodderstedt, torsten@lodderstedt.net
o Change controller: IESG o Change controller: IESG
o Provisional registration? No o Provisional registration? No
11.4. JWT Claim Registration
This section registers the "token_introspection" claim in the JSON
Web Token (JWT) IANA registry [IANA.JWT] in the manner described in
[RFC7519].
11.4.1. Registry Contents
o Claim name: token_introspection
o Claim description: Token introspection response
o Change Controller: IESG
o Specification Document(s): Section 5 of [[this specification]]
12. References 12. References
12.1. Normative References 12.1. Normative References
[I-D.ietf-oauth-jwt-bcp] [I-D.ietf-oauth-jwt-bcp]
Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best
Current Practices", draft-ietf-oauth-jwt-bcp-06 (work in Current Practices", draft-ietf-oauth-jwt-bcp-06 (work in
progress), June 2019. progress), June 2019.
[I-D.ietf-oauth-security-topics] [I-D.ietf-oauth-security-topics]
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett,
"OAuth 2.0 Security Best Current Practice", draft-ietf- "OAuth 2.0 Security Best Current Practice", draft-ietf-
oauth-security-topics-13 (work in progress), July 2019. oauth-security-topics-13 (work in progress), July 2019.
[IANA.JWT]
IANA, "JSON Web Token (JWT)",
<https://www.iana.org/assignments/jwt/jwt.xhtml>.
[IANA.MediaTypes] [IANA.MediaTypes]
IANA, "Media Types", IANA, "Media Types",
<http://www.iana.org/assignments/media-types>. <http://www.iana.org/assignments/media-types>.
[OpenID.Core] [OpenID.Core]
Sakimura, N., Bradley, J., Jones, M., Medeiros, B. D., and Sakimura, N., Bradley, J., Jones, M., Medeiros, B. D., and
C. Mortimore, "OpenID Connect Core 1.0 incorporating C. Mortimore, "OpenID Connect Core 1.0 incorporating
errata set 1", Nov 2014, errata set 1", Nov 2014,
<http://openid.net/specs/openid-connect-core-1_0.html>. <http://openid.net/specs/openid-connect-core-1_0.html>.
[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", Nov 2014, <https://openid.net/specs/ 1", Nov 2014, <https://openid.net/specs/openid-connect-
openid-connect-registration-1_0.html>. 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,
<https://www.rfc-editor.org/info/rfc6838>. <https://www.rfc-editor.org/info/rfc6838>.
skipping to change at page 15, line 47 skipping to change at page 16, line 9
12.2. Informative References 12.2. Informative References
[IANA.OAuth.Parameters] [IANA.OAuth.Parameters]
IANA, "OAuth Parameters", IANA, "OAuth Parameters",
<http://www.iana.org/assignments/oauth-parameters>. <http://www.iana.org/assignments/oauth-parameters>.
Appendix A. Document History Appendix A. Document History
[[ To be removed from the final specification ]] [[ To be removed from the final specification ]]
-09
o changes the Accept and Content-Type HTTP headers from
"application/json" to "application/token-introspection+jwt" so
they match the registered media type
o moves the token introspection response members into a JSON object
claim named "token_introspection" to provide isolation from the
top-level JWT-specific claims
o "iss", "aud" and "iat" MUST be present as top-level JWT claims
o the "sub" and "exp" claims SHOULD NOT be used as top-level JWT
claims as additional prevention against JWT access token
substitution attacks
-08 -08
o made difference between introspected access token and o made difference between introspected access token and
introspection response clearer introspection response clearer
o defined semantics of JWT claims overlapping between introspected o defined semantics of JWT claims overlapping between introspected
access token and introspection response as JWT access token and introspection response as JWT
o added section about RS management o added section about RS management
 End of changes. 47 change blocks. 
156 lines changed or deleted 183 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/