idnits 2.17.1 draft-ietf-ace-oauth-params-16.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: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. 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 (7 September 2021) is 933 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-45 ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 1 error (**), 0 flaws (~~), 3 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 7 September 2021 5 Expires: 11 March 2022 7 Additional OAuth Parameters for Authorization in Constrained 8 Environments (ACE) 9 draft-ietf-ace-oauth-params-16 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 11 March 2022. 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 (https://trustee.ietf.org/ 45 license-info) in effect on the date of publication of this document. 46 Please review these documents carefully, as they describe your rights 47 and restrictions with respect to this document. Code Components 48 extracted from this document must include Simplified BSD License text 49 as described in Section 4.e of the Trust Legal Provisions and are 50 provided without warranty as described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. Parameters for the Token Endpoint . . . . . . . . . . . . . . 3 57 3.1. Client-to-AS Request . . . . . . . . . . . . . . . . . . 3 58 3.2. AS-to-Client Response . . . . . . . . . . . . . . . . . . 4 59 4. Parameters for the Introspection Endpoint . . . . . . . . . . 6 60 5. Confirmation Method Parameters . . . . . . . . . . . . . . . 7 61 6. CBOR Mappings . . . . . . . . . . . . . . . . . . . . . . . . 8 62 7. Requirements when using asymmetric keys . . . . . . . . . . . 8 63 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 64 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 9 65 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 66 10.1. OAuth Parameter Registration . . . . . . . . . . . . . . 9 67 10.2. OAuth Parameters CBOR Mappings Registration . . . . . . 9 68 10.3. OAuth Token Introspection Response CBOR Mappings 69 Registration . . . . . . . . . . . . . . . . . . . . . . 10 70 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 71 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 72 12.1. Normative References . . . . . . . . . . . . . . . . . . 10 73 12.2. Informative References . . . . . . . . . . . . . . . . . 11 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 76 1. Introduction 78 The Authentication and Authorization for Constrained Environments 79 (ACE) specification [I-D.ietf-ace-oauth-authz] requires some new 80 parameters for interactions with the OAuth 2.0 [RFC6749] token and 81 introspection endpoints, as well as some new claims to be used in 82 access tokens. These parameters and claims can also be used in other 83 contexts and have therefore been put into a dedicated document, to 84 facilitate their use in a manner independent of 85 [I-D.ietf-ace-oauth-authz]. 87 Note that although all examples are shown in Concise Binary Object 88 Representation (CBOR) [RFC8949], JSON [RFC8259] MAY be used as an 89 alternative for HTTP-based communications, as specified in 90 [I-D.ietf-ace-oauth-authz]. 92 2. Terminology 94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 96 "OPTIONAL" in this document are to be interpreted as described in BCP 97 14 [RFC2119] [RFC8174] when, and only when, they appear in all 98 capitals, as shown here. 100 Readers are assumed to be familiar with the terminology from 101 [I-D.ietf-ace-oauth-authz], especially the terminology for entities 102 in the architecture such as client (C), resource server (RS) and 103 authorization server (AS). 105 Terminology from [RFC8152] is used in the examples, especially 106 COSE_Key defined in section 7 of [RFC8152]. 108 Note that the term "endpoint" is used here following its OAuth 2.0 109 [RFC6749] definition, which is to denote resources such as token and 110 introspection at the AS and authz-info at the RS. The Constrained 111 Application Protocol (CoAP) [RFC7252] definition, which is "An entity 112 participating in the CoAP protocol" is not used in this 113 specification. 115 3. Parameters for the Token Endpoint 117 This section defines additional parameters for the interactions with 118 the token endpoint in the ACE framework [I-D.ietf-ace-oauth-authz]. 120 3.1. Client-to-AS Request 122 This section defines the "req_cnf" parameter allowing clients to 123 request a specific proof-of-possession key in an access token from a 124 token endpoint in the ACE framework [I-D.ietf-ace-oauth-authz]: 126 req_cnf 127 OPTIONAL. This field contains information about the key the 128 client would like to bind to the access token for proof-of- 129 possession. It is RECOMMENDED that an AS rejects a request 130 containing a symmetric key value in the 'req_cnf' field 131 (kty=Symmetric), since the AS is expected to be able to generate 132 better symmetric keys than a constrained client (Note: this does 133 not apply to key identifiers referencing a symmetric key). The AS 134 MUST verify that the client really is in possession of the 135 corresponding key. Profiles of [I-D.ietf-ace-oauth-authz] using 136 this specification MUST define the proof-of-possession method used 137 by the AS, if they allow clients to use this request parameter. 138 Values of this parameter follow the syntax and semantics of the 139 "cnf" claim either from section 3.1 of [RFC8747] for CBOR-based 140 interactions or from section 3.1 of [RFC7800] for JSON-based 141 interactions. 143 Figure 1 shows a request for an access token using the "req_cnf" 144 parameter to request a specific public key as proof-of-possession 145 key. The content is displayed in CBOR diagnostic notation, without 146 abbreviations and with line-breaks for better readability. 148 Header: POST (Code=0.02) 149 Uri-Host: "as.example.com" 150 Uri-Path: "token" 151 Content-Format: "application/ace+cbor" 152 Payload: 153 { 154 "req_cnf" : { 155 "COSE_Key" : { 156 "kty" : "EC2", 157 "kid" : h'11', 158 "crv" : "P-256", 159 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 160 4DC189F745228255A219A86D6A09EFF', 161 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 162 A64B6D72CCFED6B6FB6ED28BBFC117E' 163 } 164 } 165 } 167 Figure 1: Example request for an access token bound to an 168 asymmetric key. 170 3.2. AS-to-Client Response 172 This section defines the following additional parameters for an AS 173 response to a request to the token endpoint: 175 cnf 176 REQUIRED if the token type is "pop" and a symmetric key is used. 177 MAY be present for asymmetric proof-of-possession keys. This 178 field contains the proof-of-possession key that the AS selected 179 for the token. Values of this parameter follow the syntax and 180 semantics of the "cnf" claim either from section 3.1 of [RFC8747] 181 for CBOR-based interactions or from section 3.1 of [RFC7800] for 182 JSON-based interactions. See Section 5 for additional discussion 183 of the usage of this parameter. 185 rs_cnf 186 OPTIONAL if the token type is "pop" and asymmetric keys are used. 187 MUST NOT be present otherwise. This field contains information 188 about the public key used by the RS to authenticate. If this 189 parameter is absent, either the RS does not use a public key or 190 the AS knows that the RS can authenticate itself to the client 191 without additional information. Values of this parameter follow 192 the syntax and semantics of the "cnf" claim either from section 193 3.1 of [RFC8747] for CBOR-based interactions or from section 3.1 194 of [RFC7800] for JSON-based interactions. See Section 5 for 195 additional discussion of the usage of this parameter. 197 Figure 2 shows an AS response containing a token and a "cnf" 198 parameter with a symmetric proof-of-possession key. 200 Header: Created (Code=2.01) 201 Content-Format: "application/ace+cbor" 202 Payload: 203 { 204 "access_token" : h'4A5015DF686428 ... 205 (remainder of CWT omitted for brevity; 206 CWT contains COSE_Key in the "cnf" claim)', 207 "cnf" : { 208 "COSE_Key" : { 209 "kty" : "Symmetric", 210 "kid" : h'DFD1AA97', 211 "k" : h'849B5786457C1491BE3A76DCEA6C427108' 212 } 213 } 214 } 216 Figure 2: Example AS response with an access token bound to a 217 symmetric key. 219 Figure 3 shows an AS response containing a token bound to a 220 previously requested asymmetric proof-of-possession key (not shown) 221 and a "rs_cnf" parameter containing the public key of the RS. 223 Header: Created (Code=2.01) 224 Content-Format: "application/ace+cbor" 225 Payload: 226 { 227 "access_token" : h'D08343A1010AA1054D2A45DF6FBC5A5A ... 228 (remainder of CWT omitted for brevity)', 229 "rs_cnf" : { 230 "COSE_Key" : { 231 "kty" : "EC2", 232 "kid" : h'12', 233 "crv" : "P-256", 234 "x" : h'BCEE7EAAC162F91E6F330F5771211E220 235 B8B546C96589B0AC4AD0FD24C77E1F1', 236 "y" : h'C647B38C55EFBBC4E62E651720F002D5D 237 75B2E0C02CD1326E662BCA222B90416' 238 } 239 } 240 } 242 Figure 3: Example AS response, including the RS's public key. 244 4. Parameters for the Introspection Endpoint 246 This section defines the use of CBOR instead of JSON for the "cnf" 247 introspection response parameter specified in section 9.4 of 248 [RFC8705]. 250 If CBOR is used instead of JSON in an interaction with the 251 introspection endpoint, the AS MUST use the parameter mapping 252 specified in Figure 5 and the value must follow the syntax of "cnf" 253 claim values from section 3.1 of [RFC8747]. 255 Figure 4 shows an AS response to an introspection request including 256 the "cnf" parameter to indicate the proof-of-possession key bound to 257 the token. 259 Header: Created (Code=2.01) 260 Content-Format: "application/ace+cbor" 261 Payload: 262 { 263 "active" : true, 264 "scope" : "read", 265 "aud" : "tempSensor4711", 266 "cnf" : { 267 "COSE_Key" : { 268 "kty" : "EC2", 269 "kid" : h'11', 270 "crv" : "P-256", 271 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 272 4DC189F745228255A219A86D6A09EFF', 273 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 274 A64B6D72CCFED6B6FB6ED28BBFC117E' 275 } 276 } 277 } 279 Figure 4: Example introspection response. 281 5. Confirmation Method Parameters 283 The confirmation method parameters are used in 284 [I-D.ietf-ace-oauth-authz] as follows: 286 * "req_cnf" in the access token request C -> AS, OPTIONAL to 287 indicate the client's raw public key, or the key-identifier of a 288 previously established key between C and RS that the client wishes 289 to use for proof-of-possession of the access token. 291 * "cnf" in the token response AS -> C, OPTIONAL if using an 292 asymmetric key or a key that the client requested via a key 293 identifier in the request. REQUIRED if the client didn't specify 294 a "req_cnf" and symmetric keys are used. Used to indicate the 295 symmetric key generated by the AS for proof-of-possession of the 296 access token. 298 * "cnf" in the introspection response AS -> RS, REQUIRED if the 299 access token that was subject to introspection is a proof-of- 300 possession token, absent otherwise. Indicates the proof-of- 301 possession key bound to the access token. 303 * "rs_cnf" in the token response AS -> C, OPTIONAL to indicate the 304 public key of the RS, if it uses one to authenticate itself to the 305 client and the binding between key and RS identity is not 306 established through other means. 308 Note that the COSE_Key structure in a confirmation claim or parameter 309 may contain an "alg" or "key_ops" parameter. If such parameters are 310 present, a client MUST NOT use a key that is incompatible with the 311 profile or proof-of-possession algorithm according to those 312 parameters. An RS MUST reject a proof-of-possession using such a key 313 with a response code equivalent to the CoAP code 4.00 (Bad Request). 315 If an access token is issued for an audience that includes several 316 RS, the "rs_cnf" parameter MUST NOT be used, since the client cannot 317 determine for which RS the key applies. This document recommends to 318 specify a different endpoint that the client can use to acquire RS 319 authentication keys in such cases. The specification of such an 320 endpoint is out of scope for this document. 322 6. CBOR Mappings 324 If CBOR is used, the new parameters and claims defined in this 325 document MUST be mapped to CBOR types as specified in Figure 5, using 326 the given integer abbreviation for the map key. 328 /----------+----------+-------------------------------------\ 329 | Name | CBOR Key | Value Type | Usage | 330 |----------+----------+-------------------------------------| 331 | req_cnf | TBD (4) | map | token request | 332 | cnf | TBD (8) | map | token response | 333 | cnf | TBD (8) | map | introspection response | 334 | rs_cnf | TBD (41) | map | token response | 335 \----------+----------+------------+------------------------/ 337 Figure 5: CBOR mappings for new parameters and claims. 339 7. Requirements when using asymmetric keys 341 An RS using asymmetric keys to authenticate to the client MUST NOT 342 hold several different asymmetric key pairs, applicable to the same 343 authentication algorithm. For example when using DTLS, the RS MUST 344 NOT hold several asymmetric key pairs applicable to the same cipher 345 suite. The reason for this restriction is that the RS has no way of 346 determining which key to use before the client's identity is 347 established. Therefore authentication attempts by the RS could 348 randomly fail based on which key the RS selects, unless the algorithm 349 negotiation produces a unique choice of key pair for the RS. 351 8. Security Considerations 353 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 354 security considerations from that document apply here as well. 356 9. Privacy Considerations 358 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 359 privacy considerations from that document apply here as well. 361 10. IANA Considerations 363 10.1. OAuth Parameter Registration 365 This section registers the following parameters in the "OAuth 366 Parameters" registry [IANA.OAuthParameters]: 368 * Name: "req_cnf" 369 * Parameter Usage Location: token request 370 * Change Controller: IETF 371 * Reference: Section 5 of [this document] 373 * Name: "rs_cnf" 374 * Parameter Usage Location: token response 375 * Change Controller: IETF 376 * Reference: Section 5 of [this document] 378 * Name: "cnf" 379 * Parameter Usage Location: token response 380 * Change Controller: IETF 381 * Reference: Section 5 of [this document] 383 10.2. OAuth Parameters CBOR Mappings Registration 385 This section registers the following parameter mappings in the "OAuth 386 Parameters CBOR Mappings" registry established in section 8.9. of 387 [I-D.ietf-ace-oauth-authz]. 389 * Name: "req_cnf" 390 * CBOR key: TBD (suggested: 4) 391 * Value Type: map 392 * Reference: Section 3.1 of [this document] 393 * Original specification: [this document] 395 * Name: "cnf" 396 * CBOR key: TBD (suggested: 8) 397 * Value Type: map 398 * Reference: Section 3.2 of [this document] 399 * Original specification: [this document] 401 * Name: "rs_cnf" 402 * CBOR key: TBD (suggested: 41) 403 * Value Type: map 404 * Reference: Section 3.2 of [this document] 405 * Original specification: [this document] 407 10.3. OAuth Token Introspection Response CBOR Mappings Registration 409 This section registers the following parameter mapping in the "OAuth 410 Token Introspection Response CBOR Mappings" registry established in 411 section 8.11. of [I-D.ietf-ace-oauth-authz]. 413 * Name: "cnf" 414 * CBOR key: TBD (suggested: 8) 415 * Value Type: map 416 * Reference: Section 4 of [this document] 417 * Original specification: [RFC8705] 419 11. Acknowledgments 421 This document is a product of the ACE working group of the IETF. 422 Special thanks to Brian Campbell for his thorough review of this 423 document. 425 Ludwig Seitz worked on this document as part of the CelticNext 426 projects CyberWI, and CRITISEC with funding from Vinnova. 428 12. References 430 12.1. Normative References 432 [I-D.ietf-ace-oauth-authz] 433 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 434 H. Tschofenig, "Authentication and Authorization for 435 Constrained Environments (ACE) using the OAuth 2.0 436 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 437 draft-ietf-ace-oauth-authz-45, 29 August 2021, 438 . 441 [IANA.OAuthParameters] 442 IANA, "OAuth Parameters", 443 . 446 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 447 Requirement Levels", BCP 14, RFC 2119, 448 DOI 10.17487/RFC2119, March 1997, 449 . 451 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 452 RFC 6749, DOI 10.17487/RFC6749, October 2012, 453 . 455 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 456 Possession Key Semantics for JSON Web Tokens (JWTs)", 457 RFC 7800, DOI 10.17487/RFC7800, April 2016, 458 . 460 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 461 RFC 8152, DOI 10.17487/RFC8152, July 2017, 462 . 464 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 465 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 466 May 2017, . 468 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 469 Interchange Format", STD 90, RFC 8259, 470 DOI 10.17487/RFC8259, December 2017, 471 . 473 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 474 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 475 and Certificate-Bound Access Tokens", RFC 8705, 476 DOI 10.17487/RFC8705, February 2020, 477 . 479 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 480 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 481 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 482 2020, . 484 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 485 Representation (CBOR)", STD 94, RFC 8949, 486 DOI 10.17487/RFC8949, December 2020, 487 . 489 12.2. Informative References 491 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 492 Application Protocol (CoAP)", RFC 7252, 493 DOI 10.17487/RFC7252, June 2014, 494 . 496 Author's Address 497 Ludwig Seitz 498 Combitech 499 Djäknegatan 31 500 SE-211 35 Malmö 501 Sweden 503 Email: ludwig.seitz@combitech.com