idnits 2.17.1 draft-sakimura-oauth-jpop-02.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 2 characters in excess of 72. ** The abstract seems to contain references ([POPKD], [RFC6750]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 11, 2017) is 2601 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: 'RFC2617' is defined on line 503, but no explicit reference was found in the text == Unused Reference: 'RFC7517' is defined on line 527, but no explicit reference was found in the text == Unused Reference: 'PKCE' is defined on line 550, but no explicit reference was found in the text == Unused Reference: 'POPA' is defined on line 553, but no explicit reference was found in the text == Unused Reference: 'TINTRO' is defined on line 558, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'POPKD' ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group N. Sakimura 3 Internet-Draft Nomura Research Institute 4 Intended status: Standards Track K. Li 5 Expires: September 12, 2017 Alibaba Group 6 J. Bradley 7 Ping Identity 8 March 11, 2017 10 The OAuth 2.0 Authorization Framework: JWT Pop Token Usage 11 draft-sakimura-oauth-jpop-02 13 Abstract 15 This specification describes how to use JWT POP (Jpop) tokens that 16 were obtained through [POPKD] in HTTP requests to access OAuth 2.0 17 protected resources. Only the party in possession of the 18 corresponding cryptographic key for the Jpop token can use it to get 19 access to the associated resources unlike in the case of the bearer 20 token described in [RFC6750] where any party in posession of the 21 access token can access the resource. 23 Requirements Language 25 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 26 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 27 document are to be interpreted as described in RFC 2119 [RFC2119]. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on September 12, 2017. 46 Copyright Notice 48 Copyright (c) 2017 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 65 2. Terms and definitions . . . . . . . . . . . . . . . . . . . . 3 66 3. JWT POP Token . . . . . . . . . . . . . . . . . . . . . . . . 3 67 4. Sender Constrained Token . . . . . . . . . . . . . . . . . . 4 68 4.1. CN Constrained Token . . . . . . . . . . . . . . . . . . 4 69 4.2. Client ID Constrained Token . . . . . . . . . . . . . . . 5 70 5. Key Constrained Token . . . . . . . . . . . . . . . . . . . . 5 71 6. Resource access method . . . . . . . . . . . . . . . . . . . 7 72 6.1. Mutual TLS acess method . . . . . . . . . . . . . . . . . 7 73 6.2. Signature method . . . . . . . . . . . . . . . . . . . . 8 74 7. Authorization Error . . . . . . . . . . . . . . . . . . . . . 9 75 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 76 8.1. Jpop Authentication Scheme . . . . . . . . . . . . . . . 10 77 8.2. JWT Confirmation Methods . . . . . . . . . . . . . . . . 10 78 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 79 9.1. Certificate validation . . . . . . . . . . . . . . . . . 11 80 9.2. Key protection . . . . . . . . . . . . . . . . . . . . . 11 81 9.3. Audiance Restriction . . . . . . . . . . . . . . . . . . 11 82 9.4. Dynamic client registration elements . . . . . . . . . . 11 83 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 84 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 85 11.1. Normative References . . . . . . . . . . . . . . . . . . 12 86 11.2. Informative References . . . . . . . . . . . . . . . . . 13 87 Appendix A. Document History . . . . . . . . . . . . . . . . . . 13 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 90 1. Introduction 92 This document specifies the method for the client to use a proof-of- 93 possestion token against a protected resource. The format of such 94 token is defined in section 3 of [RFC7800]. 96 The same methods and JWT schema elements can be used with opaque 97 tokens and OAuth 2.0 Token Introspection. [RFC7662] 99 [POPKD] can be used for a client to dynamically specify a key, or the 100 Authorization Server can use information provided by the client at 101 registration to provide the confirmation element. 103 1.1. Notational Conventions 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in RFC 108 2119 [RFC2119]. 110 Unless otherwise noted, all the protocol parameter names and values 111 are case sensitive. 113 2. Terms and definitions 115 For the purpose of this document, the terms defined in [RFC6749] and 116 [RFC7800] are used. 118 3. JWT POP Token 120 JWT PoP token is a JWS signed JWT whose payload is a JWT Claims Set. 121 The JWT claims set MUST include the following: 123 iss The issuer identifier of the auhtorization server. 125 aud The identifier of the resource server. 127 iat The issuance time of this token. 129 exp The expiry time of this token. 131 cnf The confirmation method. 133 Their semantics are defined in [RFC7519] and [RFC7800]. 135 Following is an example of such. 137 { 138 "iss": "https://server.example.com", 139 "aud": "https://resource.example.org", 140 "iat": "1360189224", 141 "exp": "1361398868", 142 "cnf":{...} 143 } 145 Figure 1: Example of JWT PoP Token. 147 4. Sender Constrained Token 149 There are several varieties of sender constrained token. Namely: 151 1. CN Constrained Token 153 2. Client ID Constrained Token 155 4.1. CN Constrained Token 157 CN constrained token is typically used when X.509 client certificate 158 authentication is used at the token endpoint. In this case, the 159 constraint is expressed by including the following member at the top 160 level of cnf claim. 162 cn The Common Name of the client certificate that the client used in 163 the authorization request. 165 The authorization server finds the relevant CN from the X.509 client 166 certificate authentication that is performed at the token endpoint. 168 { 169 "iss": "https://server.example.com", 170 "sub": "joe@example.com", 171 "aud": "https://resource.example.org", 172 "exp": "1361398824", 173 "nbf": "1360189224", 174 "cnf":{ 175 "cn": "client.example.com" 176 } 178 Figure 2: Example of CN Constrained JWT. 180 4.2. Client ID Constrained Token 182 The constraint in the Client ID constrained token is expressed by 183 including the following member at the top level of cnf claim. 185 cid The client_id of the client that the client used in the 186 authorization request. The combination of the "iss" of the access 187 token and this value forms a globally unique identifier for the 188 client. 190 The authorization server finds the client ID from the client ID used 191 in the client authentication at the token endpoint. 193 5. Key Constrained Token 195 Methods to express key constraints are extensively described in the 196 section 3 of [RFC7800]. Such cnf claim is used in the access token 197 described in section 3 to form a key constrained token. [RFC7800] 198 defines 4 confirmation methods. 200 jwk JSON Web Key Representing a Public Key 202 jwe Encrypted JSON Web Key 204 jwkt#s256 [RFC7638] Thumbprint of a JWK using the SHA-256 hash 205 function. 207 x5t#s256 [RFC7515] X.509 Certificate SHA-256 Thumbprint 209 jku JWK Set URL 211 Following is an example of a JWT payload containing a JWK with a raw 212 key. 214 { 215 "iss": "https://server.example.com", 216 "sub": "joe@example.com", 217 "aud": "https://resource.example.org", 218 "exp": "1361398824", 219 "nbf": "1360189224", 220 "cnf":{ 221 "jwk":{ 222 "kty": "EC", 223 "use": "sig", 224 "crv": "P-256", 225 "x": "18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM", 226 "y": "-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA" 227 } 228 } 229 } 231 Figure 3: Example of a JWK Key Constrained JWT. 233 Following is an example of a JWT payload containing a jku URI. 235 { 236 "iss": "https://server.example.com", 237 "sub": "joe@example.com", 238 "aud": "https://resource.example.org", 239 "exp": "1361398824", 240 "nbf": "1360189224", 241 "cnf":{ 242 "jku": "https://client.example.com/keys/client123-jwks" 243 } 244 } 246 Figure 4: Example of a jku Constrained JWT. 248 Following is an example of a JWT payload containing a x5t#s256 249 Certificate Thumbprint of a x509 certificate. . 251 { 252 "iss": "https://server.example.com", 253 "sub": "joe@example.com", 254 "aud": "https://resource.example.org", 255 "exp": "1361398824", 256 "nbf": "1360189224", 257 "cnf":{ 258 "x5t#s256": "w5cK0ebwmCZUYDB2Y5SlESsXE8o9yZg05O89jdNidgI" 259 } 260 } 262 Figure 5: Example of a x5t#s256 Certificate Thumbprint Constrained 263 JWT. 265 6. Resource access method 267 The resource server that supports this specification MUST 268 authenticate the Client by having it demonstrate that it is the 269 holder of the key associated with the access token being used. The 270 confirmation method can be broadly categorized in two forms. 272 Mutual TLS method A method leveraging on the X.509 client 273 certificate authentication of the TLS connection. cn, x5t#s256, 274 and jku confirmation methods can be used with this access method. 275 (The JWKS referenced by the jku MUST contain JWK with x5c 276 certificate elements for this access method) 278 Signature method A method leveraging the signature on the nonce. 279 cid, jku, jwk, jwe, and, jwkt#S256 confirmation methods can be 280 used with this access method. 282 6.1. Mutual TLS acess method 284 CN cnf method Under this method, X.509 client certificate 285 authentication at the resource endpoint is being leveraged. The 286 resource endpoint MUST obtain the CN of the client certificate 287 used for the authentication and MUST verify that the value of the 288 cn member in the cnf member matches with it. 290 If it does not match, the process stops here and the resource 291 access MUST be denied. 293 If it is valid, then the resource server MUST verify the access 294 token. If it is valid, the resource SHOULD be returned as HTTP 295 response. 297 x5t#s256 cnf method Under this method, X.509 client certificate 298 authentication at the resource endpoint is being leveraged. The 299 resource endpoint MUST obtain the client certificate used for the 300 authentication and MUST verify that the base64url-encoded SHA-256 301 thumprint of the DER encoded X.509 client certificate. The 302 x5t#s256 member in the cnf member MUST exactly match the 303 calculated thumbprint. 305 If the thumbprint does not match, access token validation fails 306 and the resource MUST NOT be returned. 308 If the thumbprint is valid, then the resource server MUST verify 309 the access token. If the access token is valid, the resource 310 SHOULD be returned as a HTTP response. 312 jku cnf method Under this method, X.509 client certificate 313 authentication at the resource endpoint is being leveraged. The 314 resource endpoint MUST obtain the client certificate used for the 315 authentication and MUST verify that the certificate matches one of 316 the x5c elements retrieved from the [RFC7517]JWKS. Each x5c 317 element may contain a chain of base64-encoded certificates. The 318 client certificate MUST only be compared with the last certificate 319 in the chain. 321 If the certificate does not match one in the JWKS object, access 322 token validation fails and the resource MUST NOT be returned. 324 NOTE need a reference to comparing certificates. This should 325 probably be by string comparison of the Base64 or DER encoded 326 formats. 328 If the certificate matches, then the resource server MUST verify 329 the access token. If it is valid, the resource SHOULD be returned 330 as HTTP response. 332 6.2. Signature method 334 For this, the following steps are taken: 336 1. The client prepares a nonce. 338 NOTE The client should be getting the nonce from tha authorization 339 error in sec 7 341 2. The client creates JWS compact serialization over the nonce. 343 To obtain it, first create a JSON with a name "nonce" and the value 344 being what was received in the previous step. The JWS MUST contain a 345 kid header element if the client has more than one signing key 346 published via JWKS URI e.g., 348 { 349 "nonce":"dcd98b7102dd2f0e8b11d0f600bfb0c093" 350 } 352 Then, "jws-on-nonce" is obtained by creating a compact serialization 353 of JWS on this JSON. 355 3. The client sends the request to the resource server, this time 356 with Authorization Request Header as defined in section 4.2 of 357 [RFC7235] with the credential as follows: 359 credentials = "Jpop" jpop-response 360 jpop-response = at-response "," s-response 361 at-response = "at" "=" access-token; As specified by [POPKD] 362 s-response = "s" "=" jws-on-nonce; Created in the step 3. 363 access-token = quoted-string 364 jws-on-nonce = quoted-string 366 In the following example, the access token and the jws-on-nonce are 367 represented as access.token.jwt and jws.of.nonce for the sake of 368 brevity. 370 GET /resource/1234 HTTP/1.0 371 Host: server.example.com 372 Authorization: Jpop at="access.token.jwt", s="jws.of.nonce" 374 Figure 6: Example resouce request 376 4. The resource server finds the client's public key form the access 377 token through the methods described in [RFC7800]. 379 5. The resource server MUST verify the value of "s" of the 380 Authorization header. If it fails, the process stops here and the 381 resource access MUST be denied. 383 6. The resource server MUST verify the access token. If it is 384 valid, the resource SHOULD NOT be returned as HTTP response. 386 7. Authorization Error 388 If the client requests the resource without the proper authoization 389 header, the resource server returns a HTTP 401 response with "WWW- 390 Authenticate" header as defined in section 4.1 of [RFC7235] with the 391 challenge as follows: 393 challenge = "Jpop" jpop-challenge 394 jpop-challenge = "nonce" "=" nonce-value 395 nonce-value = quoted-string 397 Following example depicts what the response would look like. 399 HTTP/1.0 401 Unauthorized 400 Server: HTTPd/0.9 401 Date: Wed, 14 March 2017 09:26:53 GMT 402 WWW-Authenticate: Jpop nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093" 404 Figure 7: Example error response. 406 8. IANA Considerations 408 8.1. Jpop Authentication Scheme 410 A new scheme has been registered in the HTTP Authentication Scheme 411 Registry as follows: 413 Authentication Scheme Name: Jpop 415 Reference: Section 3 of this specification 417 Notes (optional): The Named Authentication scheme is intended to be 418 used only with OAuth Resource Access, and thus does not support proxy 419 authentication. 421 8.2. JWT Confirmation Methods 423 o Confirmation Method Value: "cn" 425 o Confirmation Method Description: CN match with the TLS client 426 auth. 428 o Change Controller: IESG 430 o Specification Document(s): This document. 432 o Confirmation Method Value: "cid" 434 o Confirmation Method Description: Client ID Confirmation 436 o Change Controller: IESG 438 o Specification Document(s): This document. 440 9. Security Considerations 442 9.1. Certificate validation 444 The "cn" JWT confirmation method relies its security property on the 445 X.509 client certificate authentication. In particular, the validity 446 of the certificate needs to be verified properly. It involves the 447 traversal of all the certificate chain and the certificate validation 448 (e.g., with OCSP). 450 9.2. Key protection 452 The client's secret key must be kept securely. Otherwise, the notion 453 of PoP breaks down. 455 It should be noted that JWE confirmation method is significantly 456 weaker form of the PoP, as the resource server and the authorization 457 server can masquerade as the client. 459 9.3. Audiance Restriction 461 When using the signature method the client must specify to the AS the 462 aud it intends to send the token to, so that it can be included in 463 the AT. 465 A malicious RS could receive a AT with no aud or a logical audience 466 and then replay the AT and jws-on-nonce to the actual server. 468 NOTE another approach would be to include the resource in the jws-on- 469 nonce 471 9.4. Dynamic client registration elements 473 When a AS uses dynamic client registration it may accept software 474 statements supplied by a federation operator. Those software 475 statements can contain a JWKS-URI that is hosted by the federation 476 operator or protected by a certificate provisioned from a trusted 477 root. These methods would allow the federation operator to 478 administratively revoke the keys at the JWKS-URI without requiring 479 the JWKS to contain x5c elements with CA issued certificates and 480 having to have the RS perform full certificate validation for each 481 request. 483 10. Acknowledgements 485 The authors thank the following people for providing valuable 486 feedback to this document. Nov Matake (YAuth). 488 11. References 490 11.1. Normative References 492 [POPKD] Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 493 "OAuth 2.0 Proof-of-Possession: Authorization Server to 494 Client Key Distribution", March 2017, 495 . 498 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 499 Requirement Levels", BCP 14, RFC 2119, 500 DOI 10.17487/RFC2119, March 1997, 501 . 503 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 504 Leach, P., Luotonen, A., and L. Stewart, "HTTP 505 Authentication: Basic and Digest Access Authentication", 506 RFC 2617, DOI 10.17487/RFC2617, June 1999, 507 . 509 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 510 RFC 6749, DOI 10.17487/RFC6749, October 2012, 511 . 513 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 514 Framework: Bearer Token Usage", RFC 6750, 515 DOI 10.17487/RFC6750, October 2012, 516 . 518 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 519 Protocol (HTTP/1.1): Authentication", RFC 7235, 520 DOI 10.17487/RFC7235, June 2014, 521 . 523 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 524 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 525 2015, . 527 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 528 DOI 10.17487/RFC7517, May 2015, 529 . 531 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 532 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 533 . 535 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 536 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 537 2015, . 539 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 540 RFC 7662, DOI 10.17487/RFC7662, October 2015, 541 . 543 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 544 Possession Key Semantics for JSON Web Tokens (JWTs)", 545 RFC 7800, DOI 10.17487/RFC7800, April 2016, 546 . 548 11.2. Informative References 550 [PKCE] Sakimura, N., "Proof Key for Code Exchange by OAuth Public 551 Clients", July 2015. 553 [POPA] Hunt, P., Ed., "OAuth 2.0 Proof-of-Possession (PoP) 554 Security Architecture", March 2015, 555 . 558 [TINTRO] Richer, J., "OAuth 2.0 Token Introspection", July 2015. 560 Appendix A. Document History 562 -02 Chicago Version. 564 -00 Initial Version. 566 Authors' Addresses 568 Nat Sakimura 569 Nomura Research Institute 570 Otemachi Financial City Grand Cube, 1-9-2 Otemachi 571 Chiyoda-ku, Tokyo 100-0004 572 Japan 574 Phone: +81-3-5533-2111 575 Email: n-sakimura@nri.co.jp 576 URI: https://nat.sakimura.org/ 578 Kepeng Li 579 Alibaba Group 581 Email: kepeng.lkp@alibaba-inc.com 582 John Bradley 583 Ping Identity 585 Email: ve7jtb@ve7jtb.com 586 URI: http://www.thread-safe.com/