idnits 2.17.1 draft-ietf-oauth-jwt-introspection-response-00.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: In the latter case, confidentiality is ensured by the fact that only the legitimate recipient is able to decrypt the response. An attacker could try to circumvent this measure by requesting a plain JSON response, using an Accept header with the content type set to "application/json" instead of "application/jwt". To prevent this attack the authorization server MUST not serve requests with content type "application/json" if the resource server is set up to receive encrypted responses (see also Section 3). -- The document date (August 05, 2018) is 2089 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) == Unused Reference: 'RFC2119' is defined on line 387, but no explicit reference was found in the text == Unused Reference: 'RFC2246' is defined on line 392, but no explicit reference was found in the text == Outdated reference: A later version (-07) exists of draft-ietf-oauth-jwt-bcp-03 == Outdated reference: A later version (-26) exists of draft-ietf-oauth-security-topics-06 ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) Summary: 1 error (**), 0 flaws (~~), 7 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: February 6, 2019 Connect2id Ltd. 6 August 05, 2018 8 JWT Response for OAuth Token Introspection 9 draft-ietf-oauth-jwt-introspection-response-00 11 Abstract 13 This draft proposes an additional JSON Web Token (JWT) based response 14 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 February 6, 2019. 33 Copyright Notice 35 Copyright (c) 2018 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. Requesting a JWT Response . . . . . . . . . . . . . . . . . . 3 52 3. JWT Response . . . . . . . . . . . . . . . . . . . . . . . . 3 53 4. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 4 54 5. Authorization Server Metadata . . . . . . . . . . . . . . . . 5 55 6. Security Considerations . . . . . . . . . . . . . . . . . . . 5 56 6.1. Cross-JWT Confusion . . . . . . . . . . . . . . . . . . . 5 57 6.2. Token Data Leakage . . . . . . . . . . . . . . . . . . . 6 58 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 59 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 60 8.1. OAuth Dynamic Client Registration Metadata Registration . 7 61 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 7 62 8.2. OAuth Authorization Server Metadata Registration . . . . 7 63 8.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 7 64 8.3. OAuth Token Introspection Response . . . . . . . . . . . 8 65 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 67 9.2. Informative References . . . . . . . . . . . . . . . . . 10 68 Appendix A. Document History . . . . . . . . . . . . . . . . . . 10 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 71 1. Introduction 73 OAuth 2.0 Token Introspection [RFC7662] specifies a method for a 74 protected resource to query an OAuth 2.0 authorization server to 75 determine the state of an access token and obtain data associated 76 with the access token. This allows deployments to implement 77 identifier-based access tokens in an interoperable way. 79 The introspection response, as specified in OAuth 2.0 Token 80 Introspection [RFC7662], is a plain JSON object. However, there are 81 use cases where the resource server requires stronger assurance that 82 the authorization server issued the access token, including cases 83 where the authorization server assumes liability for the token's 84 content. An example is a resource server using verified person data 85 to create certificates, which in turn are used to create qualified 86 electronic signatures. 88 In such use cases it may be useful or even required to return a 89 signed JWT as the introspection response. This specification extends 90 the token introspection endpoint with the capability to return 91 responses as JWTs. 93 2. Requesting a JWT Response 95 A resource server requests to receive a JWT introspection response by 96 including an Accept header with content type "application/jwt" in the 97 introspection request. 99 The following is a non-normative example request: 101 POST /introspect HTTP/1.1 102 Host: server.example.com 103 Accept: application/jwt 104 Content-Type: application/x-www-form-urlencoded 106 token=2YotnFZFEjr1zCsicMWpAA 108 3. JWT Response 110 The introspection endpoint responds with a JWT, setting the Content- 111 Type header to "application/jwt". 113 This JWT MUST contain the claims "iss" and "aud" in order to prevent 114 misuse of the JWT as ID or access token (see Section 6.1). 116 This JWT may furthermore contain all other claims described in 117 Section 2.2. of [RFC7662]. 119 The following is a non-normative example response (with line breaks 120 for display purposes only): 122 HTTP/1.1 200 OK 123 Content-Type: application/jwt 125 eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJaNU8zdXBQQzg4UXJBa 126 ngwMGRpcyIsImF1ZCI6Imh0dHBzOlwvXC9wcm90ZWN0ZWQuZXhhbXBsZS5uZXRcL 127 3Jlc291cmNlIiwiZXh0ZW5zaW9uX2ZpZWxkIjoidHdlbnR5LXNldmVuIiwic2Nvc 128 GUiOiJyZWFkIHdyaXRlIGRvbHBoaW4iLCJpc3MiOiJodHRwczpcL1wvc2VydmVyL 129 mV4YW1wbGUuY29tXC8iLCJhY3RpdmUiOnRydWUsImV4cCI6MTQxOTM1NjIzOCwia 130 WF0IjoxNDE5MzUwMjM4LCJjbGllbnRfaWQiOiJsMjM4ajMyM2RzLTIzaWo0Iiwid 131 XNlcm5hbWUiOiJqZG9lIn0.HEQHf05vqVvWVnWuEjbzUnPz6JDQVR69QkxgzBNq5 132 kk-sK54ieg1STazXGsdFAT8nUhiiV1f_Z4HOKNnBs8TLKaFXokhA0MqNBOYI--2u 133 nVHDqI_RPmC3p0NmP02Xmv4hzxFmTmpgjSy3vpKQDihOjhwNBh7G81JNaJqjJQTR 134 v_1dHUPJotQjMK3k8_5FyiO2p64Y2VyxyQn1VWVlgOHlJwhj6BaGHk4Qf5F8DHQZ 135 1WCPg2p_-hwfINfXh1_buSjxyDRF4oe9pKy6ZB3ejh9qIMm-WrwltuU1uWMXxN6e 136 S6tUtpKo8UCHBwLWCHmJN7KU6ZojmaISspdS23lELAlyw 138 The example response contains the following JSON document: 140 { 141 "sub": "Z5O3upPC88QrAjx00dis", 142 "aud": "https://protected.example.net/resource", 143 "scope": "read write dolphin", 144 "iss": "https://server.example.com/", 145 "active": true, 146 "exp": 1419356238, 147 "iat": 1419350238, 148 "client_id": "l238j323ds-23ij4", 149 "given_name": "John", 150 "family_name":"Doe", 151 "birthdate":"1982-02-01" 152 } 154 Depending on the specific resource server policy the JWT is either 155 signed, or signed and encrypted. If the JWT is signed and encrypted 156 it MUST be a Nested JWT, as defined in JWT [RFC7519]. 158 Note: If the resource server policy requires a signed and encrypted 159 response and the authorization server receives an unauthenticated 160 request containing an Accept header with content type "application/ 161 json", it MUST refuse to serve the request and return an HTTP status 162 code 400. This is done to prevent downgrading attacks to obtain 163 token data intended for release to legitimate recipients only (which 164 possess the respective decryption key). 166 4. Client Metadata 168 The authorization server determines what algorithm to employ to 169 secure the JWT for a particular introspection response. This 170 decision can be based on registered metadata parameters for the 171 resource server, supplied via dynamic client registration with the 172 resource server posing as the client, as defined by this draft. 174 The parameter names follow the pattern established by OpenID Connect 175 Dynamic Client Registration [OpenID.Registration] for configuring 176 signing and encryption algorithms for JWT responses at the UserInfo 177 endpoint. 179 The following client metadata parameters are introduced by this 180 specification: 182 introspection_signed_response_alg JWS [RFC7515] "alg" algorithm JWA 183 [RFC7518] REQUIRED for signing introspection responses. If 184 this is specified, the response will be signed using JWS and 185 the configured algorithm. The default, if omitted, is RSA 186 SHA-256. 188 introspection_encrypted_response_alg JWE [RFC7516] "alg" algorithm 189 JWA [RFC7518] REQUIRED for encrypting introspection 190 responses. If both signing and encryption are requested, the 191 response will be signed then encrypted, with the result being 192 a Nested JWT, as defined in JWT [RFC7519]. The default, if 193 omitted, is that no encryption is performed. 195 introspection_encrypted_response_enc JWE [RFC7516] "enc" algorithm 196 JWA [RFC7518] REQUIRED for encrypting introspection 197 responses. If "introspection_encrypted_response_alg" is 198 specified, the default for this value is A128CBC-HS256. When 199 "introspection_encrypted_response_enc" is included, 200 "introspection_encrypted_response_alg" MUST also be provided. 202 Resource servers may register their public encryption keys using the 203 "jwks_uri" or "jwks" metadata parameters. 205 5. Authorization Server Metadata 207 Authorization servers SHOULD publish the supported algorithms for 208 signing and encrypting the JWT of an introspection response by 209 utilizing OAuth 2.0 Authorization Server Metadata [RFC8414] 210 parameters. 212 The following parameters are introduced by this specification: 214 introspection_signing_alg_values_supported OPTIONAL. JSON array 215 containing a list of the JWS [RFC7515] signing algorithms 216 ("alg" values) JWA [RFC7518] supported by the introspection 217 endpoint to sign the response. 219 introspection_encryption_alg_values_supported OPTIONAL. JSON array 220 containing a list of the JWE [RFC7516] encryption algorithms 221 ("alg" values) JWA [RFC7518] supported by the introspection 222 endpoint to encrypt the response. 224 introspection_encryption_enc_values_supported OPTIONAL. JSON array 225 containing a list of the JWE [RFC7516] encryption algorithms 226 ("enc" values) JWA [RFC7518] supported by the introspection 227 endpoint to encrypt the response. 229 6. Security Considerations 231 6.1. Cross-JWT Confusion 233 JWT introspection responses and OpenID Connect ID Tokens are 234 syntactically similar. An attacker could therefore attempt to 235 impersonate an end-user at a OpenID Connect relying party by passing 236 the JWT as an ID token. 238 Such an attack can be prevented like any other token substitution 239 attack. The authorization server MUST include the claims "iss" and 240 "aud" in each JWT introspection response, with the "iss" value set to 241 the authorization server's issuer URL and the "aud" value set to the 242 resource server's identifier. This allows a correctly implemented 243 OpenID Connect relying party to detect substitution by checking the 244 "iss" and "aud" claims as described in Section 3.1.3.7. of 245 [OpenID.Core]. Relying parties SHOULD also use and check the "nonce" 246 parameter and claim to prevent token and code replay. 248 Resource servers utilizing JWTs to represent structured access tokens 249 could be susceptible to replay attacks. Resource servers should 250 therefore apply proper counter measures against replay as described 251 in [I-D.ietf-oauth-security-topics], section 2.2. 253 JWT Confusion and other attacks involving JWTs are discussed in 254 [I-D.ietf-oauth-jwt-bcp]. 256 6.2. Token Data Leakage 258 If the authorization server supports unauthenticated requests an 259 attacker could potentially retrieve token data which must be kept 260 confidential. This attack can be prevented by either authenticating 261 any request to the token introspection endpoint or by setting up the 262 respective recipient for encrypted responses. 264 In the latter case, confidentiality is ensured by the fact that only 265 the legitimate recipient is able to decrypt the response. An 266 attacker could try to circumvent this measure by requesting a plain 267 JSON response, using an Accept header with the content type set to 268 "application/json" instead of "application/jwt". To prevent this 269 attack the authorization server MUST not serve requests with content 270 type "application/json" if the resource server is set up to receive 271 encrypted responses (see also Section 3). 273 7. Acknowledgements 275 We would like to thank Petteri Stenius, Neil Madden, Filip Skokan, 276 and Tony Nadalin for their valuable feedback. 278 8. IANA Considerations 279 8.1. OAuth Dynamic Client Registration Metadata Registration 281 This specification requests registration of the following client 282 metadata definitions in the IANA "OAuth Dynamic Client Registration 283 Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 285 8.1.1. Registry Contents 287 o Client Metadata Name: "introspection_signed_response_alg" 289 o Client Metadata Description: String value indicating the client's 290 desired introspection response signing algorithm. 292 o Change Controller: IESG 294 o Specification Document(s): Section 4 of [[ this specification ]] 296 o Client Metadata Name: "introspection_encrypted_response_alg" 298 o Client Metadata Description: String value specifying the desired 299 introspection response encryption algorithm (alg value). 301 o Change Controller: IESG 303 o Specification Document(s): Section 4 of [[ this specification ]] 305 o Client Metadata Name: "introspection_encrypted_response_enc" 307 o Client Metadata Description: String value specifying the desired 308 introspection response encryption algorithm (enc value). 310 o Change Controller: IESG 312 o Specification Document(s): Section 4 of [[ this specification ]] 314 8.2. OAuth Authorization Server Metadata Registration 316 This specification requests registration of the following value in 317 the IANA "OAuth Authorization Server Metadata" registry 318 [IANA.OAuth.Parameters] established by [I-D.ietf-oauth-discovery]. 320 8.2.1. Registry Contents 322 o Metadata Name: "introspection_signing_alg_values_supported" 324 o Metadata Description: JSON array containing a list of algorithms 325 supported by the authorization server for introspection response 326 signing. 328 o Change Controller: IESG 330 o Specification Document(s): Section 5 of [[ this specification ]] 332 o Metadata Name: "introspection_encryption_alg_values_supported" 334 o Metadata Description: JSON array containing a list of algorithms 335 supported by the authorization server for introspection response 336 encryption (alg value). 338 o Change Controller: IESG 340 o Specification Document(s): Section 5 of [[ this specification ]] 342 o Metadata Name: "introspection_encryption_enc_values_supported" 344 o Metadata Description: JSON array containing a list of algorithms 345 supported by the authorization server for introspection response 346 encryption (enc value). 348 o Change Controller: IESG 350 o Specification Document(s): Section 5 of [[ this specification ]] 352 8.3. OAuth Token Introspection Response 354 TBD: add all OpenID Connect standard claims. 356 9. References 358 9.1. Normative References 360 [I-D.ietf-oauth-discovery] 361 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 362 Authorization Server Metadata", draft-ietf-oauth- 363 discovery-10 (work in progress), March 2018. 365 [I-D.ietf-oauth-jwt-bcp] 366 Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best 367 Current Practices", draft-ietf-oauth-jwt-bcp-03 (work in 368 progress), May 2018. 370 [I-D.ietf-oauth-security-topics] 371 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 372 "OAuth 2.0 Security Best Current Practice", draft-ietf- 373 oauth-security-topics-06 (work in progress), May 2018. 375 [OpenID.Core] 376 NRI, Ping Identity, Microsoft, Google, and Salesforce, 377 "OpenID Connect Core 1.0 incorporating errata set 1", Nov 378 2014, 379 . 381 [OpenID.Registration] 382 NRI, Ping Identity, and Microsoft, "OpenID Connect Dynamic 383 Client Registration 1.0 incorporating errata set 1", Nov 384 2014, . 387 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 388 Requirement Levels", BCP 14, RFC 2119, 389 DOI 10.17487/RFC2119, March 1997, 390 . 392 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 393 RFC 2246, DOI 10.17487/RFC2246, January 1999, 394 . 396 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 397 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 398 2015, . 400 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 401 RFC 7516, DOI 10.17487/RFC7516, May 2015, 402 . 404 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 405 DOI 10.17487/RFC7518, May 2015, 406 . 408 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 409 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 410 . 412 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 413 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 414 RFC 7591, DOI 10.17487/RFC7591, July 2015, 415 . 417 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 418 RFC 7662, DOI 10.17487/RFC7662, October 2015, 419 . 421 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 422 Authorization Server Metadata", RFC 8414, 423 DOI 10.17487/RFC8414, June 2018, 424 . 426 9.2. Informative References 428 [IANA.OAuth.Parameters] 429 IANA, "OAuth Parameters", 430 . 432 Appendix A. Document History 434 [[ To be removed from the final specification ]] 436 -00 438 o initial version of the WG draft 440 o defined default signing algorithm 442 o changed behavior in case resource server is set up for encryption 444 o Added text on token data leakage prevention to the security 445 considerations 447 o moved Security Considerations section forward 449 WG draft 451 -01 453 o fixed typos in client meta data field names 455 o added OAuth Server Metadata parameters to publish algorithms 456 supported for signing and encrypting the introspection response 458 o added registration of new parameters for OAuth Server Metadata and 459 Client Registration 461 o added explicit request for JWT introspection response 463 o made iss and aud claims mandatory in introspection response 465 o Stylistic and clarifying edits, updates references 467 -00 468 o initial version 470 Authors' Addresses 472 Torsten Lodderstedt (editor) 473 YES.com AG 475 Email: torsten@lodderstedt.net 477 Vladimir Dzhuvinov 478 Connect2id Ltd. 480 Email: vladimir@connect2id.com