idnits 2.17.1 draft-ietf-ace-oauth-params-04.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 11, 2019) is 1901 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 (-11) exists of draft-ietf-ace-cwt-proof-of-possession-05 == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-18 == Outdated reference: A later version (-07) exists of draft-ietf-oauth-pop-key-distribution-04 Summary: 0 errors (**), 0 flaws (~~), 4 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 RISE 4 Intended status: Standards Track February 11, 2019 5 Expires: August 15, 2019 7 Additional OAuth Parameters for Authorization in Constrained 8 Environments (ACE) 9 draft-ietf-ace-oauth-params-04 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 August 15, 2019. 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 . . . . . . . . . . . . . . . . . . . 8 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. Token Endpoint CBOR Mappings Registraton . . . . . . . . 10 72 9.6. Introspection Endpoint CBOR Mappings Registraton . . . . 10 73 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 74 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 75 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 76 11.2. Informative References . . . . . . . . . . . . . . . . . 12 77 Appendix A. Overlap with OAuth work . . . . . . . . . . . . . . 12 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 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 may need to be updated to align them with ongoing OAuth 88 work. Therefore they have been split out into this document, which 89 can be used and updated independently of [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 potentially constrained client. The AS MUST verify that the 123 client really is in possession of the corresponding key. Values 124 of this parameter follow the syntax of the "cnf" claim from 125 section 3.1 of [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 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" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 144 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 145 } 146 } 147 } 149 Figure 1: Example request for an access token bound to an asymmetric 150 key. 152 3.2. AS-to-Client Response 154 This document defines the following additional parameters for an AS 155 response to a request to the token endpoint: 157 cnf 158 REQUIRED if the token type is "pop" and a symmetric key is used. 159 MAY be present for asymmetric proof-of-possession keys. This 160 field contains the proof-of-possession key that the AS selected 161 for the token. Values of this parameter follow the syntax of the 162 "cnf" claim from section 3.1 of 163 [I-D.ietf-ace-cwt-proof-of-possession]. See Section 5 for details 164 on the use of this parameter. 166 rs_cnf 167 OPTIONAL if the token type is "pop" and asymmetric keys are used. 168 MUST NOT be present otherwise. This field contains information 169 about the public key used by the RS to authenticate. If this 170 parameter is absent, either the RS does not use a public key or 171 the AS assumes that the client already knows the public key of the 172 RS. Values of this parameter follow the syntax of the "cnf" claim 173 from section 3.1 of [I-D.ietf-ace-cwt-proof-of-possession]. See 174 Section 5 for details on the use of this parameter. 176 Figure 2 shows an AS response containing a token and a "cnf" 177 parameter with a symmetric proof-of-possession key. 179 Header: Created (Code=2.01) 180 Content-Format: "application/ace+cbor" 181 Payload: 182 { 183 "access_token" : b64'SlAV32hkKG ... 184 (remainder of CWT omitted for brevity; 185 CWT contains COSE_Key in the "cnf" claim)', 186 "cnf" : { 187 "COSE_Key" : { 188 "kty" : "Symmetric", 189 "kid" : b64'39Gqlw', 190 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 191 } 192 } 193 } 195 Figure 2: Example AS response with an access token bound to a 196 symmetric key. 198 Figure 3 shows an AS response containing a token bound to a 199 previously requested asymmetric proof-of-possession key (not shown) 200 and a "rs_cnf" parameter containing the public key of the RS. 202 Header: Created (Code=2.01) 203 Content-Format: "application/ace+cbor" 204 Payload: 205 { 206 "access_token" : b64'SlAV32hkKG ... 207 (remainder of CWT omitted for brevity; 208 CWT contains COSE_Key in the "cnf" claim)', 209 "rs_cnf" : { 210 "COSE_Key" : { 211 "kty" : "EC", 212 "kid" : h'12', 213 "crv" : "P-256", 214 "x" : b64'vO5+qsFi+R5vMw9XcSEeIguLVGyWWJsKxK0P0kx34fE', 215 "y" : b64'xkezjFXvu8TmLmUXIPAC1ddbLgwCzRMm5mK8oiK5BBY' 216 } 217 } 218 } 220 Figure 3: Example AS response with an access token bound to a 221 symmetric key. 223 3.3. The Resource Server Confirmation Claim 225 If the AS needs to convey a hint to the RS about which key it should 226 use to authenticate towards the client, this specification defines 227 the "rs_cnf" claim, which MAY be used in the access token, with the 228 same syntax and semantics as defined in for the "rs_cnf" parameter. 230 4. Parameters for the Introspection Endpoint 232 4.1. AS-to-RS Response 234 This document defines the following additional parameters for an AS 235 response to a request to the introspection endpoint: 237 cnf 238 OPTIONAL. This field contains information about the proof-of- 239 possession key that binds the client to the access token. Values 240 of this parameter follow the syntax of the "cnf" claim from 241 section 3.1 of [I-D.ietf-ace-cwt-proof-of-possession]. See 242 Section 5 for more details on the use of the "cnf" parameter. 244 rs_cnf 245 OPTIONAL. If the RS uses asymmetric keys to authenticate towards 246 the client (e.g. with a DTLS-RPK handshake) and it has several 247 such keys (e.g. for different elliptic curves), the AS can give 248 the RS a hint using this parameter, as to which key it should use. 249 Values of this parameter follow the syntax of the "cnf" claim from 250 section 3.1 of [I-D.ietf-ace-cwt-proof-of-possession]. See 251 Section 5 for details on the use of this parameter. 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 and the "rs_cnf" parameter to indicate the key the RS is 256 supposed to use to authenticate to the client. 258 Header: Created Code=2.01) 259 Content-Format: "application/ace+cbor" 260 Payload: 261 { 262 "active" : true, 263 "scope" : "read", 264 "aud" : "tempSensor4711", 265 "cnf" : { 266 "COSE_Key" : { 267 "kty" : "EC", 268 "kid" : h'11', 269 "crv" : "P-256", 270 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 271 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 272 } 273 }, 274 "rs_cnf" : { 275 "COSE_Key" : { 276 "kty" : "EC", 277 "kid" : h'12', 278 "crv" : "P-256", 279 "x" : b64'vO5+qsFi+R5vMw9XcSEeIguLVGyWWJsKxK0P0kx34fE', 280 "y" : b64'xkezjFXvu8TmLmUXIPAC1ddbLgwCzRMm5mK8oiK5BBY' 281 } 282 } 283 } 285 Figure 4: Example introspection response. 287 5. Confirmation Method Parameters 289 The confirmation method parameters are used as follows: 291 o "req_cnf" in the access token request C -> AS, OPTIONAL to 292 indicate the client's raw public key, or the key-identifier of a 293 previously established key between C and RS that the client wishes 294 to use for proof-of-possession of the access token. 296 o "cnf" in the token response AS -> C, OPTIONAL if using an 297 asymmetric key or a key that the client requested via a key 298 identifier in the request. REQUIRED if the client didn't specify 299 a "req_cnf" and symmetric keys are used. Used to indicate the 300 symmetric key generated by the AS for proof-of-possession of the 301 access token. 303 o "cnf" in the introspection response AS -> RS, REQUIRED if the 304 access token that was subject to introspection is a proof-of- 305 possession token, absent otherwise. Indicates the proof-of- 306 possession key bound to the access token. 308 o "rs_cnf" in the token response AS -> C, OPTIONAL to indicate the 309 public key of the RS, if it uses one to authenticate to the 310 client. 312 o "rs_cnf" in the introspection response AS -> RS, OPTIONAL, 313 contains the public key that the RS should use for authenticating 314 to the client (e.g. if the RS has several different public keys). 316 Note that the COSE_Key structure in a confirmation claim or parameter 317 may contain an "alg" or "key_ops" parameter. If such parameters are 318 present, a client MUST NOT use a key that is not compatible with the 319 profile or proof-of-possession algorithm according to those 320 parameters. An RS MUST reject a proof-of-possession using such a 321 key. 323 If an access token is issued for an audience that includes several 324 RS, the "rs_cnf" parameter MUST NOT be used, since the client cannot 325 determine for which RS the key applies. This document recommends to 326 specify a different endpoint that the client can use to acquire RS 327 authentication keys in such cases. The specification of such an 328 endpoint is out of scope for this document. 330 6. CBOR Mappings 332 If CBOR is used, the new parameters and claims defined in this 333 document MUST be mapped to CBOR types as specified in Figure 5, using 334 the given integer abbreviation for the map key. 336 /-----------------+----------+----------------------------------\ 337 | Parameter name | CBOR Key | Value Type | 338 |-----------------+----------+----------------------------------| 339 | cnf | 8 | map | 340 | rs_cnf | 11 | map | 341 | req_cnf | 12 | map | 342 \-----------------+----------+----------------------------------/ 344 Figure 5: CBOR mappings for new parameters. 346 7. Security Considerations 348 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 349 security considerations from that document apply here as well. 351 8. Privacy Considerations 353 This document is an extension to [I-D.ietf-ace-oauth-authz]. All 354 privacy considerations from that document apply here as well. 356 9. IANA Considerations 358 9.1. JSON Web Token Claims 360 This specification registers the following new claim in the JSON Web 361 Token (JWT) registry of JSON Web Token Claims 362 [IANA.JsonWebTokenClaims]: 364 o Claim Name: "rs_cnf" 365 o Claim Description: The public key the RS is supposed to use to 366 authenticate to the client wielding this token. 367 o Change Controller: IESG 368 o Reference: Section 3.3 of [this document] 370 9.2. CBOR Web Token Claims 372 This specification registers the following new claim in the "CBOR Web 373 Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. 375 o Claim Name: "rs_cnf" 376 o Claim Description: The public key the RS is supposed to use to 377 authenticate to the client wielding this token. 378 o JWT Claim Name: rs_cnf 379 o Claim Key: TBD (suggested: 40) 380 o Claim Value Type(s): map 381 o Change Controller: IESG 382 o Specification Document(s): Section 3.3 of [this document] 384 9.3. OAuth Parameter Registration 386 This section registers the following parameters in the "OAuth 387 Parameters" registry [IANA.OAuthParameters]: 389 o Name: "req_cnf" 390 o Parameter Usage Location: token request 391 o Change Controller: IESG 392 o Reference: Section 5 of [this document] 394 o Name: "rs_cnf" 395 o Parameter Usage Location: token response 396 o Change Controller: IESG 397 o Reference: Section 5 of [this document] 398 o Name: "cnf" 399 o Parameter Usage Location: token response 400 o Change Controller: IESG 401 o Reference: Section 5 of [this document] 403 9.4. OAuth Introspection Response Parameter Registration 405 This section registers the following parameters in the OAuth Token 406 Introspection Response registry [IANA.TokenIntrospectionResponse]. 408 o Name: "cnf" 409 o Description: Key to prove the right to use a PoP token. 410 o Change Controller: IESG 411 o Reference: Section 4.1 of [this document] 413 o Name: "rs_cnf" 414 o Description: The key the RS should use to authenticate to the 415 client. 416 o Change Controller: IESG 417 o Reference: Section 4.1 of [this document] 419 9.5. Token Endpoint CBOR Mappings Registraton 421 This section registers the following parameter mappings in the "Token 422 Endpoint CBOR Mappings" registry established in section 8.9. of 423 [I-D.ietf-ace-oauth-authz]. 425 o Name: "req_cnf" 426 o CBOR key: 19 427 o Change Controller: IESG 428 o Reference: Section 3.1 of [this document] 430 o Name: "cnf" 431 o CBOR key: 8 432 o Change Controller: IESG 433 o Reference: Section 3.2 of [this document] 435 o Name: "rs_cnf" 436 o CBOR key: 17 437 o Change Controller: IESG 438 o Reference: Section 3.2 of [this document] 440 9.6. Introspection Endpoint CBOR Mappings Registraton 442 This section registers the following parameter mappings in the 443 "Introspection Endpoint CBOR Mappings" registry established in 444 section 8.11. of [I-D.ietf-ace-oauth-authz]. 446 o Name: "cnf" 447 o CBOR key: 8 448 o Change Controller: IESG 449 o Reference: Section 4.1 of [this document] 451 o Name: "rs_cnf" 452 o CBOR key: 17 453 o Change Controller: IESG 454 o Reference: Section 4.1 of [this document] 456 10. Acknowledgments 458 This document is a product of the ACE working group of the IETF. 460 Ludwig Seitz worked on this document as part of the CelticPlus 461 project CyberWI, with funding from Vinnova. 463 11. References 465 11.1. Normative References 467 [I-D.ietf-ace-cwt-proof-of-possession] 468 Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 469 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 470 Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- 471 possession-05 (work in progress), November 2018. 473 [I-D.ietf-ace-oauth-authz] 474 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 475 H. Tschofenig, "Authentication and Authorization for 476 Constrained Environments (ACE) using the OAuth 2.0 477 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-18 478 (work in progress), January 2019. 480 [IANA.CborWebTokenClaims] 481 IANA, "CBOR Web Token (CWT) Claims", 482 . 485 [IANA.JsonWebTokenClaims] 486 IANA, "JSON Web Token Claims", 487 . 489 [IANA.OAuthParameters] 490 IANA, "OAuth Parameters", 491 . 494 [IANA.TokenIntrospectionResponse] 495 IANA, "OAuth Token Introspection Response", 496 . 499 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 500 Requirement Levels", BCP 14, RFC 2119, 501 DOI 10.17487/RFC2119, March 1997, 502 . 504 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 505 RFC 6749, DOI 10.17487/RFC6749, October 2012, 506 . 508 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 509 Application Protocol (CoAP)", RFC 7252, 510 DOI 10.17487/RFC7252, June 2014, 511 . 513 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 514 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 515 May 2017, . 517 11.2. Informative References 519 [I-D.ietf-oauth-pop-key-distribution] 520 Bradley, J., Hunt, P., Jones, M., Tschofenig, H., and M. 521 Mihaly, "OAuth 2.0 Proof-of-Possession: Authorization 522 Server to Client Key Distribution", draft-ietf-oauth-pop- 523 key-distribution-04 (work in progress), October 2018. 525 Appendix A. Overlap with OAuth work 527 This document overlaps with draft work from OAuth on proof-of- 528 possesion keys [I-D.ietf-oauth-pop-key-distribution]. 530 The OAuth draft specifies the use of "req_cnf" and "cnf" for 531 requesting proof-of-possession tokens and indicating the key that the 532 AS has selected. It it was initially deemed that the work at OAuth 533 had been discontinued and therefore equivalent functionality was 534 defined here. Work in OAuth has since resumed, but it is lagging 535 behind the planned milestones of the ACE working group. We have 536 therefore split this work out into a separate document so that it can 537 later be updated or obsoleted to align it with the final result of 538 the OAuth work, without affecting [I-D.ietf-ace-oauth-authz]. 540 Author's Address 542 Ludwig Seitz 543 RISE 544 Scheelevaegen 17 545 Lund 223 70 546 Sweden 548 Email: ludwig.seitz@ri.se