idnits 2.17.1 draft-ietf-ace-oauth-params-08.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 21, 2019) is 1587 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 Summary: 0 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 21, 2019 5 Expires: June 23, 2020 7 Additional OAuth Parameters for Authorization in Constrained 8 Environments (ACE) 9 draft-ietf-ace-oauth-params-08 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 whishes to use, the proof-of-possession key that the AS has selected, 18 and the key the RS should use to authenticate to the client. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on June 23, 2020. 37 Copyright Notice 39 Copyright (c) 2019 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 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 3.3. The Resource Server Confirmation Claim . . . . . . . . . 6 60 4. Parameters for the Introspection Endpoint . . . . . . . . . . 6 61 4.1. AS-to-RS Response . . . . . . . . . . . . . . . . . . . . 6 62 5. Confirmation Method Parameters . . . . . . . . . . . . . . . 7 63 6. CBOR Mappings . . . . . . . . . . . . . . . . . . . . . . . . 8 64 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 65 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 9 66 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 9.1. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 9 68 9.2. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 9 69 9.3. OAuth Parameter Registration . . . . . . . . . . . . . . 9 70 9.4. OAuth Introspection Response Parameter Registration . . . 10 71 9.5. OAuth Parameters CBOR Mappings Registraton . . . . . . . 10 72 9.6. OAuth Token Introspection Response CBOR Mappings 73 Registration . . . . . . . . . . . . . . . . . . . . . . 11 74 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 75 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 76 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 77 11.2. Informative References . . . . . . . . . . . . . . . . . 12 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 80 1. Introduction 82 The Authentication and Authorization for Constrained Environments 83 (ACE) specification [I-D.ietf-ace-oauth-authz] requires some new 84 parameters for interactions with the OAuth 2.0 [RFC6749] token and 85 introspection endpoints, as well as some new claims to be used in 86 access tokens. These parameters and claims can also be used in other 87 contexts and have therefore been put into a dedicated document, to 88 facilitate their use in a manner independent of 89 [I-D.ietf-ace-oauth-authz]. 91 2. Terminology 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 95 "OPTIONAL" in this document are to be interpreted as described in BCP 96 14 [RFC2119] [RFC8174] when, and only when, they appear in all 97 capitals, as shown here. 99 Readers are assumed to be familiar with the terminology from 100 [I-D.ietf-ace-oauth-authz]. 102 Note that the term "endpoint" is used here following its OAuth 2.0 103 [RFC6749] definition, which is to denote resources such as token and 104 introspection at the AS and authz-info at the RS. The CoAP [RFC7252] 105 definition, which is "An entity participating in the CoAP protocol" 106 is not used in this specification. 108 3. Parameters for the Token Endpoint 110 3.1. Client-to-AS Request 112 This document defines the following additional parameters for 113 requesting an access token from a token endpoint in the ACE framework 114 [I-D.ietf-ace-oauth-authz]: 116 req_cnf 117 OPTIONAL. This field contains information about the key the 118 client would like to bind to the access token for proof-of- 119 possession. It is RECOMMENDED that an AS reject a request 120 containing a symmetric key value in the 'req_cnf' field, since the 121 AS is expected to be able to generate better symmetric keys than a 122 constrained client. The AS MUST verify that the client really is 123 in possession of the corresponding key. Values of this parameter 124 follow the syntax of the "cnf" claim from section 3.1 of 125 [I-D.ietf-ace-cwt-proof-of-possession]. 127 Figure 1 shows a request for an access token using the "req_cnf" 128 parameter to request a specific public key as proof-of-possession 129 key. The content is displayed in CBOR diagnostic notation, without 130 abbreviations and with linebreaks for better readability. 132 Header: POST (Code=0.02) 133 Uri-Host: "as.example.com" 134 Uri-Path: "token" 135 Content-Format: "application/ace+cbor" 136 Payload: 137 { 138 "req_cnf" : { 139 "COSE_Key" : { 140 "kty" : "EC", 141 "kid" : h'11', 142 "crv" : "P-256", 143 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 144 4DC189F745228255A219A86D6A09EFF', 145 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 146 A64B6D72CCFED6B6FB6ED28BBFC117E' 147 } 148 } 149 } 151 Figure 1: Example request for an access token bound to an asymmetric 152 key. 154 3.2. AS-to-Client Response 156 This document defines the following additional parameters for an AS 157 response to a request to the token endpoint: 159 cnf 160 REQUIRED if the token type is "pop" and a symmetric key is used. 161 MAY be present for asymmetric proof-of-possession keys. This 162 field contains the proof-of-possession key that the AS selected 163 for the token. Values of this parameter follow the syntax of the 164 "cnf" claim from section 3.1 of 165 [I-D.ietf-ace-cwt-proof-of-possession]. See Section 5 for 166 additional discussion of the usage of this parameter. 168 rs_cnf 169 OPTIONAL if the token type is "pop" and asymmetric keys are used. 170 MUST NOT be present otherwise. This field contains information 171 about the public key used by the RS to authenticate. If this 172 parameter is absent, either the RS does not use a public key or 173 the AS knows that the RS can authenticate itself to the client 174 without additional information. Values of this parameter follow 175 the syntax of the "cnf" claim from section 3.1 of 176 [I-D.ietf-ace-cwt-proof-of-possession]. See Section 5 for 177 additional discussion of the usage of this parameter. 179 Figure 2 shows an AS response containing a token and a "cnf" 180 parameter with a symmetric proof-of-possession key. 182 Header: Created (Code=2.01) 183 Content-Format: "application/ace+cbor" 184 Payload: 185 { 186 "access_token" : h'4A5015DF686428 ... 187 (remainder of CWT omitted for brevity; 188 CWT contains COSE_Key in the "cnf" claim)', 189 "cnf" : { 190 "COSE_Key" : { 191 "kty" : "Symmetric", 192 "kid" : h'DFD1AA97', 193 "k" : h'849B5786457C1491BE3A76DCEA6C427108' 194 } 195 } 196 } 198 Figure 2: Example AS response with an access token bound to a 199 symmetric key. 201 Figure 3 shows an AS response containing a token bound to a 202 previously requested asymmetric proof-of-possession key (not shown) 203 and a "rs_cnf" parameter containing the public key of the RS. 205 Header: Created (Code=2.01) 206 Content-Format: "application/ace+cbor" 207 Payload: 208 { 209 "access_token" : h'D08343A1010AA1054D2A45DF6FBC5A5A ... 210 (remainder of CWT omitted for brevity; 211 CWT contains COSE_Key in the "cnf" claim)', 212 "rs_cnf" : { 213 "COSE_Key" : { 214 "kty" : "EC", 215 "kid" : h'12', 216 "crv" : "P-256", 217 "x" : h'BCEE7EAAC162F91E6F330F5771211E220 218 B8B546C96589B0AC4AD0FD24C77E1F1', 219 "y" : h'C647B38C55EFBBC4E62E651720F002D5D 220 75B2E0C02CD1326E662BCA222B90416' 221 } 222 } 223 } 225 Figure 3: Example AS response, including the RS's public key. 227 3.3. The Resource Server Confirmation Claim 229 If the AS needs to convey a hint to the RS about which key it should 230 use to authenticate towards the client, this specification defines 231 the "rs_cnf" claim, which MAY be used in the access token, with the 232 same syntax and semantics as defined in for the "rs_cnf" parameter. 234 4. Parameters for the Introspection Endpoint 236 4.1. AS-to-RS Response 238 This document defines the following additional parameters for an AS 239 response to a request to the introspection endpoint: 241 cnf 242 OPTIONAL. This field contains information about the proof-of- 243 possession key that binds the client to the access token. Values 244 of this parameter follow the syntax of the "cnf" claim from 245 section 3.1 of [I-D.ietf-ace-cwt-proof-of-possession]. See 246 Section 5 for additional discussion of the usage of this 247 parameter. 249 rs_cnf 250 OPTIONAL. If the RS uses asymmetric keys to authenticate towards 251 the client (e.g. with a DTLS-RPK handshake) and it has several 252 such keys (e.g. for different elliptic curves), the AS can give 253 the RS a hint using this parameter, as to which key it should use. 254 Values of this parameter follow the syntax of the "cnf" claim from 255 section 3.1 of [I-D.ietf-ace-cwt-proof-of-possession]. See 256 Section 5 for additional discussion of the usage of this 257 parameter. 259 Figure 4 shows an AS response to an introspection request including 260 the "cnf" parameter to indicate the proof-of-possession key bound to 261 the token and the "rs_cnf" parameter to indicate the key the RS is 262 supposed to use to authenticate to the client. 264 Header: Created Code=2.01) 265 Content-Format: "application/ace+cbor" 266 Payload: 267 { 268 "active" : true, 269 "scope" : "read", 270 "aud" : "tempSensor4711", 271 "cnf" : { 272 "COSE_Key" : { 273 "kty" : "EC", 274 "kid" : h'11', 275 "crv" : "P-256", 276 "x" : h'BAC5B11CAD8F99F9C72B05CF4B9E26D24 277 4DC189F745228255A219A86D6A09EFF', 278 "y" : h'20138BF82DC1B6D562BE0FA54AB7804A3 279 A64B6D72CCFED6B6FB6ED28BBFC117E' 280 } 281 }, 282 "rs_cnf" : { 283 "COSE_Key" : { 284 "kty" : "EC", 285 "kid" : h'12', 286 "crv" : "P-256", 287 "x" : h'BCEE7EAAC162F91E6F330F5771211E220 288 B8B546C96589B0AC4AD0FD24C77E1F1', 289 "y" : h'C647B38C55EFBBC4E62E651720F002D5D 290 75B2E0C02CD1326E662BCA222B90416' 291 } 292 } 293 } 295 Figure 4: Example introspection response. 297 5. Confirmation Method Parameters 299 The confirmation method parameters are used as follows: 301 o "req_cnf" in the access token request C -> AS, OPTIONAL to 302 indicate the client's raw public key, or the key-identifier of a 303 previously established key between C and RS that the client wishes 304 to use for proof-of-possession of the access token. 306 o "cnf" in the token response AS -> C, OPTIONAL if using an 307 asymmetric key or a key that the client requested via a key 308 identifier in the request. REQUIRED if the client didn't specify 309 a "req_cnf" and symmetric keys are used. Used to indicate the 310 symmetric key generated by the AS for proof-of-possession of the 311 access token. 313 o "cnf" in the introspection response AS -> RS, REQUIRED if the 314 access token that was subject to introspection is a proof-of- 315 possession token, absent otherwise. Indicates the proof-of- 316 possession key bound to the access token. 318 o "rs_cnf" in the token response AS -> C, OPTIONAL to indicate the 319 public key of the RS, if it uses one to authenticate itself to the 320 client and the binding between key and RS identity is not 321 established through other means. 323 o "rs_cnf" in the introspection response AS -> RS, OPTIONAL, 324 contains the public key that the RS should use for authenticating 325 itself to the client (e.g. if the RS has several different public 326 keys, and there may be ambiguity as to which key to use). 328 Note that the COSE_Key structure in a confirmation claim or parameter 329 may contain an "alg" or "key_ops" parameter. If such parameters are 330 present, a client MUST NOT use a key that is incompatible with the 331 profile or proof-of-possession algorithm according to those 332 parameters. An RS MUST reject a proof-of-possession using such a 333 key. 335 If an access token is issued for an audience that includes several 336 RS, the "rs_cnf" parameter MUST NOT be used, since the client cannot 337 determine for which RS the key applies. This document recommends to 338 specify a different endpoint that the client can use to acquire RS 339 authentication keys in such cases. The specification of such an 340 endpoint is out of scope for this document. 342 6. CBOR Mappings 344 If CBOR is used, the new parameters and claims defined in this 345 document MUST be mapped to CBOR types as specified in Figure 5, using 346 the given integer abbreviation for the map key. 348 /----------+----------+-------------------------------------\ 349 | Name | CBOR Key | Value Type | Usage | 350 |----------+----------+-------------------------------------| 351 | req_cnf | TBD (4) | map | token request | 352 | cnf | TBD (8) | map | token response | 353 | cnf | TBD (8) | map | introspection response | 354 | rs_cnf | TBD (41) | map | token response | 355 | rs_cnf | TBD (41) | map | introspection response | 356 | rs_cnf | TBD (41) | map | CWT claim | 357 \----------+----------+------------+------------------------/ 359 Figure 5: CBOR mappings for new parameters and claims. 361 7. Security Considerations 363 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 364 security considerations from that document apply here as well. 366 8. Privacy Considerations 368 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 369 privacy considerations from that document apply here as well. 371 9. IANA Considerations 373 9.1. JSON Web Token Claims 375 This specification registers the following new claim in the JSON Web 376 Token (JWT) registry of JSON Web Token Claims 377 [IANA.JsonWebTokenClaims]: 379 o Claim Name: "rs_cnf" 380 o Claim Description: public key used by RS to authenticate itself to 381 the client. 382 o Change Controller: IESG 383 o Reference: Section 3.3 of [this document] 385 9.2. CBOR Web Token Claims 387 This specification registers the following new claim in the "CBOR Web 388 Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. 390 o Claim Name: "rs_cnf" 391 o Claim Description: public key used by RS to authenticate itself to 392 the client. 393 o JWT Claim Name: rs_cnf 394 o Claim Key: TBD (suggested: 41) 395 o Claim Value Type(s): map 396 o Change Controller: IESG 397 o Specification Document(s): Section 3.3 of [this document] 399 9.3. OAuth Parameter Registration 401 This section registers the following parameters in the "OAuth 402 Parameters" registry [IANA.OAuthParameters]: 404 o Name: "req_cnf" 405 o Parameter Usage Location: token request 406 o Change Controller: IESG 407 o Reference: Section 5 of [this document] 408 o Name: "rs_cnf" 409 o Parameter Usage Location: token response 410 o Change Controller: IESG 411 o Reference: Section 5 of [this document] 413 o Name: "cnf" 414 o Parameter Usage Location: token response 415 o Change Controller: IESG 416 o Reference: Section 5 of [this document] 418 9.4. OAuth Introspection Response Parameter Registration 420 This section registers the following parameters in the OAuth Token 421 Introspection Response registry [IANA.TokenIntrospectionResponse]. 423 o Name: "cnf" 424 o Description: Key to prove the right to use a PoP token. 425 o Change Controller: IESG 426 o Reference: Section 4.1 of [this document] 428 o Name: "rs_cnf" 429 o Description: public key used by RS to authenticate itself to the 430 client. 431 o Change Controller: IESG 432 o Reference: Section 4.1 of [this document] 434 9.5. OAuth Parameters CBOR Mappings Registraton 436 This section registers the following parameter mappings in the "OAuth 437 Parameters CBOR Mappings" registry established in section 8.9. of 438 [I-D.ietf-ace-oauth-authz]. 440 o Name: "req_cnf" 441 o CBOR key: TBD (suggested: 4) 442 o Change Controller: IESG 443 o Reference: Section 3.1 of [this document] 445 o Name: "cnf" 446 o CBOR key: TBD (suggested: 8) 447 o Change Controller: IESG 448 o Reference: Section 3.2 of [this document] 450 o Name: "rs_cnf" 451 o CBOR key: TBD (suggested: 41) 452 o Change Controller: IESG 453 o Reference: Section 3.2 of [this document] 455 9.6. OAuth Token Introspection Response CBOR Mappings Registration 457 This section registers the following parameter mappings in the "OAuth 458 Token Introspection Response CBOR Mappings" registry established in 459 section 8.11. of [I-D.ietf-ace-oauth-authz]. 461 o Name: "cnf" 462 o CBOR key: TBD (suggested: 8) 463 o Change Controller: IESG 464 o Reference: Section 4.1 of [this document] 466 o Name: "rs_cnf" 467 o CBOR key: TBD (suggested: 41) 468 o Change Controller: IESG 469 o Reference: Section 4.1 of [this document] 471 10. Acknowledgments 473 This document is a product of the ACE working group of the IETF. 475 Ludwig Seitz worked on this document as part of the CelticNext 476 projects CyberWI, and CRITISEC with funding from Vinnova. 478 11. References 480 11.1. Normative References 482 [I-D.ietf-ace-cwt-proof-of-possession] 483 Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 484 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 485 Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- 486 possession-11 (work in progress), October 2019. 488 [I-D.ietf-ace-oauth-authz] 489 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 490 H. Tschofenig, "Authentication and Authorization for 491 Constrained Environments (ACE) using the OAuth 2.0 492 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-29 493 (work in progress), December 2019. 495 [IANA.CborWebTokenClaims] 496 IANA, "CBOR Web Token (CWT) Claims", 497 . 500 [IANA.JsonWebTokenClaims] 501 IANA, "JSON Web Token Claims", 502 . 504 [IANA.OAuthParameters] 505 IANA, "OAuth Parameters", 506 . 509 [IANA.TokenIntrospectionResponse] 510 IANA, "OAuth Token Introspection Response", 511 . 514 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 515 Requirement Levels", BCP 14, RFC 2119, 516 DOI 10.17487/RFC2119, March 1997, 517 . 519 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 520 RFC 6749, DOI 10.17487/RFC6749, October 2012, 521 . 523 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 524 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 525 May 2017, . 527 11.2. Informative References 529 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 530 Application Protocol (CoAP)", RFC 7252, 531 DOI 10.17487/RFC7252, June 2014, 532 . 534 Author's Address 536 Ludwig Seitz 537 Combitech 538 Djaeknegatan 31 539 Malmoe 211 35 540 Sweden 542 Email: ludwig.seitz@combitech.se