idnits 2.17.1 draft-ietf-ace-oauth-params-12.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 (February 1, 2020) is 1546 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-31 ** 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 February 1, 2020 5 Expires: August 4, 2020 7 Additional OAuth Parameters for Authorization in Constrained 8 Environments (ACE) 9 draft-ietf-ace-oauth-params-12 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 August 4, 2020. 38 Copyright Notice 40 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . . . . . . . . 2 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 CBOR [RFC7049], JSON 89 [RFC8259] MAY be used as an alternative for HTTP-based 90 communications, as specified in [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 CoAP [RFC7252] 111 definition, which is "An entity participating in the CoAP protocol" 112 is not used in this specification. 114 3. Parameters for the Token Endpoint 116 This section defines additional parameters for the interactions with 117 the token endpoint in the ACE framework [I-D.ietf-ace-oauth-authz]. 119 3.1. Client-to-AS Request 121 This section defines the "req_cnf" parameter allowing clients to 122 request a specific proof-of-possession key in an access token from a 123 token endpoint in the ACE framework [I-D.ietf-ace-oauth-authz]: 125 req_cnf 126 OPTIONAL. This field contains information about the key the 127 client would like to bind to the access token for proof-of- 128 possession. It is RECOMMENDED that an AS reject a request 129 containing a symmetric key value in the 'req_cnf' field 130 (kty=Symmetric), since the AS is expected to be able to generate 131 better symmetric keys than a constrained client. The AS MUST 132 verify that the client really is in possession of the 133 corresponding key. Values of this parameter follow the syntax and 134 semantics of the "cnf" claim either from section 3.1 of 135 [I-D.ietf-ace-cwt-proof-of-possession] for CBOR-based interactions 136 or from section 3.1 of [RFC7800] for JSON-based interactions. 138 Figure 1 shows a request for an access token using the "req_cnf" 139 parameter to request a specific public key as proof-of-possession 140 key. The content is displayed in CBOR diagnostic notation, without 141 abbreviations and with line-breaks for better readability. 143 Header: POST (Code=0.02) 144 Uri-Host: "as.example.com" 145 Uri-Path: "token" 146 Content-Format: "application/ace+cbor" 147 Payload: 148 { 149 "req_cnf" : { 150 "COSE_Key" : { 151 "kty" : "EC2", 152 "kid" : h'11', 153 "crv" : "P-256", 154 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 155 4DC189F745228255A219A86D6A09EFF', 156 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 157 A64B6D72CCFED6B6FB6ED28BBFC117E' 158 } 159 } 160 } 162 Figure 1: Example request for an access token bound to an asymmetric 163 key. 165 3.2. AS-to-Client Response 167 This section defines the following additional parameters for an AS 168 response to a request to the token endpoint: 170 cnf 171 REQUIRED if the token type is "pop" and a symmetric key is used. 172 MAY be present for asymmetric proof-of-possession keys. This 173 field contains the proof-of-possession key that the AS selected 174 for the token. Values of this parameter follow the syntax and 175 semantics of the "cnf" claim either from section 3.1 of 176 [I-D.ietf-ace-cwt-proof-of-possession] for CBOR-based interactions 177 of from section 3.1 of [RFC7800] for JSON-based interactions. See 178 Section 5 for additional discussion of the usage of this 179 parameter. 181 rs_cnf 182 OPTIONAL if the token type is "pop" and asymmetric keys are used. 183 MUST NOT be present otherwise. This field contains information 184 about the public key used by the RS to authenticate. If this 185 parameter is absent, either the RS does not use a public key or 186 the AS knows that the RS can authenticate itself to the client 187 without additional information. Values of this parameter follow 188 the syntax and semantics of the "cnf" claim either from section 189 3.1 of [I-D.ietf-ace-cwt-proof-of-possession] for CBOR-based 190 interactions or from section 3.1 of [RFC7800] for JSON-based 191 interactions. See Section 5 for additional discussion of the 192 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 "rs_cnf" : { 227 "COSE_Key" : { 228 "kty" : "EC2", 229 "kid" : h'12', 230 "crv" : "P-256", 231 "x" : h'BCEE7EAAC162F91E6F330F5771211E220 232 B8B546C96589B0AC4AD0FD24C77E1F1', 233 "y" : h'C647B38C55EFBBC4E62E651720F002D5D 234 75B2E0C02CD1326E662BCA222B90416' 235 } 236 } 237 } 239 Figure 3: Example AS response, including the RS's public key. 241 4. Parameters for the Introspection Endpoint 243 This section defines the use of CBOR instead of JSON for the "cnf" 244 introspection response parameter specified in section 9.4 of 245 [I-D.ietf-oauth-mtls]. 247 If CBOR is used instead of JSON in an interaction with the 248 introspection endpoint, the AS MUST use the parameter mapping 249 specified in Figure 5 and the value must follow the syntax of "cnf" 250 claim values from section 3.1 of 251 [I-D.ietf-ace-cwt-proof-of-possession]. 253 Figure 4 shows an AS response to an introspection request including 254 the "cnf" parameter to indicate the proof-of-possession key bound to 255 the token. 257 Header: Created Code=2.01) 258 Content-Format: "application/ace+cbor" 259 Payload: 260 { 261 "active" : true, 262 "scope" : "read", 263 "aud" : "tempSensor4711", 264 "cnf" : { 265 "COSE_Key" : { 266 "kty" : "EC2", 267 "kid" : h'11', 268 "crv" : "P-256", 269 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 270 4DC189F745228255A219A86D6A09EFF', 271 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 272 A64B6D72CCFED6B6FB6ED28BBFC117E' 273 } 274 } 275 } 277 Figure 4: Example introspection response. 279 5. Confirmation Method Parameters 281 The confirmation method parameters are used as follows: 283 o "req_cnf" in the access token request C -> AS, OPTIONAL to 284 indicate the client's raw public key, or the key-identifier of a 285 previously established key between C and RS that the client wishes 286 to use for proof-of-possession of the access token. 288 o "cnf" in the token response AS -> C, OPTIONAL if using an 289 asymmetric key or a key that the client requested via a key 290 identifier in the request. REQUIRED if the client didn't specify 291 a "req_cnf" and symmetric keys are used. Used to indicate the 292 symmetric key generated by the AS for proof-of-possession of the 293 access token. 295 o "cnf" in the introspection response AS -> RS, REQUIRED if the 296 access token that was subject to introspection is a proof-of- 297 possession token, absent otherwise. Indicates the proof-of- 298 possession key bound to the access token. 300 o "rs_cnf" in the token response AS -> C, OPTIONAL to indicate the 301 public key of the RS, if it uses one to authenticate itself to the 302 client and the binding between key and RS identity is not 303 established through other means. 305 Note that the COSE_Key structure in a confirmation claim or parameter 306 may contain an "alg" or "key_ops" parameter. If such parameters are 307 present, a client MUST NOT use a key that is incompatible with the 308 profile or proof-of-possession algorithm according to those 309 parameters. An RS MUST reject a proof-of-possession using such a 310 key. 312 If an access token is issued for an audience that includes several 313 RS, the "rs_cnf" parameter MUST NOT be used, since the client cannot 314 determine for which RS the key applies. This document recommends to 315 specify a different endpoint that the client can use to acquire RS 316 authentication keys in such cases. The specification of such an 317 endpoint is out of scope for this document. 319 6. CBOR Mappings 321 If CBOR is used, the new parameters and claims defined in this 322 document MUST be mapped to CBOR types as specified in Figure 5, using 323 the given integer abbreviation for the map key. 325 /----------+----------+-------------------------------------\ 326 | Name | CBOR Key | Value Type | Usage | 327 |----------+----------+-------------------------------------| 328 | req_cnf | TBD (4) | map | token request | 329 | cnf | TBD (8) | map | token response | 330 | cnf | TBD (8) | map | introspection response | 331 | rs_cnf | TBD (41) | map | token response | 332 \----------+----------+------------+------------------------/ 334 Figure 5: CBOR mappings for new parameters and claims. 336 7. Requirements when using asymmetric keys 338 An RS using asymmetric keys to authenticate to the client MUST NOT 339 hold several different asymmetric key pairs, applicable to the same 340 authentication algorithm. For example when using DTLS, the RS MUST 341 NOT hold several asymmetric key pairs applicable to the same cipher 342 suite. The reason for this restriction is that the RS has no way of 343 determining which key to use before the client's identity is 344 established. Therefore authentication attempts by the RS could 345 randomly fail based on which key the RS selects, unless the algorithm 346 negotiation produces a unique choice of key pair for the RS. 348 8. Security Considerations 350 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 351 security considerations from that document apply here as well. 353 9. Privacy Considerations 355 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 356 privacy considerations from that document apply here as well. 358 10. IANA Considerations 360 10.1. OAuth Parameter Registration 362 This section registers the following parameters in the "OAuth 363 Parameters" registry [IANA.OAuthParameters]: 365 o Name: "req_cnf" 366 o Parameter Usage Location: token request 367 o Change Controller: IESG 368 o Reference: Section 5 of [this document] 370 o Name: "rs_cnf" 371 o Parameter Usage Location: token response 372 o Change Controller: IESG 373 o Reference: Section 5 of [this document] 375 o Name: "cnf" 376 o Parameter Usage Location: token response 377 o Change Controller: IESG 378 o Reference: Section 5 of [this document] 380 10.2. OAuth Parameters CBOR Mappings Registration 382 This section registers the following parameter mappings in the "OAuth 383 Parameters CBOR Mappings" registry established in section 8.9. of 384 [I-D.ietf-ace-oauth-authz]. 386 o Name: "req_cnf" 387 o CBOR key: TBD (suggested: 4) 388 o Change Controller: IESG 389 o Reference: Section 3.1 of [this document] 391 o Name: "cnf" 392 o CBOR key: TBD (suggested: 8) 393 o Change Controller: IESG 394 o Reference: Section 3.2 of [this document] 396 o Name: "rs_cnf" 397 o CBOR key: TBD (suggested: 41) 398 o Change Controller: IESG 399 o Reference: Section 3.2 of [this document] 401 10.3. OAuth Token Introspection Response CBOR Mappings Registration 403 This section registers the following parameter mapping in the "OAuth 404 Token Introspection Response CBOR Mappings" registry established in 405 section 8.11. of [I-D.ietf-ace-oauth-authz]. 407 o Name: "cnf" 408 o CBOR key: TBD (suggested: 8) 409 o Change Controller: IESG 410 o Reference: Section 4 of [this document] 412 11. Acknowledgments 414 This document is a product of the ACE working group of the IETF. 415 Special thanks to Brian Campbell for his thorough review of this 416 document. 418 Ludwig Seitz worked on this document as part of the CelticNext 419 projects CyberWI, and CRITISEC with funding from Vinnova. 421 12. References 423 12.1. Normative References 425 [I-D.ietf-ace-cwt-proof-of-possession] 426 Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 427 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 428 Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- 429 possession-11 (work in progress), October 2019. 431 [I-D.ietf-ace-oauth-authz] 432 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 433 H. Tschofenig, "Authentication and Authorization for 434 Constrained Environments (ACE) using the OAuth 2.0 435 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-31 436 (work in progress), January 2020. 438 [I-D.ietf-oauth-mtls] 439 Campbell, B., Bradley, J., Sakimura, N., and T. 440 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 441 and Certificate-Bound Access Tokens", draft-ietf-oauth- 442 mtls-17 (work in progress), August 2019. 444 [IANA.OAuthParameters] 445 IANA, "OAuth Parameters", 446 . 449 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 450 Requirement Levels", BCP 14, RFC 2119, 451 DOI 10.17487/RFC2119, March 1997, 452 . 454 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 455 RFC 6749, DOI 10.17487/RFC6749, October 2012, 456 . 458 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 459 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 460 October 2013, . 462 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 463 Possession Key Semantics for JSON Web Tokens (JWTs)", 464 RFC 7800, DOI 10.17487/RFC7800, April 2016, 465 . 467 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 468 RFC 8152, DOI 10.17487/RFC8152, July 2017, 469 . 471 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 472 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 473 May 2017, . 475 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 476 Interchange Format", STD 90, RFC 8259, 477 DOI 10.17487/RFC8259, December 2017, 478 . 480 12.2. Informative References 482 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 483 Application Protocol (CoAP)", RFC 7252, 484 DOI 10.17487/RFC7252, June 2014, 485 . 487 Author's Address 489 Ludwig Seitz 490 Combitech 491 Djaeknegatan 31 492 Malmoe 211 35 493 Sweden 495 Email: ludwig.seitz@combitech.se