idnits 2.17.1 draft-ietf-oauth-jwt-introspection-response-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 25, 2020) is 1434 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-07) exists of draft-ietf-oauth-jwt-bcp-06 == Outdated reference: A later version (-25) exists of draft-ietf-oauth-security-topics-13 ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Open Authentication Protocol T. Lodderstedt, Ed. 3 Internet-Draft yes.com AG 4 Intended status: Standards Track V. Dzhuvinov 5 Expires: October 27, 2020 Connect2id Ltd. 6 April 25, 2020 8 JWT Response for OAuth Token Introspection 9 draft-ietf-oauth-jwt-introspection-response-09 11 Abstract 13 This specification proposes an additional JSON Web Token (JWT) 14 secured response for OAuth 2.0 Token Introspection. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on October 27, 2020. 33 Copyright Notice 35 Copyright (c) 2020 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Requirements Notation and Conventions . . . . . . . . . . . . 3 52 3. Resource Server Management . . . . . . . . . . . . . . . . . 3 53 4. Requesting a JWT Response . . . . . . . . . . . . . . . . . . 4 54 5. JWT Response . . . . . . . . . . . . . . . . . . . . . . . . 4 55 6. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 7 56 7. Authorization Server Metadata . . . . . . . . . . . . . . . . 8 57 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 58 8.1. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 9 59 8.2. Token Data Leakage . . . . . . . . . . . . . . . . . . . 9 60 8.3. Keeping Token Data Confidential from OAuth Clients . . . 10 61 8.4. Logging and Audit of Introspection Activity . . . . . . . 10 62 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10 63 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 64 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 65 11.1. OAuth Dynamic Client Registration Metadata Registration 11 66 11.1.1. Registry Contents . . . . . . . . . . . . . . . . . 11 67 11.2. OAuth Authorization Server Metadata Registration . . . . 11 68 11.2.1. Registry Contents . . . . . . . . . . . . . . . . . 12 69 11.3. Media Type Registration . . . . . . . . . . . . . . . . 12 70 11.3.1. Registry Contents . . . . . . . . . . . . . . . . . 12 71 11.4. JWT Claim Registration . . . . . . . . . . . . . . . . . 13 72 11.4.1. Registry Contents . . . . . . . . . . . . . . . . . 13 73 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 74 12.1. Normative References . . . . . . . . . . . . . . . . . . 14 75 12.2. Informative References . . . . . . . . . . . . . . . . . 15 76 Appendix A. Document History . . . . . . . . . . . . . . . . . . 16 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 79 1. Introduction 81 OAuth 2.0 Token Introspection [RFC7662] specifies a method for a 82 protected resource to query an OAuth 2.0 authorization server to 83 determine the state of an access token and obtain data associated 84 with the access token. This enables deployments to implement opaque 85 access tokens in an interoperable way. 87 The introspection response, as specified in OAuth 2.0 Token 88 Introspection [RFC7662], is a plain JSON object. However, there are 89 use cases where the resource server requires stronger assurance that 90 the authorization server issued the token introspection response for 91 an access token, including cases where the authorization server 92 assumes liability for the content of the token introspection 93 response. An example is a resource server using verified person data 94 to create certificates, which in turn are used to create qualified 95 electronic signatures. 97 In such use cases it may be useful or even required to return a 98 signed JWT [RFC7519] as the introspection response. This 99 specification extends the token introspection endpoint with the 100 capability to return responses as JWTs. 102 2. Requirements Notation and Conventions 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 106 "OPTIONAL" in this document are to be interpreted as described in BCP 107 14 [RFC2119] [RFC8174] when, and only when, they appear in all 108 capitals, as shown here. 110 3. Resource Server Management 112 The authorization server (AS) and the resource server (RS) maintain a 113 strong two-way trust relationship. The resource server relies on the 114 authorization server to obtain authorization, user and other data as 115 input to its access control decisions and service delivery. The 116 authorization server relies on the resource server to handle the 117 provided data appropriately. 119 In the context of this specification, the Token Introspection 120 Endpoint is used to convey such security data and potentially also 121 privacy sensitive data related to an access token. 123 In order to process the introspection requests in a secure and 124 privacy-preserving manner, the authorization server MUST be able to 125 identify, authenticate and authorize resource servers. 127 To support encrypted token introspection response JWTs, the 128 authorization server MUST also be provided with the respective 129 resource server encryption keys and algorithms. 131 The authorization server MUST be able to determine whether an RS is 132 the audience for a particular access token and what data it is 133 entitled to receive, otherwise the RS is not authorized to obtain 134 data for the access token. The AS has the discretion how to fulfil 135 this requirement. The AS could, for example, maintain a mapping 136 between scopes values and resource servers. 138 The requirements given above imply that the authorization server 139 maintains credentials and other configuration data for each RS. 141 One way is by utilizing dynamic client registration [RFC7591] and 142 treating every RS as an OAuth client. In this case, the 143 authorization server is assumed to at least maintain "client_id" and 144 "token_endpoint_auth_method" with complementary authentication method 145 metadata, such as "jwks" or "client_secret". In cases where the AS 146 needs to acquire consent to transmit data to a RS, the following 147 client metadata fields are recommended: "client_name", "client_uri", 148 "contacts", "tos_uri", "policy_uri". 150 The AS MUST restrict the use of client credentials by a RS to the 151 calls it requires, e.g. the AS MAY restrict such a client to call the 152 token introspection endpoint only. How the AS implements this 153 restriction is beyond the scope of this specification. 155 This specification further introduces client metadata to manage the 156 configuration options required to sign and encrypt token 157 introspection response JWTs. 159 4. Requesting a JWT Response 161 A resource server requests a JWT introspection response by including 162 an "Accept" HTTP header "application/token-introspection+jwt" in the 163 introspection request. 165 The AS SHOULD authenticate the caller at the token introspection 166 endpoint. Authentication can utilize client authentication methods 167 or a separate access token issued to the resource server. Whether a 168 resource server is required to authenticate is determined by the 169 respective RS-specific policy at the AS. 171 The following is a non-normative example request with client 172 authentication: 174 POST /introspect HTTP/1.1 175 Host: as.example.com 176 Accept: application/token-introspection+jwt 177 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 178 Content-Type: application/x-www-form-urlencoded 180 token=2YotnFZFEjr1zCsicMWpAA 182 5. JWT Response 184 The introspection endpoint responds with a JWT, setting the "Content- 185 Type" HTTP header to "application/token-introspection+jwt" and the 186 JWT "typ" ("type") header to "token-introspection+jwt". 188 The JWT MUST include the following top-level claims: 190 iss MUST be set to the issuer URL of the authorization server. 192 aud MUST identify the resource server receiving the token 193 introspection response. 195 iat MUST be set to the time when the introspection response was 196 created by the authorization server. 198 token_introspection A JSON object containing the members of the 199 token introspection response, as specified in the "OAuth 200 Token Introspection Response" registry established by 201 [RFC7662] as well as other members. The separation of the 202 introspection members into a dedicated containing JWT claim 203 is intended to prevent conflict and confusion with top-level 204 JWT claims that may bear the same name. 206 If the access token is invalid, expired, revoked, or is not 207 intended for the calling resource server (audience), the 208 authorization server MUST set the value of the "active" 209 member in the "token_introspection" claim to "false" and 210 other members MUST NOT be included. Otherwise, the "active" 211 member is set to "true". 213 If possible, the AS MUST narrow down the "scope" value to the 214 scopes relevant to the particular RS. 216 Claims from the "JSON Web Token Claims" registry that are 217 commonly used in [OpenID.Core] and can be applied to the 218 resource owner MAY be included as members in the 219 "token_introspection" claim. They can serve to convey the 220 privileges delegated to the client, to identify the resource 221 owner as a natural person or to provide a required contact 222 detail, such as an e-Mail address or phone number. When 223 transmitting such claims the AS acts as an identity provider 224 in regard to the RS. The AS determines based on its RS- 225 specific policy what claims about the resource owner to 226 return in the token introspection response. 228 The AS MUST ensure the release of any privacy-sensitive data 229 is legally based. 231 Further content of the introspection response is determined 232 by the RS-specific policy at the AS. 234 The JWT MAY include other claims, including those from the "JSON Web 235 Token Claims" registry established by [RFC7519]. The JWT SHOULD NOT 236 include the "sub" and "exp" claims as an additional prevention 237 against misuse of the JWT as an access token (see Section 8.1). 239 Note: Although the JWT format is widely used as an access token 240 format, the JWT returned in the introspection response is not an 241 alternative representation of the introspected access token and is 242 not intended to be used as an access token. 244 This specification registers the "application/token- 245 introspection+jwt" media type, which is used as value of the "typ" 246 ("type") header parameter of the JWT to indicate that the payload is 247 a token introspection response. 249 The JWT is cryptographically secured as specified in [RFC7662]. 251 Depending on the specific resource server policy the JWT is either 252 signed, or signed and encrypted. If the JWT is signed and encrypted 253 it MUST be a Nested JWT, as defined in JWT [RFC7519]. 255 Note: If the resource server policy requires a signed and encrypted 256 response and the authorization server receives an unauthenticated 257 request containing an "Accept" header with content type other than 258 "application/token-introspection+jwt", it MUST refuse to serve the 259 request and return an HTTP status code 400. This is done to prevent 260 downgrading attacks to obtain token data intended for release to 261 legitimate recipients only (see Section 8.2). 263 The following is a non-normative example response (with line breaks 264 for display purposes only): 266 HTTP/1.1 200 OK 267 Content-Type: application/token-introspection+jwt 269 eyJraWQiOiJ3RzZEIiwidHlwIjoidG9rZW4taW50cm9zcGVjdGlvbitqd3QiLCJhbGc 270 iOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FzLmV4YW1wbGUuY29tLyIsImF1ZCI6I 271 mh0dHBzOi8vcnMuZXhhbXBsZS5jb20vcmVzb3VyY2UiLCJpYXQiOjE1MTQ3OTc4OTIs 272 InRva2VuX2ludHJvc3BlY3Rpb24iOnsiYWN0aXZlIjp0cnVlLCJpc3MiOiJodHRwczo 273 vL2FzLmV4YW1wbGUuY29tLyIsImF1ZCI6Imh0dHBzOi8vcnMuZXhhbXBsZS5jb20vcm 274 Vzb3VyY2UiLCJpYXQiOjE1MTQ3OTc4MjIsImV4cCI6MTUxNDc5Nzk0MiwiY2xpZW50X 275 2lkIjoicGFpQjJnb28wYSIsInNjb3BlIjoicmVhZHdyaXRlZG9scGhpbiIsInN1YiI6 276 Ilo1TzN1cFBDODhRckFqeDAwZGlzIiwiYmlydGhkYXRlIjoiMTk4Mi0wMi0wMSIsImd 277 pdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJEb2UiLCJqdGkiOiJ0MUZvQ0 278 NhWmQ0WHY0T1JKVVdWVWVUWmZzS2hXMzBDUUNyV0REandYeTZ3In19.przJMU5GhmNz 279 vwtt1Sr-xa9xTkpiAg5IshbQsRiRVP_7eGR1GHYrNwQh84kxOkHCyje2g5WSRcYosGE 280 VIiC-eoPJJ-qBwqwSlgx9JEeCDw2W5DjrblOI_N0Jvsq_dUeOyoWVMqlOydOBhKNY0s 281 mBrI4NZvEExucOm9WUJXMuJtvq1gBes-0go5j4TEv9sOP9uu81gqWTr_LOo6pgT0tFF 282 yZfWC4kbXPXiQ2YT6mxCiQRRNM-l9cBdF6Jx6IOrsfFhBuYdYQ_mlL19HgDDOFaleyq 283 mru6lKlASOsaE8dmLSeKcX91FbG79FKN8un24iwIDCbKT9xlUFl54xWVShNDFA 285 The example response JWT header contains the following JSON document: 287 { 288 "typ": "token-introspection+jwt", 289 "alg": "RS256" 290 "kid": "wG6D" 291 } 293 The example response JWT payload contains the following JSON 294 document: 296 { 297 "iss":"https://as.example.com/", 298 "aud":"https://rs.example.com/resource", 299 "iat":1514797892, 300 "token_introspection": 301 { 302 "active":true, 303 "iss":"https://as.example.com/", 304 "aud":"https://rs.example.com/resource", 305 "iat":1514797822, 306 "exp":1514797942, 307 "client_id":"paiB2goo0a", 308 "scope":"read write dolphin", 309 "sub":"Z5O3upPC88QrAjx00dis", 310 "birthdate":"1982-02-01", 311 "given_name":"John", 312 "family_name":"Doe", 313 "jti":"t1FoCCaZd4Xv4ORJUWVUeTZfsKhW30CQCrWDDjwXy6w" 314 } 315 } 317 6. Client Metadata 319 The authorization server determines the algorithm to secure the JWT 320 for a particular introspection response. This decision can be based 321 on registered metadata parameters for the resource server, supplied 322 via dynamic client registration [RFC7591] with the resource server 323 acting as a client, as specified below. 325 The parameter names follow the pattern established by OpenID Connect 326 Dynamic Client Registration [OpenID.Registration] for configuring 327 signing and encryption algorithms for JWT responses at the UserInfo 328 endpoint. 330 The following client metadata parameters are introduced by this 331 specification: 333 introspection_signed_response_alg OPTIONAL. JWS [RFC7515] algorithm 334 ("alg" value) as defined in JWA [RFC7518] for signing 335 introspection responses. If this is specified, the response 336 will be signed using JWS and the configured algorithm. The 337 default, if omitted, is "RS256". 339 introspection_encrypted_response_alg OPTIONAL. JWE [RFC7516] 340 algorithm ("alg" value) as defined in JWA [RFC7518] for 341 content key encryption. If this is specified, the response 342 will be encrypted using JWE and the configured content 343 encryption algorithm 344 ("introspection_encrypted_response_enc"). The default, if 345 omitted, is that no encryption is performed. If both signing 346 and encryption are requested, the response will be signed 347 then encrypted, with the result being a Nested JWT, as 348 defined in JWT [RFC7519]. 350 introspection_encrypted_response_enc OPTIONAL. JWE [RFC7516] 351 algorithm ("enc" value) as defined in JWA [RFC7518] for 352 content encryption of introspection responses. The default, 353 if omitted, is "A128CBC-HS256". Note: This parameter MUST 354 NOT be specified without setting 355 "introspection_encrypted_response_alg". 357 Resource servers may register their public encryption keys using the 358 "jwks_uri" or "jwks" metadata parameters. 360 7. Authorization Server Metadata 362 Authorization servers SHOULD publish the supported algorithms for 363 signing and encrypting the JWT of an introspection response by 364 utilizing OAuth 2.0 Authorization Server Metadata [RFC8414] 365 parameters. Resource servers use this data to parametrize their 366 client registration requests. 368 The following parameters are introduced by this specification: 370 introspection_signing_alg_values_supported OPTIONAL. JSON array 371 containing a list of the JWS [RFC7515] signing algorithms 372 ("alg" values) as defined in JWA [RFC7518] supported by the 373 introspection endpoint to sign the response. 375 introspection_encryption_alg_values_supported OPTIONAL. JSON array 376 containing a list of the JWE [RFC7516] encryption algorithms 377 ("alg" values) as defined in JWA [RFC7518] supported by the 378 introspection endpoint to encrypt the content encryption key 379 for introspection responses (content key encryption). 381 introspection_encryption_enc_values_supported OPTIONAL. JSON array 382 containing a list of the JWE [RFC7516] encryption algorithms 383 ("enc" values) as defined in JWA [RFC7518] supported by the 384 introspection endpoint to encrypt the response (content 385 encryption). 387 8. Security Considerations 389 8.1. Cross-JWT Confusion 391 The "iss" and potentially the "aud" claim of a token introspection 392 JWT can resemble those of a JWT-encoded access token. An attacker 393 could try to exploit this and pass a JWT token introspection response 394 as an access token to the resource server. The "typ" ("type") JWT 395 header "token-introspection+jwt" and the encapsulation of the token 396 introspection members such as "sub" and "scope" in the 397 "token_introspection" claim is intended to prevent such substitution 398 attacks. Resource servers MUST therefore check the "typ" JWT header 399 value of received JWT-encoded access tokens and ensure all minimally 400 required claims for a valid access token are present. 402 Resource servers MUST additionally apply the countermeasures against 403 replay as described in [I-D.ietf-oauth-security-topics], section 3.2. 405 JWT Confusion and other attacks involving JWTs are discussed in 406 [I-D.ietf-oauth-jwt-bcp]. 408 8.2. Token Data Leakage 410 The authorization server MUST use Transport Layer Security (TLS) 1.2 411 (or higher) per BCP 195 [RFC7525] in order to prevent token data 412 leakage. 414 To prevent introspection of leaked tokens and to present an 415 additional security layer against token guessing attacks the 416 authorization server MAY require all requests to the token 417 introspection endpoint to be authenticated. As an alternative or as 418 an addition to the authentication, the intended recipients MAY be set 419 up for encrypted responses. 421 In the latter case, confidentiality is ensured by the fact that only 422 the legitimate recipient is able to decrypt the response. An 423 attacker could try to circumvent this measure by requesting a plain 424 JSON response, using an "Accept" header with the content type set to, 425 for example, "application/json" instead of "application/token- 426 introspection+jwt". To prevent this attack the authorization server 427 MUST NOT serve requests with a content type other than "application/ 428 token-introspection+jwt" if the resource server is set up to receive 429 encrypted responses (see also Section 5). 431 8.3. Keeping Token Data Confidential from OAuth Clients 433 Authorization servers with a policy that requires token data to be 434 kept confidential from OAuth clients must require all requests to the 435 token introspection endpoint to be authenticated. As an alternative 436 or as an addition to the authentication, the intended recipients may 437 be set up for encrypted responses. 439 8.4. Logging and Audit of Introspection Activity 441 Authorization servers with a policy that requires token introspection 442 activity to be logged and audited must require all requests to the 443 token introspection endpoint to be authenticated. 445 9. Privacy Considerations 447 The token introspection response can be used to transfer personal 448 identifiable information from the AS to the RS. The AS MUST ensure a 449 legal basis exists for the data transfer before any data is released 450 to a particular RS. The way the legal basis is established might 451 vary among jurisdictions and MUST consider the legal entities 452 involved. 454 For example, the classical way to establish the legal basis is by 455 explicit user consent gathered from the resource owner by the AS 456 during the authorization flow. 458 It is also possible that the legal basis is established out of band, 459 e.g. in an explicit contract or by the client gathering the resource 460 owner's consent. 462 If the AS and the RS belong to the same legal entity (1st party 463 scenario), there is potentially no need for an explicit user consent 464 but the terms of service and policy of the respective service 465 provider MUST be enforced at all times. 467 In any case, the AS MUST ensure that the scope of the legal basis is 468 enforced throughout the whole process. The AS MUST retain the scope 469 of the legal basis with the access token, e.g. in the scope value, 470 and the AS MUST determine the data a resource server is allowed to 471 receive based on the resource server's identity and suitable token 472 data, e.g. the scope value. 474 10. Acknowledgements 476 We would like to thank Petteri Stenius, Neil Madden, Filip Skokan, 477 Tony Nadalin, Remco Schaar, Justin Richer and Takahiko Kawasaki for 478 their valuable feedback. 480 11. IANA Considerations 482 11.1. OAuth Dynamic Client Registration Metadata Registration 484 This specification requests registration of the following client 485 metadata definitions in the IANA "OAuth Dynamic Client Registration 486 Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 488 11.1.1. Registry Contents 490 o Client Metadata Name: "introspection_signed_response_alg" 492 o Client Metadata Description: String value indicating the client's 493 desired introspection response signing algorithm. 495 o Change Controller: IESG 497 o Specification Document(s): Section 6 of [[ this specification ]] 499 o Client Metadata Name: "introspection_encrypted_response_alg" 501 o Client Metadata Description: String value specifying the desired 502 introspection response content key encryption algorithm (alg 503 value). 505 o Change Controller: IESG 507 o Specification Document(s): Section 6 of [[ this specification ]] 509 o Client Metadata Name: "introspection_encrypted_response_enc" 511 o Client Metadata Description: String value specifying the desired 512 introspection response content encryption algorithm (enc value). 514 o Change Controller: IESG 516 o Specification Document(s): Section 6 of [[ this specification ]] 518 11.2. OAuth Authorization Server Metadata Registration 520 This specification requests registration of the following values in 521 the IANA "OAuth Authorization Server Metadata" registry 522 [IANA.OAuth.Parameters] established by [RFC8414]. 524 11.2.1. Registry Contents 526 o Metadata Name: "introspection_signing_alg_values_supported" 528 o Metadata Description: JSON array containing a list of algorithms 529 supported by the authorization server for introspection response 530 signing. 532 o Change Controller: IESG 534 o Specification Document(s): Section 7 of [[ this specification ]] 536 o Metadata Name: "introspection_encryption_alg_values_supported" 538 o Metadata Description: JSON array containing a list of algorithms 539 supported by the authorization server for introspection response 540 content key encryption (alg value). 542 o Change Controller: IESG 544 o Specification Document(s): Section 7 of [[ this specification ]] 546 o Metadata Name: "introspection_encryption_enc_values_supported" 548 o Metadata Description: JSON array containing a list of algorithms 549 supported by the authorization server for introspection response 550 content encryption (enc value). 552 o Change Controller: IESG 554 o Specification Document(s): Section 7 of [[ this specification ]] 556 11.3. Media Type Registration 558 This section registers the "application/token-introspection+jwt" 559 media type in the "Media Types" registry [IANA.MediaTypes] in the 560 manner described in [RFC6838], which can be used to indicate that the 561 content is a token introspection response in JWT format. 563 11.3.1. Registry Contents 565 o Type name: application 567 o Subtype name: token-introspection+jwt 569 o Required parameters: N/A 571 o Optional parameters: N/A 572 o Encoding considerations: binary; A token introspection response is 573 a JWT; JWT values are encoded as a series of base64url-encoded 574 values (with trailing '=' characters removed), some of which may 575 be the empty string, separated by period ('.') characters. 577 o Security considerations: See Section 7 of this specification 579 o Interoperability considerations: N/A 581 o Published specification: Section 4 of this specification 583 o Applications that use this media type: Applications that produce 584 and consume OAuth Token Introspection Responses in JWT format 586 o Fragment identifier considerations: N/A 588 o Additional information: 590 * Magic number(s): N/A 592 * File extension(s): N/A 594 * Macintosh file type code(s): N/A 596 o Person & email address to contact for further information: Torsten 597 Lodderstedt, torsten@lodderstedt.net 599 o Intended usage: COMMON 601 o Restrictions on usage: none 603 o Author: Torsten Lodderstedt, torsten@lodderstedt.net 605 o Change controller: IESG 607 o Provisional registration? No 609 11.4. JWT Claim Registration 611 This section registers the "token_introspection" claim in the JSON 612 Web Token (JWT) IANA registry [IANA.JWT] in the manner described in 613 [RFC7519]. 615 11.4.1. Registry Contents 617 o Claim name: token_introspection 619 o Claim description: Token introspection response 620 o Change Controller: IESG 622 o Specification Document(s): Section 5 of [[this specification]] 624 12. References 626 12.1. Normative References 628 [I-D.ietf-oauth-jwt-bcp] 629 Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 630 Current Practices", draft-ietf-oauth-jwt-bcp-06 (work in 631 progress), June 2019. 633 [I-D.ietf-oauth-security-topics] 634 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 635 "OAuth 2.0 Security Best Current Practice", draft-ietf- 636 oauth-security-topics-13 (work in progress), July 2019. 638 [IANA.JWT] 639 IANA, "JSON Web Token (JWT)", 640 . 642 [IANA.MediaTypes] 643 IANA, "Media Types", 644 . 646 [OpenID.Core] 647 Sakimura, N., Bradley, J., Jones, M., Medeiros, B. D., and 648 C. Mortimore, "OpenID Connect Core 1.0 incorporating 649 errata set 1", Nov 2014, 650 . 652 [OpenID.Registration] 653 Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect 654 Dynamic Client Registration 1.0 incorporating errata set 655 1", Nov 2014, . 658 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 659 Requirement Levels", BCP 14, RFC 2119, 660 DOI 10.17487/RFC2119, March 1997, 661 . 663 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 664 Specifications and Registration Procedures", BCP 13, 665 RFC 6838, DOI 10.17487/RFC6838, January 2013, 666 . 668 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 669 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 670 2015, . 672 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 673 RFC 7516, DOI 10.17487/RFC7516, May 2015, 674 . 676 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 677 DOI 10.17487/RFC7518, May 2015, 678 . 680 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 681 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 682 . 684 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 685 "Recommendations for Secure Use of Transport Layer 686 Security (TLS) and Datagram Transport Layer Security 687 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 688 2015, . 690 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 691 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 692 RFC 7591, DOI 10.17487/RFC7591, July 2015, 693 . 695 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 696 RFC 7662, DOI 10.17487/RFC7662, October 2015, 697 . 699 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 700 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 701 May 2017, . 703 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 704 Authorization Server Metadata", RFC 8414, 705 DOI 10.17487/RFC8414, June 2018, 706 . 708 12.2. Informative References 710 [IANA.OAuth.Parameters] 711 IANA, "OAuth Parameters", 712 . 714 Appendix A. Document History 716 [[ To be removed from the final specification ]] 718 -09 720 o changes the Accept and Content-Type HTTP headers from 721 "application/json" to "application/token-introspection+jwt" so 722 they match the registered media type 724 o moves the token introspection response members into a JSON object 725 claim named "token_introspection" to provide isolation from the 726 top-level JWT-specific claims 728 o "iss", "aud" and "iat" MUST be present as top-level JWT claims 730 o the "sub" and "exp" claims SHOULD NOT be used as top-level JWT 731 claims as additional prevention against JWT access token 732 substitution attacks 734 -08 736 o made difference between introspected access token and 737 introspection response clearer 739 o defined semantics of JWT claims overlapping between introspected 740 access token and introspection response as JWT 742 o added section about RS management 744 o added text about user claims including a privacy considerations 745 section 747 o removed registration of OpenID Connect claims to "Token 748 Introspection Response" registry and refer to "JWT Claims" 749 registry instead 751 o added registration of "application/token-introspection+jwt" media 752 type as type identifier of token introspection responses in JWT 753 format 755 o more changed to incorporate IESG review feedback 757 -07 759 o fixed wrong description of "locale" 761 o added references for ISO and ITU specifications 762 -06 764 o replaced reference to RFC 7159 with reference to RFC 8259 766 -05 768 o improved wording for TLS requirement 770 o added RFC 2119 boilerplate 772 o fixed and updated some references 774 -04 776 o reworked definition of parameters in section 4 778 o added text on data minimization to security considerations section 780 o added statement regarding TLS to security considerations section 782 -03 784 o added registration for OpenID Connect Standard Claims to OAuth 785 Token Introspection Response registry 787 -02 789 o updated references 791 -01 793 o adapted wording to preclude any accept header except "application/ 794 jwt" if encrypted responses are required 796 o use registered alg value RS256 for default signing algorithm 798 o added text on claims in the token introspection response 800 -00 802 o initial version of the WG draft 804 o defined default signing algorithm 806 o changed behavior in case resource server is set up for encryption 808 o Added text on token data leakage prevention to the security 809 considerations 811 o moved Security Considerations section forward 813 WG draft 815 -01 817 o fixed typos in client meta data field names 819 o added OAuth Server Metadata parameters to publish algorithms 820 supported for signing and encrypting the introspection response 822 o added registration of new parameters for OAuth Server Metadata and 823 Client Registration 825 o added explicit request for JWT introspection response 827 o made iss and aud claims mandatory in introspection response 829 o Stylistic and clarifying edits, updates references 831 -00 833 o initial version 835 Authors' Addresses 837 Torsten Lodderstedt (editor) 838 yes.com AG 840 Email: torsten@lodderstedt.net 842 Vladimir Dzhuvinov 843 Connect2id Ltd. 845 Email: vladimir@connect2id.com