idnits 2.17.1 draft-sakimura-oauth-jpop-01.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 2603 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 488, but no explicit reference was found in the text == Unused Reference: 'RFC7517' is defined on line 512, but no explicit reference was found in the text == Unused Reference: 'PKCE' is defined on line 531, but no explicit reference was found in the text == Unused Reference: 'POPA' is defined on line 534, but no explicit reference was found in the text == Unused Reference: 'TINTRO' is defined on line 539, 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-01 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 a corresponding 18 cryptographic key with the Jpop token can use it to get access to the 19 associated resources unlike in the case of the bearer token described 20 in [RFC6750] where any party in posession of the access token can 21 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 . . . . . . . . . . . . . . . . . . . 10 79 9.1. Certificate validation . . . . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . . . . . . . . . . . . 11 85 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 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 1.1. Notational Conventions 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 100 "OPTIONAL" in this document are to be interpreted as described in RFC 101 2119 [RFC2119]. 103 Unless otherwise noted, all the protocol parameter names and values 104 are case sensitive. 106 2. Terms and definitions 108 For the purpose of this document, the terms defined in [RFC6749] and 109 [RFC7800] are used. 111 3. JWT POP Token 113 JWT PoP token is a JWS signed JWT whose payload is a JWT Claims Set. 114 The JWT claims set MUST include the following: 116 iss The issuer identifier of the auhtorization server. 118 aud The identifier of the resource server. 120 iat The issuance time of this token. 122 exp The expiry time of this token. 124 cnf The confirmation method. 126 Their semantics are defined in [RFC7519] and [RFC7800]. 128 Following is an example of such. 130 { 131 "iss": "https://server.example.com", 132 "aud": "https://resource.example.org", 133 "iat": "1360189224", 134 "exp": "1361398868", 135 "cnf":{...} 136 } 138 Figure 1: Example of JWT PoP Token. 140 4. Sender Constrained Token 142 There are several varieties of sender constrained token. Namely: 144 1. CN Constrained Token 146 2. Client ID Constrained Token 148 4.1. CN Constrained Token 150 CN constrained token is typically used when X.509 client certificate 151 authentication is used at the token endpoint. In this case, the 152 constraint is expressed by including the following member at the top 153 level of cnf claim. 155 cn The Common Name of the client certificate that the client used in 156 the authorization request. 158 The authorization server finds the relevant CN from the X.509 client 159 certificate authentication that is performed at the token endpoint. 161 { 162 "iss": "https://server.example.com", 163 "sub": "joe@example.com", 164 "aud": "https://resource.example.org", 165 "exp": "1361398824", 166 "nbf": "1360189224", 167 "cnf":{ 168 "cn": "client.example.com" 169 } 171 Figure 2: Example of CN Constrained JWT. 173 4.2. Client ID Constrained Token 175 The constraint in the Client ID constrained token is expressed by 176 including the following member at the top level of cnf claim. 178 cid The client_id of the client that the client used in the 179 authorization request. The combination of the "iss" of the access 180 token and this value forms a globally unique identifier for the 181 client. 183 The authorization server finds the client ID from the client ID used 184 in the client authentication at the token endpoint. 186 5. Key Constrained Token 188 Methods to express key constraints are extensively described in the 189 section 3 of [RFC7800]. Such cnf claim is used in the access token 190 described in section 3 to form a key constrained token. [RFC7800] 191 defines 4 confirmation methods. 193 jwk JSON Web Key Representing a Public Key 195 jwe Encrypted JSON Web Key 197 jwkt#s256 [RFC7638] Thumbprint of a JWK using the SHA-256 hash 198 function. 200 x5t#s256 [RFC7515] X.509 Certificate SHA-256 Thumbprint 202 jku JWK Set URL 204 Following is an example of a JWT payload containing a JWK with a raw 205 key. 207 { 208 "iss": "https://server.example.com", 209 "sub": "joe@example.com", 210 "aud": "https://resource.example.org", 211 "exp": "1361398824", 212 "nbf": "1360189224", 213 "cnf":{ 214 "jwk":{ 215 "kty": "EC", 216 "use": "sig", 217 "crv": "P-256", 218 "x": "18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM", 219 "y": "-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA" 220 } 221 } 222 } 224 Figure 3: Example of a JWK Key Constrained JWT. 226 Following is an example of a JWT payload containing a jku URI. 228 { 229 "iss": "https://server.example.com", 230 "sub": "joe@example.com", 231 "aud": "https://resource.example.org", 232 "exp": "1361398824", 233 "nbf": "1360189224", 234 "cnf":{ 235 "jku": "https://client.example.com/keys/client123-jwks" 236 } 237 } 239 Figure 4: Example of a jku Constrained JWT. 241 Following is an example of a JWT payload containing a x5t#s256 242 Certificate Thumbprint of a x509 certificate. . 244 { 245 "iss": "https://server.example.com", 246 "sub": "joe@example.com", 247 "aud": "https://resource.example.org", 248 "exp": "1361398824", 249 "nbf": "1360189224", 250 "cnf":{ 251 "x5t#s256": "w5cK0ebwmCZUYDB2Y5SlESsXE8o9yZg05O89jdNidgI" 252 } 253 } 255 Figure 5: Example of a x5t#s256 Certificate Thumbprint Constrained 256 JWT. 258 6. Resource access method 260 The resource server that supports this specification MUST 261 authenticate the Client by having it demonstrate that it is the 262 holder of the key associated with the access token being used. The 263 confirmation method can be broadly categorized in two forms. 265 Mutual TLS method A method leveraging on the X.509 client 266 certificate authentication of the TLS connection. cn, x5t#s256, 267 and jku confirmation methods can be used with this access method. 268 (The JWKS referenced by the jku MUST contain JWK with x5c 269 certificate elements for this access method) 271 Signature method A method leveraging the signature on the nonce. 272 cid, jku, jwk, jwe, and, jwkt#S256 confirmation methods can be 273 used with this access method. 275 6.1. Mutual TLS acess method 277 CN cnf method Under this method, X.509 client certificate 278 authentication at the resource endpoint is being leveraged. The 279 resource endpoint MUST obtain the CN of the client certificate 280 used for the authentication and MUST verify that the value of the 281 cn member in the cnf member matches with it. 283 If it does not match, the process stops here and the resource 284 access MUST be denied. 286 If it is valid, then the resource server MUST verify the access 287 token. If it is valid, the resource SHOULD be returned as HTTP 288 response. 290 x5t#s256 cnf method Under this method, X.509 client certificate 291 authentication at the resource endpoint is being leveraged. The 292 resource endpoint MUST obtain the client certificate used for the 293 authentication and MUST verify that the base64url-encoded SHA-256 294 thumprint of the DER encoded X.509 client certificate. The 295 x5t#s256 member in the cnf member MUST exactly match the 296 calculated thumbprint. 298 If it does not match, the process stops here and the resource 299 access MUST be denied. 301 If it is valid, then the resource server MUST verify the access 302 token. If it is valid, the resource SHOULD be returned as HTTP 303 response. 305 jku cnf method Under this method, X.509 client certificate 306 authentication at the resource endpoint is being leveraged. The 307 resource endpoint MUST obtain the client certificate used for the 308 authentication and MUST verify that the certificate matches one of 309 the x5c elements retrieved from the [RFC7517]JWKS. Each x5c 310 element may contain a chain of base64-encoded certificates. The 311 client certificate MUST only be compared with the last certificate 312 in the chain. 314 If it does not match, the process stops here and the resource 315 access MUST be denied. 317 If it is valid, then the resource server MUST verify the access 318 token. If it is valid, the resource SHOULD be returned as HTTP 319 response. 321 6.2. Signature method 323 For this, the following steps are taken: 325 1. The client prepares a nonce. 327 2. The client creates JWS compact serialization over the nonce. 329 To obtain it, first create a JSON with a name "nonce" and the value 330 being what was received in the previous step. The JWS MUST contain a 331 kid header element if the client has more than one signing key 332 published via JWKS URI e.g., 334 { 335 "nonce":"dcd98b7102dd2f0e8b11d0f600bfb0c093" 336 } 337 Then, "jws-on-nonce" is obtained by creating a compact serialization 338 of JWS on this JSON. 340 3. The client sends the request to the resource server, this time 341 with Authorization Request Header as defined in section 4.2 of 342 [RFC7235] with the credential as follows: 344 credentials = "Jpop" jpop-response 345 jpop-response = at-response "," s-response 346 at-response = "at" "=" access-token; As specified by [POPKD] 347 s-response = "s" "=" jws-on-nonce; Created in the step 3. 348 access-token = quoted-string 349 jws-on-nonce = quoted-string 351 In the following example, the access token and the jws-on-nonce are 352 represented as access.token.jwt and jws.of.nonce for the sake of 353 brevity. 355 GET /resource/1234 HTTP/1.0 356 Host: server.example.com 357 Authorization: Jpop at="access.token.jwt", s="jws.of.nonce" 359 Figure 6: Example resouce request 361 4. The resource server finds the client's public key form the access 362 token through the methods described in [RFC7800]. 364 5. The resource server MUST verify the value of "s" of the 365 Authorization header. If it fails, the process stops here and the 366 resource access MUST be denied. 368 6. The resource server MUST verify the access token. If it is 369 valid, the resource SHOULD be returned as HTTP response. 371 7. Authorization Error 373 If the client requests the resource without the proper authoization 374 header, the resource server returns a HTTP 401 response with "WWW- 375 Authenticate" header as defined in section 4.1 of [RFC7235] with the 376 challenge as follows: 378 challenge = "Jpop" jpop-challenge 379 jpop-challenge = "nonce" "=" nonce-value 380 nonce-value = quoted-string 382 Following example depicts what the response would look like. 384 HTTP/1.0 401 Unauthorized 385 Server: HTTPd/0.9 386 Date: Wed, 14 March 2017 09:26:53 GMT 387 WWW-Authenticate: Jpop nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093" 389 Figure 7: Example error response. 391 8. IANA Considerations 393 8.1. Jpop Authentication Scheme 395 A new scheme has been registered in the HTTP Authentication Scheme 396 Registry as follows: 398 Authentication Scheme Name: Jpop 400 Reference: Section 3 of this specification 402 Notes (optional): The Named Authentication scheme is intended to be 403 used only with OAuth Resource Access, and thus does not support proxy 404 authentication. 406 8.2. JWT Confirmation Methods 408 o Confirmation Method Value: "cn" 410 o Confirmation Method Description: CN match with the TLS client 411 auth. 413 o Change Controller: IESG 415 o Specification Document(s): This document. 417 o Confirmation Method Value: "cid" 419 o Confirmation Method Description: Client ID Confirmation 421 o Change Controller: IESG 423 o Specification Document(s): This document. 425 9. Security Considerations 427 9.1. Certificate validation 429 The "cn" JWT confirmation method relies its security property on the 430 X.509 client certificate authentication. In particular, the validity 431 of the certificate needs to be verified properly. It involves the 432 traversal of all the certificate chain and the certificate validation 433 (e.g., with OCSP). 435 9.2. Key protection 437 The client's secret key must be kept securely. Otherwise, the notion 438 of PoP breaks down. 440 It should be noted that JWE confirmation method is significantly 441 weaker form of the PoP, as the resource server and the authorization 442 server can masquerade as the client. 444 9.3. Audiance Restriction 446 When using the signature method the client must specify to the AS the 447 aud it intends to send the token to, so that it can be included in 448 the AT. 450 A malicious RS could receive a AT with no aud or a logical audience 451 and then replay the AT and jws-on-nonce to the actual server. 453 NOTE another approach would be to include the resource in the jws-on- 454 nonce 456 9.4. Dynamic client registration elements 458 When a AS uses dynamic client registration it may accept software 459 statements supplied by a federation operator. Those software 460 statements can contain a JWKS-URI that is hosted by the federation 461 operator or protected by a certificate provisioned from a trusted 462 root. These methods would allow the federation operator to 463 administratively revoke the keys at the JWKS-URI without requiring 464 the JWKS to contain x5c elements with CA issued certificates and 465 having to have the RS perform full certificate validation for each 466 request. 468 10. Acknowledgements 470 The authors thank the following people for providing valuable 471 feedback to this document. Nov Matake (YAuth). 473 11. References 475 11.1. Normative References 477 [POPKD] Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 478 "OAuth 2.0 Proof-of-Possession: Authorization Server to 479 Client Key Distribution", March 2017, 480 . 483 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 484 Requirement Levels", BCP 14, RFC 2119, 485 DOI 10.17487/RFC2119, March 1997, 486 . 488 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 489 Leach, P., Luotonen, A., and L. Stewart, "HTTP 490 Authentication: Basic and Digest Access Authentication", 491 RFC 2617, DOI 10.17487/RFC2617, June 1999, 492 . 494 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 495 RFC 6749, DOI 10.17487/RFC6749, October 2012, 496 . 498 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 499 Framework: Bearer Token Usage", RFC 6750, 500 DOI 10.17487/RFC6750, October 2012, 501 . 503 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 504 Protocol (HTTP/1.1): Authentication", RFC 7235, 505 DOI 10.17487/RFC7235, June 2014, 506 . 508 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 509 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 510 2015, . 512 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 513 DOI 10.17487/RFC7517, May 2015, 514 . 516 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 517 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 518 . 520 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 521 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 522 2015, . 524 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 525 Possession Key Semantics for JSON Web Tokens (JWTs)", 526 RFC 7800, DOI 10.17487/RFC7800, April 2016, 527 . 529 11.2. Informative References 531 [PKCE] Sakimura, N., "Proof Key for Code Exchange by OAuth Public 532 Clients", July 2015. 534 [POPA] Hunt, P., Ed., "OAuth 2.0 Proof-of-Possession (PoP) 535 Security Architecture", March 2015, 536 . 539 [TINTRO] Richer, J., "OAuth 2.0 Token Introspection", July 2015. 541 Appendix A. Document History 543 -00 Initial Version. 545 Authors' Addresses 547 Nat Sakimura 548 Nomura Research Institute 549 Otemachi Financial City Grand Cube, 1-9-2 Otemachi 550 Chiyoda-ku, Tokyo 100-0004 551 Japan 553 Phone: +81-3-5533-2111 554 Email: n-sakimura@nri.co.jp 555 URI: https://nat.sakimura.org/ 557 Kepeng Li 558 Alibaba Group 560 Email: kepeng.lkp@alibaba-inc.com 562 John Bradley 563 Ping Identity 565 Email: ve7jtb@ve7jtb.com 566 URI: http://www.thread-safe.com/