idnits 2.17.1 draft-ietf-ace-oauth-params-09.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 date (December 22, 2019) is 1586 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) == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-29 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group L. Seitz 3 Internet-Draft Combitech 4 Intended status: Standards Track December 22, 2019 5 Expires: June 24, 2020 7 Additional OAuth Parameters for Authorization in Constrained 8 Environments (ACE) 9 draft-ietf-ace-oauth-params-09 11 Abstract 13 This specification defines new parameters for the OAuth 2.0 token and 14 introspection endpoints when used with the framework for 15 authentication and authorization for constrained environments (ACE). 16 These are used to express the proof-of-possession key the client 17 wishes to use, the proof-of-possession key that the Authorization 18 Server has selected, and the key the Resource Server should use to 19 authenticate to the client. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on June 24, 2020. 38 Copyright Notice 40 Copyright (c) 2019 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. Parameters for the Token Endpoint . . . . . . . . . . . . . . 3 58 3.1. Client-to-AS Request . . . . . . . . . . . . . . . . . . 3 59 3.2. AS-to-Client Response . . . . . . . . . . . . . . . . . . 4 60 3.3. The Resource Server Confirmation Claim . . . . . . . . . 6 61 4. Parameters for the Introspection Endpoint . . . . . . . . . . 6 62 4.1. AS-to-RS Response . . . . . . . . . . . . . . . . . . . . 6 63 5. Confirmation Method Parameters . . . . . . . . . . . . . . . 8 64 6. CBOR Mappings . . . . . . . . . . . . . . . . . . . . . . . . 9 65 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 66 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 9 67 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 68 9.1. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 9 69 9.2. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 9 70 9.3. OAuth Parameter Registration . . . . . . . . . . . . . . 10 71 9.4. OAuth Introspection Response Parameter Registration . . . 10 72 9.5. OAuth Parameters CBOR Mappings Registraton . . . . . . . 11 73 9.6. OAuth Token Introspection Response CBOR Mappings 74 Registration . . . . . . . . . . . . . . . . . . . . . . 11 75 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 76 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 77 11.1. Normative References . . . . . . . . . . . . . . . . . . 12 78 11.2. Informative References . . . . . . . . . . . . . . . . . 13 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 81 1. Introduction 83 The Authentication and Authorization for Constrained Environments 84 (ACE) specification [I-D.ietf-ace-oauth-authz] requires some new 85 parameters for interactions with the OAuth 2.0 [RFC6749] token and 86 introspection endpoints, as well as some new claims to be used in 87 access tokens. These parameters and claims can also be used in other 88 contexts and have therefore been put into a dedicated document, to 89 facilitate their use in a manner independent of 90 [I-D.ietf-ace-oauth-authz]. 92 Note that although all examples are shown in CBOR [RFC7049], JSON 93 [RFC8259] MAY be used as an alternative for HTTP-based 94 communications, as specified in [I-D.ietf-ace-oauth-authz]. 96 2. Terminology 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 BCP 101 14 [RFC2119] [RFC8174] when, and only when, they appear in all 102 capitals, as shown here. 104 Readers are assumed to be familiar with the terminology from 105 [I-D.ietf-ace-oauth-authz], especially the terminology for entities 106 in the architecture such as client (C), resource server (RS) and 107 authorization server (AS). 109 Terminology from [RFC8152] is used in the examples, especially 110 COSE_Key defined in section 7 of [RFC8152]. 112 Note that the term "endpoint" is used here following its OAuth 2.0 113 [RFC6749] definition, which is to denote resources such as token and 114 introspection at the AS and authz-info at the RS. The CoAP [RFC7252] 115 definition, which is "An entity participating in the CoAP protocol" 116 is not used in this specification. 118 3. Parameters for the Token Endpoint 120 This section defines additional parameters for the interations with 121 the token endpoint in the ACE framework [I-D.ietf-ace-oauth-authz]. 123 3.1. Client-to-AS Request 125 This section defines the "req_cnf" parameter allowing clients to 126 request a specific proof-of-possession key in an access token from a 127 token endpoint in the ACE framework [I-D.ietf-ace-oauth-authz]: 129 req_cnf 130 OPTIONAL. This field contains information about the key the 131 client would like to bind to the access token for proof-of- 132 possession. It is RECOMMENDED that an AS reject a request 133 containing a symmetric key value in the 'req_cnf' field 134 (kty=Symmetric), since the AS is expected to be able to generate 135 better symmetric keys than a constrained client. The AS MUST 136 verify that the client really is in possession of the 137 corresponding key. Values of this parameter follow the syntax of 138 the "cnf" claim from section 3.1 of 139 [I-D.ietf-ace-cwt-proof-of-possession]. 141 Figure 1 shows a request for an access token using the "req_cnf" 142 parameter to request a specific public key as proof-of-possession 143 key. The content is displayed in CBOR diagnostic notation, without 144 abbreviations and with line-breaks for better readability. 146 Header: POST (Code=0.02) 147 Uri-Host: "as.example.com" 148 Uri-Path: "token" 149 Content-Format: "application/ace+cbor" 150 Payload: 151 { 152 "req_cnf" : { 153 "COSE_Key" : { 154 "kty" : "EC2", 155 "kid" : h'11', 156 "crv" : "P-256", 157 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 158 4DC189F745228255A219A86D6A09EFF', 159 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 160 A64B6D72CCFED6B6FB6ED28BBFC117E' 161 } 162 } 163 } 165 Figure 1: Example request for an access token bound to an asymmetric 166 key. 168 3.2. AS-to-Client Response 170 This section defines the following additional parameters for an AS 171 response to a request to the token endpoint: 173 cnf 174 REQUIRED if the token type is "pop" and a symmetric key is used. 175 MAY be present for asymmetric proof-of-possession keys. This 176 field contains the proof-of-possession key that the AS selected 177 for the token. Values of this parameter follow the syntax of the 178 "cnf" claim from section 3.1 of 179 [I-D.ietf-ace-cwt-proof-of-possession]. See Section 5 for 180 additional discussion of the usage of this parameter. 182 rs_cnf 183 OPTIONAL if the token type is "pop" and asymmetric keys are used. 184 MUST NOT be present otherwise. This field contains information 185 about the public key used by the RS to authenticate. If this 186 parameter is absent, either the RS does not use a public key or 187 the AS knows that the RS can authenticate itself to the client 188 without additional information. Values of this parameter follow 189 the syntax of the "cnf" claim from section 3.1 of 191 [I-D.ietf-ace-cwt-proof-of-possession]. See Section 5 for 192 additional discussion of the usage of this parameter. 194 Figure 2 shows an AS response containing a token and a "cnf" 195 parameter with a symmetric proof-of-possession key. 197 Header: Created (Code=2.01) 198 Content-Format: "application/ace+cbor" 199 Payload: 200 { 201 "access_token" : h'4A5015DF686428 ... 202 (remainder of CWT omitted for brevity; 203 CWT contains COSE_Key in the "cnf" claim)', 204 "cnf" : { 205 "COSE_Key" : { 206 "kty" : "Symmetric", 207 "kid" : h'DFD1AA97', 208 "k" : h'849B5786457C1491BE3A76DCEA6C427108' 209 } 210 } 211 } 213 Figure 2: Example AS response with an access token bound to a 214 symmetric key. 216 Figure 3 shows an AS response containing a token bound to a 217 previously requested asymmetric proof-of-possession key (not shown) 218 and a "rs_cnf" parameter containing the public key of the RS. 220 Header: Created (Code=2.01) 221 Content-Format: "application/ace+cbor" 222 Payload: 223 { 224 "access_token" : h'D08343A1010AA1054D2A45DF6FBC5A5A ... 225 (remainder of CWT omitted for brevity; 226 CWT contains COSE_Key in the "cnf" claim)', 227 "rs_cnf" : { 228 "COSE_Key" : { 229 "kty" : "EC2", 230 "kid" : h'12', 231 "crv" : "P-256", 232 "x" : h'BCEE7EAAC162F91E6F330F5771211E220 233 B8B546C96589B0AC4AD0FD24C77E1F1', 234 "y" : h'C647B38C55EFBBC4E62E651720F002D5D 235 75B2E0C02CD1326E662BCA222B90416' 236 } 237 } 238 } 240 Figure 3: Example AS response, including the RS's public key. 242 3.3. The Resource Server Confirmation Claim 244 If the AS needs to convey a hint to the RS about which key it should 245 use to authenticate towards the client, this specification defines 246 the "rs_cnf" claim, which MAY be used in the access token, with the 247 same syntax and semantics as defined in for the "rs_cnf" parameter. 249 4. Parameters for the Introspection Endpoint 251 This section defines additional parameters for the interations with 252 the introspection endpoint in the ACE framework 253 [I-D.ietf-ace-oauth-authz]. 255 4.1. AS-to-RS Response 257 This section defines the following additional parameters for an AS 258 response to a request to the introspection endpoint: 260 cnf 261 OPTIONAL. This field contains information about the proof-of- 262 possession key that binds the client to the access token. Values 263 of this parameter follow the syntax of the "cnf" claim from 264 section 3.1 of [I-D.ietf-ace-cwt-proof-of-possession]. See 265 Section 5 for additional discussion of the usage of this 266 parameter. 268 rs_cnf 269 OPTIONAL. If the RS uses asymmetric keys to authenticate towards 270 the client (e.g., with a DTLS Raw Public Key handshake [RFC7250] 271 and it has several such keys (e.g., for different elliptic 272 curves), the AS can give the RS a hint using this parameter, as to 273 which key it should use. Values of this parameter follow the 274 syntax of the "cnf" claim from section 3.1 of 275 [I-D.ietf-ace-cwt-proof-of-possession]. See Section 5 for 276 additional discussion of the usage of this parameter. 278 Figure 4 shows an AS response to an introspection request including 279 the "cnf" parameter to indicate the proof-of-possession key bound to 280 the token and the "rs_cnf" parameter to indicate the key the RS is 281 supposed to use to authenticate to the client. 283 Header: Created Code=2.01) 284 Content-Format: "application/ace+cbor" 285 Payload: 286 { 287 "active" : true, 288 "scope" : "read", 289 "aud" : "tempSensor4711", 290 "cnf" : { 291 "COSE_Key" : { 292 "kty" : "EC2", 293 "kid" : h'11', 294 "crv" : "P-256", 295 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 296 4DC189F745228255A219A86D6A09EFF', 297 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 298 A64B6D72CCFED6B6FB6ED28BBFC117E' 299 } 300 }, 301 "rs_cnf" : { 302 "COSE_Key" : { 303 "kty" : "EC2", 304 "kid" : h'12', 305 "crv" : "P-256", 306 "x" : h'BCEE7EAAC162F91E6F330F5771211E220 307 B8B546C96589B0AC4AD0FD24C77E1F1', 308 "y" : h'C647B38C55EFBBC4E62E651720F002D5D 309 75B2E0C02CD1326E662BCA222B90416' 310 } 311 } 312 } 314 Figure 4: Example introspection response. 316 5. Confirmation Method Parameters 318 The confirmation method parameters are used as follows: 320 o "req_cnf" in the access token request C -> AS, OPTIONAL to 321 indicate the client's raw public key, or the key-identifier of a 322 previously established key between C and RS that the client wishes 323 to use for proof-of-possession of the access token. 325 o "cnf" in the token response AS -> C, OPTIONAL if using an 326 asymmetric key or a key that the client requested via a key 327 identifier in the request. REQUIRED if the client didn't specify 328 a "req_cnf" and symmetric keys are used. Used to indicate the 329 symmetric key generated by the AS for proof-of-possession of the 330 access token. 332 o "cnf" in the introspection response AS -> RS, REQUIRED if the 333 access token that was subject to introspection is a proof-of- 334 possession token, absent otherwise. Indicates the proof-of- 335 possession key bound to the access token. 337 o "rs_cnf" in the token response AS -> C, OPTIONAL to indicate the 338 public key of the RS, if it uses one to authenticate itself to the 339 client and the binding between key and RS identity is not 340 established through other means. 342 o "rs_cnf" in the introspection response AS -> RS, OPTIONAL, 343 contains the public key that the RS should use for authenticating 344 itself to the client (e.g., if the RS has several different public 345 keys, and there may be ambiguity as to which key to use). 347 Note that the COSE_Key structure in a confirmation claim or parameter 348 may contain an "alg" or "key_ops" parameter. If such parameters are 349 present, a client MUST NOT use a key that is incompatible with the 350 profile or proof-of-possession algorithm according to those 351 parameters. An RS MUST reject a proof-of-possession using such a 352 key. 354 If an access token is issued for an audience that includes several 355 RS, the "rs_cnf" parameter MUST NOT be used, since the client cannot 356 determine for which RS the key applies. This document recommends to 357 specify a different endpoint that the client can use to acquire RS 358 authentication keys in such cases. The specification of such an 359 endpoint is out of scope for this document. 361 6. CBOR Mappings 363 If CBOR is used, the new parameters and claims defined in this 364 document MUST be mapped to CBOR types as specified in Figure 5, using 365 the given integer abbreviation for the map key. 367 /----------+----------+-------------------------------------\ 368 | Name | CBOR Key | Value Type | Usage | 369 |----------+----------+-------------------------------------| 370 | req_cnf | TBD (4) | map | token request | 371 | cnf | TBD (8) | map | token response | 372 | cnf | TBD (8) | map | introspection response | 373 | rs_cnf | TBD (41) | map | token response | 374 | rs_cnf | TBD (41) | map | introspection response | 375 | rs_cnf | TBD (41) | map | CWT claim | 376 \----------+----------+------------+------------------------/ 378 Figure 5: CBOR mappings for new parameters and claims. 380 7. Security Considerations 382 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 383 security considerations from that document apply here as well. 385 8. Privacy Considerations 387 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 388 privacy considerations from that document apply here as well. 390 9. IANA Considerations 392 9.1. JSON Web Token Claims 394 This specification registers the following new claim in the JSON Web 395 Token (JWT) registry of JSON Web Token Claims 396 [IANA.JsonWebTokenClaims]: 398 o Claim Name: "rs_cnf" 399 o Claim Description: public key used by RS to authenticate itself to 400 the client. 401 o Change Controller: IESG 402 o Reference: Section 3.3 of [this document] 404 9.2. CBOR Web Token Claims 406 This specification registers the following new claim in the "CBOR Web 407 Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. 409 o Claim Name: "rs_cnf" 410 o Claim Description: public key used by RS to authenticate itself to 411 the client. 412 o JWT Claim Name: rs_cnf 413 o Claim Key: TBD (suggested: 41) 414 o Claim Value Type(s): map 415 o Change Controller: IESG 416 o Specification Document(s): Section 3.3 of [this document] 418 9.3. OAuth Parameter Registration 420 This section registers the following parameters in the "OAuth 421 Parameters" registry [IANA.OAuthParameters]: 423 o Name: "req_cnf" 424 o Parameter Usage Location: token request 425 o Change Controller: IESG 426 o Reference: Section 5 of [this document] 428 o Name: "rs_cnf" 429 o Parameter Usage Location: token response 430 o Change Controller: IESG 431 o Reference: Section 5 of [this document] 433 o Name: "cnf" 434 o Parameter Usage Location: token response 435 o Change Controller: IESG 436 o Reference: Section 5 of [this document] 438 9.4. OAuth Introspection Response Parameter Registration 440 This section registers the following parameters in the OAuth Token 441 Introspection Response registry [IANA.TokenIntrospectionResponse]. 443 o Name: "cnf" 444 o Description: Key to prove the right to use a PoP token. 445 o Change Controller: IESG 446 o Reference: Section 4.1 of [this document] 448 o Name: "rs_cnf" 449 o Description: public key used by RS to authenticate itself to the 450 client. 451 o Change Controller: IESG 452 o Reference: Section 4.1 of [this document] 454 9.5. OAuth Parameters CBOR Mappings Registraton 456 This section registers the following parameter mappings in the "OAuth 457 Parameters CBOR Mappings" registry established in section 8.9. of 458 [I-D.ietf-ace-oauth-authz]. 460 o Name: "req_cnf" 461 o CBOR key: TBD (suggested: 4) 462 o Change Controller: IESG 463 o Reference: Section 3.1 of [this document] 465 o Name: "cnf" 466 o CBOR key: TBD (suggested: 8) 467 o Change Controller: IESG 468 o Reference: Section 3.2 of [this document] 470 o Name: "rs_cnf" 471 o CBOR key: TBD (suggested: 41) 472 o Change Controller: IESG 473 o Reference: Section 3.2 of [this document] 475 9.6. OAuth Token Introspection Response CBOR Mappings Registration 477 This section registers the following parameter mappings in the "OAuth 478 Token Introspection Response CBOR Mappings" registry established in 479 section 8.11. of [I-D.ietf-ace-oauth-authz]. 481 o Name: "cnf" 482 o CBOR key: TBD (suggested: 8) 483 o Change Controller: IESG 484 o Reference: Section 4.1 of [this document] 486 o Name: "rs_cnf" 487 o CBOR key: TBD (suggested: 41) 488 o Change Controller: IESG 489 o Reference: Section 4.1 of [this document] 491 10. Acknowledgments 493 This document is a product of the ACE working group of the IETF. 495 Ludwig Seitz worked on this document as part of the CelticNext 496 projects CyberWI, and CRITISEC with funding from Vinnova. 498 11. References 500 11.1. Normative References 502 [I-D.ietf-ace-cwt-proof-of-possession] 503 Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 504 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 505 Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- 506 possession-11 (work in progress), October 2019. 508 [I-D.ietf-ace-oauth-authz] 509 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 510 H. Tschofenig, "Authentication and Authorization for 511 Constrained Environments (ACE) using the OAuth 2.0 512 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-29 513 (work in progress), December 2019. 515 [IANA.CborWebTokenClaims] 516 IANA, "CBOR Web Token (CWT) Claims", 517 . 520 [IANA.JsonWebTokenClaims] 521 IANA, "JSON Web Token Claims", 522 . 524 [IANA.OAuthParameters] 525 IANA, "OAuth Parameters", 526 . 529 [IANA.TokenIntrospectionResponse] 530 IANA, "OAuth Token Introspection Response", 531 . 534 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 535 Requirement Levels", BCP 14, RFC 2119, 536 DOI 10.17487/RFC2119, March 1997, 537 . 539 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 540 RFC 6749, DOI 10.17487/RFC6749, October 2012, 541 . 543 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 544 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 545 October 2013, . 547 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 548 RFC 8152, DOI 10.17487/RFC8152, July 2017, 549 . 551 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 552 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 553 May 2017, . 555 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 556 Interchange Format", STD 90, RFC 8259, 557 DOI 10.17487/RFC8259, December 2017, 558 . 560 11.2. Informative References 562 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 563 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 564 Transport Layer Security (TLS) and Datagram Transport 565 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 566 June 2014, . 568 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 569 Application Protocol (CoAP)", RFC 7252, 570 DOI 10.17487/RFC7252, June 2014, 571 . 573 Author's Address 575 Ludwig Seitz 576 Combitech 577 Djaeknegatan 31 578 Malmoe 211 35 579 Sweden 581 Email: ludwig.seitz@combitech.se