idnits 2.17.1 draft-ietf-oauth-jwt-introspection-response-10.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 (October 18, 2020) is 1285 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 (-26) 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: April 21, 2021 Connect2id Ltd. 6 October 18, 2020 8 JWT Response for OAuth Token Introspection 9 draft-ietf-oauth-jwt-introspection-response-10 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 April 21, 2021. 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 . . . . . . . . . . . . . . . . . . . . . . . 8 56 7. Authorization Server Metadata . . . . . . . . . . . . . . . . 9 57 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 58 8.1. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 10 59 8.2. Token Data Leakage . . . . . . . . . . . . . . . . . . . 10 60 8.3. Keeping Token Data Confidential from OAuth Clients . . . 10 61 8.4. Logging and Audit of Introspection Activity . . . . . . . 11 62 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 11 63 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 64 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 65 11.1. OAuth Dynamic Client Registration Metadata Registration 12 66 11.1.1. Registry Contents . . . . . . . . . . . . . . . . . 12 67 11.2. OAuth Authorization Server Metadata Registration . . . . 13 68 11.2.1. Registry Contents . . . . . . . . . . . . . . . . . 13 69 11.3. Media Type Registration . . . . . . . . . . . . . . . . 13 70 11.3.1. Registry Contents . . . . . . . . . . . . . . . . . 14 71 11.4. JWT Claim Registration . . . . . . . . . . . . . . . . . 15 72 11.4.1. Registry Contents . . . . . . . . . . . . . . . . . 15 73 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 74 12.1. Normative References . . . . . . . . . . . . . . . . . . 15 75 12.2. Informative References . . . . . . . . . . . . . . . . . 17 76 Appendix A. Document History . . . . . . . . . . . . . . . . . . 17 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 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 [RFC7662], 200 section 2.2. The separation of the introspection response 201 members into a dedicated containing JWT claim is intended to 202 prevent conflict and confusion with top-level JWT claims that 203 may bear the same name. 205 If the access token is invalid, expired, revoked, or is not 206 intended for the calling resource server (audience), the 207 authorization server MUST set the value of the "active" 208 member in the "token_introspection" claim to "false" and 209 other members MUST NOT be included. Otherwise, the "active" 210 member is set to "true". 212 If possible, the AS MUST narrow down the "scope" value to the 213 scopes relevant to the particular RS. 215 As specified in section 2.2. of [RFC7662], specific 216 implementations MAY extend the token introspection response 217 with service-specific claims. In the context of this 218 specification, such claims will be added as top-level members 219 of the "token_introspection" claim. Response names intended 220 to be used across domains MUST be registered in the OAuth 221 Token Introspection Response registry 222 [IANA.OAuth.Token.Introspection] defined by [RFC7662]. In 223 addition, claims from the JSON Web Token Claims registry 224 [IANA.JWT] established by [RFC7519] MAY be included as 225 members in the "token_introspection" claim. They can serve 226 to convey the privileges delegated to the client, to identify 227 the resource owner or to provide a required contact detail, 228 such as an e-Mail address or phone number. When transmitting 229 such claims the AS acts as an identity provider in regard to 230 the RS. The AS determines based on its RS-specific policy 231 what claims about the resource owner to return in the token 232 introspection response. 234 The AS MUST ensure the release of any privacy-sensitive data 235 is legally based (see Section 9). 237 Further content of the introspection response is determined 238 by the RS-specific policy at the AS. 240 The JWT MAY include other claims, including those from the "JSON Web 241 Token Claims" registry established by [RFC7519]. The JWT SHOULD NOT 242 include the "sub" and "exp" claims as an additional prevention 243 against misuse of the JWT as an access token (see Section 8.1). 245 Note: Although the JWT format is widely used as an access token 246 format, the JWT returned in the introspection response is not an 247 alternative representation of the introspected access token and is 248 not intended to be used as an access token. 250 This specification registers the "application/token- 251 introspection+jwt" media type, which is used as value of the "typ" 252 ("type") header parameter of the JWT to indicate that the payload is 253 a token introspection response. 255 The JWT is cryptographically secured as specified in [RFC7662]. 257 Depending on the specific resource server policy the JWT is either 258 signed, or signed and encrypted. If the JWT is signed and encrypted 259 it MUST be a Nested JWT, as defined in JWT [RFC7519]. 261 Note: If the resource server policy requires a signed and encrypted 262 response and the authorization server receives an unauthenticated 263 request containing an "Accept" header with content type other than 264 "application/token-introspection+jwt", it MUST refuse to serve the 265 request and return an HTTP status code 400. This is done to prevent 266 downgrading attacks to obtain token data intended for release to 267 legitimate recipients only (see Section 8.2). 269 The following is a non-normative example response (with line breaks 270 for display purposes only): 272 HTTP/1.1 200 OK 273 Content-Type: application/token-introspection+jwt 275 eyJraWQiOiJ3RzZEIiwidHlwIjoidG9rZW4taW50cm9zcGVjdGlvbitqd3QiLCJhbGc 276 iOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FzLmV4YW1wbGUuY29tLyIsImF1ZCI6I 277 mh0dHBzOi8vcnMuZXhhbXBsZS5jb20vcmVzb3VyY2UiLCJpYXQiOjE1MTQ3OTc4OTIs 278 InRva2VuX2ludHJvc3BlY3Rpb24iOnsiYWN0aXZlIjp0cnVlLCJpc3MiOiJodHRwczo 279 vL2FzLmV4YW1wbGUuY29tLyIsImF1ZCI6Imh0dHBzOi8vcnMuZXhhbXBsZS5jb20vcm 280 Vzb3VyY2UiLCJpYXQiOjE1MTQ3OTc4MjIsImV4cCI6MTUxNDc5Nzk0MiwiY2xpZW50X 281 2lkIjoicGFpQjJnb28wYSIsInNjb3BlIjoicmVhZHdyaXRlZG9scGhpbiIsInN1YiI6 282 Ilo1TzN1cFBDODhRckFqeDAwZGlzIiwiYmlydGhkYXRlIjoiMTk4Mi0wMi0wMSIsImd 283 pdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJEb2UiLCJqdGkiOiJ0MUZvQ0 284 NhWmQ0WHY0T1JKVVdWVWVUWmZzS2hXMzBDUUNyV0REandYeTZ3In19.przJMU5GhmNz 285 vwtt1Sr-xa9xTkpiAg5IshbQsRiRVP_7eGR1GHYrNwQh84kxOkHCyje2g5WSRcYosGE 286 VIiC-eoPJJ-qBwqwSlgx9JEeCDw2W5DjrblOI_N0Jvsq_dUeOyoWVMqlOydOBhKNY0s 287 mBrI4NZvEExucOm9WUJXMuJtvq1gBes-0go5j4TEv9sOP9uu81gqWTr_LOo6pgT0tFF 288 yZfWC4kbXPXiQ2YT6mxCiQRRNM-l9cBdF6Jx6IOrsfFhBuYdYQ_mlL19HgDDOFaleyq 289 mru6lKlASOsaE8dmLSeKcX91FbG79FKN8un24iwIDCbKT9xlUFl54xWVShNDFA 291 The example response JWT header contains the following JSON document: 293 { 294 "typ": "token-introspection+jwt", 295 "alg": "RS256", 296 "kid": "wG6D" 297 } 299 The example response JWT payload contains the following JSON 300 document: 302 { 303 "iss":"https://as.example.com/", 304 "aud":"https://rs.example.com/resource", 305 "iat":1514797892, 306 "token_introspection": 307 { 308 "active":true, 309 "iss":"https://as.example.com/", 310 "aud":"https://rs.example.com/resource", 311 "iat":1514797822, 312 "exp":1514797942, 313 "client_id":"paiB2goo0a", 314 "scope":"read write dolphin", 315 "sub":"Z5O3upPC88QrAjx00dis", 316 "birthdate":"1982-02-01", 317 "given_name":"John", 318 "family_name":"Doe", 319 "jti":"t1FoCCaZd4Xv4ORJUWVUeTZfsKhW30CQCrWDDjwXy6w" 320 } 321 } 323 6. Client Metadata 325 The authorization server determines the algorithm to secure the JWT 326 for a particular introspection response. This decision can be based 327 on registered metadata parameters for the resource server, supplied 328 via dynamic client registration [RFC7591] with the resource server 329 acting as a client, as specified below. 331 The parameter names follow the pattern established by OpenID Connect 332 Dynamic Client Registration [OpenID.Registration] for configuring 333 signing and encryption algorithms for JWT responses at the UserInfo 334 endpoint. 336 The following client metadata parameters are introduced by this 337 specification: 339 introspection_signed_response_alg OPTIONAL. JWS [RFC7515] algorithm 340 ("alg" value) as defined in JWA [RFC7518] for signing 341 introspection responses. If this is specified, the response 342 will be signed using JWS and the configured algorithm. The 343 default, if omitted, is "RS256". 345 introspection_encrypted_response_alg OPTIONAL. JWE [RFC7516] 346 algorithm ("alg" value) as defined in JWA [RFC7518] for 347 content key encryption. If this is specified, the response 348 will be encrypted using JWE and the configured content 349 encryption algorithm 350 ("introspection_encrypted_response_enc"). The default, if 351 omitted, is that no encryption is performed. If both signing 352 and encryption are requested, the response will be signed 353 then encrypted, with the result being a Nested JWT, as 354 defined in JWT [RFC7519]. 356 introspection_encrypted_response_enc OPTIONAL. JWE [RFC7516] 357 algorithm ("enc" value) as defined in JWA [RFC7518] for 358 content encryption of introspection responses. The default, 359 if omitted, is "A128CBC-HS256". Note: This parameter MUST 360 NOT be specified without setting 361 "introspection_encrypted_response_alg". 363 Resource servers may register their public encryption keys using the 364 "jwks_uri" or "jwks" metadata parameters. 366 7. Authorization Server Metadata 368 Authorization servers SHOULD publish the supported algorithms for 369 signing and encrypting the JWT of an introspection response by 370 utilizing OAuth 2.0 Authorization Server Metadata [RFC8414] 371 parameters. Resource servers use this data to parametrize their 372 client registration requests. 374 The following parameters are introduced by this specification: 376 introspection_signing_alg_values_supported OPTIONAL. JSON array 377 containing a list of the JWS [RFC7515] signing algorithms 378 ("alg" values) as defined in JWA [RFC7518] supported by the 379 introspection endpoint to sign the response. 381 introspection_encryption_alg_values_supported OPTIONAL. JSON array 382 containing a list of the JWE [RFC7516] encryption algorithms 383 ("alg" values) as defined in JWA [RFC7518] supported by the 384 introspection endpoint to encrypt the content encryption key 385 for introspection responses (content key encryption). 387 introspection_encryption_enc_values_supported OPTIONAL. JSON array 388 containing a list of the JWE [RFC7516] encryption algorithms 389 ("enc" values) as defined in JWA [RFC7518] supported by the 390 introspection endpoint to encrypt the response (content 391 encryption). 393 8. Security Considerations 394 8.1. Cross-JWT Confusion 396 The "iss" and potentially the "aud" claim of a token introspection 397 JWT can resemble those of a JWT-encoded access token. An attacker 398 could try to exploit this and pass a JWT token introspection response 399 as an access token to the resource server. The "typ" ("type") JWT 400 header "token-introspection+jwt" and the encapsulation of the token 401 introspection members such as "sub" and "scope" in the 402 "token_introspection" claim is intended to prevent such substitution 403 attacks. Resource servers MUST therefore check the "typ" JWT header 404 value of received JWT-encoded access tokens and ensure all minimally 405 required claims for a valid access token are present. 407 Resource servers MUST additionally apply the countermeasures against 408 replay as described in [I-D.ietf-oauth-security-topics], section 3.2. 410 JWT Confusion and other attacks involving JWTs are discussed in 411 [I-D.ietf-oauth-jwt-bcp]. 413 8.2. Token Data Leakage 415 The authorization server MUST use Transport Layer Security (TLS) 1.2 416 (or higher) per BCP 195 [RFC7525] in order to prevent token data 417 leakage. 419 To prevent introspection of leaked tokens and to present an 420 additional security layer against token guessing attacks the 421 authorization server MAY require all requests to the token 422 introspection endpoint to be authenticated. As an alternative or as 423 an addition to the authentication, the intended recipients MAY be set 424 up for encrypted responses. 426 In the latter case, confidentiality is ensured by the fact that only 427 the legitimate recipient is able to decrypt the response. An 428 attacker could try to circumvent this measure by requesting a plain 429 JSON response, using an "Accept" header with the content type set to, 430 for example, "application/json" instead of "application/token- 431 introspection+jwt". To prevent this attack the authorization server 432 MUST NOT serve requests with a content type other than "application/ 433 token-introspection+jwt" if the resource server is set up to receive 434 encrypted responses (see also Section 5). 436 8.3. Keeping Token Data Confidential from OAuth Clients 438 Authorization servers with a policy that requires token data to be 439 kept confidential from OAuth clients must require all requests to the 440 token introspection endpoint to be authenticated. As an alternative 441 or as an addition to the authentication, the intended recipients may 442 be set up for encrypted responses. 444 8.4. Logging and Audit of Introspection Activity 446 Authorization servers with a policy that requires token introspection 447 activity to be logged and audited must require all requests to the 448 token introspection endpoint to be authenticated. 450 9. Privacy Considerations 452 The token introspection response can be used to transfer personal 453 identifiable information from the AS to the RS. The AS MUST ensure a 454 legal basis exists for the data transfer before any data is released 455 to a particular RS. The way the legal basis is established might 456 vary among jurisdictions and MUST consider the legal entities 457 involved. 459 For example, the classical way to establish the legal basis is by 460 explicit user consent gathered from the resource owner by the AS 461 during the authorization flow. 463 It is also possible that the legal basis is established out of band, 464 e.g. in an explicit contract or by the client gathering the resource 465 owner's consent. 467 If the AS and the RS belong to the same legal entity (1st party 468 scenario), there is potentially no need for an explicit user consent 469 but the terms of service and policy of the respective service 470 provider MUST be enforced at all times. 472 In any case, the AS MUST ensure that the scope of the legal basis is 473 enforced throughout the whole process. The AS MUST retain the scope 474 of the legal basis with the access token, e.g. in the scope value, it 475 MUST authenicate the RS, and the AS MUST determine the data a 476 resource server is allowed to receive based on the resource server's 477 identity and suitable token data, e.g. the scope value. 479 Implementers should be aware that a token introspection request lets 480 the AS know when the client (and potentially the user) is accessing 481 the RS, which is also an indication of when the user is using the 482 client. If this impliction is not accepatable, implementars MUST use 483 other means to carry access token data, e.g. directly transferring 484 the data needed by the RS within the access token. 486 10. Acknowledgements 488 We would like to thank Petteri Stenius, Neil Madden, Filip Skokan, 489 Tony Nadalin, Remco Schaar, Justin Richer and Takahiko Kawasaki for 490 their valuable feedback. 492 11. IANA Considerations 494 11.1. OAuth Dynamic Client Registration Metadata Registration 496 This specification requests registration of the following client 497 metadata definitions in the IANA "OAuth Dynamic Client Registration 498 Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 500 11.1.1. Registry Contents 502 o Client Metadata Name: "introspection_signed_response_alg" 504 o Client Metadata Description: String value indicating the client's 505 desired introspection response signing algorithm. 507 o Change Controller: IESG 509 o Specification Document(s): Section 6 of [[ this specification ]] 511 o Client Metadata Name: "introspection_encrypted_response_alg" 513 o Client Metadata Description: String value specifying the desired 514 introspection response content key encryption algorithm (alg 515 value). 517 o Change Controller: IESG 519 o Specification Document(s): Section 6 of [[ this specification ]] 521 o Client Metadata Name: "introspection_encrypted_response_enc" 523 o Client Metadata Description: String value specifying the desired 524 introspection response content encryption algorithm (enc value). 526 o Change Controller: IESG 528 o Specification Document(s): Section 6 of [[ this specification ]] 530 11.2. OAuth Authorization Server Metadata Registration 532 This specification requests registration of the following values in 533 the IANA "OAuth Authorization Server Metadata" registry 534 [IANA.OAuth.Parameters] established by [RFC8414]. 536 11.2.1. Registry Contents 538 o Metadata Name: "introspection_signing_alg_values_supported" 540 o Metadata Description: JSON array containing a list of algorithms 541 supported by the authorization server for introspection response 542 signing. 544 o Change Controller: IESG 546 o Specification Document(s): Section 7 of [[ this specification ]] 548 o Metadata Name: "introspection_encryption_alg_values_supported" 550 o Metadata Description: JSON array containing a list of algorithms 551 supported by the authorization server for introspection response 552 content key encryption (alg value). 554 o Change Controller: IESG 556 o Specification Document(s): Section 7 of [[ this specification ]] 558 o Metadata Name: "introspection_encryption_enc_values_supported" 560 o Metadata Description: JSON array containing a list of algorithms 561 supported by the authorization server for introspection response 562 content encryption (enc value). 564 o Change Controller: IESG 566 o Specification Document(s): Section 7 of [[ this specification ]] 568 11.3. Media Type Registration 570 This section registers the "application/token-introspection+jwt" 571 media type in the "Media Types" registry [IANA.MediaTypes] in the 572 manner described in [RFC6838], which can be used to indicate that the 573 content is a token introspection response in JWT format. 575 11.3.1. Registry Contents 577 o Type name: application 579 o Subtype name: token-introspection+jwt 581 o Required parameters: N/A 583 o Optional parameters: N/A 585 o Encoding considerations: binary; A token introspection response is 586 a JWT; JWT values are encoded as a series of base64url-encoded 587 values (with trailing '=' characters removed), some of which may 588 be the empty string, separated by period ('.') characters. 590 o Security considerations: See Section 7 of this specification 592 o Interoperability considerations: N/A 594 o Published specification: Section 4 of this specification 596 o Applications that use this media type: Applications that produce 597 and consume OAuth Token Introspection Responses in JWT format 599 o Fragment identifier considerations: N/A 601 o Additional information: 603 * Magic number(s): N/A 605 * File extension(s): N/A 607 * Macintosh file type code(s): N/A 609 o Person & email address to contact for further information: Torsten 610 Lodderstedt, torsten@lodderstedt.net 612 o Intended usage: COMMON 614 o Restrictions on usage: none 616 o Author: Torsten Lodderstedt, torsten@lodderstedt.net 618 o Change controller: IESG 620 o Provisional registration? No 622 11.4. JWT Claim Registration 624 This section registers the "token_introspection" claim in the JSON 625 Web Token (JWT) IANA registry [IANA.JWT] in the manner described in 626 [RFC7519]. 628 11.4.1. Registry Contents 630 o Claim name: token_introspection 632 o Claim description: Token introspection response 634 o Change Controller: IESG 636 o Specification Document(s): Section 5 of [[this specification]] 638 12. References 640 12.1. Normative References 642 [I-D.ietf-oauth-jwt-bcp] 643 Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 644 Current Practices", draft-ietf-oauth-jwt-bcp-06 (work in 645 progress), June 2019. 647 [I-D.ietf-oauth-security-topics] 648 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 649 "OAuth 2.0 Security Best Current Practice", draft-ietf- 650 oauth-security-topics-13 (work in progress), July 2019. 652 [IANA.JWT] 653 IANA, "JSON Web Token (JWT) claims registry", 654 . 656 [IANA.MediaTypes] 657 IANA, "Media Types", 658 . 660 [IANA.OAuth.Token.Introspection] 661 IANA, "OAuth Token Introspection Response registry", 662 . 665 [OpenID.Registration] 666 Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect 667 Dynamic Client Registration 1.0 incorporating errata set 668 1", Nov 2014, . 671 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 672 Requirement Levels", BCP 14, RFC 2119, 673 DOI 10.17487/RFC2119, March 1997, 674 . 676 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 677 Specifications and Registration Procedures", BCP 13, 678 RFC 6838, DOI 10.17487/RFC6838, January 2013, 679 . 681 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 682 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 683 2015, . 685 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 686 RFC 7516, DOI 10.17487/RFC7516, May 2015, 687 . 689 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 690 DOI 10.17487/RFC7518, May 2015, 691 . 693 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 694 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 695 . 697 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 698 "Recommendations for Secure Use of Transport Layer 699 Security (TLS) and Datagram Transport Layer Security 700 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 701 2015, . 703 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 704 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 705 RFC 7591, DOI 10.17487/RFC7591, July 2015, 706 . 708 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 709 RFC 7662, DOI 10.17487/RFC7662, October 2015, 710 . 712 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 713 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 714 May 2017, . 716 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 717 Authorization Server Metadata", RFC 8414, 718 DOI 10.17487/RFC8414, June 2018, 719 . 721 12.2. Informative References 723 [IANA.OAuth.Parameters] 724 IANA, "OAuth Parameters", 725 . 727 Appendix A. Document History 729 [[ To be removed from the final specification ]] 731 -10 733 o added requirement to authenticate RS if privacy sensitive data is 734 released 736 o reworked text on claims from different registries 738 o added forward reference to privacy considerations to section 5 740 o added text in privacy considerations regarding client/user 741 tracking 743 -09 745 o changes the Accept and Content-Type HTTP headers from 746 "application/json" to "application/token-introspection+jwt" so 747 they match the registered media type 749 o moves the token introspection response members into a JSON object 750 claim named "token_introspection" to provide isolation from the 751 top-level JWT-specific claims 753 o "iss", "aud" and "iat" MUST be present as top-level JWT claims 755 o the "sub" and "exp" claims SHOULD NOT be used as top-level JWT 756 claims as additional prevention against JWT access token 757 substitution attacks 759 -08 761 o made difference between introspected access token and 762 introspection response clearer 764 o defined semantics of JWT claims overlapping between introspected 765 access token and introspection response as JWT 767 o added section about RS management 769 o added text about user claims including a privacy considerations 770 section 772 o removed registration of OpenID Connect claims to "Token 773 Introspection Response" registry and refer to "JWT Claims" 774 registry instead 776 o added registration of "application/token-introspection+jwt" media 777 type as type identifier of token introspection responses in JWT 778 format 780 o more changed to incorporate IESG review feedback 782 -07 784 o fixed wrong description of "locale" 786 o added references for ISO and ITU specifications 788 -06 790 o replaced reference to RFC 7159 with reference to RFC 8259 792 -05 794 o improved wording for TLS requirement 796 o added RFC 2119 boilerplate 798 o fixed and updated some references 800 -04 802 o reworked definition of parameters in section 4 804 o added text on data minimization to security considerations section 806 o added statement regarding TLS to security considerations section 808 -03 810 o added registration for OpenID Connect Standard Claims to OAuth 811 Token Introspection Response registry 813 -02 815 o updated references 817 -01 819 o adapted wording to preclude any accept header except "application/ 820 jwt" if encrypted responses are required 822 o use registered alg value RS256 for default signing algorithm 824 o added text on claims in the token introspection response 826 -00 828 o initial version of the WG draft 830 o defined default signing algorithm 832 o changed behavior in case resource server is set up for encryption 834 o Added text on token data leakage prevention to the security 835 considerations 837 o moved Security Considerations section forward 839 WG draft 841 -01 843 o fixed typos in client meta data field names 845 o added OAuth Server Metadata parameters to publish algorithms 846 supported for signing and encrypting the introspection response 848 o added registration of new parameters for OAuth Server Metadata and 849 Client Registration 851 o added explicit request for JWT introspection response 853 o made iss and aud claims mandatory in introspection response 855 o Stylistic and clarifying edits, updates references 857 -00 859 o initial version 861 Authors' Addresses 863 Torsten Lodderstedt (editor) 864 yes.com AG 866 Email: torsten@lodderstedt.net 868 Vladimir Dzhuvinov 869 Connect2id Ltd. 871 Email: vladimir@connect2id.com