idnits 2.17.1 draft-ietf-ace-oauth-authz-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 19, 2017) is 2381 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 (-15) exists of draft-ietf-ace-cbor-web-token-08 ** 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 (-02) exists of draft-erdtman-ace-rpcc-01 == Outdated reference: A later version (-07) exists of draft-ietf-ace-actors-05 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-05 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-11 == Outdated reference: A later version (-15) exists of draft-ietf-oauth-device-flow-06 == Outdated reference: A later version (-10) exists of draft-ietf-oauth-discovery-07 -- 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 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 5 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: April 22, 2018 Ericsson 6 E. Wahlstroem 7 (no affiliation) 8 S. Erdtman 9 Spotify AB 10 H. Tschofenig 11 ARM Ltd. 12 October 19, 2017 14 Authentication and Authorization for Constrained Environments (ACE) 15 draft-ietf-ace-oauth-authz-08 17 Abstract 19 This specification defines a framework for authentication and 20 authorization in Internet of Things (IoT) environments. The 21 framework is based on a set of building blocks including OAuth 2.0 22 and CoAP, thus making a well-known and widely used authorization 23 solution suitable for IoT devices. Existing specifications are used 24 where possible, but where the constraints of IoT devices require it, 25 extensions are added and profiles are defined. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on April 22, 2018. 44 Copyright Notice 46 Copyright (c) 2017 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 7 65 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 66 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10 67 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14 68 5.1. Discovering Authorization Servers . . . . . . . . . . . . 15 69 5.1.1. Unauthorized Resource Request Message . . . . . . . . 15 70 5.1.2. AS Information . . . . . . . . . . . . . . . . . . . 16 71 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17 72 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 18 73 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18 74 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18 75 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 19 76 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 19 77 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 22 78 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 24 79 5.6.4. Request and Response Parameters . . . . . . . . . . . 25 80 5.6.4.1. Audience . . . . . . . . . . . . . . . . . . . . 25 81 5.6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 25 82 5.6.4.3. Token Type . . . . . . . . . . . . . . . . . . . 26 83 5.6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 26 84 5.6.4.5. Confirmation . . . . . . . . . . . . . . . . . . 26 85 5.6.5. Mapping parameters to CBOR . . . . . . . . . . . . . 27 86 5.7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 28 87 5.7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 29 88 5.7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 29 89 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 30 90 5.7.4. Client Token . . . . . . . . . . . . . . . . . . . . 31 91 5.7.5. Mapping Introspection parameters to CBOR . . . . . . 33 92 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 33 93 5.8.1. The 'Authorization Information' Endpoint . . . . . . 34 94 5.8.2. Token Expiration . . . . . . . . . . . . . . . . . . 35 95 6. Security Considerations . . . . . . . . . . . . . . . . . . . 36 96 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 37 97 6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 37 98 6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 37 99 6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 37 100 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 38 101 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 102 8.1. OAuth Introspection Response Parameter Registration . . . 39 103 8.2. OAuth Parameter Registration . . . . . . . . . . . . . . 39 104 8.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 40 105 8.4. OAuth Token Type CBOR Mappings . . . . . . . . 40 106 8.4.1. Registration Template . . . . . . . . . . . . . . . . 40 107 8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 40 108 8.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 41 109 8.6. ACE OAuth Profile Registry . . . . . . . . . . . . . . . 41 110 8.6.1. Registration Template . . . . . . . . . . . . . . . . 41 111 8.7. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 41 112 8.7.1. Registration Template . . . . . . . . . . . . . . . . 42 113 8.7.2. Initial Registry Contents . . . . . . . . . . . . . . 42 114 8.8. Introspection Endpoint CBOR Mappings Registry . . . . . . 44 115 8.8.1. Registration Template . . . . . . . . . . . . . . . . 44 116 8.8.2. Initial Registry Contents . . . . . . . . . . . . . . 45 117 8.9. CoAP Option Number Registration . . . . . . . . . . . . . 47 118 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47 119 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 120 10.1. Normative References . . . . . . . . . . . . . . . . . . 48 121 10.2. Informative References . . . . . . . . . . . . . . . . . 49 122 Appendix A. Design Justification . . . . . . . . . . . . . . . . 51 123 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 55 124 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 57 125 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 58 126 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 58 127 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 58 128 E.2. Introspection Aided Token Validation . . . . . . . . . . 62 129 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 66 130 F.1. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 66 131 F.2. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 67 132 F.3. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 67 133 F.4. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 67 134 F.5. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 67 135 F.6. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 67 136 F.7. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 68 137 F.8. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 68 138 F.9. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 68 139 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 69 141 1. Introduction 143 Authorization is the process for granting approval to an entity to 144 access a resource [RFC4949]. The authorization task itself can best 145 be described as granting access to a requesting client, for a 146 resource hosted on a device, the resource server (RS). This exchange 147 is mediated by one or multiple authorization servers (AS). Managing 148 authorization for a large number of devices and users can be a 149 complex task. 151 While prior work on authorization solutions for the Web and for the 152 mobile environment also applies to the Internet of Things (IoT) 153 environment, many IoT devices are constrained, for example, in terms 154 of processing capabilities, available memory, etc. For web 155 applications on constrained nodes, this specification RECOMMENDS the 156 use of CoAP [RFC7252] as replacement for HTTP. 158 A detailed treatment of constraints can be found in [RFC7228], and 159 the different IoT deployments present a continuous range of device 160 and network capabilities. Taking energy consumption as an example: 161 At one end there are energy-harvesting or battery powered devices 162 which have a tight power budget, on the other end there are mains- 163 powered devices, and all levels in between. 165 Hence, IoT devices may be very different in terms of available 166 processing and message exchange capabilities and there is a need to 167 support many different authorization use cases [RFC7744]. 169 This specification describes a framework for authentication and 170 authorization in constrained environments (ACE) built on re-use of 171 OAuth 2.0 [RFC6749], thereby extending authorization to Internet of 172 Things devices. This specification contains the necessary building 173 blocks for adjusting OAuth 2.0 to IoT environments. 175 More detailed, interoperable specifications can be found in profiles. 176 Implementations may claim conformance with a specific profile, 177 whereby implementations utilizing the same profile interoperate while 178 implementations of different profiles are not expected to be 179 interoperable. Some devices, such as mobile phones and tablets, may 180 implement multiple profiles and will therefore be able to interact 181 with a wider range of low end devices. Requirements on profiles are 182 described at contextually appropriate places throughout this 183 specification, and also summarized in Appendix C. 185 2. Terminology 187 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 188 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 189 "OPTIONAL" in this document are to be interpreted as described in 190 [RFC2119]. 192 Certain security-related terms such as "authentication", 193 "authorization", "confidentiality", "(data) integrity", "message 194 authentication code", and "verify" are taken from [RFC4949]. 196 Since exchanges in this specification are described as RESTful 197 protocol interactions, HTTP [RFC7231] offers useful terminology. 199 Terminology for entities in the architecture is defined in OAuth 2.0 200 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 201 server (RS), and authorization server (AS). 203 Note that the term "endpoint" is used here following its OAuth 204 definition, which is to denote resources such as token and 205 introspection at the AS and authz-info at the RS (see Section 5.8.1 206 for a definition of the authz-info endpoint). The CoAP [RFC7252] 207 definition, which is "An entity participating in the CoAP protocol" 208 is not used in this specification. 210 Since this specification focuses on the problem of access control to 211 resources, the actors has been simplified by assuming that the client 212 authorization server (CAS) functionality is not stand-alone but 213 subsumed by either the authorization server or the client (see 214 section 2.2 in [I-D.ietf-ace-actors]). 216 The specifications in this document is called the "framework" or "ACE 217 framework". When referring to "profiles of this framework" it refers 218 to additional specifications that define the use of this 219 specification with concrete transport, and communication security 220 protocols (e.g., CoAP over DTLS). 222 We use the term "RS Information" for parameters describing 223 characteristics of the RS (e.g. public key) that the AS provides to 224 the client. 226 3. Overview 228 This specification defines the ACE framework for authorization in the 229 Internet of Things environment. It consists of a set of building 230 blocks. 232 The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys 233 widespread deployment. Many IoT devices can support OAuth 2.0 234 without any additional extensions, but for certain constrained 235 settings additional profiling is needed. 237 Another building block is the lightweight web transfer protocol CoAP 238 [RFC7252], for those communication environments where HTTP is not 239 appropriate. CoAP typically runs on top of UDP, which further 240 reduces overhead and message exchanges. While this specification 241 defines extensions for the use of OAuth over CoAP, other underlying 242 protocols are not prohibited from beeing supported in the future, 243 such as HTTP/2, MQTT, BLE and QUIC. 245 A third building block is CBOR [RFC7049], for encodings where JSON 246 [RFC7159] is not sufficiently compact. CBOR is a binary encoding 247 designed for small code and message size, which may be used for 248 encoding of self contained tokens, and also for encoding payload 249 transferred in protocol messages. 251 A fourth building block is the compact CBOR-based secure message 252 format COSE [RFC8152], which enables application layer security as an 253 alternative or complement to transport layer security (DTLS [RFC6347] 254 or TLS [RFC5246]). COSE is used to secure self-contained tokens such 255 as proof-of-possession (PoP) tokens, which is an extension to the 256 OAuth tokens, and "client tokens" which are defined in this framework 257 (see Section 5.7.4). The default token format is defined in CBOR web 258 token (CWT) [I-D.ietf-ace-cbor-web-token]. Application layer 259 security for CoAP using COSE can be provided with OSCOAP 260 [I-D.ietf-core-object-security]. 262 With the building blocks listed above, solutions satisfying various 263 IoT device and network constraints are possible. A list of 264 constraints is described in detail in RFC 7228 [RFC7228] and a 265 description of how the building blocks mentioned above relate to the 266 various constraints can be found in Appendix A. 268 Luckily, not every IoT device suffers from all constraints. The ACE 269 framework nevertheless takes all these aspects into account and 270 allows several different deployment variants to co-exist, rather than 271 mandating a one-size-fits-all solution. It is important to cover the 272 wide range of possible interworking use cases and the different 273 requirements from a security point of view. Once IoT deployments 274 mature, popular deployment variants will be documented in the form of 275 ACE profiles. 277 3.1. OAuth 2.0 279 The OAuth 2.0 authorization framework enables a client to obtain 280 scoped access to a resource with the permission of a resource owner. 281 Authorization information, or references to it, is passed between the 282 nodes using access tokens. These access tokens are issued to clients 283 by an authorization server with the approval of the resource owner. 284 The client uses the access token to access the protected resources 285 hosted by the resource server. 287 A number of OAuth 2.0 terms are used within this specification: 289 The token and introspection Endpoints: 291 The AS hosts the token endpoint that allows a client to request 292 access tokens. The client makes a POST request to the token 293 endpoint on the AS and receives the access token in the response 294 (if the request was successful). 296 In some deployments, a token introspection endpoint is provied by 297 the AS, which can be used by the RS if it needs to request 298 additional information regarding a received access token. The RS 299 makes a POST request to the introspecton endpoint on the AS and 300 receives information about the access token in the response. (See 301 "Introspection" below.) 303 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: 317 An access token may be bound to a cryptographic key, which is then 318 used by an RS to authenticate requests from a client. Such tokens 319 are called proof-of-possession access tokens (or PoP access 320 tokens). 322 The proof-of-possession (PoP) security concept assumes that the AS 323 acts as a trusted third party that binds keys to access tokens. 324 These so called PoP keys are then used by the client to 325 demonstrate the possession of the secret to the RS when accessing 326 the resource. The RS, when receiving an access token, needs to 327 verify that the key used by the client matches the one bound to 328 the access token. When this specification uses the term "access 329 token" it is assumed to be a PoP access token token unless 330 specifically stated otherwise. 332 The key bound to the access token (the PoP key) may use either 333 symmetric or asymmetric cryptography. The appropriate choice of 334 the kind of cryptography depends on the constraints of the IoT 335 devices as well as on the security requirements of the use case. 337 Symmetric PoP key: The AS generates a random symmetric PoP key. 338 The key is either stored to be returned on introspection calls 339 or encrypted and included in the access token. The PoP key is 340 also encrypted for the client and sent together with the access 341 token to the client. 343 Asymmetric PoP key: An asymmetric key pair is generated on the 344 client and the public key is sent to the AS (if it does not 345 already have knowledge of the client's public key). 346 Information about the public key, which is the PoP key in this 347 case, is either stored to be returned on introspection calls or 348 included inside the access token and sent back to the 349 requesting client. The RS can identify the client's public key 350 from the information in the token, which allows the client to 351 use the corresponding private key for the proof of possession. 353 The access token is either a simple reference, or a structured 354 information object (e.g., CWT [I-D.ietf-ace-cbor-web-token]), 355 protected by a cryptographic wrapper (e.g., COSE [RFC8152]). The 356 choice of PoP key does not necessarily imply a specific credential 357 type for the integrity protection of the token. 359 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 uses CBOR encoding as data formt, defined in Section 5, to request 367 scopes and to be informed what scopes the access token actually 368 authorizes. 370 The values of the scope parameter are expressed as a list of 371 space-delimited, case-sensitive strings, with a semantic that is 372 well-known to the AS and the RS. More details about the concept 373 of scopes is found under Section 3.3 in [RFC6749]. 375 Claims: 377 Information carried in the access token or returned from 378 introspection, called claims, is in the form of name-value pairs. 379 An access token may, for example, include a claim identifying the 380 AS that issued the token (via the "iss" claim) and what audience 381 the access token is intended for (via the "aud" claim). The 382 audience of an access token can be a specific resource or one or 383 many resource servers. The resource owner policies influence what 384 claims are put into the access token by the authorization server. 386 While the structure and encoding of the access token varies 387 throughout deployments, a standardized format has been defined 388 with the JSON Web Token (JWT) [RFC7519] where claims are encoded 389 as a JSON object. In [I-D.ietf-ace-cbor-web-token], an equivalent 390 format using CBOR encoding (CWT) has been defined. 392 Introspection: 394 Introspection is a method for a resource server to query the 395 authorization server for the active state and content of a 396 received access token. This is particularly useful in those cases 397 where the authorization decisions are very dynamic and/or where 398 the received access token itself is an opaque reference rather 399 than a self-contained token. More information about introspection 400 in OAuth 2.0 can be found in [RFC7662]. 402 3.2. CoAP 404 CoAP is an application layer protocol similar to HTTP, but 405 specifically designed for constrained environments. CoAP typically 406 uses datagram-oriented transport, such as UDP, where reordering and 407 loss of packets can occur. A security solution needs to take the 408 latter aspects into account. 410 While HTTP uses headers and query strings to convey additional 411 information about a request, CoAP encodes such information into 412 header parameters called 'options'. 414 CoAP supports application-layer fragmentation of the CoAP payloads 415 through blockwise transfers [RFC7959]. However, blockwise transfer 416 does not increase the size limits of CoAP options, therefore data 417 encoded in options has to be kept small. 419 Transport layer security for CoAP can be provided by DTLS 1.2 420 [RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy 421 operations that require transport layer security to be terminated at 422 the proxy. One approach for protecting CoAP communication end-to-end 423 through proxies, and also to support security for CoAP over a 424 different transport in a uniform way, is to provide security at the 425 application layer using an object-based security mechanism such as 426 COSE [RFC8152]. 428 One application of COSE is OSCOAP [I-D.ietf-core-object-security], 429 which provides end-to-end confidentiality, integrity and replay 430 protection, and a secure binding between CoAP request and response 431 messages. In OSCOAP, the CoAP messages are wrapped in COSE objects 432 and sent using CoAP. 434 This framework RECOMMENDS the use of CoAP as replacement for HTTP. 436 4. Protocol Interactions 438 The ACE framework is based on the OAuth 2.0 protocol interactions 439 using the token endpoint and optionally the introspection endpoint. 440 A client obtains an access token from an AS using the token endpoint 441 and subsequently presents the access token to a RS to gain access to 442 a protected resource. In most deployments the RS can process the 443 access token locally, however in some cases the RS may present it to 444 the AS via the introspection endpoint to get fresh information. 445 These interactions are shown in Figure 1. An overview of various 446 OAuth concepts is provided in Section 3.1. 448 The OAuth 2.0 framework defines a number of "protocol flows" via 449 grant types, which have been extended further with extensions to 450 OAuth 2.0 (such as RFC 7521 [RFC7521] and 451 [I-D.ietf-oauth-device-flow]). What grant types works best depends 452 on the usage scenario and RFC 7744 [RFC7744] describes many different 453 IoT use cases but there are two preferred grant types, namely the 454 Authorization Code Grant (described in Section 4.1 of [RFC7521]) and 455 the Client Credentials Grant (described in Section 4.4 of [RFC7521]). 456 The Authorization Code Grant is a good fit for use with apps running 457 on smart phones and tablets that request access to IoT devices, a 458 common scenario in the smart home environment, where users need to go 459 through an authentication and authorization phase (at least during 460 the initial setup phase). The native apps guidelines described in 461 [I-D.ietf-oauth-native-apps] are applicable to this use case. The 462 Client Credential Grant is a good fit for use with IoT devices where 463 the OAuth client itself is constrained. In such a case, the resource 464 owner has pre-arranged access rights for the client with the 465 authorization server, which is often accomplished using a 466 commissioning tool. 468 The consent of the resource owner, for giving a client access to a 469 protected resource, can be provided dynamically as in the traditional 470 OAuth flows, or it could be pre-configured by the resource owner as 471 authorization policies at the AS, which the AS evaluates when a token 472 request arrives. The resource owner and the requesting party (i.e., 473 client owner) are not shown in Figure 1. 475 This framework supports a wide variety of communication security 476 mechanisms between the ACE entities, such as client, AS, and RS. It 477 is assumed that the client has been registered (also called enrolled 478 or onboarded) to an AS using a mechanism defined outside the scope of 479 this document. In practice, various techniques for onboarding have 480 been used, such as factory-based provisioning or the use of 481 commissioning tools. Regardless of the onboarding technique, this 482 provisioning procedure implies that the client and the AS exchange 483 credentials and configuration parameters. These credentials are used 484 to mutually authenticate each other and to protect messages exchanged 485 between the client and the AS. 487 It is also assumed that the RS has been registered with the AS, 488 potentially in a similar way as the client has been registered with 489 the AS. Established keying material between the AS and the RS allows 490 the AS to apply cryptographic protection to the access token to 491 ensure that its content cannot be modified, and if needed, that the 492 content is confidentiality protected. 494 The keying material necessary for establishing communication security 495 between C and RS is dynamically established as part of the protocol 496 described in this document. 498 At the start of the protocol, there is an optional discovery step 499 where the client discovers the resource server and the resources this 500 server hosts. In this step, the client might also determine what 501 permissions are needed to access the protected resource. A generic 502 procedure is described in Section 5.1, profiles MAY define other 503 procedures for discovery. 505 In Bluetooth Low Energy, for example, advertisements are broadcasted 506 by a peripheral, including information about the primary services. 507 In CoAP, as a second example, a client can make a request to "/.well- 508 known/core" to obtain information about available resources, which 509 are returned in a standardized format as described in [RFC6690]. 511 +--------+ +---------------+ 512 | |---(A)-- Token Request ------->| | 513 | | | Authorization | 514 | |<--(B)-- Access Token ---------| Server | 515 | | + RS Information | | 516 | | +---------------+ 517 | | ^ | 518 | | Introspection Request (D)| | 519 | Client | (optional) | | 520 | | Response + Client Token | |(E) 521 | | (optional) | v 522 | | +--------------+ 523 | |---(C)-- Token + Request ----->| | 524 | | | Resource | 525 | |<--(F)-- Protected Resource ---| Server | 526 | | | | 527 +--------+ +--------------+ 529 Figure 1: Basic Protocol Flow. 531 Requesting an Access Token (A): 533 The client makes an access token request to the token endpoint at 534 the AS. This framework assumes the use of PoP access tokens (see 535 Section 3.1 for a short description) wherein the AS binds a key to 536 an access token. The client may include permissions it seeks to 537 obtain, and information about the credentials it wants to use 538 (e.g., symmetric/asymmetric cryptography or a reference to a 539 specific credential). 541 Access Token Response (B): 543 If the AS successfully processes the request from the client, it 544 returns an access token. It can also return additional 545 parameters, referred to as "RS Information". In addition to the 546 response parameters defined by OAuth 2.0 and the PoP access token 547 extension, this framework defines parameters that can be used to 548 inform the client about capabilities of the RS. More information 549 about these parameters can be found in Section 5.6.4. 551 Resource Request (C): 553 The client interacts with the RS to request access to the 554 protected resource and provides the access token. The protocol to 555 use between the client and the RS is not restricted to CoAP. 556 HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also 557 viable candidates. 559 Depending on the device limitations and the selected protocol, 560 this exchange may be split up into two parts: 562 (1) the client sends the access token containing, or 563 referencing, the authorization information to the RS, that may 564 be used for subsequent resource requests by the client, and 565 (2) the client makes the resource access request, using the 566 communication security protocol and other RS Information 567 obtained from the AS. 569 The Client and the RS mutually authenticate using the security 570 protocol specified in the profile (see step B) and the keys 571 obtained in the access token or the RS Information or the client 572 token. The RS verifies that the token is integrity protected by 573 the AS and compares the claims contained in the access token with 574 the resource request. If the RS is online, validation can be 575 handed over to the AS using token introspection (see messages D 576 and E) over HTTP or CoAP, in which case the different parts of 577 step C may be interleaved with introspection. 579 Token Introspection Request (D): 581 A resource server may be configured to introspect the access token 582 by including it in a request to the introspection endpoint at that 583 AS. Token introspection over CoAP is defined in Section 5.7 and 584 for HTTP in [RFC7662]. 586 Note that token introspection is an optional step and can be 587 omitted if the token is self-contained and the resource server is 588 prepared to perform the token validation on its own. 590 Token Introspection Response (E): 592 The AS validates the token and returns the most recent parameters, 593 such as scope, audience, validity etc. associated with it back to 594 the RS. The RS then uses the received parameters to process the 595 request to either accept or to deny it. The AS can additionally 596 return information that the RS needs to pass on to the client in 597 the form of a client token. The latter is used to establish keys 598 for mutual authentication between client and RS, when the client 599 has no direct connectivity to the AS, see Section 5.7.4 for 600 details. 602 Protected Resource (F): 604 If the request from the client is authorized, the RS fulfills the 605 request and returns a response with the appropriate response code. 607 The RS uses the dynamically established keys to protect the 608 response, according to used communication security protocol. 610 5. Framework 612 The following sections detail the profiling and extensions of OAuth 613 2.0 for constrained environments, which constitutes the ACE 614 framework. 616 Credential Provisioning 618 For IoT, it cannot be assumed that the client and RS are part of a 619 common key infrastructure, so the AS provisions credentials or 620 associated information to allow mutual authentication. These 621 credentials need to be provided to the parties before or during 622 the authentication protocol is executed, and may be re-used for 623 subsequent token requests. 625 Proof-of-Possession 627 The ACE framework, by default, implements proof-of-possession for 628 access tokens, i.e., that the token holder can prove being a 629 holder of the key bound to the token. The binding is provided by 630 the "cnf" claim [I-D.jones-ace-cwt-proof-of-possession] indicating 631 what key is used for proof-of-possession. If a client needs to 632 submit a new access token e.g., to obtain additional access 633 rights, they can request that the AS binds this token to the same 634 key as the previous one. 636 ACE Profiles 638 The client or RS may be limited in the encodings or protocols it 639 supports. To support a variety of different deployment settings, 640 specific interactions between client and RS are defined in an ACE 641 profile. In ACE framework the AS is expected to manage the 642 matching of compatible profile choices between a client and an RS. 643 The AS informs the client of the selected profile using the 644 "profile" parameter in the token response. 646 OAuth 2.0 requires the use of TLS both to protect the communication 647 between AS and client when requesting an access token; between client 648 and RS when accessing a resource and between AS and RS if 649 introspection is used. In constrained settings TLS is not always 650 feasible, or desirable. Nevertheless it is REQUIRED that the data 651 exchanged with the AS is encrypted and integrity protected. It is 652 furthermore REQUIRED that the AS and the endpoint communicating with 653 it (client or RS) perform mutual authentication. 655 Profiles MUST specify how mutual authentication is done, depending 656 e.g. on the communication protocol and the credentials used by the 657 client or the RS. 659 In OAuth 2.0 the communication with the Token and the Introspection 660 endpoints at the AS is assumed to be via HTTP and may use Uri-query 661 parameters. This framework RECOMMENDS to use CoAP instead and 662 RECOMMENDS the use of the following alternative instead of Uri-query 663 parameters: The sender (client or RS) encodes the parameters of its 664 request as a CBOR map and submits that map as the payload of the POST 665 request. The Content-format depends on the security applied to the 666 content and MUST be specified by the profile that is used. 668 The OAuth 2.0 AS uses a JSON structure in the payload of its 669 responses both to client and RS. This framework REQUIRES the use of 670 CBOR [RFC7049] instead. Depending on the profile, the CBOR payload 671 MAY be enclosed in a non-CBOR cryptographic wrapper. 673 5.1. Discovering Authorization Servers 675 In order to determine the AS in charge of a resource hosted at the 676 RS, C MAY send an initial Unauthorized Resource Request message to 677 RS. RS then denies the request and sends the address of its AS back 678 to C. 680 Instead of the initial Unauthorized Resource Request message, C MAY 681 look up the desired resource in a resource directory (cf. 682 [I-D.ietf-core-resource-directory]). 684 5.1.1. Unauthorized Resource Request Message 686 The optional Unauthorized Resource Request message is a request for a 687 resource hosted by RS for which no proper authorization is granted. 688 RS MUST treat any request for a protected resource as Unauthorized 689 Resource Request message when any of the following holds: 691 o The request has been received on an unprotected channel. 692 o RS has no valid access token for the sender of the request 693 regarding the requested action on that resource. 694 o RS has a valid access token for the sender of the request, but 695 this does not allow the requested action on the requested 696 resource. 698 Note: These conditions ensure that RS can handle requests 699 autonomously once access was granted and a secure channel has been 700 established between C and RS. The authz-info endpoint MUST NOT be 701 protected as specified above, in order to allow clients to upload 702 access tokens to RS (cf. Section 5.8.1). 704 Unauthorized Resource Request messages MUST be denied with a client 705 error response. In this response, the Resource Server SHOULD provide 706 proper AS Information to enable the Client to request an access token 707 from RS's AS as described in Section 5.1.2. 709 The response code MUST be 4.01 (Unauthorized) in case the sender of 710 the Unauthorized Resource Request message is not authenticated, or if 711 RS has no valid access token for C. If RS has an access token for C 712 but not for the resource that C has requested, RS MUST reject the 713 request with a 4.03 (Forbidden). If RS has an access token for C but 714 it does not cover the action C requested on the resource, RS MUST 715 reject the request with a 4.05 (Method Not Allowed). 717 Note: The use of the response codes 4.03 and 4.05 is intended to 718 prevent infinite loops where a dumb Client optimistically tries to 719 access a requested resource with any access token received from AS. 720 As malicious clients could pretend to be C to determine C's 721 privileges, these detailed response codes must be used only when a 722 certain level of security is already available which can be achieved 723 only when the Client is authenticated. 725 5.1.2. AS Information 727 The AS Information is sent by RS as a response to an Unauthorized 728 Resource Request message (see Section 5.1.1) to point the sender of 729 the Unauthorized Resource Request message to RS's AS. The AS 730 information is a set of attributes containing an absolute URI (see 731 Section 4.3 of [RFC3986]) that specifies the AS in charge of RS. 733 The message MAY also contain a nonce generated by RS to ensure 734 freshness in case that the RS and AS do not have synchronized clocks. 736 Figure 2 summarizes the parameters that may be part of the AS 737 Information. 739 /----------------+----------+-------------------\ 740 | Parameter name | CBOR Key | Major Type | 741 |----------------+----------+-------------------| 742 | AS | 0 | 3 (text string) | 743 | nonce | 5 | 2 (byte string) | 744 \----------------+----------+-------------------/ 746 Figure 2: AS Information parameters 748 Figure 3 shows an example for an AS Information message payload using 749 CBOR [RFC7049] diagnostic notation, using the parameter names instead 750 of the CBOR keys for better human readability. 752 4.01 Unauthorized 753 Content-Format: application/ace+cbor 754 {AS: "coaps://as.example.com/token", 755 nonce: h'e0a156bb3f'} 757 Figure 3: AS Information payload example 759 In this example, the attribute AS points the receiver of this message 760 to the URI "coaps://as.example.com/token" to request access 761 permissions. The originator of the AS Information payload (i.e., RS) 762 uses a local clock that is loosely synchronized with a time scale 763 common between RS and AS (e.g., wall clock time). Therefore, it has 764 included a parameter "nonce" for replay attack prevention. 766 Note: There is an ongoing discussion how freshness of access 767 tokens 768 can be achieved in constrained environments. This specification 769 for now assumes that RS and AS do not have a common understanding 770 of time that allows RS to achieve its security objectives without 771 explicitly adding a nonce. 773 Figure 4 illustrates the mandatory to use binary encoding of the 774 message payload shown in Figure 3. 776 a2 # map(2) 777 00 # unsigned(0) (=AS) 778 78 1c # text(28) 779 636f6170733a2f2f61732e657861 780 6d706c652e636f6d2f746f6b656e # "coaps://as.example.com/token" 781 05 # unsigned(5) (=nonce) 782 45 # bytes(5) 783 e0a156bb3f 785 Figure 4: AS Information example encoded in CBOR 787 5.2. Authorization Grants 789 To request an access token, the client obtains authorization from the 790 resource owner or uses its client credentials as grant. The 791 authorization is expressed in the form of an authorization grant. 793 The OAuth framework defines four grant types. The grant types can be 794 split up into two groups, those granted on behalf of the resource 795 owner (password, authorization code, implicit) and those for the 796 client (client credentials). 798 The grant type is selected depending on the use case. In cases where 799 the client acts on behalf of the resource owner, authorization code 800 grant is recommended. If the client acts on behalf of the resource 801 owner, but does not have any display or very limited interaction 802 possibilities it is recommended to use the device code grant defined 803 in [I-D.ietf-oauth-device-flow]. In cases where the client does not 804 act on behalf of the resource owner, client credentials grant is 805 recommended. 807 For details on the different grant types, see the OAuth 2.0 framework 808 [RFC6749]. The OAuth 2.0 framework provides an extension mechanism 809 for defining additional grant types so profiles of this framework MAY 810 define additional grant types, if needed. 812 5.3. Client Credentials 814 Authentication of the client is mandatory independent of the grant 815 type when requesting the access token from the token endpoint. In 816 the case of client credentials grant type, the authentication and 817 grant coincide. 819 Client registration and provisioning of client credentials to the 820 client is out of scope for this specification. 822 The OAuth framework [RFC6749] defines one client credential type, 823 client id and client secret. [I-D.erdtman-ace-rpcc] adds raw-public- 824 key and pre-shared-key to the client credentials types. Profiles of 825 this framework MAY extend with additional client credentials client 826 certificates. 828 5.4. AS Authentication 830 Client credential does not, by default, authenticate the AS that the 831 client connects to. In classic OAuth, the AS is authenticated with a 832 TLS server certificate. 834 Profiles of this framework MUST specify how clients authenticate the 835 AS and how communication security is implemented, otherwise server 836 side TLS certificates, as defined by OAuth 2.0, are required. 838 5.5. The Authorization Endpoint 840 The authorization endpoint is used to interact with the resource 841 owner and obtain an authorization grant in certain grant flows. 842 Since it requires the use of a user agent (i.e., browser), it is not 843 expected that these types of grant flow will be used by constrained 844 clients. This endpoint is therefore out of scope for this 845 specification. Implementations should use the definition and 846 recommendations of [RFC6749] and [RFC6819]. 848 If clients involved cannot support HTTP and TLS, profiles MAY define 849 mappings for the authorization endpoint. 851 5.6. The Token Endpoint 853 In standard OAuth 2.0, the AS provides the token endpoint for 854 submitting access token requests. This framework extends the 855 functionality of the token endpoint, giving the AS the possibility to 856 help the client and RS to establish shared keys or to exchange their 857 public keys. Furthermore, this framework defines encodings using 858 CBOR, as a substitute for JSON. 860 For the AS to be able to issue a token, the client MUST be 861 authenticated and present a valid grant for the scopes requested. 862 Profiles of this framework MUST specify how the AS authenticates the 863 client and how the communication between client and AS is protected. 865 The figures of this section use CBOR diagnostic notation without the 866 integer abbreviations for the parameters or their values for 867 illustrative purposes. Note that implementations MUST use the 868 integer abbreviations and the binary CBOR encoding. 870 5.6.1. Client-to-AS Request 872 The client sends a POST request to the token endpoint at the AS. The 873 profile MUST specify the Content-Type and wrapping of the payload. 874 The content of the request consists of the parameters specified in 875 section 4 of the OAuth 2.0 specification [RFC6749], encoded as a CBOR 876 map. 878 In addition to these parameters, this framework defines the following 879 parameters for requesting an access token from a token endpoint: 881 aud 882 OPTIONAL. Specifies the audience for which the client is 883 requesting an access token. If this parameter is missing, it is 884 assumed that the client and the AS have a pre-established 885 understanding of the audience that an access token should address. 886 If a client submits a request for an access token without 887 specifying an "aud" parameter, and the AS does not have an 888 implicit understanding of the "aud" value for this client, then 889 the AS MUST respond with an error message using a response code 890 equivalent to the CoAP response code 4.00 (Bad Request). 892 cnf 893 OPTIONAL. This field contains information about the key the 894 client would like to bind to the access token for proof-of- 895 possession. It is RECOMMENDED that an AS reject a request 896 containing a symmetric key value in the 'cnf' field, since the AS 897 is expected to be able to generate better symmetric keys than a 898 potentially constrained client. See Section 5.6.4.5 for more 899 details on the formatting of the 'cnf' parameter. 901 The following examples illustrate different types of requests for 902 proof-of-possession tokens. 904 Figure 5 shows a request for a token with a symmetric proof-of- 905 possession key. Note that in this example it is assumed that 906 transport layer communication security is used, therefore the 907 Content-Type is "application/cbor". The content is displayed in CBOR 908 diagnostic notation, without abbreviations for better readability. 910 Header: POST (Code=0.02) 911 Uri-Host: "server.example.com" 912 Uri-Path: "token" 913 Content-Type: "application/cbor" 914 Payload: 915 { 916 "grant_type" : "client_credentials", 917 "client_id" : "myclient", 918 "aud" : "tempSensor4711" 919 } 921 Figure 5: Example request for an access token bound to a symmetric 922 key. 924 Figure 6 shows a request for a token with an asymmetric proof-of- 925 possession key. Note that in this example COSE is used to provide 926 object-security, therefore the Content-Type is "application/cose". 928 Header: POST (Code=0.02) 929 Uri-Host: "server.example.com" 930 Uri-Path: "token" 931 Content-Type: "application/cose" 932 Payload: 933 "COSE_Encrypted" : { 934 16( 935 [ h'a1010a', # protected header: {"alg" : "AES-CCM-16-64-128"} 936 {5 : b64'ifUvZaHFgJM7UmGnjA'}, # unprotected header, IV 937 b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext 938 ] 939 ) 940 } 942 Decrypted payload: 943 { 944 "grant_type" : "client_credentials", 945 "client_id" : "myclient", 946 "cnf" : { 947 "COSE_Key" : { 948 "kty" : "EC", 949 "kid" : h'11', 950 "crv" : "P-256", 951 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 952 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 953 } 954 } 955 } 957 Figure 6: Example token request bound to an asymmetric key. 959 Figure 7 shows a request for a token where a previously communicated 960 proof-of-possession key is only referenced. Note that a transport 961 layer based communication security profile is assumed in this 962 example, therefore the Content-Type is "application/cbor". Also note 963 that the client performs a password based authentication in this 964 example by submitting its client_secret (see section 2.3.1. of 965 [RFC6749]). 967 Header: POST (Code=0.02) 968 Uri-Host: "server.example.com" 969 Uri-Path: "token" 970 Content-Type: "application/cbor" 971 Payload: 972 { 973 "grant_type" : "client_credentials", 974 "client_id" : "myclient", 975 "client_secret" : "mysecret234", 976 "aud" : "valve424", 977 "scope" : "read", 978 "cnf" : { 979 "kid" : b64'6kg0dXJM13U' 980 } 981 } 983 Figure 7: Example request for an access token bound to a key 984 reference. 986 5.6.2. AS-to-Client Response 988 If the access token request has been successfully verified by the AS 989 and the client is authorized to obtain an access token corresponding 990 to its access token request, the AS sends a response with the 991 response code equivalent to the CoAP response code 2.01 (Created). 992 If client request was invalid, or not authorized, the AS returns an 993 error response as described in Section 5.6.3. 995 Note that the AS decides which token type and profile to use when 996 issuing a successful response. It is assumed that the AS has prior 997 knowledge of the capabilities of the client and the RS (see 998 Appendix D. This prior knowledge may, for example, be set by the use 999 of a dynamic client registration protocol exchange [RFC7591]. 1001 The content of the successful reply is the RS Information. It MUST 1002 be encoded as CBOR map, containing parameters as specified in section 1003 5.1 of [RFC6749]. In addition to these parameters, the following 1004 parameters are also part of a successful response: 1006 profile 1007 OPTIONAL. This indicates the profile that the client MUST use 1008 towards the RS. See Section 5.6.4.4 for the formatting of this 1009 parameter. 1011 . If this parameter is absent, the AS assumes that the client 1012 implicitly knows which profile to use towards the RS. 1013 cnf 1014 REQUIRED if the token type is "pop" and a symmetric key is used. 1015 MUST NOT be present otherwise. This field contains the symmetric 1016 proof-of-possession key the client is supposed to use. See 1017 Section 5.6.4.5 for details on the use of this parameter. 1018 rs_cnf 1019 OPTIONAL if the token type is "pop" and asymmetric keys are used. 1020 MUST NOT be present otherwise. This field contains information 1021 about the public key used by the RS to authenticate. See 1022 Section 5.6.4.5 for details on the use of this parameter. If this 1023 parameter is absent, the AS assumes that the client already knows 1024 the public key of the RS. 1025 token_type 1026 OPTIONAL. By default implementations of this framework SHOULD 1027 assume that the token_type is "pop". If a specific use case 1028 requires another token_type (e.g., "Bearer") to be used then this 1029 parameter is REQUIRED. 1031 Note that if CBOR Web Tokens [I-D.ietf-ace-cbor-web-token] are used, 1032 the access token can also contain a "cnf" claim 1033 [I-D.jones-ace-cwt-proof-of-possession]. This claim is however 1034 consumed by a different party. The access token is created by the AS 1035 and processed by the RS (and opaque to the client) whereas the RS 1036 Information is created by the AS and processed by the client; it is 1037 never forwarded to the resource server. 1039 Figure 8 summarizes the parameters that may be part of the RS 1040 Information. 1042 /-------------------+--------------------------\ 1043 | Parameter name | Specified in | 1044 |-------------------+--------------------------| 1045 | access_token | RFC 6749 | 1046 | token_type | RFC 6749 | 1047 | expires_in | RFC 6749 | 1048 | refresh_token | RFC 6749 | 1049 | scope | RFC 6749 | 1050 | state | RFC 6749 | 1051 | error | RFC 6749 | 1052 | error_description | RFC 6749 | 1053 | error_uri | RFC 6749 | 1054 | profile | [[ this specification ]] | 1055 | cnf | [[ this specification ]] | 1056 | rs_cnf | [[ this specification ]] | 1057 \-------------------+--------------------------/ 1059 Figure 8: RS Information parameters 1061 Figure 9 shows a response containing a token and a "cnf" parameter 1062 with a symmetric proof-of-possession key. Note that transport layer 1063 security is assumed in this example, therefore the Content-Type is 1064 "application/cbor". 1066 Header: Created (Code=2.01) 1067 Content-Type: "application/cbor" 1068 Payload: 1069 { 1070 "access_token" : b64'SlAV32hkKG ... 1071 (remainder of CWT omitted for brevity; 1072 CWT contains COSE_Key in the "cnf" claim)', 1073 "profile" : "coap_dtls", 1074 "expires_in" : "3600", 1075 "cnf" : { 1076 "COSE_Key" : { 1077 "kty" : "Symmetric", 1078 "kid" : b64'39Gqlw', 1079 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1080 } 1081 } 1082 } 1084 Figure 9: Example AS response with an access token bound to a 1085 symmetric key. 1087 5.6.3. Error Response 1089 The error responses for CoAP-based interactions with the AS are 1090 equivalent to the ones for HTTP-based interactions as defined in 1091 section 5.2 of [RFC6749], with the following differences: 1093 o The Content-Type MUST be specified by the communication security 1094 profile used between client and AS. The raw payload before being 1095 processed by the communication security protocol MUST be encoded 1096 as a CBOR map. 1097 o A response code equivalent to the CoAP code 4.00 (Bad Request) 1098 MUST be used for all error responses, except for invalid_client 1099 where a response code equivalent to the CoAP code 4.01 1100 (Unauthorized) MAY be used under the same conditions as specified 1101 in section 5.2 of [RFC6749]. 1102 o The parameters "error", "error_description" and "error_uri" MUST 1103 be abbreviated using the codes specified in Figure 12. 1104 o The error code (i.e., value of the "error" parameter) MUST be 1105 abbreviated as specified in Figure 10. 1107 /------------------------+-------------------\ 1108 | error code | CBOR Value (uint) | 1109 |------------------------+-------------------| 1110 | invalid_request | 0 | 1111 | invalid_client | 1 | 1112 | invalid_grant | 2 | 1113 | unauthorized_client | 3 | 1114 | unsupported_grant_type | 4 | 1115 | invalid_scope | 5 | 1116 | unsupported_pop_key | 6 | 1117 \------------------------+-------------------/ 1119 Figure 10: CBOR abbreviations for common error codes 1121 In addition to the error responses defined in OAuth 2.0, the 1122 following behavior MUST be implemented by the AS: If the client 1123 submits an asymmetric key in the token request that the RS cannot 1124 process, the AS MUST reject that request with a response code 1125 equivalent to the CoAP code 4.00 (Bad Request) including the error 1126 code "unsupported_pop_key" defined in Figure 10. 1128 5.6.4. Request and Response Parameters 1130 This section provides more detail about the new parameters that can 1131 be used in access token requests and responses, as well as 1132 abbreviations for more compact encoding of existing parameters and 1133 common parameter values. 1135 5.6.4.1. Audience 1137 This parameter specifies for which audience the client is requesting 1138 a token. It should be encoded as CBOR text string (major type 3). 1139 The formatting and semantics of these strings are application 1140 specific. 1142 5.6.4.2. Grant Type 1144 The abbreviations in Figure 11 MUST be used in CBOR encodings instead 1145 of the string values defined in [RFC6749]. 1147 /--------------------+-------------------\ 1148 | grant_type | CBOR Value (uint) | 1149 |--------------------+-------------------| 1150 | password | 0 | 1151 | authorization_code | 1 | 1152 | client_credentials | 2 | 1153 | refresh_token | 3 | 1154 \--------------------+-------------------/ 1156 Figure 11: CBOR abbreviations for common grant types 1158 5.6.4.3. Token Type 1160 The token_type parameter is defined in [RFC6749], allowing the AS to 1161 indicate to the client which type of access token it is receiving 1162 (e.g., a bearer token). 1164 This document registers the new value "pop" for the OAuth Access 1165 Token Types registry, specifying a Proof-of-Possession token. How 1166 the proof-of-possession is performed MUST be specified by the 1167 profiles. 1169 The values in the "token_type" parameter MUST be CBOR text strings 1170 (major type 3). 1172 In this framework token type "pop" MUST be assumed by default if the 1173 AS does not provide a different value. 1175 5.6.4.4. Profile 1177 Profiles of this framework MUST define the communication protocol and 1178 the communication security protocol between the client and the RS. 1179 The security protocol MUST provide encryption, integrity and replay 1180 protection. Furthermore profiles MUST define proof-of-possession 1181 methods, if they support proof-of-possession tokens. 1183 A profile MUST specify an identifier that can be used to uniquely 1184 identify itself in the "profile" parameter. 1186 Profiles MAY define additional parameters for both the token request 1187 and the RS Information in the access token response in order to 1188 support negotiation or signaling of profile specific parameters. 1190 5.6.4.5. Confirmation 1192 The "cnf" parameter identifies or provides the key used for proof-of- 1193 possession, while the "rs_cnf" parameter provides the raw public key 1194 of the RS. Both parameters use the same formatting and semantics as 1195 the "cnf" claim specified in [I-D.jones-ace-cwt-proof-of-possession]. 1197 In addition to the use as a claim in a CWT, the "cnf" parameter is 1198 used in the following contexts with the following meaning: 1200 o In the token request C -> AS, to indicate the client's raw public 1201 key, or the key-identifier of a previously established key between 1202 C and RS. 1203 o In the token response AS -> C, to indicate the symmetric key 1204 generated by the AS for proof-of-possession. 1205 o In the introspection response AS -> RS, to indicate the proof-of- 1206 possession key bound to the introspected token. 1207 o In the client token AS -> RS -> C, to indicate the proof-of- 1208 possession key bound to the access token. 1210 Note that the COSE_Key structure in a "cnf" claim or parameter may 1211 contain an "alg" or "key_ops" parameter. If such parameters are 1212 present, a client MUST NOT use a key that is not compatible with the 1213 profile or proof-of-possession algorithm according to those 1214 parameters. An RS MUST reject a proof-of-possession using such a 1215 key. 1217 5.6.5. Mapping parameters to CBOR 1219 All OAuth parameters in access token requests and responses MUST be 1220 mapped to CBOR types as specified in Figure 12, using the given 1221 integer abbreviation for the key. 1223 Note that we have aligned these abbreviations with the claim 1224 abbreviations defined in [I-D.ietf-ace-cbor-web-token]. 1226 /-------------------+----------+------------------\ 1227 | Parameter name | CBOR Key | Type | 1228 |-------------------+----------+------------------| 1229 | aud | 3 | text string | 1230 | client_id | 8 | text string | 1231 | client_secret | 9 | byte string | 1232 | response_type | 10 | text string | 1233 | redirect_uri | 11 | text string | 1234 | scope | 12 | text string | 1235 | state | 13 | text string | 1236 | code | 14 | byte string | 1237 | error | 15 | text string | 1238 | error_description | 16 | text string | 1239 | error_uri | 17 | text string | 1240 | grant_type | 18 | unsigned integer | 1241 | access_token | 19 | text string | 1242 | token_type | 20 | unsigned integer | 1243 | expires_in | 21 | unsigned integer | 1244 | username | 22 | text string | 1245 | password | 23 | text string | 1246 | refresh_token | 24 | text string | 1247 | cnf | 25 | map | 1248 | profile | 26 | text string | 1249 | rs_cnf | 31 | map | 1250 \-------------------+----------+------------------/ 1252 Figure 12: CBOR mappings used in token requests 1254 5.7. The 'Introspect' Endpoint 1256 Token introspection [RFC7662] can be OPTIONALLY provided by the AS, 1257 and is then used by the RS and potentially the client to query the AS 1258 for metadata about a given token e.g., validity or scope. Analogous 1259 to the protocol defined in RFC 7662 [RFC7662] for HTTP and JSON, this 1260 section defines adaptations to more constrained environments using 1261 CBOR and leaving the choice of the application protocol to the 1262 profile. 1264 Communication between the RS and the introspection endpoint at the AS 1265 MUST be integrity protected and encrypted. Furthermore AS and RS 1266 MUST perform mutual authentication. Finally the AS SHOULD verify 1267 that the RS has the right to access introspection information about 1268 the provided token. Profiles of this framework that support 1269 introspection MUST specify how authentication and communication 1270 security between RS and AS is implemented. 1272 The figures of this section uses CBOR diagnostic notation without the 1273 integer abbreviations for the parameters or their values for better 1274 readability. 1276 Note that supporting introspection is OPTIONAL for implementations of 1277 this framework. 1279 5.7.1. RS-to-AS Request 1281 The RS sends a POST request to the introspection endpoint at the AS, 1282 the profile MUST specify the Content-Type and wrapping of the 1283 payload. The payload MUST be encoded as a CBOR map with a "token" 1284 parameter containing either the access token or a reference to the 1285 token (e.g., the cti). Further optional parameters representing 1286 additional context that is known by the RS to aid the AS in its 1287 response MAY be included. 1289 The same parameters are required and optional as in section 2.1 of 1290 RFC 7662 [RFC7662]. 1292 For example, Figure 13 shows a RS calling the token introspection 1293 endpoint at the AS to query about an OAuth 2.0 proof-of-possession 1294 token. Note that object security based on COSE is assumed in this 1295 example, therefore the Content-Type is "application/cose+cbor". 1297 Header: POST (Code=0.02) 1298 Uri-Host: "server.example.com" 1299 Uri-Path: "introspect" 1300 Content-Type: "application/cose+cbor" 1301 Payload: 1302 { 1303 "token" : b64'7gj0dXJQ43U', 1304 "token_type_hint" : "pop" 1305 } 1307 Figure 13: Example introspection request. 1309 5.7.2. AS-to-RS Response 1311 If the introspection request is authorized and successfully 1312 processed, the AS sends a response with the response code equivalent 1313 to the CoAP code 2.01 (Created). If the introspection request was 1314 invalid, not authorized or couldn't be processed the AS returns an 1315 error response as described in Section 5.7.3. 1317 In a successful response, the AS encodes the response parameters in a 1318 CBOR map including with the same required and optional parameters as 1319 in section 2.2. of RFC 7662 [RFC7662] with the following additions: 1321 cnf 1322 OPTIONAL. This field contains information about the proof-of- 1323 possession key that binds the client to the access token. See 1324 Section 5.6.4.5 for more details on the use of the "cnf" 1325 parameter. 1327 profile 1328 OPTIONAL. This indicates the profile that the RS MUST use with 1329 the client. See Section 5.6.4.4 for more details on the 1330 formatting of this parameter. 1332 client_token 1333 OPTIONAL. This parameter contains information that the RS MUST 1334 pass on to the client. See Section 5.7.4 for more details. 1336 For example, Figure 14 shows an AS response to the introspection 1337 request in Figure 13. Note that transport layer security is assumed 1338 in this example, therefore the Content-Type is "application/cbor". 1340 Header: Created Code=2.01) 1341 Content-Type: "application/cbor" 1342 Payload: 1343 { 1344 "active" : true, 1345 "scope" : "read", 1346 "profile" : "coap_dtls", 1347 "client_token" : b64'2QPhg0OhAQo ... 1348 (remainder of client token omitted for brevity)', 1349 "cnf" : { 1350 "COSE_Key" : { 1351 "kty" : "Symmetric", 1352 "kid" : b64'39Gqlw', 1353 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1354 } 1355 } 1356 } 1358 Figure 14: Example introspection response. 1360 5.7.3. Error Response 1362 The error responses for CoAP-based interactions with the AS are 1363 equivalent to the ones for HTTP-based interactions as defined in 1364 section 2.3 of [RFC7662], with the following differences: 1366 o If content is sent, the Content-Type MUST be set according to the 1367 specification of the communication security profile, and the 1368 content payload MUST be encoded as a CBOR map. 1370 o If the credentials used by the RS are invalid the AS MUST respond 1371 with the response code equivalent to the CoAP code 4.01 1372 (Unauthorized) and use the required and optional parameters from 1373 section 5.2 in RFC 6749 [RFC6749]. 1374 o If the RS does not have the right to perform this introspection 1375 request, the AS MUST respond with a response code equivalent to 1376 the CoAP code 4.03 (Forbidden). In this case no payload is 1377 returned. 1378 o The parameters "error", "error_description" and "error_uri" MUST 1379 be abbreviated using the codes specified in Figure 12. 1380 o The error codes MUST be abbreviated using the codes specified in 1381 Figure 10. 1383 Note that a properly formed and authorized query for an inactive or 1384 otherwise invalid token does not warrant an error response by this 1385 specification. In these cases, the authorization server MUST instead 1386 respond with an introspection response with the "active" field set to 1387 "false". 1389 5.7.4. Client Token 1391 In cases where the client has limited connectivity and needs to get 1392 access to a previously unknown resource servers, this framework 1393 suggests the following OPTIONAL approach: The client is pre- 1394 configured with a long-term access token, which is not self-contained 1395 (i.e. it is only a reference to a token at the AS) when it is 1396 commissioned. When the client then tries to access a RS it transmits 1397 this access token. The RS then performs token introspection to learn 1398 what access this token grants. In the introspection response, the AS 1399 also relays information for the client, such as the proof-of- 1400 possession key, through the RS. The RS passes on this Client Token 1401 to the client in response to the submission of the token. 1403 The client_token parameter is designed to carry such information, and 1404 is intended to be used as described in Figure 15. 1406 Resource Authorization 1407 Client Server Server 1408 | | | 1409 | | | 1410 C: +--------------->| | 1411 | POST | | 1412 | Access Token | | 1413 | D: +--------------->| 1414 | | Introspection | 1415 | | Request | 1416 | | | 1417 | E: +<---------------+ 1418 | | Introspection | 1419 | | Response | 1420 | | + Client Token | 1421 |<---------------+ | 1422 | 2.01 Created | | 1423 | + Client Token | 1425 Figure 15: Use of the client_token parameter. 1427 The client token is a COSE_Encrypted object, containing as payload a 1428 CBOR map with the following claims: 1430 cnf 1431 REQUIRED if the token type is "pop", OPTIONAL otherwise. Contains 1432 information about the proof-of-possession key the client is to use 1433 with its access token. See Section 5.6.4.5. 1435 token_type 1436 OPTIONAL. See Section 5.6.4.3. 1438 profile 1439 REQUIRED. See Section 5.6.4.4. 1441 rs_cnf 1442 OPTIONAL. Contains information about the key that the RS uses to 1443 authenticate towards the client. If the key is symmetric then 1444 this claim MUST NOT be part of the Client Token, since this is the 1445 same key as the one specified through the "cnf" claim. This claim 1446 uses the same encoding as the "cnf" parameter. See 1447 Section 5.6.4.4. 1449 The AS encrypts this token using a key shared between the AS and the 1450 client, so that only the client can decrypt it and access its 1451 payload. How this key is established is out of scope of this 1452 framework, however it can be established at the same time at which 1453 the client's long term token is created. 1455 An RS that is configured to perform introspection, MUST do so 1456 immediately after receiving an access token, in order to be able to 1457 return a potential client token to the client. This does not 1458 preclude the RS to perform additional introspection asynchronously, 1459 e.g., when the token is later used. 1461 5.7.5. Mapping Introspection parameters to CBOR 1463 The introspection request and response parameters MUST be mapped to 1464 CBOR types as specified in Figure 16, using the given integer 1465 abbreviation for the key. 1467 Note that we have aligned these abbreviatations with the claim 1468 abbreviations defined in [I-D.ietf-ace-cbor-web-token]. 1470 /-----------------+----------+-----------------\ 1471 | Parameter name | CBOR Key | Major Type | 1472 |-----------------+----------+-----------------| 1473 | iss | 1 | 3 (text string) | 1474 | sub | 2 | 3 | 1475 | aud | 3 | 3 | 1476 | exp | 4 | 6 tag value 1 | 1477 | nbf | 5 | 6 tag value 1 | 1478 | iat | 6 | 6 tag value 1 | 1479 | cti | 7 | 2 (byte string) | 1480 | client_id | 8 | 3 | 1481 | scope | 12 | 3 | 1482 | token_type | 20 | 3 | 1483 | username | 22 | 3 | 1484 | cnf | 25 | 5 (map) | 1485 | profile | 26 | 0 (uint) | 1486 | token | 27 | 3 | 1487 | token_type_hint | 28 | 3 | 1488 | active | 29 | 0 | 1489 | client_token | 30 | 3 | 1490 | rs_cnf | 31 | 5 | 1491 \-----------------+----------+-----------------/ 1493 Figure 16: CBOR Mappings to Token Introspection Parameters. 1495 5.8. The Access Token 1497 This framework RECOMMENDS the use of CBOR web token (CWT) as 1498 specified in [I-D.ietf-ace-cbor-web-token]. 1500 In order to facilitate offline processing of access tokens, this 1501 draft uses the "cnf" claim from 1503 [I-D.jones-ace-cwt-proof-of-possession] and specifies the "scope" 1504 claim for CBOR web tokens. 1506 The "scope" claim explicitly encodes the scope of a given access 1507 token. This claim follows the same encoding rules as defined in 1508 section 3.3 of [RFC6749]. The meaning of a specific scope value is 1509 application specific and expected to be known to the RS running that 1510 application. 1512 5.8.1. The 'Authorization Information' Endpoint 1514 The access token, containing authorization information and 1515 information about the key used by the client, needs to be transported 1516 to the RS so that the RS can authenticate and authorize the client 1517 request. 1519 This section defines a method for transporting the access token to 1520 the RS using a RESTful protocol such as CoAP. Profiles of this 1521 framework MAY define other methods for token transport. 1523 The method consists of an authz-info endpoint, implemented by the RS. 1524 A client using this method MUST make a POST request to the authz-info 1525 endpoint at the RS with the access token in the payload. The RS 1526 receiving the token MUST verify the validity of the token. If the 1527 token is valid, the RS MUST respond to the POST request with 2.01 1528 (Created). This response MAY contain an identifier of the token 1529 (e.g., the cti for a CWT) as a payload, in order to allow the client 1530 to refer to the token. 1532 The RS MUST be prepared to store at least one access token for future 1533 use. This is a difference to how access tokens are handled in OAuth 1534 2.0, where the access token is typically sent along with each 1535 request, and therefore not stored at the RS. 1537 If the token is not valid, the RS MUST respond with a response code 1538 equivalent to the CoAP code 4.01 (Unauthorized). If the token is 1539 valid but the audience of the token does not match the RS, the RS 1540 MUST respond with a response code equivalent to the CoAP code 4.03 1541 (Forbidden). If the token is valid but is associated to claims that 1542 the RS cannot process (e.g., an unknown scope) the RS MUST respond 1543 with a response code equivalent to the CoAP code 4.00 (Bad Request). 1544 In the latter case the RS MAY provide additional information in the 1545 error response, in order to clarify what went wrong. 1547 The RS MAY make an introspection request to validate the token before 1548 responding to the POST request to the authz-info endpoint. If the 1549 introspection response contains a client token (Section 5.7.4) then 1550 this token SHALL be included in the payload of the 2.01 (Created) 1551 response. 1553 Profiles MUST specify how the authz-info endpoint is protected. Note 1554 that since the token contains information that allow the client and 1555 the RS to establish a security context in the first place, mutual 1556 authentication may not be possible at this point. 1558 5.8.2. Token Expiration 1560 Depending on the capabilities of the RS, there are various ways in 1561 which it can verify the validity of a received access token. Here 1562 follows a list of the possibilities including what functionality they 1563 require of the RS. 1565 o The token is a CWT and includes an "exp" claim and possibly the 1566 "nbf" claim. The RS verifies these by comparing them to values 1567 from its internal clock as defined in [RFC7519]. In this case the 1568 RS's internal clock must reflect the current date and time, or at 1569 least be synchronized with the AS's clock. How this clock 1570 synchronization would be performed is out of scope for this 1571 specification. 1572 o The RS verifies the validity of the token by performing an 1573 introspection request as specified in Section 5.7. This requires 1574 the RS to have a reliable network connection to the AS and to be 1575 able to handle two secure sessions in parallel (C to RS and AS to 1576 RS). 1577 o The RS and the AS both store a sequence number linked to their 1578 common security association. The AS increments this number for 1579 each access token it issues and includes it in the access token, 1580 which is a CWT. The RS keeps track of the most recently received 1581 sequence number, and only accepts tokens as valid, that are in a 1582 certain range around this number. This method does only require 1583 the RS to keep track of the sequence number. The method does not 1584 provide timely expiration, but it makes sure that older tokens 1585 cease to be valid after a certain number of newer ones got issued. 1586 For a constrained RS with no network connectivity and no means of 1587 reliably measuring time, this is the best that can be achieved. 1589 If a token that authorizes a long running request such as a CoAP 1590 Observe [RFC7641] expires, the RS MUST send an error response with 1591 the response code 4.01 Unauthorized to the client and then terminate 1592 processing the long running request. 1594 6. Security Considerations 1596 Security considerations applicable to authentication and 1597 authorization in RESTful environments provided in OAuth 2.0 [RFC6749] 1598 apply to this work, as well as the security considerations from 1599 [I-D.ietf-ace-actors]. Furthermore [RFC6819] provides additional 1600 security considerations for OAuth which apply to IoT deployments as 1601 well. 1603 A large range of threats can be mitigated by protecting the contents 1604 of the access token by using a digital signature or a keyed message 1605 digest (MAC) or an Authenticated Encryption with Associated Data 1606 (AEAD) algorithm. Consequently, the token integrity protection MUST 1607 be applied to prevent the token from being modified, particularly 1608 since it contains a reference to the symmetric key or the asymmetric 1609 key. If the access token contains the symmetric key, this symmetric 1610 key MUST be encrypted by the authorization server so that only the 1611 resource server can decrypt it. Note that using an AEAD algorithm is 1612 preferable over using a MAC unless the message needs to be publicly 1613 readable. 1615 It is important for the authorization server to include the identity 1616 of the intended recipient (the audience), typically a single resource 1617 server (or a list of resource servers), in the token. Using a single 1618 shared secret with multiple resource servers to simplify key 1619 management is NOT RECOMMENDED since the benefit from using the proof- 1620 of-possession concept is significantly reduced. 1622 The authorization server MUST offer confidentiality protection for 1623 any interactions with the client. This step is extremely important 1624 since the client may obtain the proof-of-possession key from the 1625 authorization server for use with a specific access token. Not using 1626 confidentiality protection exposes this secret (and the access token) 1627 to an eavesdropper thereby completely negating proof-of-possession 1628 security. Profiles MUST specify how confidentiality protection is 1629 provided, and additional protection can be applied by encrypting the 1630 token, for example encryption of CWTs is specified in section 5.1 of 1631 [I-D.ietf-ace-cbor-web-token]. 1633 Developers MUST ensure that the ephemeral credentials (i.e., the 1634 private key or the session key) are not leaked to third parties. An 1635 adversary in possession of the ephemeral credentials bound to the 1636 access token will be able to impersonate the client. Be aware that 1637 this is a real risk with many constrained environments, since 1638 adversaries can often easily get physical access to the devices. 1640 Clients can at any time request a new proof-of-possession capable 1641 access token. If clients have that capability, the AS can keep the 1642 lifetime of the access token and the associated proof-of-possession 1643 key short and therefore use shorter proof-of-possession key sizes, 1644 which translate to a performance benefit for the client and for the 1645 resource server. Shorter keys also lead to shorter messages 1646 (particularly with asymmetric keying material). 1648 When authorization servers bind symmetric keys to access tokens, they 1649 SHOULD scope these access tokens to a specific permissions. 1650 Furthermore access tokens using symmetric keys for proof-of- 1651 possession SHOULD NOT be targeted at an audience that contains more 1652 than one RS, since otherwise any RS in the audience that receives 1653 that access token can impersonate the client towards the other 1654 members of the audience. 1656 6.1. Unprotected AS Information 1658 Initially, no secure channel exists to protect the communication 1659 between C and RS. Thus, C cannot determine if the AS information 1660 contained in an unprotected response from RS to an unauthorized 1661 request (c.f. Section 5.1.2) is authentic. It is therefore 1662 advisable to provide C with a (possibly hard-coded) list of 1663 trustworthy authorization servers. AS information responses 1664 referring to a URI not listed there would be ignored. 1666 6.2. Use of Nonces for Replay Protection 1668 RS may add a nonce to the AS Information message sent as a response 1669 to an unauthorized request to ensure freshness of an Access Token 1670 subsequently presented to RS. While a timestamp of some granularity 1671 would be sufficient to protect against replay attacks, using 1672 randomized nonce is preferred to prevent disclosure of information 1673 about RS's internal clock characteristics. 1675 6.3. Combining profiles 1677 There may exist reasonable use cases where implementers want to 1678 combine different profiles of this framework, e.g., using an MQTT 1679 profile between client and RS, while using a DTLS profile for 1680 interactions between client and AS. Profiles should be designed in a 1681 way that the security of a protocol interaction does not depend on 1682 the specific security mechanisms used in other protocol interactions. 1684 6.4. Error responses 1686 The various error responses defined in this framework may leak 1687 information to an adversary. For example errors responses for 1688 requests to the Authorization Information endpoint can reveal 1689 information about an otherwise opaque access token to an adversary 1690 who has intercepted this token. This framework is written under the 1691 assumption that, in general, the benefits of detailed error messages 1692 outweigh the risk due to information leakage. For particular use 1693 cases, where this assessment does not apply, detailed error messages 1694 can be replaced by more generic ones. 1696 7. Privacy Considerations 1698 Implementers and users should be aware of the privacy implications of 1699 the different possible deployments of this framework. 1701 The AS is in a very central position and can potentially learn 1702 sensitive information about the clients requesting access tokens. If 1703 the client credentials grant is used, the AS can track what kind of 1704 access the client intends to perform. With other grants this can be 1705 prevented by the Resource Owner. To do so, the resource owner needs 1706 to bind the grants it issues to anonymous, ephemeral credentials that 1707 do not allow the AS to link different grants and thus different 1708 access token requests by the same client. 1710 If access tokens are only integrity protected and not encrypted, they 1711 may reveal information to attackers listening on the wire, or able to 1712 acquire the access tokens in some other way. In the case of CWTs the 1713 token may e.g., reveal the audience, the scope and the confirmation 1714 method used by the client. The latter may reveal the identity of the 1715 device or application running the client. This may be linkable to 1716 the identity of the person using the client (if there is a person and 1717 not a machine-to-machine interaction). 1719 Clients using asymmetric keys for proof-of-possession should be aware 1720 of the consequences of using the same key pair for proof-of- 1721 possession towards different RSs. A set of colluding RSs or an 1722 attacker able to obtain the access tokens will be able to link the 1723 requests, or even to determine the client's identity. 1725 An unprotected response to an unauthorized request (c.f. 1726 Section 5.1.2) may disclose information about RS and/or its existing 1727 relationship with C. It is advisable to include as little 1728 information as possible in an unencrypted response. Means of 1729 encrypting communication between C and RS already exist, more 1730 detailed information may be included with an error response to 1731 provide C with sufficient information to react on that particular 1732 error. 1734 8. IANA Considerations 1736 This specification registers new parameters for OAuth and establishes 1737 registries for mappings to CBOR. 1739 8.1. OAuth Introspection Response Parameter Registration 1741 This specification registers the following parameters in the OAuth 1742 introspection response parameters 1744 o Name: "cnf" 1745 o Description: Key to prove the right to use an access token, 1746 formatted as specified in [I-D.jones-ace-cwt-proof-of-possession]. 1747 o Change Controller: IESG 1748 o Specification Document(s): this document 1750 o Name: "profile" 1751 o Description: The communication and communication security profile 1752 used between client and RS, as defined in ACE profiles. 1753 o Change Controller: IESG 1754 o Specification Document(s): this document 1756 o Name: "client_token" 1757 o Description: Information that the RS MUST pass to the client e.g., 1758 about the proof-of-possession keys. 1759 o Change Controller: IESG 1760 o Specification Document(s): this document 1762 o Name: "rs_cnf" 1763 o Description: Describes the public key the RS uses to authenticate. 1764 o Change Controller: IESG 1765 o Specification Document(s): this document 1767 8.2. OAuth Parameter Registration 1769 This specification registers the following parameters in the OAuth 1770 Parameters Registry 1772 o Parameter name: "profile" 1773 o Parameter usage location: token request, and token response 1774 o Change Controller: IESG 1775 o Specification Document(s): this document 1777 o Name: "cnf" 1778 o Description: Key to prove the right to use an access token, 1779 formatted as defined in [I-D.jones-ace-cwt-proof-of-possession]. 1780 o Change Controller: IESG 1781 o Specification Document(s): this document 1783 8.3. OAuth Access Token Types 1785 This specification registers the following new token type in the 1786 OAuth Access Token Types Registry 1788 o Name: "PoP" 1789 o Description: A proof-of-possession token. 1790 o Change Controller: IESG 1791 o Specification Document(s): this document 1793 8.4. OAuth Token Type CBOR Mappings 1795 A new registry will be requested from IANA, entitled "Token Type 1796 Mappings". The registry is to be created as Expert Review Required. 1798 8.4.1. Registration Template 1800 Token Type: 1801 Name of token type as registered in the OAuth token type registry 1802 e.g., "Bearer". 1803 Mapped value: 1804 Integer representation for the token type value. The key value 1805 MUST be an integer. Integer values from -65536 to 65535 are 1806 designated as Specification Required. Integer values of greater 1807 than 65535 designated as expert review. Integer values less than 1808 -65536 are marked as private use. 1809 Change Controller: 1810 For Standards Track RFCs, list the "IESG". For others, give the 1811 name of the responsible party. Other details (e.g., postal 1812 address, email address, home page URI) may also be included. 1813 Specification Document(s): 1814 Reference to the document or documents that specify the 1815 parameter,preferably including URIs that can be used to retrieve 1816 copies of the documents. An indication of the relevant sections 1817 may also be included but is not required. 1819 8.4.2. Initial Registry Contents 1821 o Parameter name: "Bearer" 1822 o Mapped value: 1 1823 o Change Controller: IESG 1824 o Specification Document(s): this document 1826 o Parameter name: "pop" 1827 o Mapped value: 2 1828 o Change Controller: IESG 1829 o Specification Document(s): this document 1831 8.5. CBOR Web Token Claims 1833 This specification registers the following new claims in the CBOR Web 1834 Token (CWT) registry: 1836 o Claim Name: "scope" 1837 o Claim Description: The scope of an access token as defined in 1838 [RFC6749]. 1839 o Change Controller: IESG 1840 o Specification Document(s): this document 1842 8.6. ACE OAuth Profile Registry 1844 A new registry will be requested from IANA, entitled "ACE Profile 1845 Registry". The registry is to be created as Expert Review Required. 1847 8.6.1. Registration Template 1849 Profile name: 1850 Name of the profile to be included in the profile attribute. 1851 Profile description: 1852 Text giving an overview of the profile and the context it is 1853 developed for. 1854 Profile ID: 1855 Integer value to identify the profile. Integer values from -65536 1856 to 65535 are designated as Specification Required. Integer values 1857 of greater than 65535 designated as expert review. Integer values 1858 less than -65536 are marked as private use. 1859 Change Controller: 1860 For Standards Track RFCs, list the "IESG". For others, give the 1861 name of the responsible party. Other details (e.g., postal 1862 address, email address, home page URI) may also be included. 1863 Specification Document(s): 1864 Reference to the document or documents that specify the 1865 parameter,preferably including URIs that can be used to retrieve 1866 copies of the documents. An indication of the relevant sections 1867 may also be included but is not required. 1869 8.7. OAuth CBOR Parameter Mappings Registry 1871 A new registry will be requested from IANA, entitled "Token Endpoint 1872 CBOR Mappings Registry". The registry is to be created as Expert 1873 Review Required. 1875 8.7.1. Registration Template 1877 Parameter name: 1878 OAuth Parameter name, refers to the name in the OAuth parameter 1879 registry e.g., "client_id". 1880 CBOR key value: 1881 Key value for the claim. The key value MUST be an integer. 1882 Integer values from -65536 to 65535 are designated as 1883 Specification Required. Integer values of greater than 65535 1884 designated as expert review. Integer values less than -65536 are 1885 marked as private use. 1886 Change Controller: 1887 For Standards Track RFCs, list the "IESG". For others, give the 1888 name of the responsible party. Other details (e.g., postal 1889 address, email address, home page URI) may also be included. 1890 Specification Document(s): 1891 Reference to the document or documents that specify the 1892 parameter,preferably including URIs that can be used to retrieve 1893 copies of the documents. An indication of the relevant sections 1894 may also be included but is not required. 1896 8.7.2. Initial Registry Contents 1898 o Parameter name: "aud" 1899 o CBOR key value: 3 1900 o Change Controller: IESG 1901 o Specification Document(s): this document 1903 o Parameter name: "client_id" 1904 o CBOR key value: 8 1905 o Change Controller: IESG 1906 o Specification Document(s): this document 1908 o Parameter name: "client_secret" 1909 o CBOR key value: 9 1910 o Change Controller: IESG 1911 o Specification Document(s): this document 1913 o Parameter name: "response_type" 1914 o CBOR key value: 10 1915 o Change Controller: IESG 1916 o Specification Document(s): this document 1918 o Parameter name: "redirect_uri" 1919 o CBOR key value: 11 1920 o Change Controller: IESG 1921 o Specification Document(s): this document 1922 o Parameter name: "scope" 1923 o CBOR key value: 12 1924 o Change Controller: IESG 1925 o Specification Document(s): this document 1927 o Parameter name: "state" 1928 o CBOR key value: 13 1929 o Change Controller: IESG 1930 o Specification Document(s): this document 1932 o Parameter name: "code" 1933 o CBOR key value: 14 1934 o Change Controller: IESG 1935 o Specification Document(s): this document 1937 o Parameter name: "error" 1938 o CBOR key value: 15 1939 o Change Controller: IESG 1940 o Specification Document(s): this document 1942 o Parameter name: "error_description" 1943 o CBOR key value: 16 1944 o Change Controller: IESG 1945 o Specification Document(s): this document 1947 o Parameter name: "error_uri" 1948 o CBOR key value: 17 1949 o Change Controller: IESG 1950 o Specification Document(s): this document 1952 o Parameter name: "grant_type" 1953 o CBOR key value: 18 1954 o Change Controller: IESG 1955 o Specification Document(s): this document 1957 o Parameter name: "access_token" 1958 o CBOR key value: 19 1959 o Change Controller: IESG 1960 o Specification Document(s): this document 1962 o Parameter name: "token_type" 1963 o CBOR key value: 20 1964 o Change Controller: IESG 1965 o Specification Document(s): this document 1967 o Parameter name: "expires_in" 1968 o CBOR key value: 21 1969 o Change Controller: IESG 1970 o Specification Document(s): this document 1972 o Parameter name: "username" 1973 o CBOR key value: 22 1974 o Change Controller: IESG 1975 o Specification Document(s): this document 1977 o Parameter name: "password" 1978 o CBOR key value: 23 1979 o Change Controller: IESG 1980 o Specification Document(s): this document 1982 o Parameter name: "refresh_token" 1983 o CBOR key value: 24 1984 o Change Controller: IESG 1985 o Specification Document(s): this document 1987 o Parameter name: "cnf" 1988 o CBOR key value: 25 1989 o Change Controller: IESG 1990 o Specification Document(s): this document 1992 o Parameter name: "profile" 1993 o CBOR key value: 26 1994 o Change Controller: IESG 1995 o Specification Document(s): this document 1997 8.8. Introspection Endpoint CBOR Mappings Registry 1999 A new registry will be requested from IANA, entitled "Introspection 2000 Endpoint CBOR Mappings Registry". The registry is to be created as 2001 Expert Review Required. 2003 8.8.1. Registration Template 2005 Response parameter name: 2006 Name of the response parameter as defined in the "OAuth Token 2007 Introspection Response" registry e.g., "active". 2008 CBOR key value: 2009 Key value for the claim. The key value MUST be an integer. 2010 Integer values from -65536 to 65535 are designated as 2011 Specification Required. Integer values of greater than 65535 2012 designated as expert review. Integer values less than -65536 are 2013 marked as private use. 2014 Change Controller: 2015 For Standards Track RFCs, list the "IESG". For others, give the 2016 name of the responsible party. Other details (e.g., postal 2017 address, email address, home page URI) may also be included. 2019 Specification Document(s): 2020 Reference to the document or documents that specify the 2021 parameter,preferably including URIs that can be used to retrieve 2022 copies of the documents. An indication of the relevant sections 2023 may also be included but is not required. 2025 8.8.2. Initial Registry Contents 2027 o Response parameter name: "iss" 2028 o CBOR key value: 1 2029 o Change Controller: IESG 2030 o Specification Document(s): this document 2032 o Response parameter name: "sub" 2033 o CBOR key value: 2 2034 o Change Controller: IESG 2035 o Specification Document(s): this document 2037 o Response parameter name: "aud" 2038 o CBOR key value: 3 2039 o Change Controller: IESG 2040 o Specification Document(s): this document 2042 o Response parameter name: "exp" 2043 o CBOR key value: 4 2044 o Change Controller: IESG 2045 o Specification Document(s): this document 2047 o Response parameter name: "nbf" 2048 o CBOR key value: 5 2049 o Change Controller: IESG 2050 o Specification Document(s): this document 2052 o Response parameter name: "iat" 2053 o CBOR key value: 6 2054 o Change Controller: IESG 2055 o Specification Document(s): this document 2057 o Response parameter name: "cti" 2058 o CBOR key value: 7 2059 o Change Controller: IESG 2060 o Specification Document(s): this document 2062 o Response parameter name: "client_id" 2063 o CBOR key value: 8 2064 o Change Controller: IESG 2065 o Specification Document(s): this document 2066 o Response parameter name: "scope" 2067 o CBOR key value: 12 2068 o Change Controller: IESG 2069 o Specification Document(s): this document 2071 o Response parameter name: "token_type" 2072 o CBOR key value: 20 2073 o Change Controller: IESG 2074 o Specification Document(s): this document 2076 o Response parameter name: "username" 2077 o CBOR key value: 22 2078 o Change Controller: IESG 2079 o Specification Document(s): this document 2081 o Parameter name: "cnf" 2082 o CBOR key value: 25 2083 o Change Controller: IESG 2084 o Specification Document(s): this document 2086 o Parameter name: "profile" 2087 o CBOR key value: 26 2088 o Change Controller: IESG 2089 o Specification Document(s): this document 2091 o Response parameter name: "token" 2092 o CBOR key value: 27 2093 o Change Controller: IESG 2094 o Specification Document(s): this document 2096 o Response parameter name: "token_type_hint" 2097 o CBOR key value: 28 2098 o Change Controller: IESG 2099 o Specification Document(s): this document 2101 o Response parameter name: "active" 2102 o CBOR key value: 29 2103 o Change Controller: IESG 2104 o Specification Document(s): this document 2106 o Response parameter name: "client_token" 2107 o CBOR key value: 30 2108 o Change Controller: IESG 2109 o Specification Document(s): this document 2111 o Response parameter name: "rs_cnf" 2112 o CBOR key value: 31 2113 o Change Controller: IESG 2114 o Specification Document(s): this document 2116 8.9. CoAP Option Number Registration 2118 This section registers the "Access-Token" CoAP Option Number in the 2119 "CoRE Parameters" sub-registry "CoAP Option Numbers" in the manner 2120 described in [RFC7252]. 2122 Name 2124 Access-Token 2125 Number 2127 TBD 2128 Reference 2130 [This document]. 2131 Meaning in Request 2133 Contains an Access Token according to [This document] containing 2134 access permissions of the client. 2135 Meaning in Response 2137 Not used in response 2138 Safe-to-Forward 2140 Yes 2141 Format 2143 Based on the observer the format is perceived differently. Opaque 2144 data to the client and CWT or reference token to the RS. 2145 Length 2147 Less then 255 bytes 2149 9. Acknowledgments 2151 This document is a product of the ACE working group of the IETF. 2153 Thanks to Eve Maler for her contributions to the use of OAuth 2.0 and 2154 UMA in IoT scenarios, Robert Taylor for his discussion input, and 2155 Malisa Vucinic for his input on the predecessors of this proposal. 2157 Thanks to the authors of draft-ietf-oauth-pop-key-distribution, from 2158 where large parts of the security considerations where copied. 2160 Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten Bormann for 2161 contributing their work on AS discovery from draft-gerdes-ace-dcaf- 2162 authorize (see Section 5.1). 2164 Ludwig Seitz and Goeran Selander worked on this document as part of 2165 the CelticPlus project CyberWI, with funding from Vinnova. 2167 10. References 2169 10.1. Normative References 2171 [I-D.ietf-ace-cbor-web-token] 2172 Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 2173 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-08 2174 (work in progress), August 2017. 2176 [I-D.jones-ace-cwt-proof-of-possession] 2177 Jones, M., Seitz, L., Selander, G., Wahlstroem, E., 2178 Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key 2179 Semantics for CBOR Web Tokens (CWTs)", draft-jones-ace- 2180 cwt-proof-of-possession-01 (work in progress), June 2017. 2182 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2183 Requirement Levels", BCP 14, RFC 2119, 2184 DOI 10.17487/RFC2119, March 1997, . 2187 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2188 Resource Identifier (URI): Generic Syntax", STD 66, 2189 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2190 . 2192 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2193 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2194 January 2012, . 2196 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2197 Application Protocol (CoAP)", RFC 7252, 2198 DOI 10.17487/RFC7252, June 2014, . 2201 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 2202 RFC 7662, DOI 10.17487/RFC7662, October 2015, 2203 . 2205 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2206 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2207 . 2209 10.2. Informative References 2211 [I-D.erdtman-ace-rpcc] 2212 Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared- 2213 Key as OAuth client credentials", draft-erdtman-ace- 2214 rpcc-01 (work in progress), August 2017. 2216 [I-D.ietf-ace-actors] 2217 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 2218 architecture for authorization in constrained 2219 environments", draft-ietf-ace-actors-05 (work in 2220 progress), March 2017. 2222 [I-D.ietf-core-object-security] 2223 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2224 "Object Security for Constrained RESTful Environments 2225 (OSCORE)", draft-ietf-core-object-security-05 (work in 2226 progress), September 2017. 2228 [I-D.ietf-core-resource-directory] 2229 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 2230 Amsuess, "CoRE Resource Directory", draft-ietf-core- 2231 resource-directory-11 (work in progress), July 2017. 2233 [I-D.ietf-oauth-device-flow] 2234 Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2235 "OAuth 2.0 Device Flow for Browserless and Input 2236 Constrained Devices", draft-ietf-oauth-device-flow-06 2237 (work in progress), May 2017. 2239 [I-D.ietf-oauth-discovery] 2240 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 2241 Authorization Server Metadata", draft-ietf-oauth- 2242 discovery-07 (work in progress), September 2017. 2244 [I-D.ietf-oauth-native-apps] 2245 Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2246 draft-ietf-oauth-native-apps-12 (work in progress), June 2247 2017. 2249 [Margi10impact] 2250 Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr, 2251 M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold, 2252 "Impact of Operating Systems on Wireless Sensor Networks 2253 (Security) Applications and Testbeds", Proceedings of 2254 the 19th International Conference on Computer 2255 Communications and Networks (ICCCN), 2010 August. 2257 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2258 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2259 . 2261 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2262 (TLS) Protocol Version 1.2", RFC 5246, 2263 DOI 10.17487/RFC5246, August 2008, . 2266 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2267 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2268 . 2270 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2271 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2272 . 2274 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 2275 Threat Model and Security Considerations", RFC 6819, 2276 DOI 10.17487/RFC6819, January 2013, . 2279 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2280 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2281 October 2013, . 2283 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2284 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2285 2014, . 2287 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2288 Constrained-Node Networks", RFC 7228, 2289 DOI 10.17487/RFC7228, May 2014, . 2292 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2293 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2294 DOI 10.17487/RFC7231, June 2014, . 2297 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2298 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2299 . 2301 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 2302 "Assertion Framework for OAuth 2.0 Client Authentication 2303 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 2304 May 2015, . 2306 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 2307 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 2308 RFC 7591, DOI 10.17487/RFC7591, July 2015, 2309 . 2311 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2312 Application Protocol (CoAP)", RFC 7641, 2313 DOI 10.17487/RFC7641, September 2015, . 2316 [RFC7744] Seitz, L., Ed., Gerdes, S., Ed., Selander, G., Mani, M., 2317 and S. Kumar, "Use Cases for Authentication and 2318 Authorization in Constrained Environments", RFC 7744, 2319 DOI 10.17487/RFC7744, January 2016, . 2322 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2323 the Constrained Application Protocol (CoAP)", RFC 7959, 2324 DOI 10.17487/RFC7959, August 2016, . 2327 Appendix A. Design Justification 2329 This section provides further insight into the design decisions of 2330 the solution documented in this document. Section 3 lists several 2331 building blocks and briefly summarizes their importance. The 2332 justification for offering some of those building blocks, as opposed 2333 to using OAuth 2.0 as is, is given below. 2335 Common IoT constraints are: 2337 Low Power Radio: 2339 Many IoT devices are equipped with a small battery which needs to 2340 last for a long time. For many constrained wireless devices, the 2341 highest energy cost is associated to transmitting or receiving 2342 messages (roughly by a factor of 10 compared to e.g. AES) 2343 [Margi10impact]. It is therefore important to keep the total 2344 communication overhead low, including minimizing the number and 2345 size of messages sent and received, which has an impact of choice 2346 on the message format and protocol. By using CoAP over UDP and 2347 CBOR encoded messages, some of these aspects are addressed. 2348 Security protocols contribute to the communication overhead and 2349 can, in some cases, be optimized. For example, authentication and 2350 key establishment may, in certain cases where security 2351 requirements allow, be replaced by provisioning of security 2352 context by a trusted third party, using transport or application 2353 layer security. 2355 Low CPU Speed: 2357 Some IoT devices are equipped with processors that are 2358 significantly slower than those found in most current devices on 2359 the Internet. This typically has implications on what timely 2360 cryptographic operations a device is capable of performing, which 2361 in turn impacts e.g., protocol latency. Symmetric key 2362 cryptography may be used instead of the computationally more 2363 expensive public key cryptography where the security requirements 2364 so allows, but this may also require support for trusted third 2365 party assisted secret key establishment using transport or 2366 application layer security. 2367 Small Amount of Memory: 2369 Microcontrollers embedded in IoT devices are often equipped with 2370 small amount of RAM and flash memory, which places limitations 2371 what kind of processing can be performed and how much code can be 2372 put on those devices. To reduce code size fewer and smaller 2373 protocol implementations can be put on the firmware of such a 2374 device. In this case, CoAP may be used instead of HTTP, symmetric 2375 key cryptography instead of public key cryptography, and CBOR 2376 instead of JSON. Authentication and key establishment protocol, 2377 e.g., the DTLS handshake, in comparison with assisted key 2378 establishment also has an impact on memory and code. 2380 User Interface Limitations: 2382 Protecting access to resources is both an important security as 2383 well as privacy feature. End users and enterprise customers may 2384 not want to give access to the data collected by their IoT device 2385 or to functions it may offer to third parties. Since the 2386 classical approach of requesting permissions from end users via a 2387 rich user interface does not work in many IoT deployment 2388 scenarios, these functions need to be delegated to user-controlled 2389 devices that are better suitable for such tasks, such as smart 2390 phones and tablets. 2392 Communication Constraints: 2394 In certain constrained settings an IoT device may not be able to 2395 communicate with a given device at all times. Devices may be 2396 sleeping, or just disconnected from the Internet because of 2397 general lack of connectivity in the area, for cost reasons, or for 2398 security reasons, e.g., to avoid an entry point for Denial-of- 2399 Service attacks. 2401 The communication interactions this framework builds upon (as 2402 shown graphically in Figure 1) may be accomplished using a variety 2403 of different protocols, and not all parts of the message flow are 2404 used in all applications due to the communication constraints. 2405 Deployments making use of CoAP are expected, but not limited to, 2406 other protocols such as HTTP, HTTP/2 or other specific protocols, 2407 such as Bluetooth Smart communication, that do not necessarily use 2408 IP could also be used. The latter raises the need for application 2409 layer security over the various interfaces. 2411 In the light of these constraints we have made the following design 2412 decisions: 2414 CBOR, COSE, CWT: 2416 This framework REQUIRES the use of CBOR [RFC7049] as data format. 2417 Where CBOR data needs to be protected, the use of COSE [RFC8152] 2418 is RECOMMENDED. Furthermore where self-contained tokens are 2419 needed, this framework RECOMMENDS the use of CWT 2420 [I-D.ietf-ace-cbor-web-token]. These measures aim at reducing the 2421 size of messages sent over the wire, the RAM size of data objects 2422 that need to be kept in memory and the size of libraries that 2423 devices need to support. 2425 CoAP: 2427 This framework RECOMMENDS the use of CoAP [RFC7252] instead of 2428 HTTP. This does not preclude the use of other protocols 2429 specifically aimed at constrained devices, like e.g. Bluetooth 2430 Low energy (see Section 3.2). This aims again at reducing the 2431 size of messages sent over the wire, the RAM size of data objects 2432 that need to be kept in memory and the size of libraries that 2433 devices need to support. 2435 RS Information: 2437 This framework defines the name "RS Information" for data 2438 concerning the RS that the AS returns to the client in an access 2439 token response (see Section 5.6.2). This includes the "profile" 2440 and the "rs_cnf" parameters. This aims at enabling scenarios, 2441 where a powerful client, supporting multiple profiles, needs to 2442 interact with a RS for which it does not know the supported 2443 profiles and the raw public key. 2445 Proof-of-Possession: 2447 This framework makes use of proof-of-possession tokens, using the 2448 "cnf" claim [I-D.jones-ace-cwt-proof-of-possession]. A 2449 semantically and syntactically identical request and response 2450 parameter is defined for the token endpoint, to allow requesting 2451 and stating confirmation keys. This aims at making token theft 2452 harder. Token theft is specifically relevant in constrained use 2453 cases, as communication often passes through middle-boxes, which 2454 could be able to steal bearer tokens and use them to gain 2455 unauthorized access. 2457 Auth-Info endpoint: 2459 This framework introduces a new way of providing access tokens to 2460 a RS by exposing a authz-info endpoint, to which access tokens can 2461 be POSTed. This aims at reducing the size of the request message 2462 and the code complexity at the RS. The size of the request 2463 message is problematic, since many constrained protocols have 2464 severe message size limitations at the physical layer (e.g. in the 2465 order of 100 bytes). This means that larger packets get 2466 fragmented, which in turn combines badly with the high rate of 2467 packet loss, and the need to retransmit the whole message if one 2468 packet gets lost. Thus separating sending of the request and 2469 sending of the access tokens helps to reduce fragmentation. 2471 Client Credentials Grant: 2473 This framework RECOMMENDS the use of the client credentials grant 2474 for machine-to-machine communication use cases, where manual 2475 intervention of the resource owner to produce a grant token is not 2476 feasible. The intention is that the resource owner would instead 2477 pre-arrange authorization with the AS, based on the client's own 2478 credentials. The client can the (without manual intervention) 2479 obtain access tokens from the AS. 2481 Introspection: 2483 This framework RECOMMENDS the use of access token introspection in 2484 cases where the client is constrained in a way that it can not 2485 easily obtain new access tokens (i.e. it has connectivity issues 2486 that prevent it from communicating with the AS). In that case 2487 this framework RECOMMENDS the use of a long-term token, that could 2488 be a simple reference. The RS is assumed to be able to 2489 communicate with the AS, and can therefore perform introspection, 2490 in order to learn the claims associated with the token reference. 2491 The advantage of such an approach is that the resource owner can 2492 change the claims associated to the token reference without having 2493 to be in contact with the client, thus granting or revoking access 2494 rights. 2496 Client Token: 2498 In cases where the client is constrained and does not have 2499 connectivity to the AS, and furthermore does not have a previous 2500 security relation to the RS that it needs to communicate with, 2501 this framework proposes the use of "client tokens". A client 2502 token is a data object obtained from the AS by the RS, during 2503 access token introspection. The RS passes the client token on to 2504 the client. It contains information that allows the client to 2505 perform the proof of possession for its access token and to 2506 authenticate the RS (e.g. with it's public key). 2508 Appendix B. Roles and Responsibilities 2510 Resource Owner 2512 * Make sure that the RS is registered at the AS. This includes 2513 making known to the AS which profiles, token_types, scopes, and 2514 key types (symmetric/asymmetric) the RS supports. Also making 2515 it known to the AS which audience(s) the RS identifies itself 2516 with. 2517 * Make sure that clients can discover the AS that is in charge of 2518 the RS. 2519 * If the client-credentials grant is used, make sure that the AS 2520 has the necessary, up-to-date, access control policies for the 2521 RS. 2523 Requesting Party 2525 * Make sure that the client is provisioned the necessary 2526 credentials to authenticate to the AS. 2527 * Make sure that the client is configured to follow the security 2528 requirements of the Requesting Party when issuing requests 2529 (e.g., minimum communication security requirements, trust 2530 anchors). 2531 * Register the client at the AS. This includes making known to 2532 the AS which profiles, token_types, and key types (symmetric/ 2533 asymmetric) the client. 2535 Authorization Server 2537 * Register the RS and manage corresponding security contexts. 2538 * Register clients and authentication credentials. 2539 * Allow Resource Owners to configure and update access control 2540 policies related to their registered RSs. 2541 * Expose the token endpoint to allow clients to request tokens. 2542 * Authenticate clients that wish to request a token. 2543 * Process a token request using the authorization policies 2544 configured for the RS. 2546 * Optionally: Expose the introspection endpoint that allows RS's 2547 to submit token introspection requests. 2548 * If providing an introspection endpoint: Authenticate RSs that 2549 wish to get an introspection response. 2550 * If providing an introspection endpoint: Process token 2551 introspection requests. 2552 * Optionally: Handle token revocation. 2553 * Optionally: Provide discovery metadta. See 2554 [I-D.ietf-oauth-discovery] 2556 Client 2558 * Discover the AS in charge of the RS that is to be targeted with 2559 a request. 2560 * Submit the token request (see step (A) of Figure 1). 2562 + Authenticate to the AS. 2563 + Optionally (if not pre-configured): Specify which RS, which 2564 resource(s), and which action(s) the request(s) will target. 2565 + If raw public keys (rpk) or certificates are used, make sure 2566 the AS has the right rpk or certificate for this client. 2567 * Process the access token and RS Information (see step (B) of 2568 Figure 1). 2570 + Check that the RS Information provides the necessary 2571 security parameters (e.g., PoP key, information on 2572 communication security protocols supported by the RS). 2573 * Send the token and request to the RS (see step (C) of 2574 Figure 1). 2576 + Authenticate towards the RS (this could coincide with the 2577 proof of possession process). 2578 + Transmit the token as specified by the AS (default is to the 2579 authz-info endpoint, alternative options are specified by 2580 profiles). 2581 + Perform the proof-of-possession procedure as specified by 2582 the profile in use (this may already have been taken care of 2583 through the authentication procedure). 2584 * Process the RS response (see step (F) of Figure 1) of the RS. 2586 Resource Server 2588 * Expose a way to submit access tokens. By default this is the 2589 authz-info endpoint. 2590 * Process an access token. 2592 + Verify the token is from a recognized AS. 2593 + Verify that the token applies to this RS. 2595 + Check that the token has not expired (if the token provides 2596 expiration information). 2597 + Check the token's integrity. 2598 + Store the token so that it can be retrieved in the context 2599 of a matching request. 2600 * Process a request. 2602 + Set up communication security with the client. 2603 + Authenticate the client. 2604 + Match the client against existing tokens. 2605 + Check that tokens belonging to the client actually authorize 2606 the requested action. 2607 + Optionally: Check that the matching tokens are still valid, 2608 using introspection (if this is possible.) 2609 * Send a response following the agreed upon communication 2610 security. 2612 Appendix C. Requirements on Profiles 2614 This section lists the requirements on profiles of this framework, 2615 for the convenience of profile designers. 2617 o Specify the communication protocol the client and RS the must use 2618 (e.g., CoAP). Section 5 and Section 5.6.4.4 2619 o Specify the security protocol the client and RS must use to 2620 protect their communication (e.g., OSCOAP or DTLS over CoAP). 2621 This must provide encryption, integrity and replay protection. 2622 Section 5.6.4.4 2623 o Specify how the client and the RS mutually authenticate. 2624 Section 4 2625 o Specify the Content-format of the protocol messages (e.g., 2626 "application/cbor" or "application/cose+cbor"). Section 4 2627 o Specify the proof-of-possession protocol(s) and how to select one, 2628 if several are available. Also specify which key types (e.g., 2629 symmetric/asymmetric) are supported by a specific proof-of- 2630 possession protocol. Section 5.6.4.3 2631 o Specify a unique profile identifier. Section 5.6.4.4 2632 o If introspection is supported: Specify the communication and 2633 security protocol for introspection.Section 5.7 2634 o Specify the communication and security protocol for interactions 2635 between client and AS. Section 5.6 2636 o Specify how/if the authz-info endpoint is protected. 2637 Section 5.8.1 2638 o Optionally define other methods of token transport than the authz- 2639 info endpoint. Section 5.8.1 2641 Appendix D. Assumptions on AS knowledge about C and RS 2643 This section lists the assumptions on what an AS should know about a 2644 client and a RS in order to be able to respond to requests to the 2645 token and introspection endpoints. How this information is 2646 established is out of scope for this document. 2648 o The identifier of the client or RS. 2649 o The profiles that the client or RS supports. 2650 o The scopes that the RS supports. 2651 o The audiences that the RS identifies with. 2652 o The key types (e.g., pre-shared symmetric key, raw public key, key 2653 length, other key parameters) that the client or RS supports. 2654 o The types of access tokens the RS supports (e.g., CWT). 2655 o If the RS supports CWTs, the COSE parameters for the crypto 2656 wrapper (e.g., algorithm, key-wrap algorithm, key-length). 2657 o The expiration time for access tokens issued to this RS (unless 2658 the RS accepts a default time chosen by the AS). 2659 o The symmetric key shared between client or RS and AS (if any). 2660 o The raw public key of the client or RS (if any). 2662 Appendix E. Deployment Examples 2664 There is a large variety of IoT deployments, as is indicated in 2665 Appendix A, and this section highlights a few common variants. This 2666 section is not normative but illustrates how the framework can be 2667 applied. 2669 For each of the deployment variants, there are a number of possible 2670 security setups between clients, resource servers and authorization 2671 servers. The main focus in the following subsections is on how 2672 authorization of a client request for a resource hosted by a RS is 2673 performed. This requires the security of the requests and responses 2674 between the clients and the RS to consider. 2676 Note: CBOR diagnostic notation is used for examples of requests and 2677 responses. 2679 E.1. Local Token Validation 2681 In this scenario, the case where the resource server is offline is 2682 considered, i.e., it is not connected to the AS at the time of the 2683 access request. This access procedure involves steps A, B, C, and F 2684 of Figure 1. 2686 Since the resource server must be able to verify the access token 2687 locally, self-contained access tokens must be used. 2689 This example shows the interactions between a client, the 2690 authorization server and a temperature sensor acting as a resource 2691 server. Message exchanges A and B are shown in Figure 17. 2693 A: The client first generates a public-private key pair used for 2694 communication security with the RS. 2695 The client sends the POST request to the token endpoint at the AS. 2696 The security of this request can be transport or application 2697 layer. It is up the the communication security profile to define. 2698 In the example transport layer identification of the AS is done 2699 and the client identifies with client_id and client_secret as in 2700 classic OAuth. The request contains the public key of the client 2701 and the Audience parameter set to "tempSensorInLivingRoom", a 2702 value that the temperature sensor identifies itself with. The AS 2703 evaluates the request and authorizes the client to access the 2704 resource. 2705 B: The AS responds with a PoP access token and RS Information. 2706 The PoP access token contains the public key of the client, and 2707 the RS Information contains the public key of the RS. For 2708 communication security this example uses DTLS RawPublicKey between 2709 the client and the RS. The issued token will have a short 2710 validity time, i.e., "exp" close to "iat", to protect the RS from 2711 replay attacks. The token includes the claim such as "scope" with 2712 the authorized access that an owner of the temperature device can 2713 enjoy. In this example, the "scope" claim, issued by the AS, 2714 informs the RS that the owner of the token, that can prove the 2715 possession of a key is authorized to make a GET request against 2716 the /temperature resource and a POST request on the /firmware 2717 resource. Note that the syntax and semantics of the scope claim 2718 are application specific. 2719 Note: In this example it is assumed that the client knows what 2720 resource it wants to access, and is therefore able to request 2721 specific audience and scope claims for the access token. 2723 Authorization 2724 Client Server 2725 | | 2726 |<=======>| DTLS Connection Establishment 2727 | | to identify the AS 2728 | | 2729 A: +-------->| Header: POST (Code=0.02) 2730 | POST | Uri-Path:"token" 2731 | | Content-Type: application/cbor 2732 | | Payload: 2733 | | 2734 B: |<--------+ Header: 2.05 Content 2735 | 2.05 | Content-Type: application/cbor 2736 | | Payload: 2737 | | 2739 Figure 17: Token Request and Response Using Client Credentials. 2741 The information contained in the Request-Payload and the Response- 2742 Payload is shown in Figure 18. Note that a transport layer security 2743 based communication security profile is used in this example, 2744 therefore the Content-Type is "application/cbor". 2746 Request-Payload : 2747 { 2748 "grant_type" : "client_credentials", 2749 "aud" : "tempSensorInLivingRoom", 2750 "client_id" : "myclient", 2751 "client_secret" : "qwerty" 2752 } 2754 Response-Payload : 2755 { 2756 "access_token" : b64'SlAV32hkKG ...', 2757 "token_type" : "pop", 2758 "csp" : "DTLS", 2759 "rs_cnf" : { 2760 "COSE_Key" : { 2761 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2762 "kty" : "EC", 2763 "crv" : "P-256", 2764 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 2765 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 2766 } 2767 } 2768 } 2770 Figure 18: Request and Response Payload Details. 2772 The content of the access token is shown in Figure 19. 2774 { 2775 "aud" : "tempSensorInLivingRoom", 2776 "iat" : "1360189224", 2777 "exp" : "1360289224", 2778 "scope" : "temperature_g firmware_p", 2779 "cnf" : { 2780 "COSE_Key" : { 2781 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 2782 "kty" : "EC", 2783 "crv" : "P-256", 2784 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 2785 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 2786 } 2787 } 2788 } 2790 Figure 19: Access Token including Public Key of the Client. 2792 Messages C and F are shown in Figure 20 - Figure 21. 2794 C: The client then sends the PoP access token to the authz-info 2795 endpoint at the RS. This is a plain CoAP request, i.e., no 2796 transport or application layer security between client and RS, 2797 since the token is integrity protected between the AS and RS. The 2798 RS verifies that the PoP access token was created by a known and 2799 trusted AS, is valid, and responds to the client. The RS caches 2800 the security context together with authorization information about 2801 this client contained in the PoP access token. 2803 Resource 2804 Client Server 2805 | | 2806 C: +-------->| Header: POST (Code=0.02) 2807 | POST | Uri-Path:"authz-info" 2808 | | Payload: SlAV32hkKG ... 2809 | | 2810 |<--------+ Header: 2.04 Changed 2811 | 2.04 | 2812 | | 2814 Figure 20: Access Token provisioning to RS 2815 The client and the RS runs the DTLS handshake using the raw public 2816 keys established in step B and C. 2818 The client sends the CoAP request GET to /temperature on RS over 2819 DTLS. The RS verifies that the request is authorized, based on 2820 previously established security context. 2821 F: The RS responds with a resource representation over DTLS. 2823 Resource 2824 Client Server 2825 | | 2826 |<=======>| DTLS Connection Establishment 2827 | | using Raw Public Keys 2828 | | 2829 +-------->| Header: GET (Code=0.01) 2830 | GET | Uri-Path: "temperature" 2831 | | 2832 | | 2833 | | 2834 F: |<--------+ Header: 2.05 Content 2835 | 2.05 | Payload: 2836 | | 2838 Figure 21: Resource Request and Response protected by DTLS. 2840 E.2. Introspection Aided Token Validation 2842 In this deployment scenario it is assumed that a client is not able 2843 to access the AS at the time of the access request, whereas the RS is 2844 assumed to be connected to the back-end infrastructure. Thus the RS 2845 can make use of token introspection. This access procedure involves 2846 steps A-F of Figure 1, but assumes steps A and B have been carried 2847 out during a phase when the client had connectivity to AS. 2849 Since the client is assumed to be offline, at least for a certain 2850 period of time, a pre-provisioned access token has to be long-lived. 2851 Since the client is constrained, the token will not be self contained 2852 (i.e. not a CWT) but instead just a reference. The resource server 2853 uses its connectivity to learn about the claims assoicated to the 2854 access token by using introspection, which is shown in the example 2855 below. 2857 In the example interactions between an offline client (key fob), a RS 2858 (online lock), and an AS is shown. It is assumed that there is a 2859 provisioning step where the client has access to the AS. This 2860 corresponds to message exchanges A and B which are shown in 2861 Figure 22. 2863 Authorization consent from the resource owner can be pre-configured, 2864 but it can also be provided via an interactive flow with the resource 2865 owner. An example of this for the key fob case could be that the 2866 resource owner has a connected car, he buys a generic key that he 2867 wants to use with the car. To authorize the key fob he connects it 2868 to his computer that then provides the UI for the device. After that 2869 OAuth 2.0 implicit flow can used to authorize the key for his car at 2870 the the car manufacturers AS. 2872 Note: In this example the client does not know the exact door it will 2873 be used to access since the token request is not send at the time of 2874 access. So the scope and audience parameters are set quite wide to 2875 start with and new values different form the original once can be 2876 returned from introspection later on. 2878 A: The client sends the request using POST to the token endpoint 2879 at AS. The request contains the Audience parameter set to 2880 "PACS1337" (PACS, Physical Access System), a value the that the 2881 online door in question identifies itself with. The AS generates 2882 an access token as an opaque string, which it can match to the 2883 specific client, a targeted audience and a symmetric key. The 2884 security is provided by identifying the AS on transport layer 2885 using a pre shared security context (psk, rpk or certificate) and 2886 then the client is identified using client_id and client_secret as 2887 in classic OAuth. 2888 B: The AS responds with the an access token and RS Information, 2889 the latter containing a symmetric key. Communication security 2890 between C and RS will be DTLS and PreSharedKey. The PoP key is 2891 used as the PreSharedKey. 2893 Authorization 2894 Client Server 2895 | | 2896 | | 2897 A: +-------->| Header: POST (Code=0.02) 2898 | POST | Uri-Path:"token" 2899 | | Content-Type: application/cbor 2900 | | Payload: 2901 | | 2902 B: |<--------+ Header: 2.05 Content 2903 | | Content-Type: application/cbor 2904 | 2.05 | Payload: 2905 | | 2907 Figure 22: Token Request and Response using Client Credentials. 2909 The information contained in the Request-Payload and the Response- 2910 Payload is shown in Figure 23. 2912 Request-Payload: 2913 { 2914 "grant_type" : "client_credentials", 2915 "aud" : "lockOfDoor4711", 2916 "client_id" : "keyfob", 2917 "client_secret" : "qwerty" 2918 } 2920 Response-Payload: 2921 { 2922 "access_token" : b64'SlAV32hkKG ...' 2923 "token_type" : "pop", 2924 "csp" : "DTLS", 2925 "cnf" : { 2926 "COSE_Key" : { 2927 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2928 "kty" : "oct", 2929 "alg" : "HS256", 2930 "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' 2931 } 2932 } 2933 } 2935 Figure 23: Request and Response Payload for C offline 2937 The access token in this case is just an opaque string referencing 2938 the authorization information at the AS. 2940 C: Next, the client POSTs the access token to the authz-info 2941 endpoint in the RS. This is a plain CoAP request, i.e., no DTLS 2942 between client and RS. Since the token is an opaque string, the 2943 RS cannot verify it on its own, and thus defers to respond the 2944 client with a status code until after step E. 2945 D: The RS forwards the token to the introspection endpoint on the 2946 AS. Introspection assumes a secure connection between the AS and 2947 the RS, e.g., using transport of application layer security. In 2948 the example AS is identified using pre shared security context 2949 (psk, rpk or certificate) while RS is acting as client and is 2950 identified with client_id and client_secret. 2951 E: The AS provides the introspection response containing 2952 parameters about the token. This includes the confirmation key 2953 (cnf) parameter that allows the RS to verify the client's proof of 2954 possession in step F. 2955 After receiving message E, the RS responds to the client's POST in 2956 step C with the CoAP response code 2.01 (Created). 2958 Resource 2959 Client Server 2960 | | 2961 C: +-------->| Header: POST (T=CON, Code=0.02) 2962 | POST | Uri-Path:"authz-info" 2963 | | Content-Type: "application/cbor" 2964 | | Payload: b64'SlAV32hkKG ...'' 2965 | | 2966 | | Authorization 2967 | | Server 2968 | | | 2969 | D: +--------->| Header: POST (Code=0.02) 2970 | | POST | Uri-Path: "introspect" 2971 | | | Content-Type: "application/cbor" 2972 | | | Payload: 2973 | | | 2974 | E: |<---------+ Header: 2.05 Content 2975 | | 2.05 | Content-Type: "application/cbor" 2976 | | | Payload: 2977 | | | 2978 | | 2979 |<--------+ Header: 2.01 Created 2980 | 2.01 | 2981 | | 2983 Figure 24: Token Introspection for C offline 2984 The information contained in the Request-Payload and the Response- 2985 Payload is shown in Figure 25. 2987 Request-Payload: 2988 { 2989 "token" : b64'SlAV32hkKG...', 2990 "client_id" : "FrontDoor", 2991 "client_secret" : "ytrewq" 2992 } 2994 Response-Payload: 2995 { 2996 "active" : true, 2997 "aud" : "lockOfDoor4711", 2998 "scope" : "open, close", 2999 "iat" : 1311280970, 3000 "cnf" : { 3001 "kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 3002 } 3003 } 3005 Figure 25: Request and Response Payload for Introspection 3007 The client uses the symmetric PoP key to establish a DTLS 3008 PreSharedKey secure connection to the RS. The CoAP request PUT is 3009 sent to the uri-path /state on the RS, changing the state of the 3010 door to locked. 3011 F: The RS responds with a appropriate over the secure DTLS 3012 channel. 3014 Resource 3015 Client Server 3016 | | 3017 |<=======>| DTLS Connection Establishment 3018 | | using Pre Shared Key 3019 | | 3020 +-------->| Header: PUT (Code=0.03) 3021 | PUT | Uri-Path: "state" 3022 | | Payload: 3023 | | 3024 F: |<--------+ Header: 2.04 Changed 3025 | 2.04 | Payload: 3026 | | 3028 Figure 26: Resource request and response protected by OSCOAP 3030 Appendix F. Document Updates 3032 F.1. Version -08 to -09 3034 o Moved AS discovery from the DTLS profile to the framework, see 3035 Section 5.1. 3036 o Made the use of CBOR mandatory. If you use JSON you can use 3037 vanilla OAuth. 3038 o Made it mandatory for profiles to specify C-AS security and RS-AS 3039 security (the latter only if introspection is supported). 3040 o Made the use of CBOR abbreviations mandatory. 3041 o Added text to clarify the use of token references as an 3042 alternative to CWTs. 3043 o Added text to clarify that introspection must not be delayed, in 3044 case the RS has to return a client token. 3045 o Added security considerations about leakage through unprotected AS 3046 discovery information, combining profiles and leakage through 3047 error responses. 3048 o Added privacy considerations about leakage through unprotected AS 3049 discovery. 3050 o Added text that clarifies that introspection is optional. 3051 o Made profile parameter optional since it can be implicit. 3052 o Clarified that CoAP is not mandatory and other protocols can be 3053 used. 3055 o Clarified the design justification for specific features of the 3056 framework in appendix A. 3057 o Clarified appendix E.2. 3059 F.2. Version -07 to -08 3061 o Removed specification of the "cnf" claim for CBOR/COSE, and 3062 replaced with references to 3063 [I-D.jones-ace-cwt-proof-of-possession] 3065 F.3. Version -06 to -07 3067 o Various clarifications added. 3068 o Fixed erroneous author email. 3070 F.4. Version -05 to -06 3072 o Moved sections that define the ACE framework into a subsection of 3073 the framework Section 5. 3074 o Split section on client credentials and grant into two separate 3075 sections, Section 5.2, and Section 5.3. 3076 o Added Section 5.4 on AS authentication. 3077 o Added Section 5.5 on the Authorization endpoint. 3079 F.5. Version -04 to -05 3081 o Added RFC 2119 language to the specification of the required 3082 behavior of profile specifications. 3083 o Added Section 5.3 on the relation to the OAuth2 grant types. 3084 o Added CBOR abbreviations for error and the error codes defined in 3085 OAuth2. 3086 o Added clarification about token expiration and long-running 3087 requests in Section 5.8.2 3088 o Added security considerations about tokens with symmetric pop keys 3089 valid for more than one RS. 3090 o Added privacy considerations section. 3091 o Added IANA registry mapping the confirmation types from RFC 7800 3092 to equivalent COSE types. 3093 o Added appendix D, describing assumptions about what the AS knows 3094 about the client and the RS. 3096 F.6. Version -03 to -04 3098 o Added a description of the terms "framework" and "profiles" as 3099 used in this document. 3100 o Clarified protection of access tokens in section 3.1. 3101 o Clarified uses of the "cnf" parameter in section 6.4.5. 3102 o Clarified intended use of Client Token in section 7.4. 3104 F.7. Version -02 to -03 3106 o Removed references to draft-ietf-oauth-pop-key-distribution since 3107 the status of this draft is unclear. 3108 o Copied and adapted security considerations from draft-ietf-oauth- 3109 pop-key-distribution. 3110 o Renamed "client information" to "RS information" since it is 3111 information about the RS. 3112 o Clarified the requirements on profiles of this framework. 3113 o Clarified the token endpoint protocol and removed negotiation of 3114 "profile" and "alg" (section 6). 3115 o Renumbered the abbreviations for claims and parameters to get a 3116 consistent numbering across different endpoints. 3117 o Clarified the introspection endpoint. 3118 o Renamed token, introspection and authz-info to "endpoint" instead 3119 of "resource" to mirror the OAuth 2.0 terminology. 3120 o Updated the examples in the appendices. 3122 F.8. Version -01 to -02 3124 o Restructured to remove communication security parts. These shall 3125 now be defined in profiles. 3126 o Restructured section 5 to create new sections on the OAuth 3127 endpoints token, introspection and authz-info. 3128 o Pulled in material from draft-ietf-oauth-pop-key-distribution in 3129 order to define proof-of-possession key distribution. 3130 o Introduced the "cnf" parameter as defined in RFC7800 to reference 3131 or transport keys used for proof of possession. 3132 o Introduced the "client-token" to transport client information from 3133 the AS to the client via the RS in conjunction with introspection. 3134 o Expanded the IANA section to define parameters for token request, 3135 introspection and CWT claims. 3136 o Moved deployment scenarios to the appendix as examples. 3138 F.9. Version -00 to -01 3140 o Changed 5.1. from "Communication Security Protocol" to "Client 3141 Information". 3142 o Major rewrite of 5.1 to clarify the information exchanged between 3143 C and AS in the PoP access token request profile for IoT. 3145 * Allow the client to indicate preferences for the communication 3146 security protocol. 3147 * Defined the term "Client Information" for the additional 3148 information returned to the client in addition to the access 3149 token. 3150 * Require that the messages between AS and client are secured, 3151 either with (D)TLS or with COSE_Encrypted wrappers. 3153 * Removed dependency on OSCOAP and added generic text about 3154 object security instead. 3155 * Defined the "rpk" parameter in the client information to 3156 transmit the raw public key of the RS from AS to client. 3157 * (D)TLS MUST use the PoP key in the handshake (either as PSK or 3158 as client RPK with client authentication). 3159 * Defined the use of x5c, x5t and x5tS256 parameters when a 3160 client certificate is used for proof of possession. 3161 * Defined "tktn" parameter for signaling for how to transfer the 3162 access token. 3163 o Added 5.2. the CoAP Access-Token option for transferring access 3164 tokens in messages that do not have payload. 3165 o 5.3.2. Defined success and error responses from the RS when 3166 receiving an access token. 3167 o 5.6.:Added section giving guidance on how to handle token 3168 expiration in the absence of reliable time. 3169 o Appendix B Added list of roles and responsibilities for C, AS and 3170 RS. 3172 Authors' Addresses 3174 Ludwig Seitz 3175 RISE SICS 3176 Scheelevaegen 17 3177 Lund 223 70 3178 Sweden 3180 Email: ludwig.seitz@ri.se 3182 Goeran Selander 3183 Ericsson 3184 Faroegatan 6 3185 Kista 164 80 3186 Sweden 3188 Email: goran.selander@ericsson.com 3190 Erik Wahlstroem 3191 (no affiliation) 3192 Sweden 3194 Email: erik@wahlstromtekniska.se 3195 Samuel Erdtman 3196 Spotify AB 3197 Birger Jarlsgatan 61, 4tr 3198 Stockholm 113 56 3199 Sweden 3201 Email: erdtman@spotify.com 3203 Hannes Tschofenig 3204 ARM Ltd. 3205 Hall in Tirol 6060 3206 Austria 3208 Email: Hannes.Tschofenig@arm.com