idnits 2.17.1 draft-sakimura-oauth-jpop-04.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 are 2 instances of too long lines in the document, the longest one being 7 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 27, 2017) is 2587 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: 'RFC7517' is defined on line 536, but no explicit reference was found in the text == Unused Reference: 'POPA' is defined on line 559, but no explicit reference was found in the text == Unused Reference: 'RFC7636' is defined on line 564, but no explicit reference was found in the text == Unused Reference: 'TINTRO' is defined on line 569, 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 (~~), 6 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 28, 2017 Alibaba Group 6 J. Bradley 7 Ping Identity 8 March 27, 2017 10 The OAuth 2.0 Authorization Framework: JWT Pop Token Usage 11 draft-sakimura-oauth-jpop-04 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 28, 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. DN 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 . . . . . . . . . . . . . . . . . . . . . . 12 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. DN Constrained Token 153 2. Client ID Constrained Token 155 4.1. DN Constrained Token 157 DN 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 dn The Distinguished Name of the client certificate as a string that 163 the client used in the authorization request. 165 The authorization server finds the relevant DN 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 "dn": "cn=John Doe LLC,dc=client,dc=example,dc=com" 176 } 177 } 179 Figure 2: Example of DN Constrained JWT. 181 4.2. Client ID Constrained Token 183 The constraint in the Client ID constrained token is expressed by 184 including the following member at the top level of cnf claim. 186 cid The client_id of the client that the client used in the 187 authorization request. The combination of the "iss" of the access 188 token and this value forms a globally unique identifier for the 189 client. 191 The authorization server finds the client ID from the client ID used 192 in the client authentication at the token endpoint. 194 5. Key Constrained Token 196 Methods to express key constraints are extensively described in the 197 section 3 of [RFC7800]. Such cnf claim is used in the access token 198 described in section 3 to form a key constrained token. [RFC7800] 199 defines 4 confirmation methods. 201 jwk JSON Web Key Representing a Public Key 203 jwe Encrypted JSON Web Key 205 jwkt#s256 [RFC7638] Thumbprint of a JWK using the SHA-256 hash 206 function. 208 x5t#s256 [RFC7515] X.509 Certificate SHA-256 Thumbprint 210 jku JWK Set URL 212 The client provides the corresponding keys or the pointers to the 213 authorization server as a part of the client configuration. It can 214 be done through out-of-band methods (e.g., developper portal) or 215 through some form of dynamic registration, etc. 217 Following is an example of a JWT payload containing a JWK with a raw 218 key. 220 { 221 "iss": "https://server.example.com", 222 "sub": "joe@example.com", 223 "aud": "https://resource.example.org", 224 "exp": "1361398824", 225 "nbf": "1360189224", 226 "cnf":{ 227 "jwk":{ 228 "kty": "EC", 229 "use": "sig", 230 "crv": "P-256", 231 "x": "18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM", 232 "y": "-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA" 233 } 234 } 235 } 237 Figure 3: Example of a JWK Key Constrained JWT. 239 Following is an example of a JWT payload containing a jku URI. 241 { 242 "iss": "https://server.example.com", 243 "sub": "joe@example.com", 244 "aud": "https://resource.example.org", 245 "exp": "1361398824", 246 "nbf": "1360189224", 247 "cnf":{ 248 "jku": "https://client.example.com/keys/client123-jwks" 249 } 250 } 252 Figure 4: Example of a jku Constrained JWT. 254 Following is an example of a JWT payload containing a x5t#s256 255 Certificate Thumbprint of a x509 certificate. . 257 { 258 "iss": "https://server.example.com", 259 "sub": "joe@example.com", 260 "aud": "https://resource.example.org", 261 "exp": "1361398824", 262 "nbf": "1360189224", 263 "cnf":{ 264 "x5t#s256": "w5cK0ebwmCZUYDB2Y5SlESsXE8o9yZg05O89jdNidgI" 265 } 266 } 268 Figure 5: Example of a x5t#s256 Certificate Thumbprint Constrained 269 JWT. 271 6. Resource access method 273 The resource server that supports this specification MUST 274 authenticate the Client by having it demonstrate that it is the 275 holder of the key associated with the access token being used. The 276 confirmation method can be broadly categorized in two forms. 278 Mutual TLS method A method leveraging on the X.509 client 279 certificate authentication of the TLS connection. cn, x5t#s256, 280 and jku confirmation methods can be used with this access method. 281 (The JWKS referenced by the jku MUST contain JWK with x5c 282 certificate elements for this access method) 284 Signature method A method leveraging the signature on the nonce. 285 cid, jku, jwk, jwe, and, jwkt#S256 confirmation methods can be 286 used with this access method. 288 6.1. Mutual TLS acess method 290 DN 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 DN of the client certificate 293 used for the authentication and MUST verify that the value of the 294 dn member in the cnf member matches with it. 296 If it does not match, the process stops here and the resource 297 access MUST be denied. 299 If it is valid, then the resource server MUST verify the access 300 token. If it is valid, the resource SHOULD be returned as HTTP 301 response. 303 x5t#s256 cnf method Under this method, X.509 client certificate 304 authentication at the resource endpoint is being leveraged. The 305 resource endpoint MUST obtain the client certificate used for the 306 authentication and MUST verify that the base64url-encoded SHA-256 307 thumprint of the DER encoded X.509 client certificate. The 308 x5t#s256 member in the cnf member MUST exactly match the 309 calculated thumbprint. 311 If the thumbprint does not match, access token validation fails 312 and the resource access MUST be denied. 314 If the thumbprint is valid, then the resource server MUST verify 315 the access token. If the access token is valid, the resource 316 SHOULD be returned as HTTP response. 318 jku cnf method Under this method, X.509 client certificate 319 authentication at the resource endpoint is being leveraged. The 320 resource endpoint MUST obtain the client certificate used for the 321 authentication and MUST verify that the certificate matches one of 322 the x5c elements retrieved from the [RFC7517]JWKS. Each x5c 323 element may contain a chain of base64-encoded certificates. The 324 client certificate MUST only be compared with the last certificate 325 in the chain. 327 If the certificate does not match one in the JWKS object, access 328 token validation fails and the resource MUST NOT be returned. 330 Editor's Note: We need a reference to comparing certificates. 331 This should probably be by string comparison of the Base64 or DER 332 encoded formats. 334 If the certificate matches, then the resource server MUST verify 335 the access token. If it is valid, the resource SHOULD be returned 336 as HTTP response. 338 6.2. Signature method 340 For this, the following steps are taken: 342 STEP1: The client accesses the protected resource and gets an 343 authorization error as in Section 7. With it, the client 344 obtains a nonce. 346 STEP2: The client prepares a client nonce, "cnonce", and nounce 347 count, "nc" as defined in section 3.2.2 of [RFC2617]. 349 STEP3: The client creates JWS compact serialization over the nonce. 351 To obtain it, first create a JSON with a name "nonce" and the value 352 being what was received in the previous step. The JWS MUST contain a 353 kid header element if the client has more than one signing key 354 published via JWKS URI e.g., 356 { 357 "nonce":"dcd98b7102dd2f0e8b11d0f600bfb0c093", 358 "nc":"00000001", 359 "cnonce":"0a4f113b" 360 } 362 Then, "jws-on-nonce" is obtained by creating a compact serialization 363 of JWS on this JSON. 365 STEP4: The client sends the request to the resource server, this 366 time with Authorization Request Header as defined in section 367 4.2 of [RFC7235] with the credential as follows: 369 credentials = "Jpop" jpop-response 370 jpop-response = at-response "," s-response 371 at-response = "at" "=" access-token (* As specified by [POPKD] *) 372 s-response = "s" "=" jws-on-nonce (* Created in the STEP3. *) 373 access-token = quoted-string 374 jws-on-nonce = quoted-string 376 In the following example, the access token and the jws-on-nonce are 377 represented as access.token.jwt and jws.of.nonce for the sake of 378 brevity. 380 GET /resource/1234 HTTP/1.0 381 Host: server.example.com 382 Authorization: Jpop at="access.token.jwt", s="jws.of.nonce" 384 Figure 6: Example resouce request 386 STEP5: The resource server finds the client's public key form the 387 access token through the methods described in [RFC7800]. 389 STEP6: The resource server MUST verify the value of "s" of the 390 Authorization header. If it fails, the process stops here 391 and the resource access MUST be denied. 393 STEP7: The resource server MUST verify the access token. If it is 394 valid, the resource SHOULD be returned as HTTP response. 396 7. Authorization Error 398 If the client requests the resource without the proper authoization 399 header, the resource server returns a HTTP 401 response with "WWW- 400 Authenticate" header as defined in section 4.1 of [RFC7235] with the 401 challenge as follows: 403 challenge = "Jpop" jpop-challenge 404 jpop-challenge = "nonce" "=" nonce-value 405 nonce-value = quoted-string 407 Following example depicts what the response would look like. 409 HTTP/1.0 401 Unauthorized 410 Server: HTTPd/0.9 411 Date: Wed, 14 March 2017 09:26:53 GMT 412 WWW-Authenticate: Jpop nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093" 414 Figure 7: Example error response. 416 8. IANA Considerations 418 8.1. Jpop Authentication Scheme 420 A new scheme has been registered in the HTTP Authentication Scheme 421 Registry as follows: 423 Authentication Scheme Name: Jpop 425 Reference: Section 3 of this specification 427 Notes (optional): The Named Authentication scheme is intended to be 428 used only with OAuth Resource Access, and thus does not support proxy 429 authentication. 431 8.2. JWT Confirmation Methods 433 o Confirmation Method Value: "dn" 435 o Confirmation Method Description: DN match with the TLS client 436 auth. 438 o Change Controller: IESG 440 o Specification Document(s): This document. 442 o Confirmation Method Value: "cid" 444 o Confirmation Method Description: Client ID Confirmation 446 o Change Controller: IESG 447 o Specification Document(s): This document. 449 9. Security Considerations 451 9.1. Certificate validation 453 The "dn" JWT confirmation method relies its security property on the 454 X.509 client certificate authentication. In particular, the validity 455 of the certificate needs to be verified properly. It involves the 456 traversal of all the certificate chain and the certificate validation 457 (e.g., with OCSP). 459 9.2. Key protection 461 The client's secret key must be kept securely. Otherwise, the notion 462 of PoP breaks down. 464 It should be noted that JWE confirmation method is significantly 465 weaker form of the PoP, as the resource server and the authorization 466 server can masquerade as the client. 468 9.3. Audiance Restriction 470 When using the signature method the client must specify to the AS the 471 aud it intends to send the token to, so that it can be included in 472 the AT. 474 A malicious RS could receive a AT with no aud or a logical audience 475 and then replay the AT and jws-on-nonce to the actual server. 477 NOTE another approach would be to include the resource in the jws-on- 478 nonce 480 9.4. Dynamic client registration elements 482 When a AS uses dynamic client registration it may accept software 483 statements supplied by a federation operator. Those software 484 statements can contain a JWKS-URI that is hosted by the federation 485 operator or protected by a certificate provisioned from a trusted 486 root. These methods would allow the federation operator to 487 administratively revoke the keys at the JWKS-URI without requiring 488 the JWKS to contain x5c elements with CA issued certificates and 489 having to have the RS perform full certificate validation for each 490 request. 492 10. Acknowledgements 494 The authors thank the following people for providing valuable 495 feedback to this document. Nov Matake (YAuth). 497 11. References 499 11.1. Normative References 501 [POPKD] Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 502 "OAuth 2.0 Proof-of-Possession: Authorization Server to 503 Client Key Distribution", March 2017, 504 . 507 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 508 Requirement Levels", BCP 14, RFC 2119, 509 DOI 10.17487/RFC2119, March 1997, 510 . 512 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 513 Leach, P., Luotonen, A., and L. Stewart, "HTTP 514 Authentication: Basic and Digest Access Authentication", 515 RFC 2617, DOI 10.17487/RFC2617, June 1999, 516 . 518 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 519 RFC 6749, DOI 10.17487/RFC6749, October 2012, 520 . 522 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 523 Framework: Bearer Token Usage", RFC 6750, 524 DOI 10.17487/RFC6750, October 2012, 525 . 527 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 528 Protocol (HTTP/1.1): Authentication", RFC 7235, 529 DOI 10.17487/RFC7235, June 2014, 530 . 532 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 533 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 534 2015, . 536 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 537 DOI 10.17487/RFC7517, May 2015, 538 . 540 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 541 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 542 . 544 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 545 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 546 2015, . 548 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 549 RFC 7662, DOI 10.17487/RFC7662, October 2015, 550 . 552 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 553 Possession Key Semantics for JSON Web Tokens (JWTs)", 554 RFC 7800, DOI 10.17487/RFC7800, April 2016, 555 . 557 11.2. Informative References 559 [POPA] Hunt, P., Ed., "OAuth 2.0 Proof-of-Possession (PoP) 560 Security Architecture", March 2015, 561 . 564 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 565 for Code Exchange by OAuth Public Clients", RFC 7636, 566 DOI 10.17487/RFC7636, September 2015, 567 . 569 [TINTRO] Richer, J., "OAuth 2.0 Token Introspection", July 2015. 571 Appendix A. Document History 573 -00 Initial Version. 575 Authors' Addresses 577 Nat Sakimura 578 Nomura Research Institute 579 Otemachi Financial City Grand Cube, 1-9-2 Otemachi 580 Chiyoda-ku, Tokyo 100-0004 581 Japan 583 Phone: +81-3-5533-2111 584 Email: n-sakimura@nri.co.jp 585 URI: https://nat.sakimura.org/ 586 Kepeng Li 587 Alibaba Group 589 Email: kepeng.lkp@alibaba-inc.com 591 John Bradley 592 Ping Identity 594 Email: ve7jtb@ve7jtb.com 595 URI: http://www.thread-safe.com/