idnits 2.17.1 draft-ietf-ace-oauth-params-15.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 (May 5, 2021) is 1087 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-40 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 1 error (**), 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 May 5, 2021 5 Expires: November 6, 2021 7 Additional OAuth Parameters for Authorization in Constrained 8 Environments (ACE) 9 draft-ietf-ace-oauth-params-15 11 Abstract 13 This specification defines new parameters and encodings for the OAuth 14 2.0 token and introspection endpoints when used with the framework 15 for authentication and authorization for constrained environments 16 (ACE). These are used to express the proof-of-possession key the 17 client wishes to use, the proof-of-possession key that the 18 Authorization Server has selected, and the key the Resource Server 19 uses to 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 November 6, 2021. 38 Copyright Notice 40 Copyright (c) 2021 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 4. Parameters for the Introspection Endpoint . . . . . . . . . . 6 61 5. Confirmation Method Parameters . . . . . . . . . . . . . . . 7 62 6. CBOR Mappings . . . . . . . . . . . . . . . . . . . . . . . . 8 63 7. Requirements when using asymmetric keys . . . . . . . . . . . 8 64 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 65 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 9 66 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 10.1. OAuth Parameter Registration . . . . . . . . . . . . . . 9 68 10.2. OAuth Parameters CBOR Mappings Registration . . . . . . 9 69 10.3. OAuth Token Introspection Response CBOR Mappings 70 Registration . . . . . . . . . . . . . . . . . . . . . . 10 71 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 72 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 73 12.1. Normative References . . . . . . . . . . . . . . . . . . 10 74 12.2. Informative References . . . . . . . . . . . . . . . . . 11 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 77 1. Introduction 79 The Authentication and Authorization for Constrained Environments 80 (ACE) specification [I-D.ietf-ace-oauth-authz] requires some new 81 parameters for interactions with the OAuth 2.0 [RFC6749] token and 82 introspection endpoints, as well as some new claims to be used in 83 access tokens. These parameters and claims can also be used in other 84 contexts and have therefore been put into a dedicated document, to 85 facilitate their use in a manner independent of 86 [I-D.ietf-ace-oauth-authz]. 88 Note that although all examples are shown in Concise Binary Object 89 Representation (CBOR) [RFC8949], JSON [RFC8259] MAY be used as an 90 alternative for HTTP-based communications, as specified in 91 [I-D.ietf-ace-oauth-authz]. 93 2. Terminology 95 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 96 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 97 "OPTIONAL" in this document are to be interpreted as described in BCP 98 14 [RFC2119] [RFC8174] when, and only when, they appear in all 99 capitals, as shown here. 101 Readers are assumed to be familiar with the terminology from 102 [I-D.ietf-ace-oauth-authz], especially the terminology for entities 103 in the architecture such as client (C), resource server (RS) and 104 authorization server (AS). 106 Terminology from [RFC8152] is used in the examples, especially 107 COSE_Key defined in section 7 of [RFC8152]. 109 Note that the term "endpoint" is used here following its OAuth 2.0 110 [RFC6749] definition, which is to denote resources such as token and 111 introspection at the AS and authz-info at the RS. The Constrained 112 Application Protocol (CoAP) [RFC7252] definition, which is "An entity 113 participating in the CoAP protocol" is not used in this 114 specification. 116 3. Parameters for the Token Endpoint 118 This section defines additional parameters for the interactions with 119 the token endpoint in the ACE framework [I-D.ietf-ace-oauth-authz]. 121 3.1. Client-to-AS Request 123 This section defines the "req_cnf" parameter allowing clients to 124 request a specific proof-of-possession key in an access token from a 125 token endpoint in the ACE framework [I-D.ietf-ace-oauth-authz]: 127 req_cnf 128 OPTIONAL. This field contains information about the key the 129 client would like to bind to the access token for proof-of- 130 possession. It is RECOMMENDED that an AS rejects a request 131 containing a symmetric key value in the 'req_cnf' field 132 (kty=Symmetric), since the AS is expected to be able to generate 133 better symmetric keys than a constrained client (Note: this does 134 not apply to key identifiers referencing a symmetric key). The AS 135 MUST verify that the client really is in possession of the 136 corresponding key. Profiles of [I-D.ietf-ace-oauth-authz] using 137 this specification MUST define the proof-of-possession method used 138 by the AS, if they allow clients to use this request parameter. 139 Values of this parameter follow the syntax and semantics of the 140 "cnf" claim either from section 3.1 of [RFC8747] for CBOR-based 141 interactions or from section 3.1 of [RFC7800] for JSON-based 142 interactions. 144 Figure 1 shows a request for an access token using the "req_cnf" 145 parameter to request a specific public key as proof-of-possession 146 key. The content is displayed in CBOR diagnostic notation, without 147 abbreviations and with line-breaks for better readability. 149 Header: POST (Code=0.02) 150 Uri-Host: "as.example.com" 151 Uri-Path: "token" 152 Content-Format: "application/ace+cbor" 153 Payload: 154 { 155 "req_cnf" : { 156 "COSE_Key" : { 157 "kty" : "EC2", 158 "kid" : h'11', 159 "crv" : "P-256", 160 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 161 4DC189F745228255A219A86D6A09EFF', 162 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 163 A64B6D72CCFED6B6FB6ED28BBFC117E' 164 } 165 } 166 } 168 Figure 1: Example request for an access token bound to an asymmetric 169 key. 171 3.2. AS-to-Client Response 173 This section defines the following additional parameters for an AS 174 response to a request to the token endpoint: 176 cnf 177 REQUIRED if the token type is "pop" and a symmetric key is used. 178 MAY be present for asymmetric proof-of-possession keys. This 179 field contains the proof-of-possession key that the AS selected 180 for the token. Values of this parameter follow the syntax and 181 semantics of the "cnf" claim either from section 3.1 of [RFC8747] 182 for CBOR-based interactions or from section 3.1 of [RFC7800] for 183 JSON-based interactions. See Section 5 for additional discussion 184 of the usage of this parameter. 186 rs_cnf 187 OPTIONAL if the token type is "pop" and asymmetric keys are used. 188 MUST NOT be present otherwise. This field contains information 189 about the public key used by the RS to authenticate. If this 190 parameter is absent, either the RS does not use a public key or 191 the AS knows that the RS can authenticate itself to the client 192 without additional information. Values of this parameter follow 193 the syntax and semantics of the "cnf" claim either from section 194 3.1 of [RFC8747] for CBOR-based interactions or from section 3.1 195 of [RFC7800] for JSON-based interactions. See Section 5 for 196 additional discussion of the usage of this parameter. 198 Figure 2 shows an AS response containing a token and a "cnf" 199 parameter with a symmetric proof-of-possession key. 201 Header: Created (Code=2.01) 202 Content-Format: "application/ace+cbor" 203 Payload: 204 { 205 "access_token" : h'4A5015DF686428 ... 206 (remainder of CWT omitted for brevity; 207 CWT contains COSE_Key in the "cnf" claim)', 208 "cnf" : { 209 "COSE_Key" : { 210 "kty" : "Symmetric", 211 "kid" : h'DFD1AA97', 212 "k" : h'849B5786457C1491BE3A76DCEA6C427108' 213 } 214 } 215 } 217 Figure 2: Example AS response with an access token bound to a 218 symmetric key. 220 Figure 3 shows an AS response containing a token bound to a 221 previously requested asymmetric proof-of-possession key (not shown) 222 and a "rs_cnf" parameter containing the public key of the RS. 224 Header: Created (Code=2.01) 225 Content-Format: "application/ace+cbor" 226 Payload: 227 { 228 "access_token" : h'D08343A1010AA1054D2A45DF6FBC5A5A ... 229 (remainder of CWT omitted for brevity)', 230 "rs_cnf" : { 231 "COSE_Key" : { 232 "kty" : "EC2", 233 "kid" : h'12', 234 "crv" : "P-256", 235 "x" : h'BCEE7EAAC162F91E6F330F5771211E220 236 B8B546C96589B0AC4AD0FD24C77E1F1', 237 "y" : h'C647B38C55EFBBC4E62E651720F002D5D 238 75B2E0C02CD1326E662BCA222B90416' 239 } 240 } 241 } 243 Figure 3: Example AS response, including the RS's public key. 245 4. Parameters for the Introspection Endpoint 247 This section defines the use of CBOR instead of JSON for the "cnf" 248 introspection response parameter specified in section 9.4 of 249 [RFC8705]. 251 If CBOR is used instead of JSON in an interaction with the 252 introspection endpoint, the AS MUST use the parameter mapping 253 specified in Figure 5 and the value must follow the syntax of "cnf" 254 claim values from section 3.1 of [RFC8747]. 256 Figure 4 shows an AS response to an introspection request including 257 the "cnf" parameter to indicate the proof-of-possession key bound to 258 the token. 260 Header: Created (Code=2.01) 261 Content-Format: "application/ace+cbor" 262 Payload: 263 { 264 "active" : true, 265 "scope" : "read", 266 "aud" : "tempSensor4711", 267 "cnf" : { 268 "COSE_Key" : { 269 "kty" : "EC2", 270 "kid" : h'11', 271 "crv" : "P-256", 272 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 273 4DC189F745228255A219A86D6A09EFF', 274 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 275 A64B6D72CCFED6B6FB6ED28BBFC117E' 276 } 277 } 278 } 280 Figure 4: Example introspection response. 282 5. Confirmation Method Parameters 284 The confirmation method parameters are used in 285 [I-D.ietf-ace-oauth-authz] as follows: 287 o "req_cnf" in the access token request C -> AS, OPTIONAL to 288 indicate the client's raw public key, or the key-identifier of a 289 previously established key between C and RS that the client wishes 290 to use for proof-of-possession of the access token. 292 o "cnf" in the token response AS -> C, OPTIONAL if using an 293 asymmetric key or a key that the client requested via a key 294 identifier in the request. REQUIRED if the client didn't specify 295 a "req_cnf" and symmetric keys are used. Used to indicate the 296 symmetric key generated by the AS for proof-of-possession of the 297 access token. 299 o "cnf" in the introspection response AS -> RS, REQUIRED if the 300 access token that was subject to introspection is a proof-of- 301 possession token, absent otherwise. Indicates the proof-of- 302 possession key bound to the access token. 304 o "rs_cnf" in the token response AS -> C, OPTIONAL to indicate the 305 public key of the RS, if it uses one to authenticate itself to the 306 client and the binding between key and RS identity is not 307 established through other means. 309 Note that the COSE_Key structure in a confirmation claim or parameter 310 may contain an "alg" or "key_ops" parameter. If such parameters are 311 present, a client MUST NOT use a key that is incompatible with the 312 profile or proof-of-possession algorithm according to those 313 parameters. An RS MUST reject a proof-of-possession using such a key 314 with a response code equivalent to the CoAP code 4.00 (Bad Request). 316 If an access token is issued for an audience that includes several 317 RS, the "rs_cnf" parameter MUST NOT be used, since the client cannot 318 determine for which RS the key applies. This document recommends to 319 specify a different endpoint that the client can use to acquire RS 320 authentication keys in such cases. The specification of such an 321 endpoint is out of scope for this document. 323 6. CBOR Mappings 325 If CBOR is used, the new parameters and claims defined in this 326 document MUST be mapped to CBOR types as specified in Figure 5, using 327 the given integer abbreviation for the map key. 329 /----------+----------+-------------------------------------\ 330 | Name | CBOR Key | Value Type | Usage | 331 |----------+----------+-------------------------------------| 332 | req_cnf | TBD (4) | map | token request | 333 | cnf | TBD (8) | map | token response | 334 | cnf | TBD (8) | map | introspection response | 335 | rs_cnf | TBD (41) | map | token response | 336 \----------+----------+------------+------------------------/ 338 Figure 5: CBOR mappings for new parameters and claims. 340 7. Requirements when using asymmetric keys 342 An RS using asymmetric keys to authenticate to the client MUST NOT 343 hold several different asymmetric key pairs, applicable to the same 344 authentication algorithm. For example when using DTLS, the RS MUST 345 NOT hold several asymmetric key pairs applicable to the same cipher 346 suite. The reason for this restriction is that the RS has no way of 347 determining which key to use before the client's identity is 348 established. Therefore authentication attempts by the RS could 349 randomly fail based on which key the RS selects, unless the algorithm 350 negotiation produces a unique choice of key pair for the RS. 352 8. Security Considerations 354 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 355 security considerations from that document apply here as well. 357 9. Privacy Considerations 359 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 360 privacy considerations from that document apply here as well. 362 10. IANA Considerations 364 10.1. OAuth Parameter Registration 366 This section registers the following parameters in the "OAuth 367 Parameters" registry [IANA.OAuthParameters]: 369 o Name: "req_cnf" 370 o Parameter Usage Location: token request 371 o Change Controller: IESG 372 o Reference: Section 5 of [this document] 374 o Name: "rs_cnf" 375 o Parameter Usage Location: token response 376 o Change Controller: IESG 377 o Reference: Section 5 of [this document] 379 o Name: "cnf" 380 o Parameter Usage Location: token response 381 o Change Controller: IESG 382 o Reference: Section 5 of [this document] 384 10.2. OAuth Parameters CBOR Mappings Registration 386 This section registers the following parameter mappings in the "OAuth 387 Parameters CBOR Mappings" registry established in section 8.9. of 388 [I-D.ietf-ace-oauth-authz]. 390 o Name: "req_cnf" 391 o CBOR key: TBD (suggested: 4) 392 o Change Controller: IESG 393 o Reference: Section 3.1 of [this document] 395 o Name: "cnf" 396 o CBOR key: TBD (suggested: 8) 397 o Change Controller: IESG 398 o Reference: Section 3.2 of [this document] 400 o Name: "rs_cnf" 401 o CBOR key: TBD (suggested: 41) 402 o Change Controller: IESG 403 o Reference: Section 3.2 of [this document] 405 10.3. OAuth Token Introspection Response CBOR Mappings Registration 407 This section registers the following parameter mapping in the "OAuth 408 Token Introspection Response CBOR Mappings" registry established in 409 section 8.11. of [I-D.ietf-ace-oauth-authz]. 411 o Name: "cnf" 412 o CBOR key: TBD (suggested: 8) 413 o Change Controller: IESG 414 o Reference: Section 4 of [this document] 416 11. Acknowledgments 418 This document is a product of the ACE working group of the IETF. 419 Special thanks to Brian Campbell for his thorough review of this 420 document. 422 Ludwig Seitz worked on this document as part of the CelticNext 423 projects CyberWI, and CRITISEC with funding from Vinnova. 425 12. References 427 12.1. Normative References 429 [I-D.ietf-ace-oauth-authz] 430 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 431 H. Tschofenig, "Authentication and Authorization for 432 Constrained Environments (ACE) using the OAuth 2.0 433 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-40 434 (work in progress), April 2021. 436 [IANA.OAuthParameters] 437 IANA, "OAuth Parameters", 438 . 441 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 442 Requirement Levels", BCP 14, RFC 2119, 443 DOI 10.17487/RFC2119, March 1997, 444 . 446 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 447 RFC 6749, DOI 10.17487/RFC6749, October 2012, 448 . 450 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 451 Possession Key Semantics for JSON Web Tokens (JWTs)", 452 RFC 7800, DOI 10.17487/RFC7800, April 2016, 453 . 455 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 456 RFC 8152, DOI 10.17487/RFC8152, July 2017, 457 . 459 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 460 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 461 May 2017, . 463 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 464 Interchange Format", STD 90, RFC 8259, 465 DOI 10.17487/RFC8259, December 2017, 466 . 468 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 469 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 470 and Certificate-Bound Access Tokens", RFC 8705, 471 DOI 10.17487/RFC8705, February 2020, 472 . 474 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 475 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 476 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 477 2020, . 479 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 480 Representation (CBOR)", STD 94, RFC 8949, 481 DOI 10.17487/RFC8949, December 2020, 482 . 484 12.2. Informative References 486 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 487 Application Protocol (CoAP)", RFC 7252, 488 DOI 10.17487/RFC7252, June 2014, 489 . 491 Author's Address 492 Ludwig Seitz 493 Combitech 494 Djaeknegatan 31 495 Malmoe 211 35 496 Sweden 498 Email: ludwig.seitz@combitech.com