idnits 2.17.1 draft-sakimura-oauth-jpop-03.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 2585 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 525, but no explicit reference was found in the text == Unused Reference: 'PKCE' is defined on line 544, but no explicit reference was found in the text == Unused Reference: 'POPA' is defined on line 547, but no explicit reference was found in the text == Unused Reference: 'TINTRO' is defined on line 552, 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-03 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 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 . . . . . . . . . . . . . . . . . . . . . . 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 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. DN Constrained Token 146 2. Client ID Constrained Token 148 4.1. DN Constrained Token 150 DN 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 dn The Distinguished Name of the client certificate as a string that 156 the client used in the authorization request. 158 The authorization server finds the relevant DN 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 "dn": "cn=John Doe LLC,dc=client,dc=example,dc=com" 169 } 170 } 172 Figure 2: Example of DN Constrained JWT. 174 4.2. Client ID Constrained Token 176 The constraint in the Client ID constrained token is expressed by 177 including the following member at the top level of cnf claim. 179 cid The client_id of the client that the client used in the 180 authorization request. The combination of the "iss" of the access 181 token and this value forms a globally unique identifier for the 182 client. 184 The authorization server finds the client ID from the client ID used 185 in the client authentication at the token endpoint. 187 5. Key Constrained Token 189 Methods to express key constraints are extensively described in the 190 section 3 of [RFC7800]. Such cnf claim is used in the access token 191 described in section 3 to form a key constrained token. [RFC7800] 192 defines 4 confirmation methods. 194 jwk JSON Web Key Representing a Public Key 196 jwe Encrypted JSON Web Key 198 jwkt#s256 [RFC7638] Thumbprint of a JWK using the SHA-256 hash 199 function. 201 x5t#s256 [RFC7515] X.509 Certificate SHA-256 Thumbprint 203 jku JWK Set URL 205 The client provides the corresponding keys or the pointers to the 206 authorization server as a part of the client configuration. It can 207 be done through out-of-band methods (e.g., developper portal) or 208 through some form of dynamic registration, etc. 210 Following is an example of a JWT payload containing a JWK with a raw 211 key. 213 { 214 "iss": "https://server.example.com", 215 "sub": "joe@example.com", 216 "aud": "https://resource.example.org", 217 "exp": "1361398824", 218 "nbf": "1360189224", 219 "cnf":{ 220 "jwk":{ 221 "kty": "EC", 222 "use": "sig", 223 "crv": "P-256", 224 "x": "18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM", 225 "y": "-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA" 226 } 227 } 228 } 230 Figure 3: Example of a JWK Key Constrained JWT. 232 Following is an example of a JWT payload containing a jku URI. 234 { 235 "iss": "https://server.example.com", 236 "sub": "joe@example.com", 237 "aud": "https://resource.example.org", 238 "exp": "1361398824", 239 "nbf": "1360189224", 240 "cnf":{ 241 "jku": "https://client.example.com/keys/client123-jwks" 242 } 243 } 245 Figure 4: Example of a jku Constrained JWT. 247 Following is an example of a JWT payload containing a x5t#s256 248 Certificate Thumbprint of a x509 certificate. . 250 { 251 "iss": "https://server.example.com", 252 "sub": "joe@example.com", 253 "aud": "https://resource.example.org", 254 "exp": "1361398824", 255 "nbf": "1360189224", 256 "cnf":{ 257 "x5t#s256": "w5cK0ebwmCZUYDB2Y5SlESsXE8o9yZg05O89jdNidgI" 258 } 259 } 261 Figure 5: Example of a x5t#s256 Certificate Thumbprint Constrained 262 JWT. 264 6. Resource access method 266 The resource server that supports this specification MUST 267 authenticate the Client by having it demonstrate that it is the 268 holder of the key associated with the access token being used. The 269 confirmation method can be broadly categorized in two forms. 271 Mutual TLS method A method leveraging on the X.509 client 272 certificate authentication of the TLS connection. cn, x5t#s256, 273 and jku confirmation methods can be used with this access method. 274 (The JWKS referenced by the jku MUST contain JWK with x5c 275 certificate elements for this access method) 277 Signature method A method leveraging the signature on the nonce. 278 cid, jku, jwk, jwe, and, jwkt#S256 confirmation methods can be 279 used with this access method. 281 6.1. Mutual TLS acess method 283 DN cnf method Under this method, X.509 client certificate 284 authentication at the resource endpoint is being leveraged. The 285 resource endpoint MUST obtain the DN of the client certificate 286 used for the authentication and MUST verify that the value of the 287 dn member in the cnf member matches with it. 289 If it does not match, the process stops here and the resource 290 access MUST be denied. 292 If it is valid, then the resource server MUST verify the access 293 token. If it is valid, the resource SHOULD be returned as HTTP 294 response. 296 x5t#s256 cnf method Under this method, X.509 client certificate 297 authentication at the resource endpoint is being leveraged. The 298 resource endpoint MUST obtain the client certificate used for the 299 authentication and MUST verify that the base64url-encoded SHA-256 300 thumprint of the DER encoded X.509 client certificate. The 301 x5t#s256 member in the cnf member MUST exactly match the 302 calculated thumbprint. 304 If it does not match, the process stops here and the resource 305 access MUST be denied. 307 If it is valid, then the resource server MUST verify the access 308 token. If it is valid, the resource SHOULD be returned as HTTP 309 response. 311 jku cnf method Under this method, X.509 client certificate 312 authentication at the resource endpoint is being leveraged. The 313 resource endpoint MUST obtain the client certificate used for the 314 authentication and MUST verify that the certificate matches one of 315 the x5c elements retrieved from the [RFC7517]JWKS. Each x5c 316 element may contain a chain of base64-encoded certificates. The 317 client certificate MUST only be compared with the last certificate 318 in the chain. 320 If it does not match, the process stops here and the resource 321 access MUST be denied. 323 If it is valid, then the resource server MUST verify the access 324 token. If it is valid, the resource SHOULD be returned as HTTP 325 response. 327 6.2. Signature method 329 For this, the following steps are taken: 331 STEP1: The client accesses the protected resource and gets an 332 authorization error as in Section 7. With it, the client 333 obtains a nonce. 335 STEP2: The client prepares a client nonce, "cnonce", and nounce 336 count, "nc" as defined in section 3.2.2 of [RFC2617]. 338 STEP3: The client creates JWS compact serialization over the nonce. 340 To obtain it, first create a JSON with a name "nonce" and the value 341 being what was received in the previous step. The JWS MUST contain a 342 kid header element if the client has more than one signing key 343 published via JWKS URI e.g., 344 { 345 "nonce":"dcd98b7102dd2f0e8b11d0f600bfb0c093", 346 "nc":"00000001", 347 "cnonce":"0a4f113b" 348 } 350 Then, "jws-on-nonce" is obtained by creating a compact serialization 351 of JWS on this JSON. 353 STEP4: The client sends the request to the resource server, this 354 time with Authorization Request Header as defined in section 355 4.2 of [RFC7235] with the credential as follows: 357 credentials = "Jpop" jpop-response 358 jpop-response = at-response "," s-response 359 at-response = "at" "=" access-token (* As specified by [POPKD] *) 360 s-response = "s" "=" jws-on-nonce (* Created in the STEP3. *) 361 access-token = quoted-string 362 jws-on-nonce = quoted-string 364 In the following example, the access token and the jws-on-nonce are 365 represented as access.token.jwt and jws.of.nonce for the sake of 366 brevity. 368 GET /resource/1234 HTTP/1.0 369 Host: server.example.com 370 Authorization: Jpop at="access.token.jwt", s="jws.of.nonce" 372 Figure 6: Example resouce request 374 STEP5: The resource server finds the client's public key form the 375 access token through the methods described in [RFC7800]. 377 STEP6: The resource server MUST verify the value of "s" of the 378 Authorization header. If it fails, the process stops here 379 and the resource access MUST be denied. 381 STEP7: The resource server MUST verify the access token. If it is 382 valid, the resource SHOULD be returned as HTTP response. 384 7. Authorization Error 386 If the client requests the resource without the proper authoization 387 header, the resource server returns a HTTP 401 response with "WWW- 388 Authenticate" header as defined in section 4.1 of [RFC7235] with the 389 challenge as follows: 391 challenge = "Jpop" jpop-challenge 392 jpop-challenge = "nonce" "=" nonce-value 393 nonce-value = quoted-string 395 Following example depicts what the response would look like. 397 HTTP/1.0 401 Unauthorized 398 Server: HTTPd/0.9 399 Date: Wed, 14 March 2017 09:26:53 GMT 400 WWW-Authenticate: Jpop nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093" 402 Figure 7: Example error response. 404 8. IANA Considerations 406 8.1. Jpop Authentication Scheme 408 A new scheme has been registered in the HTTP Authentication Scheme 409 Registry as follows: 411 Authentication Scheme Name: Jpop 413 Reference: Section 3 of this specification 415 Notes (optional): The Named Authentication scheme is intended to be 416 used only with OAuth Resource Access, and thus does not support proxy 417 authentication. 419 8.2. JWT Confirmation Methods 421 o Confirmation Method Value: "dn" 423 o Confirmation Method Description: DN match with the TLS client 424 auth. 426 o Change Controller: IESG 428 o Specification Document(s): This document. 430 o Confirmation Method Value: "cid" 432 o Confirmation Method Description: Client ID Confirmation 434 o Change Controller: IESG 436 o Specification Document(s): This document. 438 9. Security Considerations 440 9.1. Certificate validation 442 The "dn" JWT confirmation method relies its security property on the 443 X.509 client certificate authentication. In particular, the validity 444 of the certificate needs to be verified properly. It involves the 445 traversal of all the certificate chain and the certificate validation 446 (e.g., with OCSP). 448 9.2. Key protection 450 The client's secret key must be kept securely. Otherwise, the notion 451 of PoP breaks down. 453 It should be noted that JWE confirmation method is significantly 454 weaker form of the PoP, as the resource server and the authorization 455 server can masquerade as the client. 457 9.3. Audiance Restriction 459 When using the signature method the client must specify to the AS the 460 aud it intends to send the token to, so that it can be included in 461 the AT. 463 A malicious RS could receive a AT with no aud or a logical audience 464 and then replay the AT and jws-on-nonce to the actual server. 466 NOTE another approach would be to include the resource in the jws-on- 467 nonce 469 9.4. Dynamic client registration elements 471 When a AS uses dynamic client registration it may accept software 472 statements supplied by a federation operator. Those software 473 statements can contain a JWKS-URI that is hosted by the federation 474 operator or protected by a certificate provisioned from a trusted 475 root. These methods would allow the federation operator to 476 administratively revoke the keys at the JWKS-URI without requiring 477 the JWKS to contain x5c elements with CA issued certificates and 478 having to have the RS perform full certificate validation for each 479 request. 481 10. Acknowledgements 483 The authors thank the following people for providing valuable 484 feedback to this document. Nov Matake (YAuth). 486 11. References 488 11.1. Normative References 490 [POPKD] Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 491 "OAuth 2.0 Proof-of-Possession: Authorization Server to 492 Client Key Distribution", March 2017, 493 . 496 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 497 Requirement Levels", BCP 14, RFC 2119, 498 DOI 10.17487/RFC2119, March 1997, 499 . 501 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 502 Leach, P., Luotonen, A., and L. Stewart, "HTTP 503 Authentication: Basic and Digest Access Authentication", 504 RFC 2617, DOI 10.17487/RFC2617, June 1999, 505 . 507 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 508 RFC 6749, DOI 10.17487/RFC6749, October 2012, 509 . 511 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 512 Framework: Bearer Token Usage", RFC 6750, 513 DOI 10.17487/RFC6750, October 2012, 514 . 516 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 517 Protocol (HTTP/1.1): Authentication", RFC 7235, 518 DOI 10.17487/RFC7235, June 2014, 519 . 521 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 522 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 523 2015, . 525 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 526 DOI 10.17487/RFC7517, May 2015, 527 . 529 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 530 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 531 . 533 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 534 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 535 2015, . 537 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 538 Possession Key Semantics for JSON Web Tokens (JWTs)", 539 RFC 7800, DOI 10.17487/RFC7800, April 2016, 540 . 542 11.2. Informative References 544 [PKCE] Sakimura, N., "Proof Key for Code Exchange by OAuth Public 545 Clients", July 2015. 547 [POPA] Hunt, P., Ed., "OAuth 2.0 Proof-of-Possession (PoP) 548 Security Architecture", March 2015, 549 . 552 [TINTRO] Richer, J., "OAuth 2.0 Token Introspection", July 2015. 554 Appendix A. Document History 556 -00 Initial Version. 558 Authors' Addresses 560 Nat Sakimura 561 Nomura Research Institute 562 Otemachi Financial City Grand Cube, 1-9-2 Otemachi 563 Chiyoda-ku, Tokyo 100-0004 564 Japan 566 Phone: +81-3-5533-2111 567 Email: n-sakimura@nri.co.jp 568 URI: https://nat.sakimura.org/ 570 Kepeng Li 571 Alibaba Group 573 Email: kepeng.lkp@alibaba-inc.com 574 John Bradley 575 Ping Identity 577 Email: ve7jtb@ve7jtb.com 578 URI: http://www.thread-safe.com/