idnits 2.17.1 draft-ietf-ace-oauth-params-07.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 17, 2019) is 1585 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-27 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 17, 2019 5 Expires: June 19, 2020 7 Additional OAuth Parameters for Authorization in Constrained 8 Environments (ACE) 9 draft-ietf-ace-oauth-params-07 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 19, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 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 3.3. The Resource Server Confirmation Claim . . . . . . . . . 5 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 Appendix A. Overlap with OAuth work . . . . . . . . . . . . . . 12 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 81 1. Introduction 83 The Authentication and Authorization for Constrained Environments 84 (ACE) specification [I-D.ietf-ace-oauth-authz] requires some new 85 parameters for interactions with the OAuth 2.0 [RFC6749] token and 86 introspection endpoints, as well as some new claims to be used in 87 access tokens. These parameters and claims can also be used in other 88 contexts, and may need to be updated to align them with ongoing OAuth 89 work. Therefore, these parameters and claims have been put into a 90 dedicated document, to facilitate their use and any potential updates 91 in a manner independent of [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]. 104 Note that the term "endpoint" is used here following its OAuth 2.0 105 [RFC6749] definition, which is to denote resources such as token and 106 introspection at the AS and authz-info at the RS. The CoAP [RFC7252] 107 definition, which is "An entity participating in the CoAP protocol" 108 is not used in this specification. 110 3. Parameters for the Token Endpoint 112 3.1. Client-to-AS Request 114 This document defines the following additional parameters for 115 requesting an access token from a token endpoint in the ACE framework 116 [I-D.ietf-ace-oauth-authz]: 118 req_cnf 119 OPTIONAL. This field contains information about the key the 120 client would like to bind to the access token for proof-of- 121 possession. It is RECOMMENDED that an AS reject a request 122 containing a symmetric key value in the 'req_cnf' field, since the 123 AS is expected to be able to generate better symmetric keys than a 124 constrained client. The AS MUST verify that the client really is 125 in possession of the corresponding key. Values of this parameter 126 follow the syntax of the "cnf" claim from section 3.1 of 127 [I-D.ietf-ace-cwt-proof-of-possession]. 129 Figure 1 shows a request for an access token using the "req_cnf" 130 parameter to request a specific public key as proof-of-possession 131 key. The content is displayed in CBOR diagnostic notation, without 132 abbreviations for better readability. 134 Header: POST (Code=0.02) 135 Uri-Host: "as.example.com" 136 Uri-Path: "token" 137 Content-Format: "application/ace+cbor" 138 Payload: 139 { 140 "req_cnf" : { 141 "COSE_Key" : { 142 "kty" : "EC", 143 "kid" : h'11', 144 "crv" : "P-256", 145 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 146 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 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" : b64'SlAV32hkKG ... 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" : b64'39Gqlw', 193 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 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" : b64'0INDoQEKoQVNKkXfb7xaWqMTf6 ... 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" : b64'vO5+qsFi+R5vMw9XcSEeIguLVGyWWJsKxK0P0kx34fE', 218 "y" : b64'xkezjFXvu8TmLmUXIPAC1ddbLgwCzRMm5mK8oiK5BBY' 219 } 220 } 221 } 223 Figure 3: Example AS response, including the RS's public key. 225 3.3. The Resource Server Confirmation Claim 227 If the AS needs to convey a hint to the RS about which key it should 228 use to authenticate towards the client, this specification defines 229 the "rs_cnf" claim, which MAY be used in the access token, with the 230 same syntax and semantics as defined in for the "rs_cnf" parameter. 232 4. Parameters for the Introspection Endpoint 234 4.1. AS-to-RS Response 236 This document defines the following additional parameters for an AS 237 response to a request to the introspection endpoint: 239 cnf 240 OPTIONAL. This field contains information about the proof-of- 241 possession key that binds the client to the access token. Values 242 of this parameter follow the syntax of the "cnf" claim from 243 section 3.1 of [I-D.ietf-ace-cwt-proof-of-possession]. See 244 Section 5 for additional discussion of the usage of this 245 parameter. 247 rs_cnf 248 OPTIONAL. If the RS uses asymmetric keys to authenticate towards 249 the client (e.g. with a DTLS-RPK handshake) and it has several 250 such keys (e.g. for different elliptic curves), the AS can give 251 the RS a hint using this parameter, as to which key it should use. 252 Values of this parameter follow the syntax of the "cnf" claim from 253 section 3.1 of [I-D.ietf-ace-cwt-proof-of-possession]. See 254 Section 5 for additional discussion of the usage of this 255 parameter. 257 Figure 4 shows an AS response to an introspection request including 258 the "cnf" parameter to indicate the proof-of-possession key bound to 259 the token and the "rs_cnf" parameter to indicate the key the RS is 260 supposed to use to authenticate to the client. 262 Header: Created Code=2.01) 263 Content-Format: "application/ace+cbor" 264 Payload: 265 { 266 "active" : true, 267 "scope" : "read", 268 "aud" : "tempSensor4711", 269 "cnf" : { 270 "COSE_Key" : { 271 "kty" : "EC", 272 "kid" : h'11', 273 "crv" : "P-256", 274 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 275 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 276 } 277 }, 278 "rs_cnf" : { 279 "COSE_Key" : { 280 "kty" : "EC", 281 "kid" : h'12', 282 "crv" : "P-256", 283 "x" : b64'vO5+qsFi+R5vMw9XcSEeIguLVGyWWJsKxK0P0kx34fE', 284 "y" : b64'xkezjFXvu8TmLmUXIPAC1ddbLgwCzRMm5mK8oiK5BBY' 285 } 286 } 287 } 289 Figure 4: Example introspection response. 291 5. Confirmation Method Parameters 293 The confirmation method parameters are used as follows: 295 o "req_cnf" in the access token request C -> AS, OPTIONAL to 296 indicate the client's raw public key, or the key-identifier of a 297 previously established key between C and RS that the client wishes 298 to use for proof-of-possession of the access token. 300 o "cnf" in the token response AS -> C, OPTIONAL if using an 301 asymmetric key or a key that the client requested via a key 302 identifier in the request. REQUIRED if the client didn't specify 303 a "req_cnf" and symmetric keys are used. Used to indicate the 304 symmetric key generated by the AS for proof-of-possession of the 305 access token. 307 o "cnf" in the introspection response AS -> RS, REQUIRED if the 308 access token that was subject to introspection is a proof-of- 309 possession token, absent otherwise. Indicates the proof-of- 310 possession key bound to the access token. 312 o "rs_cnf" in the token response AS -> C, OPTIONAL to indicate the 313 public key of the RS, if it uses one to authenticate itself to the 314 client and the binding between key and RS identity is not 315 established through other means. 317 o "rs_cnf" in the introspection response AS -> RS, OPTIONAL, 318 contains the public key that the RS should use for authenticating 319 itself to the client (e.g. if the RS has several different public 320 keys, and there may be ambiguity as to which key to use). 322 Note that the COSE_Key structure in a confirmation claim or parameter 323 may contain an "alg" or "key_ops" parameter. If such parameters are 324 present, a client MUST NOT use a key that is incompatible with the 325 profile or proof-of-possession algorithm according to those 326 parameters. An RS MUST reject a proof-of-possession using such a 327 key. 329 If an access token is issued for an audience that includes several 330 RS, the "rs_cnf" parameter MUST NOT be used, since the client cannot 331 determine for which RS the key applies. This document recommends to 332 specify a different endpoint that the client can use to acquire RS 333 authentication keys in such cases. The specification of such an 334 endpoint is out of scope for this document. 336 6. CBOR Mappings 338 If CBOR is used, the new parameters and claims defined in this 339 document MUST be mapped to CBOR types as specified in Figure 5, using 340 the given integer abbreviation for the map key. 342 /----------+----------+-------------------------------------\ 343 | Name | CBOR Key | Value Type | Usage | 344 |----------+----------+-------------------------------------| 345 | req_cnf | TBD (4) | map | token request | 346 | cnf | TBD (8) | map | token response | 347 | cnf | TBD (8) | map | introspection response | 348 | rs_cnf | TBD (41) | map | token response | 349 | rs_cnf | TBD (41) | map | introspection response | 350 | rs_cnf | TBD (41) | map | CWT claim | 351 \----------+----------+------------+------------------------/ 353 Figure 5: CBOR mappings for new parameters and claims. 355 7. Security Considerations 357 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 358 security considerations from that document apply here as well. 360 8. Privacy Considerations 362 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 363 privacy considerations from that document apply here as well. 365 9. IANA Considerations 367 9.1. JSON Web Token Claims 369 This specification registers the following new claim in the JSON Web 370 Token (JWT) registry of JSON Web Token Claims 371 [IANA.JsonWebTokenClaims]: 373 o Claim Name: "rs_cnf" 374 o Claim Description: public key used by RS to authenticate itself to 375 the client. 376 o Change Controller: IESG 377 o Reference: Section 3.3 of [this document] 379 9.2. CBOR Web Token Claims 381 This specification registers the following new claim in the "CBOR Web 382 Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. 384 o Claim Name: "rs_cnf" 385 o Claim Description: public key used by RS to authenticate itself to 386 the client. 387 o JWT Claim Name: rs_cnf 388 o Claim Key: TBD (suggested: 41) 389 o Claim Value Type(s): map 390 o Change Controller: IESG 391 o Specification Document(s): Section 3.3 of [this document] 393 9.3. OAuth Parameter Registration 395 This section registers the following parameters in the "OAuth 396 Parameters" registry [IANA.OAuthParameters]: 398 o Name: "req_cnf" 399 o Parameter Usage Location: token request 400 o Change Controller: IESG 401 o Reference: Section 5 of [this document] 402 o Name: "rs_cnf" 403 o Parameter Usage Location: token response 404 o Change Controller: IESG 405 o Reference: Section 5 of [this document] 407 o Name: "cnf" 408 o Parameter Usage Location: token response 409 o Change Controller: IESG 410 o Reference: Section 5 of [this document] 412 9.4. OAuth Introspection Response Parameter Registration 414 This section registers the following parameters in the OAuth Token 415 Introspection Response registry [IANA.TokenIntrospectionResponse]. 417 o Name: "cnf" 418 o Description: Key to prove the right to use a PoP token. 419 o Change Controller: IESG 420 o Reference: Section 4.1 of [this document] 422 o Name: "rs_cnf" 423 o Description: public key used by RS to authenticate itself to the 424 client. 425 o Change Controller: IESG 426 o Reference: Section 4.1 of [this document] 428 9.5. OAuth Parameters CBOR Mappings Registraton 430 This section registers the following parameter mappings in the "OAuth 431 Parameters CBOR Mappings" registry established in section 8.9. of 432 [I-D.ietf-ace-oauth-authz]. 434 o Name: "req_cnf" 435 o CBOR key: TBD (suggested: 4) 436 o Change Controller: IESG 437 o Reference: Section 3.1 of [this document] 439 o Name: "cnf" 440 o CBOR key: TBD (suggested: 8) 441 o Change Controller: IESG 442 o Reference: Section 3.2 of [this document] 444 o Name: "rs_cnf" 445 o CBOR key: TBD (suggested: 41) 446 o Change Controller: IESG 447 o Reference: Section 3.2 of [this document] 449 9.6. OAuth Token Introspection Response CBOR Mappings Registration 451 This section registers the following parameter mappings in the "OAuth 452 Token Introspection Response CBOR Mappings" registry established in 453 section 8.11. of [I-D.ietf-ace-oauth-authz]. 455 o Name: "cnf" 456 o CBOR key: TBD (suggested: 8) 457 o Change Controller: IESG 458 o Reference: Section 4.1 of [this document] 460 o Name: "rs_cnf" 461 o CBOR key: TBD (suggested: 41) 462 o Change Controller: IESG 463 o Reference: Section 4.1 of [this document] 465 10. Acknowledgments 467 This document is a product of the ACE working group of the IETF. 469 Ludwig Seitz worked on this document as part of the CelticNext 470 projects CyberWI, and CRITISEC with funding from Vinnova. 472 11. References 474 11.1. Normative References 476 [I-D.ietf-ace-cwt-proof-of-possession] 477 Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 478 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 479 Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- 480 possession-11 (work in progress), October 2019. 482 [I-D.ietf-ace-oauth-authz] 483 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 484 H. Tschofenig, "Authentication and Authorization for 485 Constrained Environments (ACE) using the OAuth 2.0 486 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-27 487 (work in progress), November 2019. 489 [IANA.CborWebTokenClaims] 490 IANA, "CBOR Web Token (CWT) Claims", 491 . 494 [IANA.JsonWebTokenClaims] 495 IANA, "JSON Web Token Claims", 496 . 498 [IANA.OAuthParameters] 499 IANA, "OAuth Parameters", 500 . 503 [IANA.TokenIntrospectionResponse] 504 IANA, "OAuth Token Introspection Response", 505 . 508 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 509 Requirement Levels", BCP 14, RFC 2119, 510 DOI 10.17487/RFC2119, March 1997, 511 . 513 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 514 RFC 6749, DOI 10.17487/RFC6749, October 2012, 515 . 517 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 518 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 519 May 2017, . 521 11.2. Informative References 523 [I-D.ietf-oauth-pop-key-distribution] 524 Bradley, J., Hunt, P., Jones, M., Tschofenig, H., and M. 525 Meszaros, "OAuth 2.0 Proof-of-Possession: Authorization 526 Server to Client Key Distribution", draft-ietf-oauth-pop- 527 key-distribution-07 (work in progress), March 2019. 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 Appendix A. Overlap with OAuth work 536 This document overlaps with draft work from OAuth on proof-of- 537 possesion keys [I-D.ietf-oauth-pop-key-distribution]. 539 The OAuth draft specifies the use of "req_cnf" and "cnf" for 540 requesting proof-of-possession tokens and indicating the key that the 541 AS has selected. It it was initially deemed that the work at OAuth 542 had been discontinued and therefore equivalent functionality was 543 defined here. Work in OAuth has since resumed, but it is lagging 544 behind the planned milestones of the ACE working group. We have 545 therefore split this work out into a separate document so that it can 546 later be updated or obsoleted to align it with the final result of 547 the OAuth work, without affecting [I-D.ietf-ace-oauth-authz]. 549 Author's Address 551 Ludwig Seitz 552 Combitech 553 Djaeknegatan 31 554 Malmoe 211 35 555 Sweden 557 Email: ludwig.seitz@combitech.se