idnits 2.17.1 draft-ietf-ace-oauth-params-13.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 (April 29, 2020) is 1458 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-33 ** 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 April 29, 2020 5 Expires: October 31, 2020 7 Additional OAuth Parameters for Authorization in Constrained 8 Environments (ACE) 9 draft-ietf-ace-oauth-params-13 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 October 31, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 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 Respresentation (CBOR) [RFC7049], 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 reject 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. The AS MUST 134 verify that the client really is in possession of the 135 corresponding key. Values of this parameter follow the syntax and 136 semantics of the "cnf" claim either from section 3.1 of 137 [I-D.ietf-ace-cwt-proof-of-possession] for CBOR-based interactions 138 or from section 3.1 of [RFC7800] for JSON-based interactions. 140 Figure 1 shows a request for an access token using the "req_cnf" 141 parameter to request a specific public key as proof-of-possession 142 key. The content is displayed in CBOR diagnostic notation, without 143 abbreviations and with line-breaks for better readability. 145 Header: POST (Code=0.02) 146 Uri-Host: "as.example.com" 147 Uri-Path: "token" 148 Content-Format: "application/ace+cbor" 149 Payload: 150 { 151 "req_cnf" : { 152 "COSE_Key" : { 153 "kty" : "EC2", 154 "kid" : h'11', 155 "crv" : "P-256", 156 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 157 4DC189F745228255A219A86D6A09EFF', 158 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 159 A64B6D72CCFED6B6FB6ED28BBFC117E' 160 } 161 } 162 } 164 Figure 1: Example request for an access token bound to an asymmetric 165 key. 167 3.2. AS-to-Client Response 169 This section defines the following additional parameters for an AS 170 response to a request to the token endpoint: 172 cnf 173 REQUIRED if the token type is "pop" and a symmetric key is used. 174 MAY be present for asymmetric proof-of-possession keys. This 175 field contains the proof-of-possession key that the AS selected 176 for the token. Values of this parameter follow the syntax and 177 semantics of the "cnf" claim either from section 3.1 of 178 [I-D.ietf-ace-cwt-proof-of-possession] for CBOR-based interactions 179 of from section 3.1 of [RFC7800] for JSON-based interactions. See 180 Section 5 for additional discussion of the usage of this 181 parameter. 183 rs_cnf 184 OPTIONAL if the token type is "pop" and asymmetric keys are used. 185 MUST NOT be present otherwise. This field contains information 186 about the public key used by the RS to authenticate. If this 187 parameter is absent, either the RS does not use a public key or 188 the AS knows that the RS can authenticate itself to the client 189 without additional information. Values of this parameter follow 190 the syntax and semantics of the "cnf" claim either from section 191 3.1 of [I-D.ietf-ace-cwt-proof-of-possession] for CBOR-based 192 interactions or from section 3.1 of [RFC7800] for JSON-based 193 interactions. See Section 5 for additional discussion of the 194 usage of this parameter. 196 Figure 2 shows an AS response containing a token and a "cnf" 197 parameter with a symmetric proof-of-possession key. 199 Header: Created (Code=2.01) 200 Content-Format: "application/ace+cbor" 201 Payload: 202 { 203 "access_token" : h'4A5015DF686428 ... 204 (remainder of CWT omitted for brevity; 205 CWT contains COSE_Key in the "cnf" claim)', 206 "cnf" : { 207 "COSE_Key" : { 208 "kty" : "Symmetric", 209 "kid" : h'DFD1AA97', 210 "k" : h'849B5786457C1491BE3A76DCEA6C427108' 211 } 212 } 213 } 215 Figure 2: Example AS response with an access token bound to a 216 symmetric key. 218 Figure 3 shows an AS response containing a token bound to a 219 previously requested asymmetric proof-of-possession key (not shown) 220 and a "rs_cnf" parameter containing the public key of the RS. 222 Header: Created (Code=2.01) 223 Content-Format: "application/ace+cbor" 224 Payload: 225 { 226 "access_token" : h'D08343A1010AA1054D2A45DF6FBC5A5A ... 227 (remainder of CWT omitted for brevity)', 228 "rs_cnf" : { 229 "COSE_Key" : { 230 "kty" : "EC2", 231 "kid" : h'12', 232 "crv" : "P-256", 233 "x" : h'BCEE7EAAC162F91E6F330F5771211E220 234 B8B546C96589B0AC4AD0FD24C77E1F1', 235 "y" : h'C647B38C55EFBBC4E62E651720F002D5D 236 75B2E0C02CD1326E662BCA222B90416' 237 } 238 } 239 } 241 Figure 3: Example AS response, including the RS's public key. 243 4. Parameters for the Introspection Endpoint 245 This section defines the use of CBOR instead of JSON for the "cnf" 246 introspection response parameter specified in section 9.4 of 247 [I-D.ietf-oauth-mtls]. 249 If CBOR is used instead of JSON in an interaction with the 250 introspection endpoint, the AS MUST use the parameter mapping 251 specified in Figure 5 and the value must follow the syntax of "cnf" 252 claim values from section 3.1 of 253 [I-D.ietf-ace-cwt-proof-of-possession]. 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 as follows: 285 o "req_cnf" in the access token request C -> AS, OPTIONAL to 286 indicate the client's raw public key, or the key-identifier of a 287 previously established key between C and RS that the client wishes 288 to use for proof-of-possession of the access token. 290 o "cnf" in the token response AS -> C, OPTIONAL if using an 291 asymmetric key or a key that the client requested via a key 292 identifier in the request. REQUIRED if the client didn't specify 293 a "req_cnf" and symmetric keys are used. Used to indicate the 294 symmetric key generated by the AS for proof-of-possession of the 295 access token. 297 o "cnf" in the introspection response AS -> RS, REQUIRED if the 298 access token that was subject to introspection is a proof-of- 299 possession token, absent otherwise. Indicates the proof-of- 300 possession key bound to the access token. 302 o "rs_cnf" in the token response AS -> C, OPTIONAL to indicate the 303 public key of the RS, if it uses one to authenticate itself to the 304 client and the binding between key and RS identity is not 305 established through other means. 307 Note that the COSE_Key structure in a confirmation claim or parameter 308 may contain an "alg" or "key_ops" parameter. If such parameters are 309 present, a client MUST NOT use a key that is incompatible with the 310 profile or proof-of-possession algorithm according to those 311 parameters. An RS MUST reject a proof-of-possession using such a 312 key. 314 If an access token is issued for an audience that includes several 315 RS, the "rs_cnf" parameter MUST NOT be used, since the client cannot 316 determine for which RS the key applies. This document recommends to 317 specify a different endpoint that the client can use to acquire RS 318 authentication keys in such cases. The specification of such an 319 endpoint is out of scope for this document. 321 6. CBOR Mappings 323 If CBOR is used, the new parameters and claims defined in this 324 document MUST be mapped to CBOR types as specified in Figure 5, using 325 the given integer abbreviation for the map key. 327 /----------+----------+-------------------------------------\ 328 | Name | CBOR Key | Value Type | Usage | 329 |----------+----------+-------------------------------------| 330 | req_cnf | TBD (4) | map | token request | 331 | cnf | TBD (8) | map | token response | 332 | cnf | TBD (8) | map | introspection response | 333 | rs_cnf | TBD (41) | map | token response | 334 \----------+----------+------------+------------------------/ 336 Figure 5: CBOR mappings for new parameters and claims. 338 7. Requirements when using asymmetric keys 340 An RS using asymmetric keys to authenticate to the client MUST NOT 341 hold several different asymmetric key pairs, applicable to the same 342 authentication algorithm. For example when using DTLS, the RS MUST 343 NOT hold several asymmetric key pairs applicable to the same cipher 344 suite. The reason for this restriction is that the RS has no way of 345 determining which key to use before the client's identity is 346 established. Therefore authentication attempts by the RS could 347 randomly fail based on which key the RS selects, unless the algorithm 348 negotiation produces a unique choice of key pair for the RS. 350 8. Security Considerations 352 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 353 security considerations from that document apply here as well. 355 9. Privacy Considerations 357 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 358 privacy considerations from that document apply here as well. 360 10. IANA Considerations 362 10.1. OAuth Parameter Registration 364 This section registers the following parameters in the "OAuth 365 Parameters" registry [IANA.OAuthParameters]: 367 o Name: "req_cnf" 368 o Parameter Usage Location: token request 369 o Change Controller: IESG 370 o Reference: Section 5 of [this document] 372 o Name: "rs_cnf" 373 o Parameter Usage Location: token response 374 o Change Controller: IESG 375 o Reference: Section 5 of [this document] 377 o Name: "cnf" 378 o Parameter Usage Location: token response 379 o Change Controller: IESG 380 o Reference: Section 5 of [this document] 382 10.2. OAuth Parameters CBOR Mappings Registration 384 This section registers the following parameter mappings in the "OAuth 385 Parameters CBOR Mappings" registry established in section 8.9. of 386 [I-D.ietf-ace-oauth-authz]. 388 o Name: "req_cnf" 389 o CBOR key: TBD (suggested: 4) 390 o Change Controller: IESG 391 o Reference: Section 3.1 of [this document] 393 o Name: "cnf" 394 o CBOR key: TBD (suggested: 8) 395 o Change Controller: IESG 396 o Reference: Section 3.2 of [this document] 398 o Name: "rs_cnf" 399 o CBOR key: TBD (suggested: 41) 400 o Change Controller: IESG 401 o Reference: Section 3.2 of [this document] 403 10.3. OAuth Token Introspection Response CBOR Mappings Registration 405 This section registers the following parameter mapping in the "OAuth 406 Token Introspection Response CBOR Mappings" registry established in 407 section 8.11. of [I-D.ietf-ace-oauth-authz]. 409 o Name: "cnf" 410 o CBOR key: TBD (suggested: 8) 411 o Change Controller: IESG 412 o Reference: Section 4 of [this document] 414 11. Acknowledgments 416 This document is a product of the ACE working group of the IETF. 417 Special thanks to Brian Campbell for his thorough review of this 418 document. 420 Ludwig Seitz worked on this document as part of the CelticNext 421 projects CyberWI, and CRITISEC with funding from Vinnova. 423 12. References 425 12.1. Normative References 427 [I-D.ietf-ace-cwt-proof-of-possession] 428 Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 429 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 430 Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- 431 possession-11 (work in progress), October 2019. 433 [I-D.ietf-ace-oauth-authz] 434 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 435 H. Tschofenig, "Authentication and Authorization for 436 Constrained Environments (ACE) using the OAuth 2.0 437 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-33 438 (work in progress), February 2020. 440 [I-D.ietf-oauth-mtls] 441 Campbell, B., Bradley, J., Sakimura, N., and T. 442 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 443 and Certificate-Bound Access Tokens", draft-ietf-oauth- 444 mtls-17 (work in progress), August 2019. 446 [IANA.OAuthParameters] 447 IANA, "OAuth Parameters", 448 . 451 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 452 Requirement Levels", BCP 14, RFC 2119, 453 DOI 10.17487/RFC2119, March 1997, 454 . 456 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 457 RFC 6749, DOI 10.17487/RFC6749, October 2012, 458 . 460 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 461 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 462 October 2013, . 464 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 465 Possession Key Semantics for JSON Web Tokens (JWTs)", 466 RFC 7800, DOI 10.17487/RFC7800, April 2016, 467 . 469 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 470 RFC 8152, DOI 10.17487/RFC8152, July 2017, 471 . 473 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 474 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 475 May 2017, . 477 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 478 Interchange Format", STD 90, RFC 8259, 479 DOI 10.17487/RFC8259, December 2017, 480 . 482 12.2. Informative References 484 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 485 Application Protocol (CoAP)", RFC 7252, 486 DOI 10.17487/RFC7252, June 2014, 487 . 489 Author's Address 491 Ludwig Seitz 492 Combitech 493 Djaeknegatan 31 494 Malmoe 211 35 495 Sweden 497 Email: ludwig.seitz@combitech.se