idnits 2.17.1 draft-ietf-ace-oauth-authz-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 (July 2, 2018) is 2123 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-02 ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-07) exists of draft-ietf-ace-actors-06 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-12 == Outdated reference: A later version (-15) exists of draft-ietf-oauth-device-flow-10 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group L. Seitz 3 Internet-Draft RISE SICS 4 Intended status: Standards Track G. Selander 5 Expires: January 3, 2019 Ericsson 6 E. Wahlstroem 8 S. Erdtman 9 Spotify AB 10 H. Tschofenig 11 Arm Ltd. 12 July 2, 2018 14 Authentication and Authorization for Constrained Environments (ACE) 15 using the OAuth 2.0 Framework (ACE-OAuth) 16 draft-ietf-ace-oauth-authz-13 18 Abstract 20 This specification defines a framework for authentication and 21 authorization in Internet of Things (IoT) environments called ACE- 22 OAuth. The framework is based on a set of building blocks including 23 OAuth 2.0 and CoAP, thus making a well-known and widely used 24 authorization solution suitable for IoT devices. Existing 25 specifications are used where possible, but where the constraints of 26 IoT devices require it, extensions are added and profiles are 27 defined. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on January 3, 2019. 46 Copyright Notice 48 Copyright (c) 2018 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 67 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10 69 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14 70 5.1. Discovering Authorization Servers . . . . . . . . . . . . 15 71 5.1.1. Unauthorized Resource Request Message . . . . . . . . 15 72 5.1.2. AS Information . . . . . . . . . . . . . . . . . . . 16 73 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17 74 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 17 75 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18 76 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18 77 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 18 78 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 19 79 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 22 80 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 24 81 5.6.4. Request and Response Parameters . . . . . . . . . . . 25 82 5.6.4.1. Audience . . . . . . . . . . . . . . . . . . . . 25 83 5.6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 25 84 5.6.4.3. Token Type . . . . . . . . . . . . . . . . . . . 26 85 5.6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 26 86 5.6.4.5. Confirmation . . . . . . . . . . . . . . . . . . 27 87 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 27 88 5.7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 28 89 5.7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 29 90 5.7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 30 91 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 31 92 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 31 93 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 32 94 5.8.1. The 'Authorization Information' Endpoint . . . . . . 33 95 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 34 96 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 34 97 6. Security Considerations . . . . . . . . . . . . . . . . . . . 35 98 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 36 99 6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 37 100 6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 37 101 6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 37 102 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37 103 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 104 8.1. Authorization Server Information . . . . . . . . . . . . 38 105 8.2. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 39 106 8.3. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 39 107 8.4. OAuth Access Token Types . . . . . . . . . . . . . . . . 40 108 8.5. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 40 109 8.5.1. Initial Registry Contents . . . . . . . . . . . . . . 41 110 8.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 41 111 8.7. OAuth Parameter Registration . . . . . . . . . . . . . . 41 112 8.8. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 42 113 8.9. OAuth Introspection Response Parameter Registration . . . 43 114 8.10. Introspection Endpoint CBOR Mappings Registry . . . . . . 43 115 8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 44 116 8.12. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 44 117 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 118 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 119 10.1. Normative References . . . . . . . . . . . . . . . . . . 45 120 10.2. Informative References . . . . . . . . . . . . . . . . . 46 121 Appendix A. Design Justification . . . . . . . . . . . . . . . . 49 122 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 52 123 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 54 124 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 55 125 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 55 126 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 56 127 E.2. Introspection Aided Token Validation . . . . . . . . . . 60 128 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 64 129 F.1. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 64 130 F.2. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 64 131 F.3. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 65 132 F.4. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 65 133 F.5. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 65 134 F.6. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 65 135 F.7. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 66 136 F.8. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 66 137 F.9. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 66 138 F.10. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 66 139 F.11. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 66 140 F.12. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 67 141 F.13. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 67 143 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 68 145 1. Introduction 147 Authorization is the process for granting approval to an entity to 148 access a resource [RFC4949]. The authorization task itself can best 149 be described as granting access to a requesting client, for a 150 resource hosted on a device, the resource server (RS). This exchange 151 is mediated by one or multiple authorization servers (AS). Managing 152 authorization for a large number of devices and users can be a 153 complex task. 155 While prior work on authorization solutions for the Web and for the 156 mobile environment also applies to the Internet of Things (IoT) 157 environment, many IoT devices are constrained, for example, in terms 158 of processing capabilities, available memory, etc. For web 159 applications on constrained nodes, this specification RECOMMENDS the 160 use of CoAP [RFC7252] as replacement for HTTP. 162 A detailed treatment of constraints can be found in [RFC7228], and 163 the different IoT deployments present a continuous range of device 164 and network capabilities. Taking energy consumption as an example: 165 At one end there are energy-harvesting or battery powered devices 166 which have a tight power budget, on the other end there are mains- 167 powered devices, and all levels in between. 169 Hence, IoT devices may be very different in terms of available 170 processing and message exchange capabilities and there is a need to 171 support many different authorization use cases [RFC7744]. 173 This specification describes a framework for authentication and 174 authorization in constrained environments (ACE) built on re-use of 175 OAuth 2.0 [RFC6749], thereby extending authorization to Internet of 176 Things devices. This specification contains the necessary building 177 blocks for adjusting OAuth 2.0 to IoT environments. 179 More detailed, interoperable specifications can be found in profiles. 180 Implementations may claim conformance with a specific profile, 181 whereby implementations utilizing the same profile interoperate while 182 implementations of different profiles are not expected to be 183 interoperable. Some devices, such as mobile phones and tablets, may 184 implement multiple profiles and will therefore be able to interact 185 with a wider range of low end devices. Requirements on profiles are 186 described at contextually appropriate places throughout this 187 specification, and also summarized in Appendix C. 189 2. Terminology 191 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 192 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 193 "OPTIONAL" in this document are to be interpreted as described in BCP 194 14 [RFC2119] [RFC8174] when, and only when, they appear in all 195 capitals, as shown here. 197 Certain security-related terms such as "authentication", 198 "authorization", "confidentiality", "(data) integrity", "message 199 authentication code", and "verify" are taken from [RFC4949]. 201 Since exchanges in this specification are described as RESTful 202 protocol interactions, HTTP [RFC7231] offers useful terminology. 204 Terminology for entities in the architecture is defined in OAuth 2.0 205 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 206 server (RS), and authorization server (AS). 208 Note that the term "endpoint" is used here following its OAuth 209 definition, which is to denote resources such as token and 210 introspection at the AS and authz-info at the RS (see Section 5.8.1 211 for a definition of the authz-info endpoint). The CoAP [RFC7252] 212 definition, which is "An entity participating in the CoAP protocol" 213 is not used in this specification. 215 Since this specification focuses on the problem of access control to 216 resources, the actors has been simplified by assuming that the client 217 authorization server (CAS) functionality is not stand-alone but 218 subsumed by either the authorization server or the client (see 219 Section 2.2 in [I-D.ietf-ace-actors]). 221 The specifications in this document is called the "framework" or "ACE 222 framework". When referring to "profiles of this framework" it refers 223 to additional specifications that define the use of this 224 specification with concrete transport, and communication security 225 protocols (e.g., CoAP over DTLS). 227 We use the term "Access Information" for parameters other than the 228 access token provided to the client by the AS to enable it to access 229 the RS (e.g. public key of the RS, profile supported by RS). 231 3. Overview 233 This specification defines the ACE framework for authorization in the 234 Internet of Things environment. It consists of a set of building 235 blocks. 237 The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys 238 widespread deployment. Many IoT devices can support OAuth 2.0 239 without any additional extensions, but for certain constrained 240 settings additional profiling is needed. 242 Another building block is the lightweight web transfer protocol CoAP 243 [RFC7252], for those communication environments where HTTP is not 244 appropriate. CoAP typically runs on top of UDP, which further 245 reduces overhead and message exchanges. While this specification 246 defines extensions for the use of OAuth over CoAP, other underlying 247 protocols are not prohibited from being supported in the future, such 248 as HTTP/2, MQTT, BLE and QUIC. 250 A third building block is CBOR [RFC7049], for encodings where JSON 251 [RFC8259] is not sufficiently compact. CBOR is a binary encoding 252 designed for small code and message size, which may be used for 253 encoding of self contained tokens, and also for encoding payload 254 transferred in protocol messages. 256 A fourth building block is the compact CBOR-based secure message 257 format COSE [RFC8152], which enables application layer security as an 258 alternative or complement to transport layer security (DTLS [RFC6347] 259 or TLS [RFC5246]). COSE is used to secure self-contained tokens such 260 as proof-of-possession (PoP) tokens, which is an extension to the 261 OAuth tokens. The default token format is defined in CBOR web token 262 (CWT) [RFC8392]. Application layer security for CoAP using COSE can 263 be provided with OSCORE [I-D.ietf-core-object-security]. 265 With the building blocks listed above, solutions satisfying various 266 IoT device and network constraints are possible. A list of 267 constraints is described in detail in RFC 7228 [RFC7228] and a 268 description of how the building blocks mentioned above relate to the 269 various constraints can be found in Appendix A. 271 Luckily, not every IoT device suffers from all constraints. The ACE 272 framework nevertheless takes all these aspects into account and 273 allows several different deployment variants to co-exist, rather than 274 mandating a one-size-fits-all solution. It is important to cover the 275 wide range of possible interworking use cases and the different 276 requirements from a security point of view. Once IoT deployments 277 mature, popular deployment variants will be documented in the form of 278 ACE profiles. 280 3.1. OAuth 2.0 282 The OAuth 2.0 authorization framework enables a client to obtain 283 scoped access to a resource with the permission of a resource owner. 284 Authorization information, or references to it, is passed between the 285 nodes using access tokens. These access tokens are issued to clients 286 by an authorization server with the approval of the resource owner. 287 The client uses the access token to access the protected resources 288 hosted by the resource server. 290 A number of OAuth 2.0 terms are used within this specification: 292 The token and introspection Endpoints: 293 The AS hosts the token endpoint that allows a client to request 294 access tokens. The client makes a POST request to the token 295 endpoint on the AS and receives the access token in the response 296 (if the request was successful). 297 In some deployments, a token introspection endpoint is provided by 298 the AS, which can be used by the RS if it needs to request 299 additional information regarding a received access token. The RS 300 makes a POST request to the introspection endpoint on the AS and 301 receives information about the access token in the response. (See 302 "Introspection" below.) 304 Access Tokens: 305 Access tokens are credentials needed to access protected 306 resources. An access token is a data structure representing 307 authorization permissions issued by the AS to the client. Access 308 tokens are generated by the AS and consumed by the RS. The access 309 token content is opaque to the client. 311 Access tokens can have different formats, and various methods of 312 utilization (e.g., cryptographic properties) based on the security 313 requirements of the given deployment. 315 Proof of Possession Tokens: 316 An access token may be bound to a cryptographic key, which is then 317 used by an RS to authenticate requests from a client. Such tokens 318 are called proof-of-possession access tokens (or PoP access 319 tokens). 321 The proof-of-possession (PoP) security concept assumes that the AS 322 acts as a trusted third party that binds keys to access tokens. 323 These so called PoP keys are then used by the client to 324 demonstrate the possession of the secret to the RS when accessing 325 the resource. The RS, when receiving an access token, needs to 326 verify that the key used by the client matches the one bound to 327 the access token. When this specification uses the term "access 328 token" it is assumed to be a PoP access token token unless 329 specifically stated otherwise. 331 The key bound to the access token (the PoP key) may use either 332 symmetric or asymmetric cryptography. The appropriate choice of 333 the kind of cryptography depends on the constraints of the IoT 334 devices as well as on the security requirements of the use case. 336 Symmetric PoP key: 337 The AS generates a random symmetric PoP key. The key is either 338 stored to be returned on introspection calls or encrypted and 339 included in the access token. The PoP key is also encrypted 340 for the client and sent together with the access token to the 341 client. 343 Asymmetric PoP key: 344 An asymmetric key pair is generated on the client and the 345 public key is sent to the AS (if it does not already have 346 knowledge of the client's public key). Information about the 347 public key, which is the PoP key in this case, is either stored 348 to be returned on introspection calls or included inside the 349 access token and sent back to the requesting client. The RS 350 can identify the client's public key from the information in 351 the token, which allows the client to use the corresponding 352 private key for the proof of possession. 354 The access token is either a simple reference, or a structured 355 information object (e.g., CWT [RFC8392]) protected by a 356 cryptographic wrapper (e.g., COSE [RFC8152]). The choice of PoP 357 key does not necessarily imply a specific credential type for the 358 integrity protection of the token. 360 Scopes and Permissions: 361 In OAuth 2.0, the client specifies the type of permissions it is 362 seeking to obtain (via the scope parameter) in the access token 363 request. In turn, the AS may use the scope response parameter to 364 inform the client of the scope of the access token issued. As the 365 client could be a constrained device as well, this specification 366 defines the use of CBOR encoding as data format, see Section 5, to 367 request scopes and to be informed what scopes the access token 368 actually authorizes. 370 The values of the scope parameter in OAuth 2.0 are expressed as a 371 list of space-delimited, case-sensitive strings, with a semantic 372 that is well-known to the AS and the RS. More details about the 373 concept of scopes is found under Section 3.3 in [RFC6749]. 375 Claims: 376 Information carried in the access token or returned from 377 introspection, called claims, is in the form of name-value pairs. 378 An access token may, for example, include a claim identifying the 379 AS that issued the token (via the "iss" claim) and what audience 380 the access token is intended for (via the "aud" claim). The 381 audience of an access token can be a specific resource or one or 382 many resource servers. The resource owner policies influence what 383 claims are put into the access token by the authorization server. 385 While the structure and encoding of the access token varies 386 throughout deployments, a standardized format has been defined 387 with the JSON Web Token (JWT) [RFC7519] where claims are encoded 388 as a JSON object. In [RFC8392], an equivalent format using CBOR 389 encoding (CWT) has been defined. 391 Introspection: 392 Introspection is a method for a resource server to query the 393 authorization server for the active state and content of a 394 received access token. This is particularly useful in those cases 395 where the authorization decisions are very dynamic and/or where 396 the received access token itself is an opaque reference rather 397 than a self-contained token. More information about introspection 398 in OAuth 2.0 can be found in [RFC7662]. 400 3.2. CoAP 402 CoAP is an application layer protocol similar to HTTP, but 403 specifically designed for constrained environments. CoAP typically 404 uses datagram-oriented transport, such as UDP, where reordering and 405 loss of packets can occur. A security solution needs to take the 406 latter aspects into account. 408 While HTTP uses headers and query strings to convey additional 409 information about a request, CoAP encodes such information into 410 header parameters called 'options'. 412 CoAP supports application-layer fragmentation of the CoAP payloads 413 through blockwise transfers [RFC7959]. However, blockwise transfer 414 does not increase the size limits of CoAP options, therefore data 415 encoded in options has to be kept small. 417 Transport layer security for CoAP can be provided by DTLS 1.2 418 [RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy 419 operations that require transport layer security to be terminated at 420 the proxy. One approach for protecting CoAP communication end-to-end 421 through proxies, and also to support security for CoAP over a 422 different transport in a uniform way, is to provide security at the 423 application layer using an object-based security mechanism such as 424 COSE [RFC8152]. 426 One application of COSE is OSCORE [I-D.ietf-core-object-security], 427 which provides end-to-end confidentiality, integrity and replay 428 protection, and a secure binding between CoAP request and response 429 messages. In OSCORE, the CoAP messages are wrapped in COSE objects 430 and sent using CoAP. 432 This framework RECOMMENDS the use of CoAP as replacement for HTTP for 433 use in constrained environments. 435 4. Protocol Interactions 437 The ACE framework is based on the OAuth 2.0 protocol interactions 438 using the token endpoint and optionally the introspection endpoint. 439 A client obtains an access token from an AS using the token endpoint 440 and subsequently presents the access token to a RS to gain access to 441 a protected resource. In most deployments the RS can process the 442 access token locally, however in some cases the RS may present it to 443 the AS via the introspection endpoint to get fresh information. 444 These interactions are shown in Figure 1. An overview of various 445 OAuth concepts is provided in Section 3.1. 447 The OAuth 2.0 framework defines a number of "protocol flows" via 448 grant types, which have been extended further with extensions to 449 OAuth 2.0 (such as RFC 7521 [RFC7521] and 450 [I-D.ietf-oauth-device-flow]). What grant types works best depends 451 on the usage scenario and RFC 7744 [RFC7744] describes many different 452 IoT use cases but there are two preferred grant types, namely the 453 Authorization Code Grant (described in Section 4.1 of [RFC7521]) and 454 the Client Credentials Grant (described in Section 4.4 of [RFC7521]). 455 The Authorization Code Grant is a good fit for use with apps running 456 on smart phones and tablets that request access to IoT devices, a 457 common scenario in the smart home environment, where users need to go 458 through an authentication and authorization phase (at least during 459 the initial setup phase). The native apps guidelines described in 460 [RFC8252] are applicable to this use case. The Client Credential 461 Grant is a good fit for use with IoT devices where the OAuth client 462 itself is constrained. In such a case, the resource owner has pre- 463 arranged access rights for the client with the authorization server, 464 which is often accomplished using a commissioning tool. 466 The consent of the resource owner, for giving a client access to a 467 protected resource, can be provided dynamically as in the traditional 468 OAuth flows, or it could be pre-configured by the resource owner as 469 authorization policies at the AS, which the AS evaluates when a token 470 request arrives. The resource owner and the requesting party (i.e., 471 client owner) are not shown in Figure 1. 473 This framework supports a wide variety of communication security 474 mechanisms between the ACE entities, such as client, AS, and RS. It 475 is assumed that the client has been registered (also called enrolled 476 or onboarded) to an AS using a mechanism defined outside the scope of 477 this document. In practice, various techniques for onboarding have 478 been used, such as factory-based provisioning or the use of 479 commissioning tools. Regardless of the onboarding technique, this 480 provisioning procedure implies that the client and the AS exchange 481 credentials and configuration parameters. These credentials are used 482 to mutually authenticate each other and to protect messages exchanged 483 between the client and the AS. 485 It is also assumed that the RS has been registered with the AS, 486 potentially in a similar way as the client has been registered with 487 the AS. Established keying material between the AS and the RS allows 488 the AS to apply cryptographic protection to the access token to 489 ensure that its content cannot be modified, and if needed, that the 490 content is confidentiality protected. 492 The keying material necessary for establishing communication security 493 between C and RS is dynamically established as part of the protocol 494 described in this document. 496 At the start of the protocol, there is an optional discovery step 497 where the client discovers the resource server and the resources this 498 server hosts. In this step, the client might also determine what 499 permissions are needed to access the protected resource. A generic 500 procedure is described in Section 5.1, profiles MAY define other 501 procedures for discovery. 503 In Bluetooth Low Energy, for example, advertisements are broadcasted 504 by a peripheral, including information about the primary services. 505 In CoAP, as a second example, a client can make a request to "/.well- 506 known/core" to obtain information about available resources, which 507 are returned in a standardized format as described in [RFC6690]. 509 +--------+ +---------------+ 510 | |---(A)-- Token Request ------->| | 511 | | | Authorization | 512 | |<--(B)-- Access Token ---------| Server | 513 | | + Access Information | | 514 | | +---------------+ 515 | | ^ | 516 | | Introspection Request (D)| | 517 | Client | (optional) | | 518 | | Response | |(E) 519 | | (optional) | v 520 | | +--------------+ 521 | |---(C)-- Token + Request ----->| | 522 | | | Resource | 523 | |<--(F)-- Protected Resource ---| Server | 524 | | | | 525 +--------+ +--------------+ 527 Figure 1: Basic Protocol Flow. 529 Requesting an Access Token (A): 530 The client makes an access token request to the token endpoint at 531 the AS. This framework assumes the use of PoP access tokens (see 532 Section 3.1 for a short description) wherein the AS binds a key to 533 an access token. The client may include permissions it seeks to 534 obtain, and information about the credentials it wants to use 535 (e.g., symmetric/asymmetric cryptography or a reference to a 536 specific credential). 538 Access Token Response (B): 539 If the AS successfully processes the request from the client, it 540 returns an access token. It can also return additional 541 parameters, referred to as "Access Information". In addition to 542 the response parameters defined by OAuth 2.0 and the PoP access 543 token extension, this framework defines parameters that can be 544 used to inform the client about capabilities of the RS. More 545 information about these parameters can be found in Section 5.6.4. 547 Resource Request (C): 548 The client interacts with the RS to request access to the 549 protected resource and provides the access token. The protocol to 550 use between the client and the RS is not restricted to CoAP. 551 HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also 552 viable candidates. 554 Depending on the device limitations and the selected protocol, 555 this exchange may be split up into two parts: 557 (1) the client sends the access token containing, or 558 referencing, the authorization information to the RS, that may 559 be used for subsequent resource requests by the client, and 560 (2) the client makes the resource access request, using the 561 communication security protocol and other Access Information 562 obtained from the AS. 564 The Client and the RS mutually authenticate using the security 565 protocol specified in the profile (see step B) and the keys 566 obtained in the access token or the Access Information. The RS 567 verifies that the token is integrity protected by the AS and 568 compares the claims contained in the access token with the 569 resource request. If the RS is online, validation can be handed 570 over to the AS using token introspection (see messages D and E) 571 over HTTP or CoAP. 573 Token Introspection Request (D): 574 A resource server may be configured to introspect the access token 575 by including it in a request to the introspection endpoint at that 576 AS. Token introspection over CoAP is defined in Section 5.7 and 577 for HTTP in [RFC7662]. 579 Note that token introspection is an optional step and can be 580 omitted if the token is self-contained and the resource server is 581 prepared to perform the token validation on its own. 583 Token Introspection Response (E): 584 The AS validates the token and returns the most recent parameters, 585 such as scope, audience, validity etc. associated with it back to 586 the RS. The RS then uses the received parameters to process the 587 request to either accept or to deny it. 589 Protected Resource (F): 590 If the request from the client is authorized, the RS fulfills the 591 request and returns a response with the appropriate response code. 592 The RS uses the dynamically established keys to protect the 593 response, according to used communication security protocol. 595 5. Framework 597 The following sections detail the profiling and extensions of OAuth 598 2.0 for constrained environments, which constitutes the ACE 599 framework. 601 Credential Provisioning 602 For IoT, it cannot be assumed that the client and RS are part of a 603 common key infrastructure, so the AS provisions credentials or 604 associated information to allow mutual authentication. These 605 credentials need to be provided to the parties before or during 606 the authentication protocol is executed, and may be re-used for 607 subsequent token requests. 609 Proof-of-Possession 610 The ACE framework, by default, implements proof-of-possession for 611 access tokens, i.e., that the token holder can prove being a 612 holder of the key bound to the token. The binding is provided by 613 the "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession] indicating 614 what key is used for proof-of-possession. If a client needs to 615 submit a new access token, e.g., to obtain additional access 616 rights, they can request that the AS binds this token to the same 617 key as the previous one. 619 ACE Profiles 620 The client or RS may be limited in the encodings or protocols it 621 supports. To support a variety of different deployment settings, 622 specific interactions between client and RS are defined in an ACE 623 profile. In ACE framework the AS is expected to manage the 624 matching of compatible profile choices between a client and an RS. 625 The AS informs the client of the selected profile using the 626 "profile" parameter in the token response. 628 OAuth 2.0 requires the use of TLS both to protect the communication 629 between AS and client when requesting an access token; between client 630 and RS when accessing a resource and between AS and RS if 631 introspection is used. In constrained settings TLS is not always 632 feasible, or desirable. Nevertheless it is REQUIRED that the data 633 exchanged with the AS is encrypted and integrity protected. It is 634 furthermore REQUIRED that the AS and the endpoint communicating with 635 it (client or RS) perform mutual authentication. 637 Profiles MUST specify how mutual authentication is done, depending 638 e.g. on the communication protocol and the credentials used by the 639 client or the RS. 641 In OAuth 2.0 the communication with the Token and the Introspection 642 endpoints at the AS is assumed to be via HTTP and may use Uri-query 643 parameters. When profiles of this framework use CoAP instead, this 644 framework REQUIRES the use of the following alternative instead of 645 Uri-query parameters: The sender (client or RS) encodes the 646 parameters of its request as a CBOR map and submits that map as the 647 payload of the POST request. The Content-format depends on the 648 security applied to the content and MUST be specified by the profile 649 that is used. 651 The OAuth 2.0 AS uses a JSON structure in the payload of its 652 responses both to client and RS. If CoAP is used, this framework 653 REQUIRES the use of CBOR [RFC7049] instead of JSON. Depending on the 654 profile, the CBOR payload MAY be enclosed in a non-CBOR cryptographic 655 wrapper. 657 5.1. Discovering Authorization Servers 659 In order to determine the AS in charge of a resource hosted at the 660 RS, C MAY send an initial Unauthorized Resource Request message to 661 RS. RS then denies the request and sends the address of its AS back 662 to C. 664 Instead of the initial Unauthorized Resource Request message, other 665 discovery methods may be used, or the client may be pre-provisioned 666 with the address of the AS. 668 5.1.1. Unauthorized Resource Request Message 670 The optional Unauthorized Resource Request message is a request for a 671 resource hosted by RS for which no proper authorization is granted. 672 RS MUST treat any request for a protected resource as Unauthorized 673 Resource Request message when any of the following holds: 675 o The request has been received on an unprotected channel. 676 o RS has no valid access token for the sender of the request 677 regarding the requested action on that resource. 678 o RS has a valid access token for the sender of the request, but 679 this does not allow the requested action on the requested 680 resource. 682 Note: These conditions ensure that RS can handle requests 683 autonomously once access was granted and a secure channel has been 684 established between C and RS. The authz-info endpoint MUST NOT be 685 protected as specified above, in order to allow clients to upload 686 access tokens to RS (cf. Section 5.8.1). 688 Unauthorized Resource Request messages MUST be denied with a client 689 error response. In this response, the Resource Server SHOULD provide 690 proper AS Information to enable the Client to request an access token 691 from RS's AS as described in Section 5.1.2. 693 The handling of all client requests (including unauthorized ones) by 694 the RS is described in Section 5.8.2. 696 5.1.2. AS Information 698 The AS Information is sent by RS as a response to an Unauthorized 699 Resource Request message (see Section 5.1.1) to point the sender of 700 the Unauthorized Resource Request message to RS's AS. The AS 701 information is a set of attributes containing an absolute URI (see 702 Section 4.3 of [RFC3986]) that specifies the AS in charge of RS. 704 The message MAY also contain a nonce generated by RS to ensure 705 freshness in case that the RS and AS do not have synchronized clocks. 707 Figure 2 summarizes the parameters that may be part of the AS 708 Information. 710 /-------+----------+-------------\ 711 | Name | CBOR Key | Value Type | 712 |-------+----------+-------------| 713 | AS | 0 | text string | 714 | nonce | 5 | byte string | 715 \-------+----------+-------------/ 717 Figure 2: AS Information parameters 719 Figure 3 shows an example for an AS Information message payload using 720 CBOR [RFC7049] diagnostic notation, using the parameter names instead 721 of the CBOR keys for better human readability. 723 4.01 Unauthorized 724 Content-Format: application/ace+cbor 725 {AS: "coaps://as.example.com/token", 726 nonce: h'e0a156bb3f'} 728 Figure 3: AS Information payload example 730 In this example, the attribute AS points the receiver of this message 731 to the URI "coaps://as.example.com/token" to request access 732 permissions. The originator of the AS Information payload (i.e., RS) 733 uses a local clock that is loosely synchronized with a time scale 734 common between RS and AS (e.g., wall clock time). Therefore, it has 735 included a parameter "nonce" for replay attack prevention. 737 Figure 4 illustrates the mandatory to use binary encoding of the 738 message payload shown in Figure 3. 740 a2 # map(2) 741 00 # unsigned(0) (=AS) 742 78 1c # text(28) 743 636f6170733a2f2f61732e657861 744 6d706c652e636f6d2f746f6b656e # "coaps://as.example.com/token" 745 05 # unsigned(5) (=nonce) 746 45 # bytes(5) 747 e0a156bb3f 749 Figure 4: AS Information example encoded in CBOR 751 5.2. Authorization Grants 753 To request an access token, the client obtains authorization from the 754 resource owner or uses its client credentials as grant. The 755 authorization is expressed in the form of an authorization grant. 757 The OAuth framework [RFC6749] defines four grant types. The grant 758 types can be split up into two groups, those granted on behalf of the 759 resource owner (password, authorization code, implicit) and those for 760 the client (client credentials). Further grant types have been added 761 later, such as [RFC7521] defining an assertion-based authorization 762 grant. 764 The grant type is selected depending on the use case. In cases where 765 the client acts on behalf of the resource owner, authorization code 766 grant is recommended. If the client acts on behalf of the resource 767 owner, but does not have any display or very limited interaction 768 possibilities it is recommended to use the device code grant defined 769 in [I-D.ietf-oauth-device-flow]. In cases where the client does not 770 act on behalf of the resource owner, client credentials grant is 771 recommended. 773 For details on the different grant types, see the OAuth 2.0 framework 774 [RFC6749]. The OAuth 2.0 framework provides an extension mechanism 775 for defining additional grant types so profiles of this framework MAY 776 define additional grant types, if needed. 778 5.3. Client Credentials 780 Authentication of the client is mandatory independent of the grant 781 type when requesting the access token from the token endpoint. In 782 the case of client credentials grant type, the authentication and 783 grant coincide. 785 Client registration and provisioning of client credentials to the 786 client is out of scope for this specification. 788 The OAuth framework [RFC6749] defines one client credential type, 789 client id and client secret. [I-D.erdtman-ace-rpcc] adds raw-public- 790 key and pre-shared-key to the client credentials types. Profiles of 791 this framework MAY extend with additional client credentials client 792 certificates. 794 5.4. AS Authentication 796 Client credential does not, by default, authenticate the AS that the 797 client connects to. In classic OAuth, the AS is authenticated with a 798 TLS server certificate. 800 Profiles of this framework MUST specify how clients authenticate the 801 AS and how communication security is implemented, otherwise server 802 side TLS certificates, as defined by OAuth 2.0, are required. 804 5.5. The Authorization Endpoint 806 The authorization endpoint is used to interact with the resource 807 owner and obtain an authorization grant in certain grant flows. 808 Since it requires the use of a user agent (i.e., browser), it is not 809 expected that these types of grant flow will be used by constrained 810 clients. This endpoint is therefore out of scope for this 811 specification. Implementations should use the definition and 812 recommendations of [RFC6749] and [RFC6819]. 814 If clients involved cannot support HTTP and TLS, profiles MAY define 815 mappings for the authorization endpoint. 817 5.6. The Token Endpoint 819 In standard OAuth 2.0, the AS provides the token endpoint for 820 submitting access token requests. This framework extends the 821 functionality of the token endpoint, giving the AS the possibility to 822 help the client and RS to establish shared keys or to exchange their 823 public keys. Furthermore, this framework defines encodings using 824 CBOR, as a substitute for JSON. 826 The endpoint may, however, be exposed over HTTPS as in classical 827 OAuth or even other transports. A profile MUST define the details of 828 the mapping between the fields described below, and these transports. 829 If HTTPS is used, JSON or CBOR payloads may be supported. If JSON 830 payloads are used, the semantics of Section 4 of the OAuth 2.0 831 specification MUST be followed (with additions as described below). 833 If CBOR payload is supported, the semantics described below MUST be 834 followed. 836 For the AS to be able to issue a token, the client MUST be 837 authenticated and present a valid grant for the scopes requested. 838 Profiles of this framework MUST specify how the AS authenticates the 839 client and how the communication between client and AS is protected. 841 The default name of this endpoint in an url-path is 'token', however 842 implementations are not required to use this name and can define 843 their own instead. 845 The figures of this section use CBOR diagnostic notation without the 846 integer abbreviations for the parameters or their values for 847 illustrative purposes. Note that implementations MUST use the 848 integer abbreviations and the binary CBOR encoding, if the CBOR 849 encoding is used. 851 5.6.1. Client-to-AS Request 853 The client sends a POST request to the token endpoint at the AS. The 854 profile MUST specify the Content-Type and wrapping of the payload. 855 The content of the request consists of the parameters specified in 856 Section 4 of the OAuth 2.0 specification [RFC6749]. 858 If CBOR is used then this parameter MUST be encoded as a CBOR map, 859 where the "scope" parameter can additionally be formatted as a byte 860 array, in order to allow compact encoding of complex scope 861 structures. 863 When HTTP is used as a transport then the client makes a request to 864 the token endpoint by sending the parameters using the "application/ 865 x-www-form-urlencoded" format with a character encoding of UTF-8 in 866 the HTTP request entity-body, as defined in RFC 6749. 868 In addition to these parameters, this framework defines the following 869 parameters for requesting an access token from a token endpoint: 871 aud: 872 OPTIONAL. Specifies the audience for which the client is 873 requesting an access token. If this parameter is missing, it is 874 assumed that the client and the AS have a pre-established 875 understanding of the audience that an access token should address. 876 If a client submits a request for an access token without 877 specifying an "aud" parameter, and the AS does not have an 878 implicit understanding of the "aud" value for this client, then 879 the AS MUST respond with an error message using a response code 880 equivalent to the CoAP response code 4.00 (Bad Request). 882 cnf: 883 OPTIONAL. This field contains information about the key the 884 client would like to bind to the access token for proof-of- 885 possession. It is RECOMMENDED that an AS reject a request 886 containing a symmetric key value in the 'cnf' field, since the AS 887 is expected to be able to generate better symmetric keys than a 888 potentially constrained client. See Section 5.6.4.5 for more 889 details on the formatting of the 'cnf' parameter. 891 The following examples illustrate different types of requests for 892 proof-of-possession tokens. 894 Figure 5 shows a request for a token with a symmetric proof-of- 895 possession key. Note that in this example it is assumed that 896 transport layer communication security is used with a CBOR payload, 897 therefore the Content-Type is "application/cbor". The content is 898 displayed in CBOR diagnostic notation, without abbreviations for 899 better readability. 901 Header: POST (Code=0.02) 902 Uri-Host: "as.example.com" 903 Uri-Path: "token" 904 Content-Type: "application/cbor" 905 Payload: 906 { 907 "grant_type" : "client_credentials", 908 "client_id" : "myclient", 909 "aud" : "tempSensor4711" 910 } 912 Figure 5: Example request for an access token bound to a symmetric 913 key. 915 Figure 6 shows a request for a token with an asymmetric proof-of- 916 possession key. Note that in this example COSE is used to provide 917 object-security, therefore the Content-Type is "application/cose". 919 Header: POST (Code=0.02) 920 Uri-Host: "as.example.com" 921 Uri-Path: "token" 922 Content-Type: "application/cose" 923 Payload: 924 16( # COSE_ENCRYPTED 925 [ h'a1010a', # protected header: {"alg" : "AES-CCM-16-64-128"} 926 {5 : b64'ifUvZaHFgJM7UmGnjA'}, # unprotected header, IV 927 b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext 928 ] 929 ) 931 Decrypted payload: 932 { 933 "grant_type" : "client_credentials", 934 "client_id" : "myclient", 935 "cnf" : { 936 "COSE_Key" : { 937 "kty" : "EC", 938 "kid" : h'11', 939 "crv" : "P-256", 940 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 941 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 942 } 943 } 944 } 946 Figure 6: Example token request bound to an asymmetric key. 948 Figure 7 shows a request for a token where a previously communicated 949 proof-of-possession key is only referenced. Note that a transport 950 layer based communication security profile with a CBOR payload is 951 assumed in this example, therefore the Content-Type is "application/ 952 cbor". Also note that the client performs a password based 953 authentication in this example by submitting its client_secret (see 954 Section 2.3.1 of [RFC6749]). 956 Header: POST (Code=0.02) 957 Uri-Host: "as.example.com" 958 Uri-Path: "token" 959 Content-Type: "application/cbor" 960 Payload: 961 { 962 "grant_type" : "client_credentials", 963 "client_id" : "myclient", 964 "client_secret" : "mysecret234", 965 "aud" : "valve424", 966 "scope" : "read", 967 "cnf" : { 968 "kid" : b64'6kg0dXJM13U' 969 } 970 } 972 Figure 7: Example request for an access token bound to a key 973 reference. 975 5.6.2. AS-to-Client Response 977 If the access token request has been successfully verified by the AS 978 and the client is authorized to obtain an access token corresponding 979 to its access token request, the AS sends a response with the 980 response code equivalent to the CoAP response code 2.01 (Created). 981 If client request was invalid, or not authorized, the AS returns an 982 error response as described in Section 5.6.3. 984 Note that the AS decides which token type and profile to use when 985 issuing a successful response. It is assumed that the AS has prior 986 knowledge of the capabilities of the client and the RS (see 987 Appendix D. This prior knowledge may, for example, be set by the use 988 of a dynamic client registration protocol exchange [RFC7591]. 990 The content of the successful reply is the Access Information. When 991 using CBOR payloads, the content MUST be encoded as CBOR map, 992 containing parameters as specified in Section 5.1 of [RFC6749]. In 993 addition to these parameters, the following parameters are also part 994 of a successful response: 996 profile: 997 OPTIONAL. This indicates the profile that the client MUST use 998 towards the RS. See Section 5.6.4.4 for the formatting of this 999 parameter. If this parameter is absent, the AS assumes that the 1000 client implicitly knows which profile to use towards the RS. 1001 cnf: 1002 REQUIRED if the token type is "pop" and a symmetric key is used. 1003 MUST NOT be present otherwise. This field contains the symmetric 1004 proof-of-possession key the client is supposed to use. See 1005 Section 5.6.4.5 for details on the use of this parameter. 1006 rs_cnf: 1007 OPTIONAL if the token type is "pop" and asymmetric keys are used. 1008 MUST NOT be present otherwise. This field contains information 1009 about the public key used by the RS to authenticate. See 1010 Section 5.6.4.5 for details on the use of this parameter. If this 1011 parameter is absent, the AS assumes that the client already knows 1012 the public key of the RS. 1013 token_type: 1014 OPTIONAL. By default implementations of this framework SHOULD 1015 assume that the token_type is "pop". If a specific use case 1016 requires another token_type (e.g., "Bearer") to be used then this 1017 parameter is REQUIRED. 1019 Note that if CBOR Web Tokens [RFC8392] are used, the access token 1020 also contains a "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession]. 1021 This claim is however consumed by a different party. The access 1022 token is created by the AS and processed by the RS (and opaque to the 1023 client) whereas the Access Information is created by the AS and 1024 processed by the client; it is never forwarded to the resource 1025 server. 1027 Figure 8 summarizes the parameters that may be part of the Access 1028 Information. 1030 /-------------------+-----------------\ 1031 | Parameter name | Specified in | 1032 |-------------------+-----------------| 1033 | access_token | RFC 6749 | 1034 | token_type | RFC 6749 | 1035 | expires_in | RFC 6749 | 1036 | refresh_token | RFC 6749 | 1037 | scope | RFC 6749 | 1038 | state | RFC 6749 | 1039 | error | RFC 6749 | 1040 | error_description | RFC 6749 | 1041 | error_uri | RFC 6749 | 1042 | profile | [this document] | 1043 | cnf | [this document] | 1044 | rs_cnf | [this document] | 1045 \-------------------+-----------------/ 1047 Figure 8: Access Information parameters 1049 Figure 9 shows a response containing a token and a "cnf" parameter 1050 with a symmetric proof-of-possession key. Note that transport layer 1051 security with CBOR encoding is assumed in this example, therefore the 1052 Content-Type is "application/cbor". 1054 Header: Created (Code=2.01) 1055 Content-Type: "application/cbor" 1056 Payload: 1057 { 1058 "access_token" : b64'SlAV32hkKG ... 1059 (remainder of CWT omitted for brevity; 1060 CWT contains COSE_Key in the "cnf" claim)', 1061 "profile" : "coap_dtls", 1062 "expires_in" : "3600", 1063 "cnf" : { 1064 "COSE_Key" : { 1065 "kty" : "Symmetric", 1066 "kid" : b64'39Gqlw', 1067 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1068 } 1069 } 1070 } 1072 Figure 9: Example AS response with an access token bound to a 1073 symmetric key. 1075 5.6.3. Error Response 1077 The error responses for CoAP-based interactions with the AS are 1078 equivalent to the ones for HTTP-based interactions as defined in 1079 Section 5.2 of [RFC6749], with the following differences: 1081 o The Content-Type MUST be specified by the communication security 1082 profile used between client and AS. When using CoAP the raw 1083 payload before being processed by the communication security 1084 protocol MUST be encoded as a CBOR map. 1085 o A response code equivalent to the CoAP code 4.00 (Bad Request) 1086 MUST be used for all error responses, except for invalid_client 1087 where a response code equivalent to the CoAP code 4.01 1088 (Unauthorized) MAY be used under the same conditions as specified 1089 in Section 5.2 of [RFC6749]. 1090 o The parameters "error", "error_description" and "error_uri" MUST 1091 be abbreviated using the codes specified in Figure 12, when a CBOR 1092 encoding is used. 1093 o The error code (i.e., value of the "error" parameter) MUST be 1094 abbreviated as specified in Figure 10, when a CBOR encoding is 1095 used. 1097 /------------------------+-------------\ 1098 | Name | CBOR Values | 1099 |------------------------+-------------| 1100 | invalid_request | 0 | 1101 | invalid_client | 1 | 1102 | invalid_grant | 2 | 1103 | unauthorized_client | 3 | 1104 | unsupported_grant_type | 4 | 1105 | invalid_scope | 5 | 1106 | unsupported_pop_key | 6 | 1107 \------------------------+-------------/ 1109 Figure 10: CBOR abbreviations for common error codes 1111 In addition to the error responses defined in OAuth 2.0, the 1112 following behavior MUST be implemented by the AS: If the client 1113 submits an asymmetric key in the token request that the RS cannot 1114 process, the AS MUST reject that request with a response code 1115 equivalent to the CoAP code 4.00 (Bad Request) including the error 1116 code "unsupported_pop_key" defined in Figure 10. 1118 5.6.4. Request and Response Parameters 1120 This section provides more detail about the new parameters that can 1121 be used in access token requests and responses, as well as 1122 abbreviations for more compact encoding of existing parameters and 1123 common parameter values. 1125 5.6.4.1. Audience 1127 This parameter specifies for which audience the client is requesting 1128 a token. The formatting and semantics of these strings are 1129 application specific. 1131 When encoded as a CBOR payload it is represented as a CBOR text 1132 string. 1134 5.6.4.2. Grant Type 1136 The abbreviations in Figure 11 MUST be used in CBOR encodings instead 1137 of the string values defined in [RFC6749], if CBOR payloads are used. 1139 /--------------------+------------+------------------------\ 1140 | Name | CBOR Value | Original Specification | 1141 |--------------------+------------+------------------------| 1142 | password | 0 | RFC6749 | 1143 | authorization_code | 1 | RFC6749 | 1144 | client_credentials | 2 | RFC6749 | 1145 | refresh_token | 3 | RFC6749 | 1146 \--------------------+------------+------------------------/ 1148 Figure 11: CBOR abbreviations for common grant types 1150 5.6.4.3. Token Type 1152 The "token_type" parameter, defined in [RFC6749], allows the AS to 1153 indicate to the client which type of access token it is receiving 1154 (e.g., a bearer token). 1156 This document registers the new value "pop" for the OAuth Access 1157 Token Types registry, specifying a proof-of-possession token. How 1158 the proof-of-possession by the client to the RS is performed MUST be 1159 specified by the profiles. 1161 The values in the "token_type" parameter MUST be CBOR text strings, 1162 if a CBOR encoding is used. 1164 In this framework the "pop" value for the "token_type" parameter is 1165 the default. The AS may, however, provide a different value. 1167 5.6.4.4. Profile 1169 Profiles of this framework MUST define the communication protocol and 1170 the communication security protocol between the client and the RS. 1171 The security protocol MUST provide encryption, integrity and replay 1172 protection. Furthermore profiles MUST define proof-of-possession 1173 methods, if they support proof-of-possession tokens. 1175 A profile MUST specify an identifier that MUST be used to uniquely 1176 identify itself in the "profile" parameter. The textual 1177 representation of the profile identifier is just intended for human 1178 readability and MUST NOT be used in parameters and claims.. 1180 Profiles MAY define additional parameters for both the token request 1181 and the Access Information in the access token response in order to 1182 support negotiation or signaling of profile specific parameters. 1184 5.6.4.5. Confirmation 1186 The "cnf" parameter identifies or provides the key used for proof-of- 1187 possession, while the "rs_cnf" parameter provides the raw public key 1188 of the RS. Both parameters use the same formatting and semantics as 1189 the "cnf" claim specified in [I-D.ietf-ace-cwt-proof-of-possession] 1190 when used with a CBOR encoding. When these parameters are used in 1191 JSON then the formatting and semantics of the "cnf" claim specified 1192 in RFC 7800 [RFC7800]. 1194 In addition to the use as a claim in a CWT, the "cnf" parameter is 1195 used in the following contexts with the following meaning: 1197 o In the token request C -> AS, to indicate the client's raw public 1198 key, or the key-identifier of a previously established key between 1199 C and RS. 1200 o In the token response AS -> C, to indicate the symmetric key 1201 generated by the AS for proof-of-possession. 1202 o In the introspection response AS -> RS, to indicate the proof-of- 1203 possession key bound to the introspected token. 1205 Note that the COSE_Key structure in a "cnf" claim or parameter may 1206 contain an "alg" or "key_ops" parameter. If such parameters are 1207 present, a client MUST NOT use a key that is not compatible with the 1208 profile or proof-of-possession algorithm according to those 1209 parameters. An RS MUST reject a proof-of-possession using such a 1210 key. 1212 Also note that the "rs_cnf" parameter is supposed to indicate the key 1213 that the RS uses to authenticate. If the access token is issued for 1214 an audience that includes several RS, this parameter MUST NOT be 1215 used, since the client cannot determine for which RS the key applies. 1216 This framework recommends to specify a different endpoint that the 1217 client can use to acquire RS authentication keys in such cases. The 1218 specification of such an endpoint is out of scope for this framework. 1220 5.6.5. Mapping Parameters to CBOR 1222 If CBOR encoding is used, all OAuth parameters in access token 1223 requests and responses MUST be mapped to CBOR types as specified in 1224 Figure 12, using the given integer abbreviation for the map keys. 1226 Note that we have aligned these abbreviations with the claim 1227 abbreviations defined in [RFC8392]. 1229 /-------------------+----------+---------------------\ 1230 | Name | CBOR Key | Value Type | 1231 |-------------------+----------+---------------------| 1232 | aud | 3 | text string | 1233 | client_id | 8 | text string | 1234 | client_secret | 9 | byte string | 1235 | response_type | 10 | text string | 1236 | redirect_uri | 11 | text string | 1237 | scope | 12 | text or byte string | 1238 | state | 13 | text string | 1239 | code | 14 | byte string | 1240 | error | 15 | unsinged integer | 1241 | error_description | 16 | text string | 1242 | error_uri | 17 | text string | 1243 | grant_type | 18 | unsigned integer | 1244 | access_token | 19 | byte string | 1245 | token_type | 20 | unsigned integer | 1246 | expires_in | 21 | unsigned integer | 1247 | username | 22 | text string | 1248 | password | 23 | text string | 1249 | refresh_token | 24 | byte string | 1250 | cnf | 25 | map | 1251 | profile | 26 | unsigned integer | 1252 | rs_cnf | 31 | map | 1253 \-------------------+----------+---------------------/ 1255 Figure 12: CBOR mappings used in token requests 1257 5.7. The 'Introspect' Endpoint 1259 Token introspection [RFC7662] can be OPTIONALLY provided by the AS, 1260 and is then used by the RS and potentially the client to query the AS 1261 for metadata about a given token, e.g., validity or scope. Analogous 1262 to the protocol defined in RFC 7662 [RFC7662] for HTTP and JSON, this 1263 section defines adaptations to more constrained environments using 1264 CBOR and leaving the choice of the application protocol to the 1265 profile. 1267 Communication between the RS and the introspection endpoint at the AS 1268 MUST be integrity protected and encrypted. Furthermore AS and RS 1269 MUST perform mutual authentication. Finally the AS SHOULD verify 1270 that the RS has the right to access introspection information about 1271 the provided token. Profiles of this framework that support 1272 introspection MUST specify how authentication and communication 1273 security between RS and AS is implemented. 1275 The default name of this endpoint in an url-path is 'introspect', 1276 however implementations are not required to use this name and can 1277 define their own instead. 1279 The figures of this section uses CBOR diagnostic notation without the 1280 integer abbreviations for the parameters or their values for better 1281 readability. 1283 Note that supporting introspection is OPTIONAL for implementations of 1284 this framework. 1286 5.7.1. RS-to-AS Request 1288 The RS sends a POST request to the introspection endpoint at the AS, 1289 the profile MUST specify the Content-Type and wrapping of the 1290 payload. If CBOR is used, the payload MUST be encoded as a CBOR map 1291 with a "token" entry containing either the access token or a 1292 reference to the token (e.g., the cti). Further optional parameters 1293 representing additional context that is known by the RS to aid the AS 1294 in its response MAY be included. 1296 The same parameters are required and optional as in Section 2.1 of 1297 RFC 7662 [RFC7662]. 1299 For example, Figure 13 shows a RS calling the token introspection 1300 endpoint at the AS to query about an OAuth 2.0 proof-of-possession 1301 token. Note that object security based on COSE is assumed in this 1302 example, therefore the Content-Type is "application/cose+cbor". 1303 Figure 14 shows the decoded payload. 1305 Header: POST (Code=0.02) 1306 Uri-Host: "as.example.com" 1307 Uri-Path: "introspect" 1308 Content-Type: "application/cose+cbor" 1309 Payload: 1310 ... COSE content ... 1312 Figure 13: Example introspection request. 1314 { 1315 "token" : b64'7gj0dXJQ43U', 1316 "token_type_hint" : "pop" 1317 } 1319 Figure 14: Decoded token. 1321 5.7.2. AS-to-RS Response 1323 If the introspection request is authorized and successfully 1324 processed, the AS sends a response with the response code equivalent 1325 to the CoAP code 2.01 (Created). If the introspection request was 1326 invalid, not authorized or couldn't be processed the AS returns an 1327 error response as described in Section 5.7.3. 1329 In a successful response, the AS encodes the response parameters in a 1330 map including with the same required and optional parameters as in 1331 Section 2.2 of RFC 7662 [RFC7662] with the following additions: 1333 cnf OPTIONAL. This field contains information about the proof-of- 1334 possession key that binds the client to the access token. See 1335 Section 5.6.4.5 for more details on the use of the "cnf" 1336 parameter. 1337 profile OPTIONAL. This indicates the profile that the RS MUST use 1338 with the client. See Section 5.6.4.4 for more details on the 1339 formatting of this parameter. 1340 rs_cnf OPTIONAL. If the RS has several keys it can use to 1341 authenticate towards the client, the AS can give the RS a hint 1342 using this parameter, as to which key it should use (e.g., if the 1343 AS previously informed the client about a public key the RS is 1344 holding). See Section 5.6.4.5 for more details on the use of this 1345 parameter. 1347 For example, Figure 15 shows an AS response to the introspection 1348 request in Figure 13. Note that transport layer security is assumed 1349 in this example, therefore the Content-Type is "application/cbor". 1351 Header: Created Code=2.01) 1352 Content-Type: "application/cbor" 1353 Payload: 1354 { 1355 "active" : true, 1356 "scope" : "read", 1357 "profile" : "coap_dtls", 1358 "cnf" : { 1359 "COSE_Key" : { 1360 "kty" : "Symmetric", 1361 "kid" : b64'39Gqlw', 1362 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1363 } 1364 } 1365 } 1367 Figure 15: Example introspection response. 1369 5.7.3. Error Response 1371 The error responses for CoAP-based interactions with the AS are 1372 equivalent to the ones for HTTP-based interactions as defined in 1373 Section 2.3 of [RFC7662], with the following differences: 1375 o If content is sent, the Content-Type MUST be set according to the 1376 specification of the communication security profile. If CoAP is 1377 used the payload MUST be encoded as a CBOR map. 1378 o If the credentials used by the RS are invalid the AS MUST respond 1379 with the response code equivalent to the CoAP code 4.01 1380 (Unauthorized) and use the required and optional parameters from 1381 Section 5.2 in RFC 6749 [RFC6749]. 1382 o If the RS does not have the right to perform this introspection 1383 request, the AS MUST respond with a response code equivalent to 1384 the CoAP code 4.03 (Forbidden). In this case no payload is 1385 returned. 1386 o The parameters "error", "error_description" and "error_uri" MUST 1387 be abbreviated using the codes specified in Figure 12. 1388 o The error codes MUST be abbreviated using the codes specified in 1389 Figure 10. 1391 Note that a properly formed and authorized query for an inactive or 1392 otherwise invalid token does not warrant an error response by this 1393 specification. In these cases, the authorization server MUST instead 1394 respond with an introspection response with the "active" field set to 1395 "false". 1397 5.7.4. Mapping Introspection parameters to CBOR 1399 If CBOR is used, the introspection request and response parameters 1400 MUST be mapped to CBOR types as specified in Figure 16, using the 1401 given integer abbreviation for the map key. 1403 Note that we have aligned these abbreviations with the claim 1404 abbreviations defined in [RFC8392]. 1406 /-----------------+----------+----------------------------------\ 1407 | Parameter name | CBOR Key | Value Type | 1408 |-----------------+----------+----------------------------------| 1409 | iss | 1 | text string | 1410 | sub | 2 | text string | 1411 | aud | 3 | text string | 1412 | exp | 4 | integer or floating-point number | 1413 | nbf | 5 | integer or floating-point number | 1414 | iat | 6 | integer or floating-point number | 1415 | cti | 7 | byte string | 1416 | client_id | 8 | text string | 1417 | scope | 12 | text OR byte string | 1418 | token_type | 20 | text string | 1419 | username | 22 | text string | 1420 | cnf | 25 | map | 1421 | profile | 26 | unsigned integer | 1422 | token | 27 | byte string | 1423 | token_type_hint | 28 | text string | 1424 | active | 29 | True or False | 1425 | rs_cnf | 30 | map | 1426 \-----------------+----------+----------------------------------/ 1428 Figure 16: CBOR Mappings to Token Introspection Parameters. 1430 5.8. The Access Token 1432 This framework RECOMMENDS the use of CBOR web token (CWT) as 1433 specified in [RFC8392]. 1435 In order to facilitate offline processing of access tokens, this 1436 draft uses the "cnf" claim from 1437 [I-D.ietf-ace-cwt-proof-of-possession] and specifies the "scope" 1438 claim for both JSON and CBOR web tokens. 1440 The "scope" claim explicitly encodes the scope of a given access 1441 token. This claim follows the same encoding rules as defined in 1442 Section 3.3 of [RFC6749], but in addition implementers MAY use byte 1443 arrays as scope values, to achieve compact encoding of large scope 1444 elements. The meaning of a specific scope value is application 1445 specific and expected to be known to the RS running that application. 1447 If the AS needs to convey a hint to the RS about which key it should 1448 use to authenticate towards the client, the rs_cnf claim MAY be used 1449 with the same syntax and semantics as defined in Section 5.6.4.5. 1451 If the AS needs to convey a hint to the RS about which profile it 1452 should use to communicate with the client, the AS MAY include a 1453 "profile" claim in the access token, with the same syntax and 1454 semantics as defined in Section 5.6.4.4. 1456 5.8.1. The 'Authorization Information' Endpoint 1458 The access token, containing authorization information and 1459 information about the key used by the client, needs to be transported 1460 to the RS so that the RS can authenticate and authorize the client 1461 request. 1463 This section defines a method for transporting the access token to 1464 the RS using a RESTful protocol such as CoAP. Profiles of this 1465 framework MAY define other methods for token transport. 1467 The method consists of an authz-info endpoint, implemented by the RS. 1468 A client using this method MUST make a POST request to the authz-info 1469 endpoint at the RS with the access token in the payload. The RS 1470 receiving the token MUST verify the validity of the token. If the 1471 token is valid, the RS MUST respond to the POST request with 2.01 1472 (Created). This response MAY contain an identifier of the token 1473 (e.g., the cti for a CWT) as a payload, in order to allow the client 1474 to refer to the token. 1476 The RS MUST be prepared to store at least one access token for future 1477 use. This is a difference to how access tokens are handled in OAuth 1478 2.0, where the access token is typically sent along with each 1479 request, and therefore not stored at the RS. 1481 If the payload sent to the authz-info endpoint does not parse to a 1482 token, the RS MUST respond with a response code equivalent to the 1483 CoAP code 4.00 (Bad Request). If the token is not valid, the RS MUST 1484 respond with a response code equivalent to the CoAP code 4.01 1485 (Unauthorized). If the token is valid but the audience of the token 1486 does not match the RS, the RS MUST respond with a response code 1487 equivalent to the CoAP code 4.03 (Forbidden). If the token is valid 1488 but is associated to claims that the RS cannot process (e.g., an 1489 unknown scope) the RS MUST respond with a response code equivalent to 1490 the CoAP code 4.00 (Bad Request). In the latter case the RS MAY 1491 provide additional information in the error response, in order to 1492 clarify what went wrong. 1494 The RS MAY make an introspection request to validate the token before 1495 responding to the POST request to the authz-info endpoint. 1497 Profiles MUST specify how the authz-info endpoint is protected, 1498 including how error responses from this endpoint are protected. Note 1499 that since the token contains information that allow the client and 1500 the RS to establish a security context in the first place, mutual 1501 authentication may not be possible at this point. 1503 The default name of this endpoint in an url-path is 'authz-info', 1504 however implementations are not required to use this name and can 1505 define their own instead. 1507 5.8.2. Client Requests to the RS 1509 A RS receiving a client request MUST first verify that it has an 1510 access token that authorizes this request, and that the client has 1511 performed the proof-of-possession for that token. 1513 The response code MUST be 4.01 (Unauthorized) in case the client has 1514 not performed the proof-of-possession, or if RS has no valid access 1515 token for the client. If RS has an access token for the client but 1516 not for the resource that was requested, RS MUST reject the request 1517 with a 4.03 (Forbidden). If RS has an access token for the client 1518 but it does not cover the action that was requested on the resource, 1519 RS MUST reject the request with a 4.05 (Method Not Allowed). 1521 Note: The use of the response codes 4.03 and 4.05 is intended to 1522 prevent infinite loops where a dumb Client optimistically tries to 1523 access a requested resource with any access token received from AS. 1524 As malicious clients could pretend to be C to determine C's 1525 privileges, these detailed response codes must be used only when a 1526 certain level of security is already available which can be achieved 1527 only when the Client is authenticated. 1529 Note: The RS MAY use introspection for timely validation of an access 1530 token, at the time when a request is presented. 1532 Note: Matching the claims of the access token (e.g., scope) to a 1533 specific request is application specific. 1535 If the request matches a valid token and the client has performed the 1536 proof-of-possession for that token, the RS continues to process the 1537 request as specified by the underlying application. 1539 5.8.3. Token Expiration 1541 Depending on the capabilities of the RS, there are various ways in 1542 which it can verify the validity of a received access token. Here 1543 follows a list of the possibilities including what functionality they 1544 require of the RS. 1546 o The token is a CWT and includes an "exp" claim and possibly the 1547 "nbf" claim. The RS verifies these by comparing them to values 1548 from its internal clock as defined in [RFC7519]. In this case the 1549 RS's internal clock must reflect the current date and time, or at 1550 least be synchronized with the AS's clock. How this clock 1551 synchronization would be performed is out of scope for this 1552 specification. 1553 o The RS verifies the validity of the token by performing an 1554 introspection request as specified in Section 5.7. This requires 1555 the RS to have a reliable network connection to the AS and to be 1556 able to handle two secure sessions in parallel (C to RS and AS to 1557 RS). 1558 o The RS and the AS both store a sequence number linked to their 1559 common security association. The AS increments this number for 1560 each access token it issues and includes it in the access token, 1561 which is a CWT. The RS keeps track of the most recently received 1562 sequence number, and only accepts tokens as valid, that are in a 1563 certain range around this number. This method does only require 1564 the RS to keep track of the sequence number. The method does not 1565 provide timely expiration, but it makes sure that older tokens 1566 cease to be valid after a certain number of newer ones got issued. 1567 For a constrained RS with no network connectivity and no means of 1568 reliably measuring time, this is the best that can be achieved. 1570 If a token that authorizes a long running request such as a CoAP 1571 Observe [RFC7641] expires, the RS MUST send an error response with 1572 the response code equivalent to the CoAP code 4.01 (Unauthorized) to 1573 the client and then terminate processing the long running request. 1575 6. Security Considerations 1577 Security considerations applicable to authentication and 1578 authorization in RESTful environments provided in OAuth 2.0 [RFC6749] 1579 apply to this work, as well as the security considerations from 1580 [I-D.ietf-ace-actors]. Furthermore [RFC6819] provides additional 1581 security considerations for OAuth which apply to IoT deployments as 1582 well. 1584 A large range of threats can be mitigated by protecting the contents 1585 of the access token by using a digital signature or a keyed message 1586 digest (MAC) or an Authenticated Encryption with Associated Data 1587 (AEAD) algorithm. Consequently, the token integrity protection MUST 1588 be applied to prevent the token from being modified, particularly 1589 since it contains a reference to the symmetric key or the asymmetric 1590 key. If the access token contains the symmetric key, this symmetric 1591 key MUST be encrypted by the authorization server so that only the 1592 resource server can decrypt it. Note that using an AEAD algorithm is 1593 preferable over using a MAC unless the message needs to be publicly 1594 readable. 1596 It is important for the authorization server to include the identity 1597 of the intended recipient (the audience), typically a single resource 1598 server (or a list of resource servers), in the token. Using a single 1599 shared secret with multiple resource servers to simplify key 1600 management is NOT RECOMMENDED since the benefit from using the proof- 1601 of-possession concept is significantly reduced. 1603 The authorization server MUST offer confidentiality protection for 1604 any interactions with the client. This step is extremely important 1605 since the client may obtain the proof-of-possession key from the 1606 authorization server for use with a specific access token. Not using 1607 confidentiality protection exposes this secret (and the access token) 1608 to an eavesdropper thereby completely negating proof-of-possession 1609 security. Profiles MUST specify how confidentiality protection is 1610 provided, and additional protection can be applied by encrypting the 1611 token, for example encryption of CWTs is specified in Section 5.1 of 1612 [RFC8392]. 1614 Developers MUST ensure that the ephemeral credentials (i.e., the 1615 private key or the session key) are not leaked to third parties. An 1616 adversary in possession of the ephemeral credentials bound to the 1617 access token will be able to impersonate the client. Be aware that 1618 this is a real risk with many constrained environments, since 1619 adversaries can often easily get physical access to the devices. 1621 Clients can at any time request a new proof-of-possession capable 1622 access token. If clients have that capability, the AS can keep the 1623 lifetime of the access token and the associated proof-of-possession 1624 key short and therefore use shorter proof-of-possession key sizes, 1625 which translate to a performance benefit for the client and for the 1626 resource server. Shorter keys also lead to shorter messages 1627 (particularly with asymmetric keying material). 1629 When authorization servers bind symmetric keys to access tokens, they 1630 SHOULD scope these access tokens to a specific permissions. 1631 Furthermore access tokens using symmetric keys for proof-of- 1632 possession SHOULD NOT be targeted at an audience that contains more 1633 than one RS, since otherwise any RS in the audience that receives 1634 that access token can impersonate the client towards the other 1635 members of the audience. 1637 6.1. Unprotected AS Information 1639 Initially, no secure channel exists to protect the communication 1640 between C and RS. Thus, C cannot determine if the AS information 1641 contained in an unprotected response from RS to an unauthorized 1642 request (see Section 5.1.2) is authentic. It is therefore advisable 1643 to provide C with a (possibly hard-coded) list of trustworthy 1644 authorization servers. AS information responses referring to a URI 1645 not listed there would be ignored. 1647 6.2. Use of Nonces for Replay Protection 1649 The RS may add a nonce to the AS Information message sent as a 1650 response to an unauthorized request to ensure freshness of an Access 1651 Token subsequently presented to RS. While a time-stamp of some 1652 granularity would be sufficient to protect against replay attacks, 1653 using randomized nonce is preferred to prevent disclosure of 1654 information about RS's internal clock characteristics. 1656 6.3. Combining profiles 1658 There may be use cases were different profiles of this framework are 1659 combined. For example, an MQTT-TLS profile is used between the 1660 client and the RS in combination with a CoAP-DTLS profile for 1661 interactions between the client and the AS. Ideally, profiles should 1662 be designed in a way that the security of system should not depend on 1663 the specific security mechanisms used in individual protocol 1664 interactions. 1666 6.4. Error responses 1668 The various error responses defined in this framework may leak 1669 information to an adversary. For example errors responses for 1670 requests to the Authorization Information endpoint can reveal 1671 information about an otherwise opaque access token to an adversary 1672 who has intercepted this token. This framework is written under the 1673 assumption that, in general, the benefits of detailed error messages 1674 outweigh the risk due to information leakage. For particular use 1675 cases, where this assessment does not apply, detailed error messages 1676 can be replaced by more generic ones. 1678 7. Privacy Considerations 1680 Implementers and users should be aware of the privacy implications of 1681 the different possible deployments of this framework. 1683 The AS is in a very central position and can potentially learn 1684 sensitive information about the clients requesting access tokens. If 1685 the client credentials grant is used, the AS can track what kind of 1686 access the client intends to perform. With other grants this can be 1687 prevented by the Resource Owner. To do so, the resource owner needs 1688 to bind the grants it issues to anonymous, ephemeral credentials that 1689 do not allow the AS to link different grants and thus different 1690 access token requests by the same client. 1692 If access tokens are only integrity protected and not encrypted, they 1693 may reveal information to attackers listening on the wire, or able to 1694 acquire the access tokens in some other way. In the case of CWTs the 1695 token may, e.g., reveal the audience, the scope and the confirmation 1696 method used by the client. The latter may reveal the identity of the 1697 device or application running the client. This may be linkable to 1698 the identity of the person using the client (if there is a person and 1699 not a machine-to-machine interaction). 1701 Clients using asymmetric keys for proof-of-possession should be aware 1702 of the consequences of using the same key pair for proof-of- 1703 possession towards different RSs. A set of colluding RSs or an 1704 attacker able to obtain the access tokens will be able to link the 1705 requests, or even to determine the client's identity. 1707 An unprotected response to an unauthorized request (see 1708 Section 5.1.2) may disclose information about RS and/or its existing 1709 relationship with C. It is advisable to include as little 1710 information as possible in an unencrypted response. Means of 1711 encrypting communication between C and RS already exist, more 1712 detailed information may be included with an error response to 1713 provide C with sufficient information to react on that particular 1714 error. 1716 8. IANA Considerations 1718 8.1. Authorization Server Information 1720 This section establishes the IANA "ACE Authorization Server 1721 Information" registry. The registry has been created to use the 1722 "Expert Review Required" registration procedure [RFC8126]. It should 1723 be noted that, in addition to the expert review, some portions of the 1724 registry require a specification, potentially a Standards Track RFC, 1725 be supplied as well. 1727 The columns of the registry are: 1729 Name The name of the parameter 1730 CBOR Key CBOR map key for the parameter. Different ranges of values 1731 use different registration policies [RFC8126]. Integer values 1732 from -256 to 255 are designated as Standards Action. Integer 1733 values from -65536 to -257 and from 256 to 65535 are designated as 1734 Specification Required. Integer values greater than 65535 are 1735 designated as Expert Review. Integer values less than -65536 are 1736 marked as Private Use. 1737 Value Type The CBOR data types allowable for the values of this 1738 parameter. 1740 Reference This contains a pointer to the public specification of the 1741 grant type abbreviation, if one exists. 1743 This registry will be initially populated by the values in Figure 2. 1744 The Reference column for all of these entries will be this document. 1746 8.2. OAuth Error Code CBOR Mappings Registry 1748 This section establish the IANA "OAuth Error Code CBOR Mappings" 1749 registry. The registry has been created to use the "Expert Review 1750 Required" registration procedure [RFC8126]. It should be noted that, 1751 in addition to the expert review, some portions of the registry 1752 require a specification, potentially a Standards Track RFC, be 1753 supplied as well. 1755 The columns of the registry are: 1757 Name The OAuth Error Code name, refers to the name in Section 5.2. 1758 of [RFC6749], e.g., "invalid_request". 1759 CBOR Value CBOR abbreviation for this error code. Different ranges 1760 of values use different registration policies [RFC8126]. Integer 1761 values from -256 to 255 are designated as Standards Action. 1762 Integer values from -65536 to -257 and from 256 to 65535 are 1763 designated as Specification Required. Integer values greater than 1764 65535 are designated as Expert Review. Integer values less than 1765 -65536 are marked as Private Use. 1766 Reference This contains a pointer to the public specification of the 1767 grant type abbreviation, if one exists. 1769 This registry will be initially populated by the values in Figure 10. 1770 The Reference column for all of these entries will be this document. 1772 8.3. OAuth Grant Type CBOR Mappings 1774 This section establishes the IANA "OAuth Grant Type CBOR Mappings" 1775 registry. The registry has been created to use the "Expert Review 1776 Required" registration procedure [RFC8126]. It should be noted that, 1777 in addition to the expert review, some portions of the registry 1778 require a specification, potentially a Standards Track RFC, be 1779 supplied as well. 1781 The columns of this registry are: 1783 Name The name of the grant type as specified in Section 1.3 of 1784 [RFC6749]. 1785 CBOR Value CBOR abbreviation for this grant type. Different ranges 1786 of values use different registration policies [RFC8126]. Integer 1787 values from -256 to 255 are designated as Standards Action. 1789 Integer values from -65536 to -257 and from 256 to 65535 are 1790 designated as Specification Required. Integer values greater than 1791 65535 are designated as Expert Review. Integer values less than 1792 -65536 are marked as Private Use. 1793 Reference This contains a pointer to the public specification of the 1794 grant type abbreviation, if one exists. 1795 Original Specification This contains a pointer to the public 1796 specification of the grant type, if one exists. 1798 This registry will be initially populated by the values in Figure 11. 1799 The Reference column for all of these entries will be this document. 1801 8.4. OAuth Access Token Types 1803 This section registers the following new token type in the "OAuth 1804 Access Token Types" registry [IANA.OAuthAccessTokenTypes]. 1806 o Name: "PoP" 1807 o Change Controller: IETF 1808 o Reference: [this document] 1810 8.5. OAuth Token Type CBOR Mappings 1812 This section eatables the IANA "Token Type CBOR Mappings" registry. 1813 The registry has been created to use the "Expert Review Required" 1814 registration procedure [RFC8126]. It should be noted that, in 1815 addition to the expert review, some portions of the registry require 1816 a specification, potentially a Standards Track RFC, be supplied as 1817 well. 1819 The columns of this registry are: 1821 Name The name of token type as registered in the OAuth Access Token 1822 Types registry, e.g., "Bearer". 1823 CBOR Value CBOR abbreviation for this token type. Different ranges 1824 of values use different registration policies [RFC8126]. Integer 1825 values from -256 to 255 are designated as Standards Action. 1826 Integer values from -65536 to -257 and from 256 to 65535 are 1827 designated as Specification Required. Integer values greater than 1828 65535 are designated as Expert Review. Integer values less than 1829 -65536 are marked as Private Use. 1830 Reference This contains a pointer to the public specification of the 1831 OAuth token type abbreviation, if one exists. 1832 Original Specification This contains a pointer to the public 1833 specification of the grant type, if one exists. 1835 8.5.1. Initial Registry Contents 1837 o Name: "Bearer" 1838 o Value: 1 1839 o Reference: [this document] 1840 o Original Specification: [RFC6749] 1842 o Name: "pop" 1843 o Value: 2 1844 o Reference: [this document] 1845 o Original Specification: [this document] 1847 8.6. ACE Profile Registry 1849 This section establishes the IANA "ACE Profile" registry. The 1850 registry has been created to use the "Expert Review Required" 1851 registration procedure [RFC8126]. It should be noted that, in 1852 addition to the expert review, some portions of the registry require 1853 a specification, potentially a Standards Track RFC, be supplied as 1854 well. 1856 The columns of this registry are: 1858 Name The name of the profile, to be used as value of the profile 1859 attribute. 1860 Description Text giving an overview of the profile and the context 1861 it is developed for. 1862 CBOR Value CBOR abbreviation for this profile name. Different 1863 ranges of values use different registration policies [RFC8126]. 1864 Integer values from -256 to 255 are designated as Standards 1865 Action. Integer values from -65536 to -257 and from 256 to 65535 1866 are designated as Specification Required. Integer values greater 1867 than 65535 are designated as Expert Review. Integer values less 1868 than -65536 are marked as Private Use. 1869 Reference This contains a pointer to the public specification of the 1870 profile abbreviation, if one exists. 1872 8.7. OAuth Parameter Registration 1874 This section registers the following parameters in the "OAuth 1875 Parameters" registry [IANA.OAuthParameters]: 1877 o Name: "aud" 1878 o Parameter Usage Location: authorization request, token request 1879 o Change Controller: IESG 1880 o Reference: Section 5.6.1 of [this document] 1882 o Name: "profile" 1883 o Parameter Usage Location: token response 1884 o Change Controller: IESG 1885 o Reference: Section 5.6.4.4 of [this document] 1887 o Name: "cnf" 1888 o Parameter Usage Location: token request, token response 1889 o Change Controller: IESG 1890 o Reference: Section 5.6.4.5 of [this document] 1892 o Name: "rs_cnf" 1893 o Parameter Usage Location: token response 1894 o Change Controller: IESG 1895 o Reference: Section 5.6.4.5 of [this document] 1897 8.8. OAuth CBOR Parameter Mappings Registry 1899 This section establishes the IANA "Token Endpoint CBOR Mappings" 1900 registry. The registry has been created to use the "Expert Review 1901 Required" registration procedure [RFC8126]. It should be noted that, 1902 in addition to the expert review, some portions of the registry 1903 require a specification, potentially a Standards Track RFC, be 1904 supplied as well. 1906 The columns of this registry are: 1908 Name The OAuth Parameter name, refers to the name in the OAuth 1909 parameter registry, e.g., "client_id". 1910 CBOR Key CBOR map key for this parameter. Different ranges of 1911 values use different registration policies [RFC8126]. Integer 1912 values from -256 to 255 are designated as Standards Action. 1913 Integer values from -65536 to -257 and from 256 to 65535 are 1914 designated as Specification Required. Integer values greater than 1915 65535 are designated as Expert Review. Integer values less than 1916 -65536 are marked as Private Use. 1917 Value Type The allowable CBOR data types for values of this 1918 parameter. 1919 Reference This contains a pointer to the public specification of the 1920 grant type abbreviation, if one exists. 1922 This registry will be initially populated by the values in Figure 12. 1923 The Reference column for all of these entries will be this document. 1925 Note that these mappings intentionally coincide with the CWT claim 1926 name mappings from [RFC8392]. 1928 8.9. OAuth Introspection Response Parameter Registration 1930 This section registers the following parameters in the OAuth Token 1931 Introspection Response registry [IANA.TokenIntrospectionResponse]. 1933 o Name: "cnf" 1934 o Description: Key to prove the right to use a PoP token. 1935 o Change Controller: IESG 1936 o Reference: Section 5.7.2 of [this document] 1938 o Name: "profile" 1939 o Description: The communication and communication security profile 1940 used between client and RS, as defined in ACE profiles. 1941 o Change Controller: IESG 1942 o Reference: Section 5.7.2 of [this document] 1944 8.10. Introspection Endpoint CBOR Mappings Registry 1946 This section establishes the IANA "Introspection Endpoint CBOR 1947 Mappings" registry. The registry has been created to use the "Expert 1948 Review Required" registration procedure [RFC8126]. It should be 1949 noted that, in addition to the expert review, some portions of the 1950 registry require a specification, potentially a Standards Track RFC, 1951 be supplied as well. 1953 The columns of this registry are: 1955 Name The OAuth Parameter name, refers to the name in the OAuth 1956 parameter registry, e.g., "client_id". 1957 CBOR Key CBOR map key for this parameter. Different ranges of 1958 values use different registration policies [RFC8126]. Integer 1959 values from -256 to 255 are designated as Standards Action. 1960 Integer values from -65536 to -257 and from 256 to 65535 are 1961 designated as Specification Required. Integer values greater than 1962 65535 are designated as Expert Review. Integer values less than 1963 -65536 are marked as Private Use. 1964 Value Type The allowable CBOR data types for values of this 1965 parameter. 1966 Reference This contains a pointer to the public specification of the 1967 grant type abbreviation, if one exists. 1969 This registry will be initially populated by the values in Figure 16. 1970 The Reference column for all of these entries will be this document. 1972 8.11. JSON Web Token Claims 1974 This specification registers the following new claims in the JSON Web 1975 Token (JWT) registry of JSON Web Token Claims 1976 [IANA.JsonWebTokenClaims]: 1978 o Claim Name: "scope" 1979 o Claim Description: The scope of an access token as defined in 1980 [RFC6749]. 1981 o Change Controller: IESG 1982 o Reference: Section 5.8 of [this document] 1984 8.12. CBOR Web Token Claims 1986 This specification registers the following new claims in the "CBOR 1987 Web Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. 1989 o Claim Name: "scope" 1990 o Claim Description: The scope of an access token as defined in 1991 [RFC6749]. 1992 o JWT Claim Name: N/A 1993 o Claim Key: 12 1994 o Claim Value Type(s): 0 (uint), 2 (byte string), 3 (text string) 1995 o Change Controller: IESG 1996 o Specification Document(s): Section 5.8 of [this document] 1998 9. Acknowledgments 2000 This document is a product of the ACE working group of the IETF. 2002 Thanks to Eve Maler for her contributions to the use of OAuth 2.0 and 2003 UMA in IoT scenarios, Robert Taylor for his discussion input, and 2004 Malisa Vucinic for his input on the predecessors of this proposal. 2006 Thanks to the authors of draft-ietf-oauth-pop-key-distribution, from 2007 where large parts of the security considerations where copied. 2009 Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten Bormann for 2010 contributing their work on AS discovery from draft-gerdes-ace-dcaf- 2011 authorize (see Section 5.1). 2013 Thanks to Jim Schaad and Mike Jones for their comprehensive reviews. 2015 Ludwig Seitz and Goeran Selander worked on this document as part of 2016 the CelticPlus project CyberWI, with funding from Vinnova. 2018 10. References 2020 10.1. Normative References 2022 [I-D.ietf-ace-cwt-proof-of-possession] 2023 Jones, M., Seitz, L., Selander, G., Wahlstroem, E., 2024 Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key 2025 Semantics for CBOR Web Tokens (CWTs)", draft-ietf-ace-cwt- 2026 proof-of-possession-02 (work in progress), March 2018. 2028 [IANA.CborWebTokenClaims] 2029 IANA, "CBOR Web Token (CWT) Claims", 2030 . 2033 [IANA.JsonWebTokenClaims] 2034 IANA, "JSON Web Token Claims", 2035 . 2037 [IANA.OAuthAccessTokenTypes] 2038 IANA, "OAuth Access Token Types", 2039 . 2042 [IANA.OAuthParameters] 2043 IANA, "OAuth Parameters", 2044 . 2047 [IANA.TokenIntrospectionResponse] 2048 IANA, "OAuth Token Introspection Response", 2049 . 2052 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2053 Requirement Levels", BCP 14, RFC 2119, 2054 DOI 10.17487/RFC2119, March 1997, . 2057 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2058 Resource Identifier (URI): Generic Syntax", STD 66, 2059 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2060 . 2062 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2063 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2064 January 2012, . 2066 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2067 Application Protocol (CoAP)", RFC 7252, 2068 DOI 10.17487/RFC7252, June 2014, . 2071 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 2072 RFC 7662, DOI 10.17487/RFC7662, October 2015, 2073 . 2075 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 2076 Possession Key Semantics for JSON Web Tokens (JWTs)", 2077 RFC 7800, DOI 10.17487/RFC7800, April 2016, 2078 . 2080 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2081 Writing an IANA Considerations Section in RFCs", BCP 26, 2082 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2083 . 2085 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2086 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2087 . 2089 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2090 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2091 May 2017, . 2093 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 2094 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 2095 May 2018, . 2097 10.2. Informative References 2099 [I-D.erdtman-ace-rpcc] 2100 Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared- 2101 Key as OAuth client credentials", draft-erdtman-ace- 2102 rpcc-02 (work in progress), October 2017. 2104 [I-D.ietf-ace-actors] 2105 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 2106 architecture for authorization in constrained 2107 environments", draft-ietf-ace-actors-06 (work in 2108 progress), November 2017. 2110 [I-D.ietf-core-object-security] 2111 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2112 "Object Security for Constrained RESTful Environments 2113 (OSCORE)", draft-ietf-core-object-security-12 (work in 2114 progress), March 2018. 2116 [I-D.ietf-oauth-device-flow] 2117 Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2118 "OAuth 2.0 Device Flow for Browserless and Input 2119 Constrained Devices", draft-ietf-oauth-device-flow-10 2120 (work in progress), June 2018. 2122 [Margi10impact] 2123 Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr, 2124 M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold, 2125 "Impact of Operating Systems on Wireless Sensor Networks 2126 (Security) Applications and Testbeds", Proceedings of 2127 the 19th International Conference on Computer 2128 Communications and Networks (ICCCN), 2010 August. 2130 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2131 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2132 . 2134 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2135 (TLS) Protocol Version 1.2", RFC 5246, 2136 DOI 10.17487/RFC5246, August 2008, . 2139 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2140 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2141 . 2143 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2144 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2145 . 2147 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 2148 Threat Model and Security Considerations", RFC 6819, 2149 DOI 10.17487/RFC6819, January 2013, . 2152 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2153 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2154 October 2013, . 2156 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2157 Constrained-Node Networks", RFC 7228, 2158 DOI 10.17487/RFC7228, May 2014, . 2161 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2162 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2163 DOI 10.17487/RFC7231, June 2014, . 2166 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2167 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2168 . 2170 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 2171 "Assertion Framework for OAuth 2.0 Client Authentication 2172 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 2173 May 2015, . 2175 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 2176 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 2177 RFC 7591, DOI 10.17487/RFC7591, July 2015, 2178 . 2180 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2181 Application Protocol (CoAP)", RFC 7641, 2182 DOI 10.17487/RFC7641, September 2015, . 2185 [RFC7744] Seitz, L., Ed., Gerdes, S., Ed., Selander, G., Mani, M., 2186 and S. Kumar, "Use Cases for Authentication and 2187 Authorization in Constrained Environments", RFC 7744, 2188 DOI 10.17487/RFC7744, January 2016, . 2191 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2192 the Constrained Application Protocol (CoAP)", RFC 7959, 2193 DOI 10.17487/RFC7959, August 2016, . 2196 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2197 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 2198 . 2200 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2201 Interchange Format", STD 90, RFC 8259, 2202 DOI 10.17487/RFC8259, December 2017, . 2205 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 2206 Authorization Server Metadata", RFC 8414, 2207 DOI 10.17487/RFC8414, June 2018, . 2210 Appendix A. Design Justification 2212 This section provides further insight into the design decisions of 2213 the solution documented in this document. Section 3 lists several 2214 building blocks and briefly summarizes their importance. The 2215 justification for offering some of those building blocks, as opposed 2216 to using OAuth 2.0 as is, is given below. 2218 Common IoT constraints are: 2220 Low Power Radio: 2222 Many IoT devices are equipped with a small battery which needs to 2223 last for a long time. For many constrained wireless devices, the 2224 highest energy cost is associated to transmitting or receiving 2225 messages (roughly by a factor of 10 compared to AES) 2226 [Margi10impact]. It is therefore important to keep the total 2227 communication overhead low, including minimizing the number and 2228 size of messages sent and received, which has an impact of choice 2229 on the message format and protocol. By using CoAP over UDP and 2230 CBOR encoded messages, some of these aspects are addressed. 2231 Security protocols contribute to the communication overhead and 2232 can, in some cases, be optimized. For example, authentication and 2233 key establishment may, in certain cases where security 2234 requirements allow, be replaced by provisioning of security 2235 context by a trusted third party, using transport or application 2236 layer security. 2238 Low CPU Speed: 2240 Some IoT devices are equipped with processors that are 2241 significantly slower than those found in most current devices on 2242 the Internet. This typically has implications on what timely 2243 cryptographic operations a device is capable of performing, which 2244 in turn impacts, e.g., protocol latency. Symmetric key 2245 cryptography may be used instead of the computationally more 2246 expensive public key cryptography where the security requirements 2247 so allows, but this may also require support for trusted third 2248 party assisted secret key establishment using transport or 2249 application layer security. 2250 Small Amount of Memory: 2252 Microcontrollers embedded in IoT devices are often equipped with 2253 small amount of RAM and flash memory, which places limitations 2254 what kind of processing can be performed and how much code can be 2255 put on those devices. To reduce code size fewer and smaller 2256 protocol implementations can be put on the firmware of such a 2257 device. In this case, CoAP may be used instead of HTTP, symmetric 2258 key cryptography instead of public key cryptography, and CBOR 2259 instead of JSON. Authentication and key establishment protocol, 2260 e.g., the DTLS handshake, in comparison with assisted key 2261 establishment also has an impact on memory and code. 2263 User Interface Limitations: 2265 Protecting access to resources is both an important security as 2266 well as privacy feature. End users and enterprise customers may 2267 not want to give access to the data collected by their IoT device 2268 or to functions it may offer to third parties. Since the 2269 classical approach of requesting permissions from end users via a 2270 rich user interface does not work in many IoT deployment 2271 scenarios, these functions need to be delegated to user-controlled 2272 devices that are better suitable for such tasks, such as smart 2273 phones and tablets. 2275 Communication Constraints: 2277 In certain constrained settings an IoT device may not be able to 2278 communicate with a given device at all times. Devices may be 2279 sleeping, or just disconnected from the Internet because of 2280 general lack of connectivity in the area, for cost reasons, or for 2281 security reasons, e.g., to avoid an entry point for Denial-of- 2282 Service attacks. 2284 The communication interactions this framework builds upon (as 2285 shown graphically in Figure 1) may be accomplished using a variety 2286 of different protocols, and not all parts of the message flow are 2287 used in all applications due to the communication constraints. 2288 Deployments making use of CoAP are expected, but not limited to, 2289 other protocols such as HTTP, HTTP/2 or other specific protocols, 2290 such as Bluetooth Smart communication, that do not necessarily use 2291 IP could also be used. The latter raises the need for application 2292 layer security over the various interfaces. 2294 In the light of these constraints we have made the following design 2295 decisions: 2297 CBOR, COSE, CWT: 2299 This framework REQUIRES the use of CBOR [RFC7049] as data format. 2300 Where CBOR data needs to be protected, the use of COSE [RFC8152] 2301 is RECOMMENDED. Furthermore where self-contained tokens are 2302 needed, this framework RECOMMENDS the use of CWT [RFC8392]. These 2303 measures aim at reducing the size of messages sent over the wire, 2304 the RAM size of data objects that need to be kept in memory and 2305 the size of libraries that devices need to support. 2307 CoAP: 2309 This framework RECOMMENDS the use of CoAP [RFC7252] instead of 2310 HTTP. This does not preclude the use of other protocols 2311 specifically aimed at constrained devices, like, e.g., Bluetooth 2312 Low Energy (see Section 3.2). This aims again at reducing the 2313 size of messages sent over the wire, the RAM size of data objects 2314 that need to be kept in memory and the size of libraries that 2315 devices need to support. 2317 Access Information: 2319 This framework defines the name "Access Information" for data 2320 concerning the RS that the AS returns to the client in an access 2321 token response (see Section 5.6.2). This includes the "profile" 2322 and the "rs_cnf" parameters. This aims at enabling scenarios, 2323 where a powerful client, supporting multiple profiles, needs to 2324 interact with a RS for which it does not know the supported 2325 profiles and the raw public key. 2327 Proof-of-Possession: 2329 This framework makes use of proof-of-possession tokens, using the 2330 "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession]. A 2331 semantically and syntactically identical request and response 2332 parameter is defined for the token endpoint, to allow requesting 2333 and stating confirmation keys. This aims at making token theft 2334 harder. Token theft is specifically relevant in constrained use 2335 cases, as communication often passes through middle-boxes, which 2336 could be able to steal bearer tokens and use them to gain 2337 unauthorized access. 2339 Auth-Info endpoint: 2341 This framework introduces a new way of providing access tokens to 2342 a RS by exposing a authz-info endpoint, to which access tokens can 2343 be POSTed. This aims at reducing the size of the request message 2344 and the code complexity at the RS. The size of the request 2345 message is problematic, since many constrained protocols have 2346 severe message size limitations at the physical layer (e.g., in 2347 the order of 100 bytes). This means that larger packets get 2348 fragmented, which in turn combines badly with the high rate of 2349 packet loss, and the need to retransmit the whole message if one 2350 packet gets lost. Thus separating sending of the request and 2351 sending of the access tokens helps to reduce fragmentation. 2353 Client Credentials Grant: 2355 This framework RECOMMENDS the use of the client credentials grant 2356 for machine-to-machine communication use cases, where manual 2357 intervention of the resource owner to produce a grant token is not 2358 feasible. The intention is that the resource owner would instead 2359 pre-arrange authorization with the AS, based on the client's own 2360 credentials. The client can the (without manual intervention) 2361 obtain access tokens from the AS. 2363 Introspection: 2365 This framework RECOMMENDS the use of access token introspection in 2366 cases where the client is constrained in a way that it can not 2367 easily obtain new access tokens (i.e. it has connectivity issues 2368 that prevent it from communicating with the AS). In that case 2369 this framework RECOMMENDS the use of a long-term token, that could 2370 be a simple reference. The RS is assumed to be able to 2371 communicate with the AS, and can therefore perform introspection, 2372 in order to learn the claims associated with the token reference. 2373 The advantage of such an approach is that the resource owner can 2374 change the claims associated to the token reference without having 2375 to be in contact with the client, thus granting or revoking access 2376 rights. 2378 Appendix B. Roles and Responsibilities 2380 Resource Owner 2382 * Make sure that the RS is registered at the AS. This includes 2383 making known to the AS which profiles, token_types, scopes, and 2384 key types (symmetric/asymmetric) the RS supports. Also making 2385 it known to the AS which audience(s) the RS identifies itself 2386 with. 2387 * Make sure that clients can discover the AS that is in charge of 2388 the RS. 2389 * If the client-credentials grant is used, make sure that the AS 2390 has the necessary, up-to-date, access control policies for the 2391 RS. 2393 Requesting Party 2395 * Make sure that the client is provisioned the necessary 2396 credentials to authenticate to the AS. 2397 * Make sure that the client is configured to follow the security 2398 requirements of the Requesting Party when issuing requests 2399 (e.g., minimum communication security requirements, trust 2400 anchors). 2401 * Register the client at the AS. This includes making known to 2402 the AS which profiles, token_types, and key types (symmetric/ 2403 asymmetric) the client. 2405 Authorization Server 2407 * Register the RS and manage corresponding security contexts. 2408 * Register clients and authentication credentials. 2409 * Allow Resource Owners to configure and update access control 2410 policies related to their registered RSs. 2411 * Expose the token endpoint to allow clients to request tokens. 2412 * Authenticate clients that wish to request a token. 2413 * Process a token request using the authorization policies 2414 configured for the RS. 2415 * Optionally: Expose the introspection endpoint that allows RS's 2416 to submit token introspection requests. 2417 * If providing an introspection endpoint: Authenticate RSs that 2418 wish to get an introspection response. 2419 * If providing an introspection endpoint: Process token 2420 introspection requests. 2421 * Optionally: Handle token revocation. 2422 * Optionally: Provide discovery metadata. See [RFC8414] 2424 Client 2426 * Discover the AS in charge of the RS that is to be targeted with 2427 a request. 2428 * Submit the token request (see step (A) of Figure 1). 2430 + Authenticate to the AS. 2431 + Optionally (if not pre-configured): Specify which RS, which 2432 resource(s), and which action(s) the request(s) will target. 2433 + If raw public keys (rpk) or certificates are used, make sure 2434 the AS has the right rpk or certificate for this client. 2435 * Process the access token and Access Information (see step (B) 2436 of Figure 1). 2438 + Check that the Access Information provides the necessary 2439 security parameters (e.g., PoP key, information on 2440 communication security protocols supported by the RS). 2442 * Send the token and request to the RS (see step (C) of 2443 Figure 1). 2445 + Authenticate towards the RS (this could coincide with the 2446 proof of possession process). 2447 + Transmit the token as specified by the AS (default is to the 2448 authz-info endpoint, alternative options are specified by 2449 profiles). 2450 + Perform the proof-of-possession procedure as specified by 2451 the profile in use (this may already have been taken care of 2452 through the authentication procedure). 2453 * Process the RS response (see step (F) of Figure 1) of the RS. 2455 Resource Server 2457 * Expose a way to submit access tokens. By default this is the 2458 authz-info endpoint. 2459 * Process an access token. 2461 + Verify the token is from a recognized AS. 2462 + Verify that the token applies to this RS. 2463 + Check that the token has not expired (if the token provides 2464 expiration information). 2465 + Check the token's integrity. 2466 + Store the token so that it can be retrieved in the context 2467 of a matching request. 2468 * Process a request. 2470 + Set up communication security with the client. 2471 + Authenticate the client. 2472 + Match the client against existing tokens. 2473 + Check that tokens belonging to the client actually authorize 2474 the requested action. 2475 + Optionally: Check that the matching tokens are still valid, 2476 using introspection (if this is possible.) 2477 * Send a response following the agreed upon communication 2478 security. 2480 Appendix C. Requirements on Profiles 2482 This section lists the requirements on profiles of this framework, 2483 for the convenience of profile designers. 2485 o Specify the communication protocol the client and RS the must use 2486 (e.g., CoAP). Section 5 and Section 5.6.4.4 2487 o Specify the security protocol the client and RS must use to 2488 protect their communication (e.g., OSCORE or DTLS over CoAP). 2490 This must provide encryption, integrity and replay protection. 2491 Section 5.6.4.4 2492 o Specify how the client and the RS mutually authenticate. 2493 Section 4 2494 o Specify the Content-format of the protocol messages (e.g., 2495 "application/cbor" or "application/cose+cbor"). Section 4 2496 o Specify the proof-of-possession protocol(s) and how to select one, 2497 if several are available. Also specify which key types (e.g., 2498 symmetric/asymmetric) are supported by a specific proof-of- 2499 possession protocol. Section 5.6.4.3 2500 o Specify a unique profile identifier. Section 5.6.4.4 2501 o If introspection is supported: Specify the communication and 2502 security protocol for introspection.Section 5.7 2503 o Specify the communication and security protocol for interactions 2504 between client and AS. Section 5.6 2505 o Specify how/if the authz-info endpoint is protected, including how 2506 error responses are protected. Section 5.8.1 2507 o Optionally define other methods of token transport than the authz- 2508 info endpoint. Section 5.8.1 2510 Appendix D. Assumptions on AS knowledge about C and RS 2512 This section lists the assumptions on what an AS should know about a 2513 client and a RS in order to be able to respond to requests to the 2514 token and introspection endpoints. How this information is 2515 established is out of scope for this document. 2517 o The identifier of the client or RS. 2518 o The profiles that the client or RS supports. 2519 o The scopes that the RS supports. 2520 o The audiences that the RS identifies with. 2521 o The key types (e.g., pre-shared symmetric key, raw public key, key 2522 length, other key parameters) that the client or RS supports. 2523 o The types of access tokens the RS supports (e.g., CWT). 2524 o If the RS supports CWTs, the COSE parameters for the crypto 2525 wrapper (e.g., algorithm, key-wrap algorithm, key-length). 2526 o The expiration time for access tokens issued to this RS (unless 2527 the RS accepts a default time chosen by the AS). 2528 o The symmetric key shared between client or RS and AS (if any). 2529 o The raw public key of the client or RS (if any). 2531 Appendix E. Deployment Examples 2533 There is a large variety of IoT deployments, as is indicated in 2534 Appendix A, and this section highlights a few common variants. This 2535 section is not normative but illustrates how the framework can be 2536 applied. 2538 For each of the deployment variants, there are a number of possible 2539 security setups between clients, resource servers and authorization 2540 servers. The main focus in the following subsections is on how 2541 authorization of a client request for a resource hosted by a RS is 2542 performed. This requires the security of the requests and responses 2543 between the clients and the RS to consider. 2545 Note: CBOR diagnostic notation is used for examples of requests and 2546 responses. 2548 E.1. Local Token Validation 2550 In this scenario, the case where the resource server is offline is 2551 considered, i.e., it is not connected to the AS at the time of the 2552 access request. This access procedure involves steps A, B, C, and F 2553 of Figure 1. 2555 Since the resource server must be able to verify the access token 2556 locally, self-contained access tokens must be used. 2558 This example shows the interactions between a client, the 2559 authorization server and a temperature sensor acting as a resource 2560 server. Message exchanges A and B are shown in Figure 17. 2562 A: The client first generates a public-private key pair used for 2563 communication security with the RS. 2564 The client sends the POST request to the token endpoint at the AS. 2565 The security of this request can be transport or application 2566 layer. It is up the the communication security profile to define. 2567 In the example transport layer identification of the AS is done 2568 and the client identifies with client_id and client_secret as in 2569 classic OAuth. The request contains the public key of the client 2570 and the Audience parameter set to "tempSensorInLivingRoom", a 2571 value that the temperature sensor identifies itself with. The AS 2572 evaluates the request and authorizes the client to access the 2573 resource. 2574 B: The AS responds with a PoP access token and Access Information. 2575 The PoP access token contains the public key of the client, and 2576 the Access Information contains the public key of the RS. For 2577 communication security this example uses DTLS RawPublicKey between 2578 the client and the RS. The issued token will have a short 2579 validity time, i.e., "exp" close to "iat", to protect the RS from 2580 replay attacks. The token includes the claim such as "scope" with 2581 the authorized access that an owner of the temperature device can 2582 enjoy. In this example, the "scope" claim, issued by the AS, 2583 informs the RS that the owner of the token, that can prove the 2584 possession of a key is authorized to make a GET request against 2585 the /temperature resource and a POST request on the /firmware 2586 resource. Note that the syntax and semantics of the scope claim 2587 are application specific. 2588 Note: In this example it is assumed that the client knows what 2589 resource it wants to access, and is therefore able to request 2590 specific audience and scope claims for the access token. 2592 Authorization 2593 Client Server 2594 | | 2595 |<=======>| DTLS Connection Establishment 2596 | | to identify the AS 2597 | | 2598 A: +-------->| Header: POST (Code=0.02) 2599 | POST | Uri-Path:"token" 2600 | | Content-Type: application/cbor 2601 | | Payload: 2602 | | 2603 B: |<--------+ Header: 2.05 Content 2604 | 2.05 | Content-Type: application/cbor 2605 | | Payload: 2606 | | 2608 Figure 17: Token Request and Response Using Client Credentials. 2610 The information contained in the Request-Payload and the Response- 2611 Payload is shown in Figure 18. Note that a TLS/DTLS-based 2612 communication security profile is used in this example. Hence, the 2613 Content-Type is "application/cbor". 2615 Request-Payload : 2616 { 2617 "grant_type" : "client_credentials", 2618 "aud" : "tempSensorInLivingRoom", 2619 "client_id" : "myclient", 2620 "client_secret" : "qwerty" 2621 } 2623 Response-Payload : 2624 { 2625 "access_token" : b64'SlAV32hkKG ...', 2626 "token_type" : "pop", 2627 "csp" : "DTLS", 2628 "rs_cnf" : { 2629 "COSE_Key" : { 2630 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2631 "kty" : "EC", 2632 "crv" : "P-256", 2633 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 2634 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 2635 } 2636 } 2637 } 2639 Figure 18: Request and Response Payload Details. 2641 The content of the access token is shown in Figure 19. 2643 { 2644 "aud" : "tempSensorInLivingRoom", 2645 "iat" : "1360189224", 2646 "exp" : "1360289224", 2647 "scope" : "temperature_g firmware_p", 2648 "cnf" : { 2649 "COSE_Key" : { 2650 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 2651 "kty" : "EC", 2652 "crv" : "P-256", 2653 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 2654 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 2655 } 2656 } 2657 } 2659 Figure 19: Access Token including Public Key of the Client. 2661 Messages C and F are shown in Figure 20 - Figure 21. 2663 C: The client then sends the PoP access token to the authz-info 2664 endpoint at the RS. This is a plain CoAP request, i.e., no 2665 transport or application layer security is used between client and 2666 RS since the token is integrity protected between the AS and RS. 2667 The RS verifies that the PoP access token was created by a known 2668 and trusted AS, is valid, and has been issued to the client. The 2669 RS caches the security context together with authorization 2670 information about this client contained in the PoP access token. 2672 Resource 2673 Client Server 2674 | | 2675 C: +-------->| Header: POST (Code=0.02) 2676 | POST | Uri-Path:"authz-info" 2677 | | Payload: SlAV32hkKG ... 2678 | | 2679 |<--------+ Header: 2.04 Changed 2680 | 2.04 | 2681 | | 2683 Figure 20: Access Token provisioning to RS 2684 The client and the RS runs the DTLS handshake using the raw public 2685 keys established in step B and C. 2686 The client sends the CoAP request GET to /temperature on RS over 2687 DTLS. The RS verifies that the request is authorized, based on 2688 previously established security context. 2689 F: The RS responds with a resource representation over DTLS. 2691 Resource 2692 Client Server 2693 | | 2694 |<=======>| DTLS Connection Establishment 2695 | | using Raw Public Keys 2696 | | 2697 +-------->| Header: GET (Code=0.01) 2698 | GET | Uri-Path: "temperature" 2699 | | 2700 | | 2701 | | 2702 F: |<--------+ Header: 2.05 Content 2703 | 2.05 | Payload: 2704 | | 2706 Figure 21: Resource Request and Response protected by DTLS. 2708 E.2. Introspection Aided Token Validation 2710 In this deployment scenario it is assumed that a client is not able 2711 to access the AS at the time of the access request, whereas the RS is 2712 assumed to be connected to the back-end infrastructure. Thus the RS 2713 can make use of token introspection. This access procedure involves 2714 steps A-F of Figure 1, but assumes steps A and B have been carried 2715 out during a phase when the client had connectivity to AS. 2717 Since the client is assumed to be offline, at least for a certain 2718 period of time, a pre-provisioned access token has to be long-lived. 2719 Since the client is constrained, the token will not be self contained 2720 (i.e. not a CWT) but instead just a reference. The resource server 2721 uses its connectivity to learn about the claims associated to the 2722 access token by using introspection, which is shown in the example 2723 below. 2725 In the example interactions between an offline client (key fob), a RS 2726 (online lock), and an AS is shown. It is assumed that there is a 2727 provisioning step where the client has access to the AS. This 2728 corresponds to message exchanges A and B which are shown in 2729 Figure 22. 2731 Authorization consent from the resource owner can be pre-configured, 2732 but it can also be provided via an interactive flow with the resource 2733 owner. An example of this for the key fob case could be that the 2734 resource owner has a connected car, he buys a generic key that he 2735 wants to use with the car. To authorize the key fob he connects it 2736 to his computer that then provides the UI for the device. After that 2737 OAuth 2.0 implicit flow can used to authorize the key for his car at 2738 the the car manufacturers AS. 2740 Note: In this example the client does not know the exact door it will 2741 be used to access since the token request is not send at the time of 2742 access. So the scope and audience parameters are set quite wide to 2743 start with and new values different form the original once can be 2744 returned from introspection later on. 2746 A: The client sends the request using POST to the token endpoint 2747 at AS. The request contains the Audience parameter set to 2748 "PACS1337" (PACS, Physical Access System), a value the that the 2749 online door in question identifies itself with. The AS generates 2750 an access token as an opaque string, which it can match to the 2751 specific client, a targeted audience and a symmetric key. The 2752 security is provided by identifying the AS on transport layer 2753 using a pre shared security context (psk, rpk or certificate) and 2754 then the client is identified using client_id and client_secret as 2755 in classic OAuth. 2757 B: The AS responds with the an access token and Access 2758 Information, the latter containing a symmetric key. Communication 2759 security between C and RS will be DTLS and PreSharedKey. The PoP 2760 key is used as the PreSharedKey. 2762 Authorization 2763 Client Server 2764 | | 2765 | | 2766 A: +-------->| Header: POST (Code=0.02) 2767 | POST | Uri-Path:"token" 2768 | | Content-Type: application/cbor 2769 | | Payload: 2770 | | 2771 B: |<--------+ Header: 2.05 Content 2772 | | Content-Type: application/cbor 2773 | 2.05 | Payload: 2774 | | 2776 Figure 22: Token Request and Response using Client Credentials. 2778 The information contained in the Request-Payload and the Response- 2779 Payload is shown in Figure 23. 2781 Request-Payload: 2782 { 2783 "grant_type" : "client_credentials", 2784 "aud" : "lockOfDoor4711", 2785 "client_id" : "keyfob", 2786 "client_secret" : "qwerty" 2787 } 2789 Response-Payload: 2790 { 2791 "access_token" : b64'SlAV32hkKG ...' 2792 "token_type" : "pop", 2793 "csp" : "DTLS", 2794 "cnf" : { 2795 "COSE_Key" : { 2796 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2797 "kty" : "oct", 2798 "alg" : "HS256", 2799 "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' 2800 } 2801 } 2802 } 2804 Figure 23: Request and Response Payload for C offline 2806 The access token in this case is just an opaque string referencing 2807 the authorization information at the AS. 2809 C: Next, the client POSTs the access token to the authz-info 2810 endpoint in the RS. This is a plain CoAP request, i.e., no DTLS 2811 between client and RS. Since the token is an opaque string, the 2812 RS cannot verify it on its own, and thus defers to respond the 2813 client with a status code until after step E. 2814 D: The RS forwards the token to the introspection endpoint on the 2815 AS. Introspection assumes a secure connection between the AS and 2816 the RS, e.g., using transport of application layer security. In 2817 the example AS is identified using pre shared security context 2818 (psk, rpk or certificate) while RS is acting as client and is 2819 identified with client_id and client_secret. 2820 E: The AS provides the introspection response containing 2821 parameters about the token. This includes the confirmation key 2822 (cnf) parameter that allows the RS to verify the client's proof of 2823 possession in step F. 2824 After receiving message E, the RS responds to the client's POST in 2825 step C with the CoAP response code 2.01 (Created). 2827 Resource 2828 Client Server 2829 | | 2830 C: +-------->| Header: POST (T=CON, Code=0.02) 2831 | POST | Uri-Path:"authz-info" 2832 | | Content-Type: "application/cbor" 2833 | | Payload: b64'SlAV32hkKG ...'' 2834 | | 2835 | | Authorization 2836 | | Server 2837 | | | 2838 | D: +--------->| Header: POST (Code=0.02) 2839 | | POST | Uri-Path: "introspect" 2840 | | | Content-Type: "application/cbor" 2841 | | | Payload: 2842 | | | 2843 | E: |<---------+ Header: 2.05 Content 2844 | | 2.05 | Content-Type: "application/cbor" 2845 | | | Payload: 2846 | | | 2847 | | 2848 |<--------+ Header: 2.01 Created 2849 | 2.01 | 2850 | | 2852 Figure 24: Token Introspection for C offline 2853 The information contained in the Request-Payload and the Response- 2854 Payload is shown in Figure 25. 2856 Request-Payload: 2857 { 2858 "token" : b64'SlAV32hkKG...', 2859 "client_id" : "FrontDoor", 2860 "client_secret" : "ytrewq" 2861 } 2863 Response-Payload: 2864 { 2865 "active" : true, 2866 "aud" : "lockOfDoor4711", 2867 "scope" : "open, close", 2868 "iat" : 1311280970, 2869 "cnf" : { 2870 "kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 2871 } 2872 } 2874 Figure 25: Request and Response Payload for Introspection 2876 The client uses the symmetric PoP key to establish a DTLS 2877 PreSharedKey secure connection to the RS. The CoAP request PUT is 2878 sent to the uri-path /state on the RS, changing the state of the 2879 door to locked. 2880 F: The RS responds with a appropriate over the secure DTLS 2881 channel. 2883 Resource 2884 Client Server 2885 | | 2886 |<=======>| DTLS Connection Establishment 2887 | | using Pre Shared Key 2888 | | 2889 +-------->| Header: PUT (Code=0.03) 2890 | PUT | Uri-Path: "state" 2891 | | Payload: 2892 | | 2893 F: |<--------+ Header: 2.04 Changed 2894 | 2.04 | Payload: 2895 | | 2897 Figure 26: Resource request and response protected by OSCORE 2899 Appendix F. Document Updates 2901 RFC EDITOR: PLEASE REMOVE THIS SECTION. 2903 F.1. Version -12 to -13 2905 o Changed "Resource Information" to "Access Information" to avoid 2906 confusion. 2907 o Clarified section about AS discovery. 2908 o Editorial changes 2910 F.2. Version -11 to -12 2912 o Moved the Request error handling to a section of its own. 2913 o Require the use of the abbreviation for profile identifiers. 2914 o Added rs_cnf parameter in the introspection response, to inform 2915 RS' with several RPKs on which key to use. 2916 o Allowed use of rs_cnf as claim in the access token in order to 2917 inform an RS with several RPKs on which key to use. 2918 o Clarified that profiles must specify if/how error responses are 2919 protected. 2920 o Fixed label number range to align with COSE/CWT. 2921 o Clarified the requirements language in order to allow profiles to 2922 specify other payload formats than CBOR if they do not use CoAP. 2924 F.3. Version -10 to -11 2926 o Fixed some CBOR data type errors. 2927 o Updated boilerplate text 2929 F.4. Version -09 to -10 2931 o Removed CBOR major type numbers. 2932 o Removed the client token design. 2933 o Rephrased to clarify that other protocols than CoAP can be used. 2934 o Clarifications regarding the use of HTTP 2936 F.5. Version -08 to -09 2938 o Allowed scope to be byte arrays. 2939 o Defined default names for endpoints. 2940 o Refactored the IANA section for briefness and consistency. 2941 o Refactored tables that define IANA registry contents for 2942 consistency. 2943 o Created IANA registry for CBOR mappings of error codes, grant 2944 types and Authorization Server Information. 2945 o Added references to other document sections defining IANA entries 2946 in the IANA section. 2948 F.6. Version -07 to -08 2950 o Moved AS discovery from the DTLS profile to the framework, see 2951 Section 5.1. 2952 o Made the use of CBOR mandatory. If you use JSON you can use 2953 vanilla OAuth. 2954 o Made it mandatory for profiles to specify C-AS security and RS-AS 2955 security (the latter only if introspection is supported). 2956 o Made the use of CBOR abbreviations mandatory. 2957 o Added text to clarify the use of token references as an 2958 alternative to CWTs. 2959 o Added text to clarify that introspection must not be delayed, in 2960 case the RS has to return a client token. 2961 o Added security considerations about leakage through unprotected AS 2962 discovery information, combining profiles and leakage through 2963 error responses. 2964 o Added privacy considerations about leakage through unprotected AS 2965 discovery. 2966 o Added text that clarifies that introspection is optional. 2967 o Made profile parameter optional since it can be implicit. 2968 o Clarified that CoAP is not mandatory and other protocols can be 2969 used. 2970 o Clarified the design justification for specific features of the 2971 framework in appendix A. 2973 o Clarified appendix E.2. 2974 o Removed specification of the "cnf" claim for CBOR/COSE, and 2975 replaced with references to [I-D.ietf-ace-cwt-proof-of-possession] 2977 F.7. Version -06 to -07 2979 o Various clarifications added. 2980 o Fixed erroneous author email. 2982 F.8. Version -05 to -06 2984 o Moved sections that define the ACE framework into a subsection of 2985 the framework Section 5. 2986 o Split section on client credentials and grant into two separate 2987 sections, Section 5.2, and Section 5.3. 2988 o Added Section 5.4 on AS authentication. 2989 o Added Section 5.5 on the Authorization endpoint. 2991 F.9. Version -04 to -05 2993 o Added RFC 2119 language to the specification of the required 2994 behavior of profile specifications. 2995 o Added Section 5.3 on the relation to the OAuth2 grant types. 2996 o Added CBOR abbreviations for error and the error codes defined in 2997 OAuth2. 2998 o Added clarification about token expiration and long-running 2999 requests in Section 5.8.3 3000 o Added security considerations about tokens with symmetric pop keys 3001 valid for more than one RS. 3002 o Added privacy considerations section. 3003 o Added IANA registry mapping the confirmation types from RFC 7800 3004 to equivalent COSE types. 3005 o Added appendix D, describing assumptions about what the AS knows 3006 about the client and the RS. 3008 F.10. Version -03 to -04 3010 o Added a description of the terms "framework" and "profiles" as 3011 used in this document. 3012 o Clarified protection of access tokens in section 3.1. 3013 o Clarified uses of the "cnf" parameter in section 6.4.5. 3014 o Clarified intended use of Client Token in section 7.4. 3016 F.11. Version -02 to -03 3018 o Removed references to draft-ietf-oauth-pop-key-distribution since 3019 the status of this draft is unclear. 3021 o Copied and adapted security considerations from draft-ietf-oauth- 3022 pop-key-distribution. 3023 o Renamed "client information" to "RS information" since it is 3024 information about the RS. 3025 o Clarified the requirements on profiles of this framework. 3026 o Clarified the token endpoint protocol and removed negotiation of 3027 "profile" and "alg" (section 6). 3028 o Renumbered the abbreviations for claims and parameters to get a 3029 consistent numbering across different endpoints. 3030 o Clarified the introspection endpoint. 3031 o Renamed token, introspection and authz-info to "endpoint" instead 3032 of "resource" to mirror the OAuth 2.0 terminology. 3033 o Updated the examples in the appendices. 3035 F.12. Version -01 to -02 3037 o Restructured to remove communication security parts. These shall 3038 now be defined in profiles. 3039 o Restructured section 5 to create new sections on the OAuth 3040 endpoints token, introspection and authz-info. 3041 o Pulled in material from draft-ietf-oauth-pop-key-distribution in 3042 order to define proof-of-possession key distribution. 3043 o Introduced the "cnf" parameter as defined in RFC7800 to reference 3044 or transport keys used for proof of possession. 3045 o Introduced the "client-token" to transport client information from 3046 the AS to the client via the RS in conjunction with introspection. 3047 o Expanded the IANA section to define parameters for token request, 3048 introspection and CWT claims. 3049 o Moved deployment scenarios to the appendix as examples. 3051 F.13. Version -00 to -01 3053 o Changed 5.1. from "Communication Security Protocol" to "Client 3054 Information". 3055 o Major rewrite of 5.1 to clarify the information exchanged between 3056 C and AS in the PoP access token request profile for IoT. 3058 * Allow the client to indicate preferences for the communication 3059 security protocol. 3060 * Defined the term "Client Information" for the additional 3061 information returned to the client in addition to the access 3062 token. 3063 * Require that the messages between AS and client are secured, 3064 either with (D)TLS or with COSE_Encrypted wrappers. 3065 * Removed dependency on OSCOAP and added generic text about 3066 object security instead. 3067 * Defined the "rpk" parameter in the client information to 3068 transmit the raw public key of the RS from AS to client. 3070 * (D)TLS MUST use the PoP key in the handshake (either as PSK or 3071 as client RPK with client authentication). 3072 * Defined the use of x5c, x5t and x5tS256 parameters when a 3073 client certificate is used for proof of possession. 3074 * Defined "tktn" parameter for signaling for how to transfer the 3075 access token. 3076 o Added 5.2. the CoAP Access-Token option for transferring access 3077 tokens in messages that do not have payload. 3078 o 5.3.2. Defined success and error responses from the RS when 3079 receiving an access token. 3080 o 5.6.:Added section giving guidance on how to handle token 3081 expiration in the absence of reliable time. 3082 o Appendix B Added list of roles and responsibilities for C, AS and 3083 RS. 3085 Authors' Addresses 3087 Ludwig Seitz 3088 RISE SICS 3089 Scheelevaegen 17 3090 Lund 223 70 3091 Sweden 3093 Email: ludwig.seitz@ri.se 3095 Goeran Selander 3096 Ericsson 3097 Faroegatan 6 3098 Kista 164 80 3099 Sweden 3101 Email: goran.selander@ericsson.com 3103 Erik Wahlstroem 3104 Sweden 3106 Email: erik@wahlstromstekniska.se 3108 Samuel Erdtman 3109 Spotify AB 3110 Birger Jarlsgatan 61, 4tr 3111 Stockholm 113 56 3112 Sweden 3114 Email: erdtman@spotify.com 3115 Hannes Tschofenig 3116 Arm Ltd. 3117 Absam 6067 3118 Austria 3120 Email: Hannes.Tschofenig@arm.com