idnits 2.17.1 draft-ietf-ace-oauth-authz-20.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 11, 2019) is 1900 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-11) exists of draft-ietf-ace-cwt-proof-of-possession-05 == Outdated reference: A later version (-16) exists of draft-ietf-ace-oauth-params-02 == Outdated reference: A later version (-19) exists of draft-ietf-oauth-token-exchange-16 ** 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 (-16) exists of draft-ietf-core-object-security-15 == Outdated reference: A later version (-15) exists of draft-ietf-oauth-device-flow-14 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-30 -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 7 warnings (==), 3 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 4 Intended status: Standards Track G. Selander 5 Expires: August 15, 2019 Ericsson 6 E. Wahlstroem 8 S. Erdtman 9 Spotify AB 10 H. Tschofenig 11 Arm Ltd. 12 February 11, 2019 14 Authentication and Authorization for Constrained Environments (ACE) 15 using the OAuth 2.0 Framework (ACE-OAuth) 16 draft-ietf-ace-oauth-authz-20 18 Abstract 20 This specification defines a framework for authentication and 21 authorization in Internet of Things (IoT) environments called ACE- 22 OAuth. The framework is based on a set of building blocks including 23 OAuth 2.0 and CoAP, thus making a well-known and widely used 24 authorization solution suitable for IoT devices. Existing 25 specifications are used where possible, but where the constraints of 26 IoT devices require it, extensions are added and profiles are 27 defined. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on August 15, 2019. 46 Copyright Notice 48 Copyright (c) 2019 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 7 67 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 10 68 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 11 69 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 15 70 5.1. Discovering Authorization Servers . . . . . . . . . . . . 16 71 5.1.1. Unauthorized Resource Request Message . . . . . . . . 16 72 5.1.2. AS Request Creation Hints . . . . . . . . . . . . . . 17 73 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 19 74 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 19 75 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 20 76 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 20 77 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 20 78 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 21 79 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 24 80 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 26 81 5.6.4. Request and Response Parameters . . . . . . . . . . . 27 82 5.6.4.1. Grant Type . . . . . . . . . . . . . . . . . . . 27 83 5.6.4.2. Token Type . . . . . . . . . . . . . . . . . . . 28 84 5.6.4.3. Profile . . . . . . . . . . . . . . . . . . . . . 28 85 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 29 86 5.7. The Introspection Endpoint . . . . . . . . . . . . . . . 29 87 5.7.1. Introspection Request . . . . . . . . . . . . . . . . 30 88 5.7.2. Introspection Response . . . . . . . . . . . . . . . 31 89 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 32 90 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 33 91 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 33 92 5.8.1. The Authorization Information Endpoint . . . . . . . 34 93 5.8.1.1. Verifying an Access Token . . . . . . . . . . . . 35 94 5.8.1.2. Protecting the Authorization Information 95 Endpoint . . . . . . . . . . . . . . . . . . . . 37 96 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 37 97 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 38 98 6. Security Considerations . . . . . . . . . . . . . . . . . . . 39 99 6.1. Unprotected AS Request Creation Hints . . . . . . . . . . 40 100 6.2. Minimal security requirements for communication . 40 101 6.3. Use of Nonces for Replay Protection . . . . . . . . . . . 41 102 6.4. Combining profiles . . . . . . . . . . . . . . . . . . . 41 103 6.5. Unprotected Information . . . . . . . . . . . . . . . . . 42 104 6.6. Identifying audiences . . . . . . . . . . . . . . . . . . 42 105 6.7. Denial of service against or with Introspection . . 43 106 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 43 107 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 108 8.1. ACE Authorization Server Request Creation Hints . . . . . 44 109 8.2. OAuth Extensions Error Registration . . . . . . . . . . . 45 110 8.3. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 45 111 8.4. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 46 112 8.5. OAuth Access Token Types . . . . . . . . . . . . . . . . 46 113 8.6. OAuth Access Token Type CBOR Mappings . . . . . . . . . . 47 114 8.6.1. Initial Registry Contents . . . . . . . . . . . . . . 47 115 8.7. ACE Profile Registry . . . . . . . . . . . . . . . . . . 47 116 8.8. OAuth Parameter Registration . . . . . . . . . . . . . . 48 117 8.9. OAuth Parameters CBOR Mappings Registry . . . . . . . . . 48 118 8.10. OAuth Introspection Response Parameter Registration . . . 49 119 8.11. OAuth Token Introspection Response CBOR Mappings Registry 49 120 8.12. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 50 121 8.13. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 50 122 8.14. Media Type Registrations . . . . . . . . . . . . . . . . 51 123 8.15. CoAP Content-Format Registry . . . . . . . . . . . . . . 52 124 8.16. Expert Review Instructions . . . . . . . . . . . . . . . 52 125 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 126 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 127 10.1. Normative References . . . . . . . . . . . . . . . . . . 54 128 10.2. Informative References . . . . . . . . . . . . . . . . . 56 129 Appendix A. Design Justification . . . . . . . . . . . . . . . . 58 130 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 62 131 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 64 132 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 64 133 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 65 134 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 65 135 E.2. Introspection Aided Token Validation . . . . . . . . . . 69 136 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 73 137 F.1. Verion -19 to 20 . . . . . . . . . . . . . . . . . . . . 73 138 F.2. Version -18 to -19 . . . . . . . . . . . . . . . . . . . 73 139 F.3. Version -17 to -18 . . . . . . . . . . . . . . . . . . . 74 140 F.4. Version -16 to -17 . . . . . . . . . . . . . . . . . . . 74 141 F.5. Version -15 to -16 . . . . . . . . . . . . . . . . . . . 74 142 F.6. Version -14 to -15 . . . . . . . . . . . . . . . . . . . 74 143 F.7. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 75 144 F.8. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 75 145 F.9. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 75 146 F.10. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 75 147 F.11. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 75 148 F.12. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 75 149 F.13. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 76 150 F.14. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 76 151 F.15. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 76 152 F.16. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 77 153 F.17. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 77 154 F.18. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 77 155 F.19. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 77 156 F.20. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 78 157 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 79 159 1. Introduction 161 Authorization is the process for granting approval to an entity to 162 access a resource [RFC4949]. The authorization task itself can best 163 be described as granting access to a requesting client, for a 164 resource hosted on a device, the resource server (RS). This exchange 165 is mediated by one or multiple authorization servers (AS). Managing 166 authorization for a large number of devices and users can be a 167 complex task. 169 While prior work on authorization solutions for the Web and for the 170 mobile environment also applies to the Internet of Things (IoT) 171 environment, many IoT devices are constrained, for example, in terms 172 of processing capabilities, available memory, etc. For web 173 applications on constrained nodes, this specification RECOMMENDS the 174 use of CoAP [RFC7252] as replacement for HTTP. 176 A detailed treatment of constraints can be found in [RFC7228], and 177 the different IoT deployments present a continuous range of device 178 and network capabilities. Taking energy consumption as an example: 179 At one end there are energy-harvesting or battery powered devices 180 which have a tight power budget, on the other end there are mains- 181 powered devices, and all levels in between. 183 Hence, IoT devices may be very different in terms of available 184 processing and message exchange capabilities and there is a need to 185 support many different authorization use cases [RFC7744]. 187 This specification describes a framework for authentication and 188 authorization in constrained environments (ACE) built on re-use of 189 OAuth 2.0 [RFC6749], thereby extending authorization to Internet of 190 Things devices. This specification contains the necessary building 191 blocks for adjusting OAuth 2.0 to IoT environments. 193 More detailed, interoperable specifications can be found in profiles. 194 Implementations may claim conformance with a specific profile, 195 whereby implementations utilizing the same profile interoperate while 196 implementations of different profiles are not expected to be 197 interoperable. Some devices, such as mobile phones and tablets, may 198 implement multiple profiles and will therefore be able to interact 199 with a wider range of low end devices. Requirements on profiles are 200 described at contextually appropriate places throughout this 201 specification, and also summarized in Appendix C. 203 2. Terminology 205 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 206 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 207 "OPTIONAL" in this document are to be interpreted as described in BCP 208 14 [RFC2119] [RFC8174] when, and only when, they appear in all 209 capitals, as shown here. 211 Certain security-related terms such as "authentication", 212 "authorization", "confidentiality", "(data) integrity", "message 213 authentication code", and "verify" are taken from [RFC4949]. 215 Since exchanges in this specification are described as RESTful 216 protocol interactions, HTTP [RFC7231] offers useful terminology. 218 Terminology for entities in the architecture is defined in OAuth 2.0 219 [RFC6749] such as client (C), resource server (RS), and authorization 220 server (AS). 222 Note that the term "endpoint" is used here following its OAuth 223 definition, which is to denote resources such as token and 224 introspection at the AS and authz-info at the RS (see Section 5.8.1 225 for a definition of the authz-info endpoint). The CoAP [RFC7252] 226 definition, which is "An entity participating in the CoAP protocol" 227 is not used in this specification. 229 The specifications in this document is called the "framework" or "ACE 230 framework". When referring to "profiles of this framework" it refers 231 to additional specifications that define the use of this 232 specification with concrete transport, and communication security 233 protocols (e.g., CoAP over DTLS). 235 We use the term "Access Information" for parameters other than the 236 access token provided to the client by the AS to enable it to access 237 the RS (e.g. public key of the RS, profile supported by RS). 239 We use the term "Authorization Information" to denote all 240 information, including the claims of relevant access tokens, that an 241 RS uses to determine whether an access request should be granted. 243 3. Overview 245 This specification defines the ACE framework for authorization in the 246 Internet of Things environment. It consists of a set of building 247 blocks. 249 The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys 250 widespread deployment. Many IoT devices can support OAuth 2.0 251 without any additional extensions, but for certain constrained 252 settings additional profiling is needed. 254 Another building block is the lightweight web transfer protocol CoAP 255 [RFC7252], for those communication environments where HTTP is not 256 appropriate. CoAP typically runs on top of UDP, which further 257 reduces overhead and message exchanges. While this specification 258 defines extensions for the use of OAuth over CoAP, other underlying 259 protocols are not prohibited from being supported in the future, such 260 as HTTP/2, MQTT, BLE and QUIC. 262 A third building block is CBOR [RFC7049], for encodings where JSON 263 [RFC8259] is not sufficiently compact. CBOR is a binary encoding 264 designed for small code and message size, which may be used for 265 encoding of self contained tokens, and also for encoding payload 266 transferred in protocol messages. 268 A fourth building block is the compact CBOR-based secure message 269 format COSE [RFC8152], which enables application layer security as an 270 alternative or complement to transport layer security (DTLS [RFC6347] 271 or TLS [RFC8446]). COSE is used to secure self-contained tokens such 272 as proof-of-possession (PoP) tokens, which is an extension to the 273 OAuth tokens. The default token format is defined in CBOR web token 274 (CWT) [RFC8392]. Application layer security for CoAP using COSE can 275 be provided with OSCORE [I-D.ietf-core-object-security]. 277 With the building blocks listed above, solutions satisfying various 278 IoT device and network constraints are possible. A list of 279 constraints is described in detail in RFC 7228 [RFC7228] and a 280 description of how the building blocks mentioned above relate to the 281 various constraints can be found in Appendix A. 283 Luckily, not every IoT device suffers from all constraints. The ACE 284 framework nevertheless takes all these aspects into account and 285 allows several different deployment variants to co-exist, rather than 286 mandating a one-size-fits-all solution. It is important to cover the 287 wide range of possible interworking use cases and the different 288 requirements from a security point of view. Once IoT deployments 289 mature, popular deployment variants will be documented in the form of 290 ACE profiles. 292 3.1. OAuth 2.0 294 The OAuth 2.0 authorization framework enables a client to obtain 295 scoped access to a resource with the permission of a resource owner. 296 Authorization information, or references to it, is passed between the 297 nodes using access tokens. These access tokens are issued to clients 298 by an authorization server with the approval of the resource owner. 299 The client uses the access token to access the protected resources 300 hosted by the resource server. 302 A number of OAuth 2.0 terms are used within this specification: 304 The token and introspection Endpoints: 305 The AS hosts the token endpoint that allows a client to request 306 access tokens. The client makes a POST request to the token 307 endpoint on the AS and receives the access token in the response 308 (if the request was successful). 309 In some deployments, a token introspection endpoint is provided by 310 the AS, which can be used by the RS if it needs to request 311 additional information regarding a received access token. The RS 312 makes a POST request to the introspection endpoint on the AS and 313 receives information about the access token in the response. (See 314 "Introspection" below.) 316 Access Tokens: 317 Access tokens are credentials needed to access protected 318 resources. An access token is a data structure representing 319 authorization permissions issued by the AS to the client. Access 320 tokens are generated by the AS and consumed by the RS. The access 321 token content is opaque to the client. 323 Access tokens can have different formats, and various methods of 324 utilization (e.g., cryptographic properties) based on the security 325 requirements of the given deployment. 327 Refresh Tokens: 328 Refresh tokens are credentials used to obtain access tokens. 329 Refresh tokens are issued to the client by the authorization 330 server and are used to obtain a new access token when the current 331 access token becomes invalid or expires, or to obtain additional 332 access tokens with identical or narrower scope (access tokens may 333 have a shorter lifetime and fewer permissions than authorized by 334 the resource owner). Issuing a refresh token is optional at the 335 discretion of the authorization server. If the authorization 336 server issues a refresh token, it is included when issuing an 337 access token (i.e., step (B) in Figure 1). 339 A refresh token in OAuth 2.0 is a string representing the 340 authorization granted to the client by the resource owner. The 341 string is usually opaque to the client. The token denotes an 342 identifier used to retrieve the authorization information. Unlike 343 access tokens, refresh tokens are intended for use only with 344 authorization servers and are never sent to resource servers. In 345 this framework, refresh tokens are encoded in binary instead of 346 strings, if used. 348 Proof of Possession Tokens: 349 An access token may be bound to a cryptographic key, which is then 350 used by an RS to authenticate requests from a client. Such tokens 351 are called proof-of-possession access tokens (or PoP access 352 tokens). 354 The proof-of-possession (PoP) security concept assumes that the AS 355 acts as a trusted third party that binds keys to access tokens. 356 These so called PoP keys are then used by the client to 357 demonstrate the possession of the secret to the RS when accessing 358 the resource. The RS, when receiving an access token, needs to 359 verify that the key used by the client matches the one bound to 360 the access token. When this specification uses the term "access 361 token" it is assumed to be a PoP access token token unless 362 specifically stated otherwise. 364 The key bound to the access token (the PoP key) may use either 365 symmetric or asymmetric cryptography. The appropriate choice of 366 the kind of cryptography depends on the constraints of the IoT 367 devices as well as on the security requirements of the use case. 369 Symmetric PoP key: 370 The AS generates a random symmetric PoP key. The key is either 371 stored to be returned on introspection calls or encrypted and 372 included in the access token. The PoP key is also encrypted 373 for the client and sent together with the access token to the 374 client. 376 Asymmetric PoP key: 377 An asymmetric key pair is generated on the client and the 378 public key is sent to the AS (if it does not already have 379 knowledge of the client's public key). Information about the 380 public key, which is the PoP key in this case, is either stored 381 to be returned on introspection calls or included inside the 382 access token and sent back to the requesting client. The RS 383 can identify the client's public key from the information in 384 the token, which allows the client to use the corresponding 385 private key for the proof of possession. 387 The access token is either a simple reference, or a structured 388 information object (e.g., CWT [RFC8392]) protected by a 389 cryptographic wrapper (e.g., COSE [RFC8152]). The choice of PoP 390 key does not necessarily imply a specific credential type for the 391 integrity protection of the token. 393 Scopes and Permissions: 394 In OAuth 2.0, the client specifies the type of permissions it is 395 seeking to obtain (via the scope parameter) in the access token 396 request. In turn, the AS may use the scope response parameter to 397 inform the client of the scope of the access token issued. As the 398 client could be a constrained device as well, this specification 399 defines the use of CBOR encoding as data format, see Section 5, to 400 request scopes and to be informed what scopes the access token 401 actually authorizes. 403 The values of the scope parameter in OAuth 2.0 are expressed as a 404 list of space-delimited, case-sensitive strings, with a semantic 405 that is well-known to the AS and the RS. More details about the 406 concept of scopes is found under Section 3.3 in [RFC6749]. 408 Claims: 409 Information carried in the access token or returned from 410 introspection, called claims, is in the form of name-value pairs. 411 An access token may, for example, include a claim identifying the 412 AS that issued the token (via the "iss" claim) and what audience 413 the access token is intended for (via the "aud" claim). The 414 audience of an access token can be a specific resource or one or 415 many resource servers. The resource owner policies influence what 416 claims are put into the access token by the authorization server. 418 While the structure and encoding of the access token varies 419 throughout deployments, a standardized format has been defined 420 with the JSON Web Token (JWT) [RFC7519] where claims are encoded 421 as a JSON object. In [RFC8392], an equivalent format using CBOR 422 encoding (CWT) has been defined. 424 Introspection: 425 Introspection is a method for a resource server to query the 426 authorization server for the active state and content of a 427 received access token. This is particularly useful in those cases 428 where the authorization decisions are very dynamic and/or where 429 the received access token itself is an opaque reference rather 430 than a self-contained token. More information about introspection 431 in OAuth 2.0 can be found in [RFC7662]. 433 3.2. CoAP 435 CoAP is an application layer protocol similar to HTTP, but 436 specifically designed for constrained environments. CoAP typically 437 uses datagram-oriented transport, such as UDP, where reordering and 438 loss of packets can occur. A security solution needs to take the 439 latter aspects into account. 441 While HTTP uses headers and query strings to convey additional 442 information about a request, CoAP encodes such information into 443 header parameters called 'options'. 445 CoAP supports application-layer fragmentation of the CoAP payloads 446 through blockwise transfers [RFC7959]. However, blockwise transfer 447 does not increase the size limits of CoAP options, therefore data 448 encoded in options has to be kept small. 450 Transport layer security for CoAP can be provided by DTLS or TLS 451 [RFC6347][RFC8446] [I-D.ietf-tls-dtls13]. CoAP defines a number of 452 proxy operations that require transport layer security to be 453 terminated at the proxy. One approach for protecting CoAP 454 communication end-to-end through proxies, and also to support 455 security for CoAP over a different transport in a uniform way, is to 456 provide security at the application layer using an object-based 457 security mechanism such as COSE [RFC8152]. 459 One application of COSE is OSCORE [I-D.ietf-core-object-security], 460 which provides end-to-end confidentiality, integrity and replay 461 protection, and a secure binding between CoAP request and response 462 messages. In OSCORE, the CoAP messages are wrapped in COSE objects 463 and sent using CoAP. 465 This framework RECOMMENDS the use of CoAP as replacement for HTTP for 466 use in constrained environments. 468 4. Protocol Interactions 470 The ACE framework is based on the OAuth 2.0 protocol interactions 471 using the token endpoint and optionally the introspection endpoint. 472 A client obtains an access token, and optionally a refresh token, 473 from an AS using the token endpoint and subsequently presents the 474 access token to a RS to gain access to a protected resource. In most 475 deployments the RS can process the access token locally, however in 476 some cases the RS may present it to the AS via the introspection 477 endpoint to get fresh information. These interactions are shown in 478 Figure 1. An overview of various OAuth concepts is provided in 479 Section 3.1. 481 The OAuth 2.0 framework defines a number of "protocol flows" via 482 grant types, which have been extended further with extensions to 483 OAuth 2.0 (such as RFC 7521 [RFC7521] and 484 [I-D.ietf-oauth-device-flow]). What grant types works best depends 485 on the usage scenario and RFC 7744 [RFC7744] describes many different 486 IoT use cases but there are two preferred grant types, namely the 487 Authorization Code Grant (described in Section 4.1 of [RFC7521]) and 488 the Client Credentials Grant (described in Section 4.4 of [RFC7521]). 489 The Authorization Code Grant is a good fit for use with apps running 490 on smart phones and tablets that request access to IoT devices, a 491 common scenario in the smart home environment, where users need to go 492 through an authentication and authorization phase (at least during 493 the initial setup phase). The native apps guidelines described in 494 [RFC8252] are applicable to this use case. The Client Credential 495 Grant is a good fit for use with IoT devices where the OAuth client 496 itself is constrained. In such a case, the resource owner has pre- 497 arranged access rights for the client with the authorization server, 498 which is often accomplished using a commissioning tool. 500 The consent of the resource owner, for giving a client access to a 501 protected resource, can be provided dynamically as in the traditional 502 OAuth flows, or it could be pre-configured by the resource owner as 503 authorization policies at the AS, which the AS evaluates when a token 504 request arrives. The resource owner and the requesting party (i.e., 505 client owner) are not shown in Figure 1. 507 This framework supports a wide variety of communication security 508 mechanisms between the ACE entities, such as client, AS, and RS. It 509 is assumed that the client has been registered (also called enrolled 510 or onboarded) to an AS using a mechanism defined outside the scope of 511 this document. In practice, various techniques for onboarding have 512 been used, such as factory-based provisioning or the use of 513 commissioning tools. Regardless of the onboarding technique, this 514 provisioning procedure implies that the client and the AS exchange 515 credentials and configuration parameters. These credentials are used 516 to mutually authenticate each other and to protect messages exchanged 517 between the client and the AS. 519 It is also assumed that the RS has been registered with the AS, 520 potentially in a similar way as the client has been registered with 521 the AS. Established keying material between the AS and the RS allows 522 the AS to apply cryptographic protection to the access token to 523 ensure that its content cannot be modified, and if needed, that the 524 content is confidentiality protected. 526 The keying material necessary for establishing communication security 527 between C and RS is dynamically established as part of the protocol 528 described in this document. 530 At the start of the protocol, there is an optional discovery step 531 where the client discovers the resource server and the resources this 532 server hosts. In this step, the client might also determine what 533 permissions are needed to access the protected resource. A generic 534 procedure is described in Section 5.1, profiles MAY define other 535 procedures for discovery. 537 In Bluetooth Low Energy, for example, advertisements are broadcasted 538 by a peripheral, including information about the primary services. 539 In CoAP, as a second example, a client can make a request to "/.well- 540 known/core" to obtain information about available resources, which 541 are returned in a standardized format as described in [RFC6690]. 543 +--------+ +---------------+ 544 | |---(A)-- Token Request ------->| | 545 | | | Authorization | 546 | |<--(B)-- Access Token ---------| Server | 547 | | + Access Information | | 548 | | + Refresh Token (optional) +---------------+ 549 | | ^ | 550 | | Introspection Request (D)| | 551 | Client | (optional) | | 552 | | Response | |(E) 553 | | (optional) | v 554 | | +--------------+ 555 | |---(C)-- Token + Request ----->| | 556 | | | Resource | 557 | |<--(F)-- Protected Resource ---| Server | 558 | | | | 559 +--------+ +--------------+ 561 Figure 1: Basic Protocol Flow. 563 Requesting an Access Token (A): 564 The client makes an access token request to the token endpoint at 565 the AS. This framework assumes the use of PoP access tokens (see 566 Section 3.1 for a short description) wherein the AS binds a key to 567 an access token. The client may include permissions it seeks to 568 obtain, and information about the credentials it wants to use 569 (e.g., symmetric/asymmetric cryptography or a reference to a 570 specific credential). 572 Access Token Response (B): 573 If the AS successfully processes the request from the client, it 574 returns an access token and optionally a refresh token (note that 575 only certain grant types support refresh tokens). It can also 576 return additional parameters, referred to as "Access Information". 577 In addition to the response parameters defined by OAuth 2.0 and 578 the PoP access token extension, this framework defines parameters 579 that can be used to inform the client about capabilities of the 580 RS. More information about these parameters can be found in 581 Section 5.6.4. 583 Resource Request (C): 584 The client interacts with the RS to request access to the 585 protected resource and provides the access token. The protocol to 586 use between the client and the RS is not restricted to CoAP. 588 HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also 589 viable candidates. 591 Depending on the device limitations and the selected protocol, 592 this exchange may be split up into two parts: 594 (1) the client sends the access token containing, or 595 referencing, the authorization information to the RS, that may 596 be used for subsequent resource requests by the client, and 598 (2) the client makes the resource access request, using the 599 communication security protocol and other Access Information 600 obtained from the AS. 602 The Client and the RS mutually authenticate using the security 603 protocol specified in the profile (see step B) and the keys 604 obtained in the access token or the Access Information. The RS 605 verifies that the token is integrity protected by the AS and 606 compares the claims contained in the access token with the 607 resource request. If the RS is online, validation can be handed 608 over to the AS using token introspection (see messages D and E) 609 over HTTP or CoAP. 611 Token Introspection Request (D): 612 A resource server may be configured to introspect the access token 613 by including it in a request to the introspection endpoint at that 614 AS. Token introspection over CoAP is defined in Section 5.7 and 615 for HTTP in [RFC7662]. 617 Note that token introspection is an optional step and can be 618 omitted if the token is self-contained and the resource server is 619 prepared to perform the token validation on its own. 621 Token Introspection Response (E): 622 The AS validates the token and returns the most recent parameters, 623 such as scope, audience, validity etc. associated with it back to 624 the RS. The RS then uses the received parameters to process the 625 request to either accept or to deny it. 627 Protected Resource (F): 628 If the request from the client is authorized, the RS fulfills the 629 request and returns a response with the appropriate response code. 631 The RS uses the dynamically established keys to protect the 632 response, according to used communication security protocol. 634 5. Framework 636 The following sections detail the profiling and extensions of OAuth 637 2.0 for constrained environments, which constitutes the ACE 638 framework. 640 Credential Provisioning 641 For IoT, it cannot be assumed that the client and RS are part of a 642 common key infrastructure, so the AS provisions credentials or 643 associated information to allow mutual authentication. These 644 credentials need to be provided to the parties before or during 645 the authentication protocol is executed, and may be re-used for 646 subsequent token requests. 648 Proof-of-Possession 649 The ACE framework, by default, implements proof-of-possession for 650 access tokens, i.e., that the token holder can prove being a 651 holder of the key bound to the token. The binding is provided by 652 the "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession] indicating 653 what key is used for proof-of-possession. If a client needs to 654 submit a new access token, e.g., to obtain additional access 655 rights, they can request that the AS binds this token to the same 656 key as the previous one. 658 ACE Profiles 659 The client or RS may be limited in the encodings or protocols it 660 supports. To support a variety of different deployment settings, 661 specific interactions between client and RS are defined in an ACE 662 profile. In ACE framework the AS is expected to manage the 663 matching of compatible profile choices between a client and an RS. 664 The AS informs the client of the selected profile using the 665 "profile" parameter in the token response. 667 OAuth 2.0 requires the use of TLS both to protect the communication 668 between AS and client when requesting an access token; between client 669 and RS when accessing a resource and between AS and RS if 670 introspection is used. In constrained settings TLS is not always 671 feasible, or desirable. Nevertheless it is REQUIRED that the data 672 exchanged with the AS is encrypted, integrity protected and protected 673 against message replay. It is also REQUIRED that the AS and the 674 endpoint communicating with it (client or RS) perform mutual 675 authentication. Furthermore it MUST be assured that responses are 676 bound to the requests in the sense that the receiver of a response 677 can be certain that the response actually belongs to a certain 678 request. 680 Profiles MUST specify a communication security protocol that provides 681 the features required above. 683 In OAuth 2.0 the communication with the Token and the Introspection 684 endpoints at the AS is assumed to be via HTTP and may use Uri-query 685 parameters. When profiles of this framework use CoAP instead, this 686 framework REQUIRES the use of the following alternative instead of 687 Uri-query parameters: The sender (client or RS) encodes the 688 parameters of its request as a CBOR map and submits that map as the 689 payload of the POST request. Profiles that use CBOR encoding of 690 protocol message parameters MUST use the media format 'application/ 691 ace+cbor', unless the protocol message is wrapped in another Content- 692 Format (e.g. object security). If CoAP is used for communication, 693 the Content-Format MUST be abbreviated with the ID: 19 (see 694 Section 8.15. 696 The OAuth 2.0 AS uses a JSON structure in the payload of its 697 responses both to client and RS. If CoAP is used, this framework 698 REQUIRES the use of CBOR [RFC7049] instead of JSON. Depending on the 699 profile, the CBOR payload MAY be enclosed in a non-CBOR cryptographic 700 wrapper. 702 5.1. Discovering Authorization Servers 704 In order to determine the AS in charge of a resource hosted at the 705 RS, C MAY send an initial Unauthorized Resource Request message to 706 RS. RS then denies the request and sends the address of its AS back 707 to C. 709 Instead of the initial Unauthorized Resource Request message, other 710 discovery methods may be used, or the client may be pre-provisioned 711 with the address of the AS. 713 5.1.1. Unauthorized Resource Request Message 715 The optional Unauthorized Resource Request message is a request for a 716 resource hosted by RS for which no proper authorization is granted. 717 RS MUST treat any request for a protected resource as Unauthorized 718 Resource Request message when any of the following holds: 720 o The request has been received on an unprotected channel. 722 o RS has no valid access token for the sender of the request 723 regarding the requested action on that resource. 725 o RS has a valid access token for the sender of the request, but 726 this does not allow the requested action on the requested 727 resource. 729 Note: These conditions ensure that RS can handle requests 730 autonomously once access was granted and a secure channel has been 731 established between C and RS. The authz-info endpoint MUST NOT be 732 protected as specified above, in order to allow clients to upload 733 access tokens to RS (cf. Section 5.8.1). 735 Unauthorized Resource Request messages MUST be denied with a client 736 error response. In this response, the Resource Server SHOULD provide 737 proper AS Request Creation Hints to enable the Client to request an 738 access token from RS's AS as described in Section 5.1.2. 740 The handling of all client requests (including unauthorized ones) by 741 the RS is described in Section 5.8.2. 743 5.1.2. AS Request Creation Hints 745 The AS Request Creation Hints message is sent by RS as a response to 746 an Unauthorized Resource Request message (see Section 5.1.1) to help 747 the sender of the Unauthorized Resource Request message in acquiring 748 a valid access token. The AS Request Creation Hints message is CBOR 749 map, with a MANDATORY element "AS" specifying an absolute URI (see 750 Section 4.3 of [RFC3986]) that identifies the AS in charge of RS. 752 The message can also contain the following OPTIONAL parameters: 754 o A "audience" element containing a suggested audience that the 755 client should request towards the AS. 757 o A "kid" element containing the key identifier of a key used in an 758 existing security association between the client and the RS. The 759 RS expects the client to request an access token bound to this 760 key, in order to avoid having to re-establish the security 761 association. 763 o A "nonce" element containing a nonce generated by RS to ensure 764 freshness in case that the RS and AS do not have synchronized 765 clocks. 767 o A "scope" element containing the suggested scope that the client 768 should request towards the AS. 770 Figure 2 summarizes the parameters that may be part of the AS Request 771 Creation Hints. 773 /-----------+----------+---------------------\ 774 | Name | CBOR Key | Value Type | 775 |-----------+----------+---------------------| 776 | AS | 0 | text string | 777 | kid | 4 | byte string | 778 | nonce | 5 | byte string | 779 | scope | 9 | text or byte string | 780 | audience | 18 | text string | 781 \-----------+----------+---------------------/ 783 Figure 2: AS Request Creation Hints 785 Note that the schema part of the AS parameter may need to be adapted 786 to the security protocol that is used between the client and the AS. 787 Thus the example AS value "coap://as.example.com/token" might need to 788 be transformed to "coaps://as.example.com/token". It is assumed that 789 the client can determine the correct schema part on its own depending 790 on the way it communicates with the AS. 792 Figure 3 shows an example for an AS Request Creation Hints message 793 payload using CBOR [RFC7049] diagnostic notation, using the parameter 794 names instead of the CBOR keys for better human readability. 796 4.01 Unauthorized 797 Content-Format: application/ace+cbor 798 {AS: "coaps://as.example.com/token", 799 audience: "coaps://rs.example.com", 800 nonce: h'e0a156bb3f', 801 scope: "rTempC" 802 } 804 Figure 3: AS Request Creation Hints payload example 806 In this example, the attribute AS points the receiver of this message 807 to the URI "coaps://as.example.com/token" to request access 808 permissions. The originator of the AS Request Creation Hints payload 809 (i.e., RS) uses a local clock that is loosely synchronized with a 810 time scale common between RS and AS (e.g., wall clock time). 811 Therefore, it has included a parameter "nonce" for replay attack 812 prevention. 814 Figure 4 illustrates the mandatory to use binary encoding of the 815 message payload shown in Figure 3. 817 a2 # map(2) 818 00 # unsigned(0) (=AS) 819 78 1c # text(28) 820 636f6170733a2f2f61732e657861 821 6d706c652e636f6d2f746f6b656e # "coaps://as.example.com/token" 822 05 # unsigned(5) (=nonce) 823 45 # bytes(5) 824 e0a156bb3f 826 Figure 4: AS Request Creation Hints example encoded in CBOR 828 5.2. Authorization Grants 830 To request an access token, the client obtains authorization from the 831 resource owner or uses its client credentials as grant. The 832 authorization is expressed in the form of an authorization grant. 834 The OAuth framework [RFC6749] defines four grant types. The grant 835 types can be split up into two groups, those granted on behalf of the 836 resource owner (password, authorization code, implicit) and those for 837 the client (client credentials). Further grant types have been added 838 later, such as [RFC7521] defining an assertion-based authorization 839 grant. 841 The grant type is selected depending on the use case. In cases where 842 the client acts on behalf of the resource owner, authorization code 843 grant is recommended. If the client acts on behalf of the resource 844 owner, but does not have any display or very limited interaction 845 possibilities it is recommended to use the device code grant defined 846 in [I-D.ietf-oauth-device-flow]. In cases where the client does not 847 act on behalf of the resource owner, client credentials grant is 848 recommended. 850 For details on the different grant types, see the OAuth 2.0 framework 851 [RFC6749]. The OAuth 2.0 framework provides an extension mechanism 852 for defining additional grant types so profiles of this framework MAY 853 define additional grant types, if needed. 855 5.3. Client Credentials 857 Authentication of the client is mandatory independent of the grant 858 type when requesting the access token from the token endpoint. In 859 the case of client credentials grant type, the authentication and 860 grant coincide. 862 Client registration and provisioning of client credentials to the 863 client is out of scope for this specification. 865 The OAuth framework [RFC6749] defines one client credential type, 866 client id and client secret. [I-D.erdtman-ace-rpcc] adds raw-public- 867 key and pre-shared-key to the client credentials types. Profiles of 868 this framework MAY extend with additional client credentials client 869 certificates. 871 5.4. AS Authentication 873 Client credential does not, by default, authenticate the AS that the 874 client connects to. In classic OAuth, the AS is authenticated with a 875 TLS server certificate. 877 Profiles of this framework MUST specify how clients authenticate the 878 AS and how communication security is implemented, otherwise server 879 side TLS certificates, as defined by OAuth 2.0, are required. 881 5.5. The Authorization Endpoint 883 The authorization endpoint is used to interact with the resource 884 owner and obtain an authorization grant in certain grant flows. 885 Since it requires the use of a user agent (i.e., browser), it is not 886 expected that these types of grant flow will be used by constrained 887 clients. This endpoint is therefore out of scope for this 888 specification. Implementations should use the definition and 889 recommendations of [RFC6749] and [RFC6819]. 891 If clients involved cannot support HTTP and TLS, profiles MAY define 892 mappings for the authorization endpoint. 894 5.6. The Token Endpoint 896 In standard OAuth 2.0, the AS provides the token endpoint for 897 submitting access token requests. This framework extends the 898 functionality of the token endpoint, giving the AS the possibility to 899 help the client and RS to establish shared keys or to exchange their 900 public keys. Furthermore, this framework defines encodings using 901 CBOR, as a substitute for JSON. 903 The endpoint may, however, be exposed over HTTPS as in classical 904 OAuth or even other transports. A profile MUST define the details of 905 the mapping between the fields described below, and these transports. 906 If HTTPS is used, JSON or CBOR payloads may be supported. If JSON 907 payloads are used, the semantics of Section 4 of the OAuth 2.0 908 specification MUST be followed (with additions as described below). 909 If CBOR payload is supported, the semantics described below MUST be 910 followed. 912 For the AS to be able to issue a token, the client MUST be 913 authenticated and present a valid grant for the scopes requested. 914 Profiles of this framework MUST specify how the AS authenticates the 915 client and how the communication between client and AS is protected. 917 The default name of this endpoint in an url-path is '/token', however 918 implementations are not required to use this name and can define 919 their own instead. 921 The figures of this section use CBOR diagnostic notation without the 922 integer abbreviations for the parameters or their values for 923 illustrative purposes. Note that implementations MUST use the 924 integer abbreviations and the binary CBOR encoding, if the CBOR 925 encoding is used. 927 5.6.1. Client-to-AS Request 929 The client sends a POST request to the token endpoint at the AS. The 930 profile MUST specify how the communication is protected. The content 931 of the request consists of the parameters specified in Section 4 of 932 the OAuth 2.0 specification [RFC6749] with the exception of the 933 "grant_type" parameter, which is OPTIONAL in the context of this 934 framework (as opposed to REQUIRED in RFC6749). If that parameter is 935 missing, the default value "client_credentials" is implied. 937 Furthermore the "audience" parameter from 938 [I-D.ietf-oauth-token-exchange] can be used to request an access 939 token bound to a specific audience. 941 In addition to these parameters, a client MUST be able to use the 942 parameters from [I-D.ietf-ace-oauth-params] in an access token 943 request to the token endpoint and the AS MUST be able to process 944 these additional parameters. 946 If CBOR is used then this parameter MUST be encoded as a CBOR map. 947 The "scope" parameter can be formatted as specified in [RFC6749] and 948 additionally as a byte string, in order to allow compact encoding of 949 complex scopes. 951 When HTTP is used as a transport then the client makes a request to 952 the token endpoint by sending the parameters using the "application/ 953 x-www-form-urlencoded" format with a character encoding of UTF-8 in 954 the HTTP request entity-body, as defined in RFC 6749. 956 The following examples illustrate different types of requests for 957 proof-of-possession tokens. 959 Figure 5 shows a request for a token with a symmetric proof-of- 960 possession key. The content is displayed in CBOR diagnostic 961 notation, without abbreviations for better readability. 963 Header: POST (Code=0.02) 964 Uri-Host: "as.example.com" 965 Uri-Path: "token" 966 Content-Format: "application/ace+cbor" 967 Payload: 968 { 969 "client_id" : "myclient", 970 "audience" : "tempSensor4711" 971 } 973 Figure 5: Example request for an access token bound to a symmetric 974 key. 976 Figure 6 shows a request for a token with an asymmetric proof-of- 977 possession key. Note that in this example OSCORE 978 [I-D.ietf-core-object-security] is used to provide object-security, 979 therefore the Content-Format is "application/oscore" wrapping the 980 "application/ace+cbor" type content. Also note that in this example 981 the audience is implicitly known by both client and AS. Furthermore 982 note that this example uses the "req_cnf" parameter from 983 [I-D.ietf-ace-oauth-params]. 985 Header: POST (Code=0.02) 986 Uri-Host: "as.example.com" 987 Uri-Path: "token" 988 OSCORE: 0x19, 0x05, 0x05, 0x44, 0x61, 0x6c, 0x65, 0x6b 989 Content-Format: "application/oscore" 990 Payload: 991 0x44025d1 ... (full payload omitted for brevity) ... 68b3825e 992 ) 994 Decrypted payload: 995 { 996 "client_id" : "myclient", 997 "req_cnf" : { 998 "COSE_Key" : { 999 "kty" : "EC", 1000 "kid" : h'11', 1001 "crv" : "P-256", 1002 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 1003 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 1004 } 1005 } 1006 } 1008 Figure 6: Example token request bound to an asymmetric key. 1010 Figure 7 shows a request for a token where a previously communicated 1011 proof-of-possession key is only referenced. Note that the client 1012 performs a password based authentication in this example by 1013 submitting its client_secret (see Section 2.3.1 of [RFC6749]). Note 1014 that this example uses the "req_cnf" parameter from 1015 [I-D.ietf-ace-oauth-params]. 1017 Header: POST (Code=0.02) 1018 Uri-Host: "as.example.com" 1019 Uri-Path: "token" 1020 Content-Format: "application/ace+cbor" 1021 Payload: 1022 { 1023 "client_id" : "myclient", 1024 "client_secret" : "mysecret234", 1025 "audience" : "valve424", 1026 "scope" : "read", 1027 "req_cnf" : { 1028 "kid" : b64'6kg0dXJM13U' 1029 } 1030 } 1032 Figure 7: Example request for an access token bound to a key 1033 reference. 1035 Refresh tokens are typically not stored as securely as proof-of- 1036 possession keys in requesting clients. Proof-of-possession based 1037 refresh token requests MUST NOT request different proof-of-possession 1038 keys or different audiences in token requests. Refresh token 1039 requests can only use to request access tokens bound to the same 1040 proof-of-possession key and the same audience as access tokens issued 1041 in the initial token request. 1043 5.6.2. AS-to-Client Response 1045 If the access token request has been successfully verified by the AS 1046 and the client is authorized to obtain an access token corresponding 1047 to its access token request, the AS sends a response with the 1048 response code equivalent to the CoAP response code 2.01 (Created). 1049 If client request was invalid, or not authorized, the AS returns an 1050 error response as described in Section 5.6.3. 1052 Note that the AS decides which token type and profile to use when 1053 issuing a successful response. It is assumed that the AS has prior 1054 knowledge of the capabilities of the client and the RS (see 1055 Appendix D. This prior knowledge may, for example, be set by the use 1056 of a dynamic client registration protocol exchange [RFC7591]. 1058 The content of the successful reply is the Access Information. When 1059 using CBOR payloads, the content MUST be encoded as CBOR map, 1060 containing parameters as specified in Section 5.1 of [RFC6749], with 1061 the following additions and changes: 1063 profile: 1065 OPTIONAL. This indicates the profile that the client MUST use 1066 towards the RS. See Section 5.6.4.3 for the formatting of this 1067 parameter. If this parameter is absent, the AS assumes that the 1068 client implicitly knows which profile to use towards the RS. 1070 token_type: 1071 This parameter is OPTIONAL, as opposed to 'required' in [RFC6749]. 1072 By default implementations of this framework SHOULD assume that 1073 the token_type is "pop". If a specific use case requires another 1074 token_type (e.g., "Bearer") to be used then this parameter is 1075 REQUIRED. 1077 Furthermore [I-D.ietf-ace-oauth-params] defines additional parameters 1078 that the AS MUST be able to use when responding to a request to the 1079 token endpoint. 1081 Figure 8 summarizes the parameters that may be part of the Access 1082 Information. This does not include the additional parameters 1083 specified in [I-D.ietf-ace-oauth-params]. 1085 /-------------------+-------------------------------\ 1086 | Parameter name | Specified in | 1087 |-------------------+-------------------------------| 1088 | access_token | RFC 6749 | 1089 | token_type | RFC 6749 | 1090 | expires_in | RFC 6749 | 1091 | refresh_token | RFC 6749 | 1092 | scope | RFC 6749 | 1093 | state | RFC 6749 | 1094 | error | RFC 6749 | 1095 | error_description | RFC 6749 | 1096 | error_uri | RFC 6749 | 1097 | profile | [this document] | 1098 \-------------------+-------------------------------/ 1100 Figure 8: Access Information parameters 1102 Figure 9 shows a response containing a token and a "cnf" parameter 1103 with a symmetric proof-of-possession key, which is defined in 1104 [I-D.ietf-ace-oauth-params]. 1106 Header: Created (Code=2.01) 1107 Content-Format: "application/ace+cbor" 1108 Payload: 1109 { 1110 "access_token" : b64'SlAV32hkKG ... 1111 (remainder of CWT omitted for brevity; 1112 CWT contains COSE_Key in the "cnf" claim)', 1113 "profile" : "coap_dtls", 1114 "expires_in" : "3600", 1115 "cnf" : { 1116 "COSE_Key" : { 1117 "kty" : "Symmetric", 1118 "kid" : b64'39Gqlw', 1119 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1120 } 1121 } 1122 } 1124 Figure 9: Example AS response with an access token bound to a 1125 symmetric key. 1127 5.6.3. Error Response 1129 The error responses for CoAP-based interactions with the AS are 1130 equivalent to the ones for HTTP-based interactions as defined in 1131 Section 5.2 of [RFC6749], with the following differences: 1133 o When using CBOR the raw payload before being processed by the 1134 communication security protocol MUST be encoded as a CBOR map. 1136 o A response code equivalent to the CoAP code 4.00 (Bad Request) 1137 MUST be used for all error responses, except for invalid_client 1138 where a response code equivalent to the CoAP code 4.01 1139 (Unauthorized) MAY be used under the same conditions as specified 1140 in Section 5.2 of [RFC6749]. 1142 o The content type (for CoAP-based interactions) or media type (for 1143 HTTP-based interactions) "application/ace+cbor" MUST be used for 1144 the error response. 1146 o The parameters "error", "error_description" and "error_uri" MUST 1147 be abbreviated using the codes specified in Figure 12, when a CBOR 1148 encoding is used. 1150 o The error code (i.e., value of the "error" parameter) MUST be 1151 abbreviated as specified in Figure 10, when a CBOR encoding is 1152 used. 1154 /------------------------+-------------\ 1155 | Name | CBOR Values | 1156 |------------------------+-------------| 1157 | invalid_request | 1 | 1158 | invalid_client | 2 | 1159 | invalid_grant | 3 | 1160 | unauthorized_client | 4 | 1161 | unsupported_grant_type | 5 | 1162 | invalid_scope | 6 | 1163 | unsupported_pop_key | 7 | 1164 | incompatible_profiles | 8 | 1165 \------------------------+-------------/ 1167 Figure 10: CBOR abbreviations for common error codes 1169 In addition to the error responses defined in OAuth 2.0, the 1170 following behavior MUST be implemented by the AS: 1172 o If the client submits an asymmetric key in the token request that 1173 the RS cannot process, the AS MUST reject that request with a 1174 response code equivalent to the CoAP code 4.00 (Bad Request) 1175 including the error code "unsupported_pop_key" defined in 1176 Figure 10. 1178 o If the client and the RS it has requested an access token for do 1179 not share a common profile, the AS MUST reject that request with a 1180 response code equivalent to the CoAP code 4.00 (Bad Request) 1181 including the error code "incompatible_profiles" defined in 1182 Figure 10. 1184 5.6.4. Request and Response Parameters 1186 This section provides more detail about the new parameters that can 1187 be used in access token requests and responses, as well as 1188 abbreviations for more compact encoding of existing parameters and 1189 common parameter values. 1191 5.6.4.1. Grant Type 1193 The abbreviations in Figure 11 MUST be used in CBOR encodings instead 1194 of the string values defined in [RFC6749], if CBOR payloads are used. 1196 /--------------------+------------+------------------------\ 1197 | Name | CBOR Value | Original Specification | 1198 |--------------------+------------+------------------------| 1199 | password | 0 | RFC6749 | 1200 | authorization_code | 1 | RFC6749 | 1201 | client_credentials | 2 | RFC6749 | 1202 | refresh_token | 3 | RFC6749 | 1203 \--------------------+------------+------------------------/ 1205 Figure 11: CBOR abbreviations for common grant types 1207 5.6.4.2. Token Type 1209 The "token_type" parameter, defined in [RFC6749], allows the AS to 1210 indicate to the client which type of access token it is receiving 1211 (e.g., a bearer token). 1213 This document registers the new value "pop" for the OAuth Access 1214 Token Types registry, specifying a proof-of-possession token. How 1215 the proof-of-possession by the client to the RS is performed MUST be 1216 specified by the profiles. 1218 The values in the "token_type" parameter MUST be CBOR text strings, 1219 if a CBOR encoding is used. 1221 In this framework the "pop" value for the "token_type" parameter is 1222 the default. The AS may, however, provide a different value. 1224 5.6.4.3. Profile 1226 Profiles of this framework MUST define the communication protocol and 1227 the communication security protocol between the client and the RS. 1228 The security protocol MUST provide encryption, integrity and replay 1229 protection. It MUST also provide a binding between requests and 1230 responses. Furthermore profiles MUST define proof-of-possession 1231 methods, if they support proof-of-possession tokens. 1233 A profile MUST specify an identifier that MUST be used to uniquely 1234 identify itself in the "profile" parameter. The textual 1235 representation of the profile identifier is just intended for human 1236 readability and MUST NOT be used in parameters and claims. 1238 Profiles MAY define additional parameters for both the token request 1239 and the Access Information in the access token response in order to 1240 support negotiation or signaling of profile specific parameters. 1242 5.6.5. Mapping Parameters to CBOR 1244 If CBOR encoding is used, all OAuth parameters in access token 1245 requests and responses MUST be mapped to CBOR types as specified in 1246 Figure 12, using the given integer abbreviation for the map keys. 1248 Note that we have aligned the abbreviations corresponding to claims 1249 with the abbreviations defined in [RFC8392]. 1251 Note also that abbreviations from -24 to 23 have a 1 byte encoding 1252 size in CBOR. We have thus chosen to assign abbreviations in that 1253 range to parameters we expect to be used most frequently in 1254 constrained scenarios. 1256 /-------------------+----------+---------------------\ 1257 | Name | CBOR Key | Value Type | 1258 |-------------------+----------+---------------------| 1259 | access_token | 1 | byte string | 1260 | scope | 9 | text or byte string | 1261 | audience | 18 | text string | 1262 | client_id | 24 | text string | 1263 | client_secret | 25 | byte string | 1264 | response_type | 26 | text string | 1265 | redirect_uri | 27 | text string | 1266 | state | 28 | text string | 1267 | code | 29 | byte string | 1268 | error | 30 | unsigned integer | 1269 | error_description | 31 | text string | 1270 | error_uri | 32 | text string | 1271 | grant_type | 33 | unsigned integer | 1272 | token_type | 34 | unsigned integer | 1273 | expires_in | 35 | unsigned integer | 1274 | username | 36 | text string | 1275 | password | 37 | text string | 1276 | refresh_token | 38 | byte string | 1277 | profile | 39 | unsigned integer | 1278 \-------------------+----------+---------------------/ 1280 Figure 12: CBOR mappings used in token requests 1282 5.7. The Introspection Endpoint 1284 Token introspection [RFC7662] can be OPTIONALLY provided by the AS, 1285 and is then used by the RS and potentially the client to query the AS 1286 for metadata about a given token, e.g., validity or scope. Analogous 1287 to the protocol defined in RFC 7662 [RFC7662] for HTTP and JSON, this 1288 section defines adaptations to more constrained environments using 1289 CBOR and leaving the choice of the application protocol to the 1290 profile. 1292 Communication between the requesting entity and the introspection 1293 endpoint at the AS MUST be integrity protected and encrypted. The 1294 communication security protocol MUST also provide a binding between 1295 requests and responses. Furthermore the two interacting parties MUST 1296 perform mutual authentication. Finally the AS SHOULD verify that the 1297 requesting entity has the right to access introspection information 1298 about the provided token. Profiles of this framework that support 1299 introspection MUST specify how authentication and communication 1300 security between the requesting entity and the AS is implemented. 1302 The default name of this endpoint in an url-path is '/introspect', 1303 however implementations are not required to use this name and can 1304 define their own instead. 1306 The figures of this section uses CBOR diagnostic notation without the 1307 integer abbreviations for the parameters or their values for better 1308 readability. 1310 Note that supporting introspection is OPTIONAL for implementations of 1311 this framework. 1313 5.7.1. Introspection Request 1315 The requesting entity sends a POST request to the introspection 1316 endpoint at the AS, the profile MUST specify how the communication is 1317 protected. If CBOR is used, the payload MUST be encoded as a CBOR 1318 map with a "token" entry containing either the access token or a 1319 reference to the token (e.g., the cti). Further optional parameters 1320 representing additional context that is known by the requesting 1321 entity to aid the AS in its response MAY be included. 1323 For CoAP-based interaction, all messages MUST use the content type 1324 "application/ace+cbor", while for HTTP-based interactions the 1325 equivalent media type "application/ace+cbor" MUST be used. 1327 The same parameters are required and optional as in Section 2.1 of 1328 RFC 7662 [RFC7662]. 1330 For example, Figure 13 shows a RS calling the token introspection 1331 endpoint at the AS to query about an OAuth 2.0 proof-of-possession 1332 token. Note that object security based on OSCORE 1333 [I-D.ietf-core-object-security] is assumed in this example, therefore 1334 the Content-Format is "application/oscore". Figure 14 shows the 1335 decoded payload. 1337 Header: POST (Code=0.02) 1338 Uri-Host: "as.example.com" 1339 Uri-Path: "introspect" 1340 OSCORE: 0x09, 0x05, 0x25 1341 Content-Format: "application/oscore" 1342 Payload: 1343 ... COSE content ... 1345 Figure 13: Example introspection request. 1347 { 1348 "token" : b64'7gj0dXJQ43U', 1349 "token_type_hint" : "pop" 1350 } 1352 Figure 14: Decoded token. 1354 5.7.2. Introspection Response 1356 If the introspection request is authorized and successfully 1357 processed, the AS sends a response with the response code equivalent 1358 to the CoAP code 2.01 (Created). If the introspection request was 1359 invalid, not authorized or couldn't be processed the AS returns an 1360 error response as described in Section 5.7.3. 1362 In a successful response, the AS encodes the response parameters in a 1363 map including with the same required and optional parameters as in 1364 Section 2.2 of RFC 7662 [RFC7662] with the following addition: 1366 profile OPTIONAL. This indicates the profile that the RS MUST use 1367 with the client. See Section 5.6.4.3 for more details on the 1368 formatting of this parameter. 1370 Furthermore [I-D.ietf-ace-oauth-params] defines more parameters that 1371 the AS MUST be able to use when responding to a request to the 1372 introspection endpoint. 1374 For example, Figure 15 shows an AS response to the introspection 1375 request in Figure 13. Note that this example contains the "cnf" 1376 parameter defined in [I-D.ietf-ace-oauth-params]. 1378 Header: Created Code=2.01) 1379 Content-Format: "application/ace+cbor" 1380 Payload: 1381 { 1382 "active" : true, 1383 "scope" : "read", 1384 "profile" : "coap_dtls", 1385 "cnf" : { 1386 "COSE_Key" : { 1387 "kty" : "Symmetric", 1388 "kid" : b64'39Gqlw', 1389 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1390 } 1391 } 1392 } 1394 Figure 15: Example introspection response. 1396 5.7.3. Error Response 1398 The error responses for CoAP-based interactions with the AS are 1399 equivalent to the ones for HTTP-based interactions as defined in 1400 Section 2.3 of [RFC7662], with the following differences: 1402 o If content is sent and CBOR is used the payload MUST be encoded as 1403 a CBOR map and the Content-Format "application/ace+cbor" MUST be 1404 used. 1406 o If the credentials used by the requesting entity (usually the RS) 1407 are invalid the AS MUST respond with the response code equivalent 1408 to the CoAP code 4.01 (Unauthorized) and use the required and 1409 optional parameters from Section 5.2 in RFC 6749 [RFC6749]. 1411 o If the requesting entity does not have the right to perform this 1412 introspection request, the AS MUST respond with a response code 1413 equivalent to the CoAP code 4.03 (Forbidden). In this case no 1414 payload is returned. 1416 o The parameters "error", "error_description" and "error_uri" MUST 1417 be abbreviated using the codes specified in Figure 12. 1419 o The error codes MUST be abbreviated using the codes specified in 1420 Figure 10. 1422 Note that a properly formed and authorized query for an inactive or 1423 otherwise invalid token does not warrant an error response by this 1424 specification. In these cases, the authorization server MUST instead 1425 respond with an introspection response with the "active" field set to 1426 "false". 1428 5.7.4. Mapping Introspection parameters to CBOR 1430 If CBOR is used, the introspection request and response parameters 1431 MUST be mapped to CBOR types as specified in Figure 16, using the 1432 given integer abbreviation for the map key. 1434 Note that we have aligned abbreviations that correspond to a claim 1435 with the abbreviations defined in [RFC8392] and the abbreviations of 1436 parameters with the same name from Section 5.6.5. 1438 /-------------------+----------+-------------------------\ 1439 | Parameter name | CBOR Key | Value Type | 1440 |-------------------+----------+-------------------------| 1441 | iss | 1 | text string | 1442 | sub | 2 | text string | 1443 | aud | 3 | text string | 1444 | exp | 4 | integer or | 1445 | | | floating-point number | 1446 | nbf | 5 | integer or | 1447 | | | floating-point number | 1448 | iat | 6 | integer or | 1449 | | | floating-point number | 1450 | cti | 7 | byte string | 1451 | scope | 9 | text or byte string | 1452 | active | 10 | True or False | 1453 | token | 12 | byte string | 1454 | client_id | 24 | text string | 1455 | error | 30 | unsigned integer | 1456 | error_description | 31 | text string | 1457 | error_uri | 32 | text string | 1458 | token_type_hint | 33 | text string | 1459 | token_type | 34 | text string | 1460 | username | 36 | text string | 1461 | profile | 39 | unsigned integer | 1462 \-------------------+----------+-------------------------/ 1464 Figure 16: CBOR Mappings to Token Introspection Parameters. 1466 5.8. The Access Token 1468 This framework RECOMMENDS the use of CBOR web token (CWT) as 1469 specified in [RFC8392]. 1471 In order to facilitate offline processing of access tokens, this 1472 document uses the "cnf" claim from 1474 [I-D.ietf-ace-cwt-proof-of-possession] and specifies the "scope" 1475 claim for JWT- and CWT-encoded tokens. 1477 The "scope" claim explicitly encodes the scope of a given access 1478 token. This claim follows the same encoding rules as defined in 1479 Section 3.3 of [RFC6749], but in addition implementers MAY use byte 1480 strings as scope values, to achieve compact encoding of large scope 1481 elements. The meaning of a specific scope value is application 1482 specific and expected to be known to the RS running that application. 1484 If the AS needs to convey a hint to the RS about which profile it 1485 should use to communicate with the client, the AS MAY include a 1486 "profile" claim in the access token, with the same syntax and 1487 semantics as defined in Section 5.6.4.3. 1489 5.8.1. The Authorization Information Endpoint 1491 The access token, containing authorization information and 1492 information about the key used by the client, needs to be transported 1493 to the RS so that the RS can authenticate and authorize the client 1494 request. 1496 This section defines a method for transporting the access token to 1497 the RS using a RESTful protocol such as CoAP. Profiles of this 1498 framework MAY define other methods for token transport. 1500 The method consists of an authz-info endpoint, implemented by the RS. 1501 A client using this method MUST make a POST request to the authz-info 1502 endpoint at the RS with the access token in the payload. The RS 1503 receiving the token MUST verify the validity of the token. If the 1504 token is valid, the RS MUST respond to the POST request with 2.01 1505 (Created). Section Section 5.8.1.1 outlines how an RS MUST proceed 1506 to verify the validity of an access token. 1508 The RS MUST be prepared to store at least one access token for future 1509 use. This is a difference to how access tokens are handled in OAuth 1510 2.0, where the access token is typically sent along with each 1511 request, and therefore not stored at the RS. 1513 This specification RECOMMENDS that an RS stores only one token per 1514 proof-of-possession key, meaning that an additional token linked to 1515 the same key will overwrite any existing token at the RS. 1517 If the payload sent to the authz-info endpoint does not parse to a 1518 token, the RS MUST respond with a response code equivalent to the 1519 CoAP code 4.00 (Bad Request). 1521 The RS MAY make an introspection request to validate the token before 1522 responding to the POST request to the authz-info endpoint. 1524 Profiles MUST specify whether the authz-info endpoint is protected, 1525 including whether error responses from this endpoint are protected. 1526 Note that since the token contains information that allow the client 1527 and the RS to establish a security context in the first place, mutual 1528 authentication may not be possible at this point. 1530 The default name of this endpoint in an url-path is '/authz-info', 1531 however implementations are not required to use this name and can 1532 define their own instead. 1534 A RS MAY use introspection on a token received through the authz-info 1535 endpoint, e.g. if the token is an opaque reference. Some transport 1536 protocols may provide a way to indicate that the RS is busy and the 1537 client should retry after an interval; this type of status update 1538 would be appropriate while the RS is waiting for an introspection 1539 response. 1541 5.8.1.1. Verifying an Access Token 1543 When an RS receives an access token, it MUST verify it before storing 1544 it. The details of token verification depends on various aspects, 1545 including the token encoding, the type of token, the security 1546 protection applied to the token, and the claims. The token encoding 1547 matters since the security wrapper differs between the token 1548 encodings. For example, a CWT token uses COSE while a JWT token uses 1549 JOSE. The type of token also has an influence on the verification 1550 procedure since tokens may be self-contained whereby token 1551 verification may happen locally at the RS while a token-by-reference 1552 requires further interaction with the authorization server, for 1553 example using token introspection, to obtain the claims associated 1554 with the token reference. Self-contained token MUST, at a minimum, 1555 be integrity protected but they MAY also be encrypted. 1557 For self-contained tokens the RS MUST process the security protection 1558 of the token first, as specified by the respective token format. For 1559 CWT the description can be found in [RFC8392] and for JWT the 1560 relevant specification is [RFC7519]. This MUST include a 1561 verification that security protection (and thus the token) was 1562 generated by an AS that has the right to issue access tokens for this 1563 RS. 1565 In case the token is communicated by reference the RS needs to obtain 1566 the claims first. When the RS uses token introspection the relevant 1567 specification is [RFC7662] with CoAP transport specified in 1568 Section 5.7. 1570 Errors may happen during this initial processing stage: 1572 o If token or claim verification fails, the RS MUST discard the 1573 token and, if this was an interaction with authz-info, return an 1574 error message with a response code equivalent to the CoAP code 1575 4.01 (Unauthorized). 1577 o If the claims cannot be obtained the RS MUST discard the token 1578 and, in case of an interaction via the authz-info endpoint, return 1579 an error message with a response code equivalent to the CoAP code 1580 4.00 (Bad Request). 1582 Next, the RS MUST verify claims, if present, contained in the access 1583 token. Errors are returned when claim checks fail, in the order of 1584 priority of this list: 1586 iss The issuer claim must identify an AS that has the authority to 1587 issue access tokens for the receiving RS. If that is not the case 1588 the RS MUST respond with a response code equivalent to the CoAP 1589 code 4.01 (Unauthorized). 1591 exp The expiration date must be in the future. If that is not the 1592 case the RS MUST respond with a response code equivalent to the 1593 CoAP code 4.01 (Unauthorized). Note that the RS has to terminate 1594 access rights to the protected resources at the time when the 1595 tokens expire. 1597 aud The audience claim must refer to an audience that the RS 1598 identifies with. If that is not the case the RS MUST respond with 1599 a response code equivalent to the CoAP code 4.03 (Forbidden). 1601 scope The RS must recognize value of the scope claim. If that is 1602 not the case the RS MUST respond with a response code equivalent 1603 to the CoAP code 4.00 (Bad Request). The RS MAY provide 1604 additional information in the error response, to clarify what went 1605 wrong. 1607 If the access token contains any other claims that the RS cannot 1608 process the RS MUST respond with a response code equivalent to the 1609 CoAP code 4.00 (Bad Request). The RS MAY provide additional detail 1610 in the error response to clarify which claim couldn't be processed. 1612 Note that the Subject (sub) claim cannot always be verified when the 1613 token is submitted to the RS since the client may not have 1614 authenticated yet. Also note that a counter for the expires_in (exi) 1615 claim MUST be initialized when the RS first verifies this token. 1617 When sending error responses, the RS MAY use the error codes from 1618 Section 3.1 of [RFC6750], to provide additional details to the 1619 client. 1621 5.8.1.2. Protecting the Authorization Information Endpoint 1623 As this framework can be used in RESTful environments, it is 1624 important to make sure that attackers cannot perform unauthorized 1625 requests on the auth-info endpoints, other than submitting access 1626 tokens. 1628 Specifically it SHOULD NOT be possible to perform GET, DELETE or PUT 1629 on the authz-info endpoint and on it's children (if any). 1631 The POST method SHOULD NOT be allowed on children of the authz-info 1632 endpoint. 1634 The RS SHOULD implement rate limiting measures to mitigate attacks 1635 aiming to overload the processing capacity of the RS by repeatedly 1636 submitting tokens. For CoAP-based communication the RS could use the 1637 mechanisms from [RFC8516] to indicate that it is overloaded. 1639 5.8.2. Client Requests to the RS 1641 If an RS receives a request from a client, and the target resource 1642 requires authorization, the RS MUST first verify that it has an 1643 access token that authorizes this request, and that the client has 1644 performed the proof-of-possession for that token. 1646 The response code MUST be 4.01 (Unauthorized) in case the client has 1647 not performed the proof-of-possession, or if RS has no valid access 1648 token for the client. If RS has an access token for the client but 1649 not for the resource that was requested, RS MUST reject the request 1650 with a 4.03 (Forbidden). If RS has an access token for the client 1651 but it does not cover the action that was requested on the resource, 1652 RS MUST reject the request with a 4.05 (Method Not Allowed). 1654 Note: The use of the response codes 4.03 and 4.05 is intended to 1655 prevent infinite loops where a dumb Client optimistically tries to 1656 access a requested resource with any access token received from AS. 1657 As malicious clients could pretend to be C to determine C's 1658 privileges, these detailed response codes must be used only when a 1659 certain level of security is already available which can be achieved 1660 only when the Client is authenticated. 1662 Note: The RS MAY use introspection for timely validation of an access 1663 token, at the time when a request is presented. 1665 Note: Matching the claims of the access token (e.g., scope) to a 1666 specific request is application specific. 1668 If the request matches a valid token and the client has performed the 1669 proof-of-possession for that token, the RS continues to process the 1670 request as specified by the underlying application. 1672 5.8.3. Token Expiration 1674 Depending on the capabilities of the RS, there are various ways in 1675 which it can verify the expiration of a received access token. Here 1676 follows a list of the possibilities including what functionality they 1677 require of the RS. 1679 o The token is a CWT and includes an "exp" claim and possibly the 1680 "nbf" claim. The RS verifies these by comparing them to values 1681 from its internal clock as defined in [RFC7519]. In this case the 1682 RS's internal clock must reflect the current date and time, or at 1683 least be synchronized with the AS's clock. How this clock 1684 synchronization would be performed is out of scope for this 1685 specification. 1687 o The RS verifies the validity of the token by performing an 1688 introspection request as specified in Section 5.7. This requires 1689 the RS to have a reliable network connection to the AS and to be 1690 able to handle two secure sessions in parallel (C to RS and AS to 1691 RS). 1693 o In order to support token expiration for devices that have no 1694 reliable way of synchronizing their internal clocks, this 1695 specification defines the following approach: The claim "exi" 1696 ("expires in") can be used, to provide the RS with the lifetime of 1697 the token in seconds from the time the RS first receives the 1698 token. This approach is of course vulnerable to malicious clients 1699 holding back tokens they do not want to expire. Such an attack 1700 can only be prevented if the RS is able to communicate with the AS 1701 in some regular intervals, so that the can AS provide the RS with 1702 a list of expired tokens. The drawback of this mitigation is that 1703 the RS might as well use the communication with the AS to 1704 synchronize its internal clock. 1706 If a token that authorizes a long running request such as a CoAP 1707 Observe [RFC7641] expires, the RS MUST send an error response with 1708 the response code equivalent to the CoAP code 4.01 (Unauthorized) to 1709 the client and then terminate processing the long running request. 1711 6. Security Considerations 1713 Security considerations applicable to authentication and 1714 authorization in RESTful environments provided in OAuth 2.0 [RFC6749] 1715 apply to this work. Furthermore [RFC6819] provides additional 1716 security considerations for OAuth which apply to IoT deployments as 1717 well. If the introspection endpoint is used, the security 1718 considerations from [RFC7662] also apply. 1720 A large range of threats can be mitigated by protecting the contents 1721 of the access token by using a digital signature or a keyed message 1722 digest (MAC) or an Authenticated Encryption with Associated Data 1723 (AEAD) algorithm. Consequently, the token integrity protection MUST 1724 be applied to prevent the token from being modified, particularly 1725 since it contains a reference to the symmetric key or the asymmetric 1726 key. If the access token contains the symmetric key, this symmetric 1727 key MUST be encrypted by the authorization server so that only the 1728 resource server can decrypt it. Note that using an AEAD algorithm is 1729 preferable over using a MAC unless the message needs to be publicly 1730 readable. 1732 If the token is intended for multiple recipients (i.e. an audience 1733 that is a group), integrity protection of the token with a symmetric 1734 key is not sufficient, since any of the recipients could modify the 1735 token undetected by the other recipients. Therefore a token with a 1736 multi-recipient audience MUST be protected with an asymmetric 1737 signature. 1739 It is important for the authorization server to include the identity 1740 of the intended recipient (the audience), typically a single resource 1741 server (or a list of resource servers), in the token. Using a single 1742 shared secret with multiple resource servers to simplify key 1743 management is NOT RECOMMENDED since the benefit from using the proof- 1744 of-possession concept is significantly reduced. 1746 The authorization server MUST offer confidentiality protection for 1747 any interactions with the client. This step is extremely important 1748 since the client may obtain the proof-of-possession key from the 1749 authorization server for use with a specific access token. Not using 1750 confidentiality protection exposes this secret (and the access token) 1751 to an eavesdropper thereby completely negating proof-of-possession 1752 security. Profiles MUST specify how confidentiality protection is 1753 provided, and additional protection can be applied by encrypting the 1754 token, for example encryption of CWTs is specified in Section 5.1 of 1755 [RFC8392]. 1757 Developers MUST ensure that the ephemeral credentials (i.e., the 1758 private key or the session key) are not leaked to third parties. An 1759 adversary in possession of the ephemeral credentials bound to the 1760 access token will be able to impersonate the client. Be aware that 1761 this is a real risk with many constrained environments, since 1762 adversaries can often easily get physical access to the devices. 1763 This risk can also be mitigated to some extent by making sure that 1764 keys are refreshed more frequently. 1766 If clients are capable of doing so, they should frequently request 1767 fresh access tokens, as this allows the AS to keep the lifetime of 1768 the tokens short. This allows the AS to use shorter proof-of- 1769 possession key sizes, which translate to a performance benefit for 1770 the client and for the resource server. Shorter keys also lead to 1771 shorter messages (particularly with asymmetric keying material). 1773 When authorization servers bind symmetric keys to access tokens, they 1774 SHOULD scope these access tokens to a specific permission. 1776 6.1. Unprotected AS Request Creation Hints 1778 Initially, no secure channel exists to protect the communication 1779 between C and RS. Thus, C cannot determine if the AS Request 1780 Creation Hints contained in an unprotected response from RS to an 1781 unauthorized request (see Section 5.1.2) are authentic. It is 1782 therefore advisable to provide C with a (possibly hard-coded) list of 1783 trustworthy authorization servers. AS Request Creation Hints 1784 referring to a URI not listed there would be ignored. 1786 6.2. Minimal security requirements for communication 1788 This section summarizes the minimal requirements for the 1789 communication security of the different protocol interactions. 1791 C-AS All communication between the client and the Authorization 1792 Server MUST be encrypted, integrity and replay protected. 1793 Furthermore responses from the AS to the client MUST be bound to 1794 the client's request to avoid attacks where the attacker swaps the 1795 intended response for an older one valid for a previous request. 1796 This requires that the client and the Authorization Server have 1797 previously exchanged either a shared secret, or their public keys 1798 in order to negotiate a secure communication. Furthermore the 1799 client MUST be able to determine whether an AS has the authority 1800 to issue access tokens for a certain RS. This can be done through 1801 pre-configured lists, or through an online lookup mechanism that 1802 in turn also must be secured. 1804 RS-AS The communication between the Resource Server and the 1805 Authorization Server via the introspection endpoint MUST be 1806 encrypted, integrity and replay protected. Furthermore responses 1807 from the AS to the RS MUST be bound to the RS's request. This 1808 requires that the client and the Authorization Server have 1809 previously exchanged either a shared secret, or their public keys 1810 in order to negotiate a secure communication. Furthermore the RS 1811 MUST be able to determine whether an AS has the authority to issue 1812 access tokens itself. This is usually configured out of band, but 1813 could also be performed through an online lookup mechanism 1814 provided that it is also secured in the same way. 1816 C-RS The initial communication between the client and the Resource 1817 Server can not be secured in general, since the RS is not in 1818 possession of on access token for that client, which would carry 1819 the necessary parameters. Certain security mechanisms (e.g. DTLS 1820 with server-side authentication via a certificate or a raw public 1821 key) can be possible and are RECOMMEND if supported by both 1822 parties. After the client has successfully transmitted the access 1823 token to the RS, a secure communication protocol MUST be 1824 established between client and RS for the actual resource request. 1825 This protocol MUST provide encryption, integrity and replay 1826 protection as well as a binding between requests and responses. 1827 This requires that the client learned either the RS's public key 1828 or received a symmetric proof-of-possession key bound to the 1829 access token from the AS. The RS must have learned either the 1830 client's public key or a shared symmetric key from the claims in 1831 the token or an introspection request. Since ACE does not provide 1832 profile negotiation between C and RS, the client MUST have learned 1833 what profile the RS supports (e.g. from the AS or pre-configured) 1834 and initiate the communication accordingly. 1836 6.3. Use of Nonces for Replay Protection 1838 The RS may add a nonce to the AS Request Creation Hints message sent 1839 as a response to an unauthorized request to ensure freshness of an 1840 Access Token subsequently presented to RS. While a time-stamp of 1841 some granularity would be sufficient to protect against replay 1842 attacks, using randomized nonce is preferred to prevent disclosure of 1843 information about RS's internal clock characteristics. 1845 6.4. Combining profiles 1847 There may be use cases were different profiles of this framework are 1848 combined. For example, an MQTT-TLS profile is used between the 1849 client and the RS in combination with a CoAP-DTLS profile for 1850 interactions between the client and the AS. Ideally, profiles should 1851 be designed in a way that the security of system should not depend on 1852 the specific security mechanisms used in individual protocol 1853 interactions. 1855 6.5. Unprotected Information 1857 Communication with the authz-info endpoint, as well as the various 1858 error responses defined in this framework all potentially include 1859 sending information over an unprotected channel. These messages may 1860 leak information to an adversary. For example errors responses for 1861 requests to the Authorization Information endpoint can reveal 1862 information about an otherwise opaque access token to an adversary 1863 who has intercepted this token. 1865 As far as error messages are concerned, this framework is written 1866 under the assumption that, in general, the benefits of detailed error 1867 messages outweigh the risk due to information leakage. For 1868 particular use cases, where this assessment does not apply, detailed 1869 error messages can be replaced by more generic ones. 1871 In some scenarios it may be possible to protect the communication 1872 with the authz-info endpoint (e.g. through DTLS with only server-side 1873 authentication). In cases where this is not possible this framework 1874 RECOMMENDS to use encrypted CWTs or opaque references and need to be 1875 subjected to introspection by the RS. 1877 If the initial unauthorized resource request message (see 1878 Section 5.1.1) is used, the client MUST make sure that it is not 1879 sending sensitive content in this request. While GET and DELETE 1880 requests only reveal the target URI of the resource, while POST and 1881 PUT requests would reveal the whole payload of the intended 1882 operation. 1884 6.6. Identifying audiences 1886 The audience claim as defined in [RFC7519] and the equivalent 1887 "audience" parameter from [I-D.ietf-oauth-token-exchange] are 1888 intentionally vague on how to match the audience value to a specific 1889 RS. This is intended to allow application specific semantics to be 1890 used. This section attempts to give some general guidance for the 1891 use of audiences in constrained environments. 1893 URLs are not a good way of identifying mobile devices that can switch 1894 networks and thus be associated with new URLs. If the audience 1895 represents a single RS, and asymmetric keys are used, the RS can be 1896 uniquely identified by a hash of its public key. If this approach is 1897 used this framework RECOMMENDS to apply the procedure from section 3 1898 of [RFC6920]. 1900 If the audience addresses a group of resource servers, the mapping of 1901 group identifier to individual RS has to be provisioned to each RS 1902 before the group-audience is usable. Managing dynamic groups could 1903 be an issue, if the RS is not always reachable when the group 1904 memberships change. Furthermore issuing access tokens bound to 1905 symmetric proof-of-possession keys that apply to a group-audience is 1906 problematic, as an RS that is in possession of the access token can 1907 impersonate the client towards the other RSs that are part of the 1908 group. It is therefore NOT RECOMMENDED to issue access tokens bound 1909 to a group audience and symmetric proof-of possession keys. 1911 Even the client must be able to determine the correct values to put 1912 into the "audience" parameter, in order to obtain a token for the 1913 intended RS. Errors in this process can lead to the client 1914 inadvertantly communicating with the wrong RS. The correct values 1915 for "audience" can either be provisioned to the client as part of its 1916 configuration, or provided by the RS as part of the "AS Request 1917 Creation Hints" Section 5.1.2 or dynamically looked up by the client 1918 in some directory. In the latter case the integrity and correctness 1919 of the directory data must be assured. 1921 6.7. Denial of service against or with Introspection 1923 The optional introspection mechanism provided by OAuth and supported 1924 in the ACE framework allows for two types of attacks that need to be 1925 considered by implementers. 1927 First an attacker could perform a denial of service attack against 1928 the introspection endpoint at the AS in order to prevent validation 1929 of access tokens. To mitigate this attack, an RS that is configured 1930 to use introspection MUST NOT allow access based on a token for which 1931 it couldn't reach the introspection endpoint. 1933 Second an attacker could use the fact that an RS performs 1934 introspection to perform a denial of service attack against that RS 1935 by repeatedly sending tokens to its authz-info endpoint that require 1936 an introspection call. RS can mitigate such attacks by implementing 1937 a rate limit on how many introspection requests they perform in a 1938 given time interval and rejecting incoming requests to authz-info for 1939 a certain amount of time, when that rate limit has been reached. 1941 7. Privacy Considerations 1943 Implementers and users should be aware of the privacy implications of 1944 the different possible deployments of this framework. 1946 The AS is in a very central position and can potentially learn 1947 sensitive information about the clients requesting access tokens. If 1948 the client credentials grant is used, the AS can track what kind of 1949 access the client intends to perform. With other grants this can be 1950 prevented by the Resource Owner. To do so, the resource owner needs 1951 to bind the grants it issues to anonymous, ephemeral credentials that 1952 do not allow the AS to link different grants and thus different 1953 access token requests by the same client. 1955 If access tokens are only integrity protected and not encrypted, they 1956 may reveal information to attackers listening on the wire, or able to 1957 acquire the access tokens in some other way. In the case of CWTs the 1958 token may, e.g., reveal the audience, the scope and the confirmation 1959 method used by the client. The latter may reveal the identity of the 1960 device or application running the client. This may be linkable to 1961 the identity of the person using the client (if there is a person and 1962 not a machine-to-machine interaction). 1964 Clients using asymmetric keys for proof-of-possession should be aware 1965 of the consequences of using the same key pair for proof-of- 1966 possession towards different RSs. A set of colluding RSs or an 1967 attacker able to obtain the access tokens will be able to link the 1968 requests, or even to determine the client's identity. 1970 An unprotected response to an unauthorized request (see 1971 Section 5.1.2) may disclose information about RS and/or its existing 1972 relationship with C. It is advisable to include as little 1973 information as possible in an unencrypted response. Means of 1974 encrypting communication between C and RS already exist, more 1975 detailed information may be included with an error response to 1976 provide C with sufficient information to react on that particular 1977 error. 1979 8. IANA Considerations 1981 8.1. ACE Authorization Server Request Creation Hints 1983 This specification establishes the IANA "ACE Authorization Server 1984 Request Creation Hints" registry. The registry has been created to 1985 use the "Expert Review Required" registration procedure [RFC8126]. 1986 It should be noted that, in addition to the expert review, some 1987 portions of the registry require a specification, potentially a 1988 Standards Track RFC, be supplied as well. 1990 The columns of the registry are: 1992 Name The name of the parameter 1994 CBOR Key CBOR map key for the parameter. Different ranges of values 1995 use different registration policies [RFC8126]. Integer values 1996 from -256 to 255 are designated as Standards Action. Integer 1997 values from -65536 to -257 and from 256 to 65535 are designated as 1998 Specification Required. Integer values greater than 65535 are 1999 designated as Expert Review. Integer values less than -65536 are 2000 marked as Private Use. 2002 Value Type The CBOR data types allowable for the values of this 2003 parameter. 2005 Reference This contains a pointer to the public specification of the 2006 grant type abbreviation, if one exists. 2008 This registry will be initially populated by the values in Figure 2. 2009 The Reference column for all of these entries will be this document. 2011 8.2. OAuth Extensions Error Registration 2013 This specification registers the following error values in the OAuth 2014 Extensions Error registry defined in [RFC6749]. 2016 o Error name: "unsupported_pop_key" 2017 o Error usage location: AS token endpoint error response 2018 o Related protocol extension: The ACE framework [this document] 2019 o Change Controller: IESG 2020 o Specification document(s): Section 5.6.3 of [this document] 2022 o Error name: "incompatible_profiles" 2023 o Error usage location: AS token endpoint error response 2024 o Related protocol extension: The ACE framework [this document] 2025 o Change Controller: IESG 2026 o Specification document(s): Section 5.6.3 of [this document] 2028 8.3. OAuth Error Code CBOR Mappings Registry 2030 This specification establishes the IANA "OAuth Error Code CBOR 2031 Mappings" registry. The registry has been created to use the "Expert 2032 Review Required" registration procedure [RFC8126]. It should be 2033 noted that, in addition to the expert review, some portions of the 2034 registry require a specification, potentially a Standards Track RFC, 2035 be supplied as well. 2037 The columns of the registry are: 2039 Name The OAuth Error Code name, refers to the name in Section 5.2. 2040 of [RFC6749], e.g., "invalid_request". 2041 CBOR Value CBOR abbreviation for this error code. Different ranges 2042 of values use different registration policies [RFC8126]. Integer 2043 values from -256 to 255 are designated as Standards Action. 2044 Integer values from -65536 to -257 and from 256 to 65535 are 2045 designated as Specification Required. Integer values greater than 2046 65535 are designated as Expert Review. Integer values less than 2047 -65536 are marked as Private Use. 2048 Reference This contains a pointer to the public specification of the 2049 grant type abbreviation, if one exists. 2051 This registry will be initially populated by the values in Figure 10. 2052 The Reference column for all of these entries will be this document. 2054 8.4. OAuth Grant Type CBOR Mappings 2056 This specification establishes the IANA "OAuth Grant Type CBOR 2057 Mappings" registry. The registry has been created to use the "Expert 2058 Review Required" registration procedure [RFC8126]. It should be 2059 noted that, in addition to the expert review, some portions of the 2060 registry require a specification, potentially a Standards Track RFC, 2061 be supplied as well. 2063 The columns of this registry are: 2065 Name The name of the grant type as specified in Section 1.3 of 2066 [RFC6749]. 2067 CBOR Value CBOR abbreviation for this grant type. Different ranges 2068 of values use different registration policies [RFC8126]. Integer 2069 values from -256 to 255 are designated as Standards Action. 2070 Integer values from -65536 to -257 and from 256 to 65535 are 2071 designated as Specification Required. Integer values greater than 2072 65535 are designated as Expert Review. Integer values less than 2073 -65536 are marked as Private Use. 2074 Reference This contains a pointer to the public specification of the 2075 grant type abbreviation, if one exists. 2076 Original Specification This contains a pointer to the public 2077 specification of the grant type, if one exists. 2079 This registry will be initially populated by the values in Figure 11. 2080 The Reference column for all of these entries will be this document. 2082 8.5. OAuth Access Token Types 2084 This section registers the following new token type in the "OAuth 2085 Access Token Types" registry [IANA.OAuthAccessTokenTypes]. 2087 o Name: "PoP" 2088 o Change Controller: IETF 2089 o Reference: [this document] 2091 8.6. OAuth Access Token Type CBOR Mappings 2093 This specification established the IANA "OAuth Access Token Type CBOR 2094 Mappings" registry. The registry has been created to use the "Expert 2095 Review Required" registration procedure [RFC8126]. It should be 2096 noted that, in addition to the expert review, some portions of the 2097 registry require a specification, potentially a Standards Track RFC, 2098 be supplied as well. 2100 The columns of this registry are: 2102 Name The name of token type as registered in the OAuth Access Token 2103 Types registry, e.g., "Bearer". 2104 CBOR Value CBOR abbreviation for this token type. Different ranges 2105 of values use different registration policies [RFC8126]. Integer 2106 values from -256 to 255 are designated as Standards Action. 2107 Integer values from -65536 to -257 and from 256 to 65535 are 2108 designated as Specification Required. Integer values greater than 2109 65535 are designated as Expert Review. Integer values less than 2110 -65536 are marked as Private Use. 2111 Reference This contains a pointer to the public specification of the 2112 OAuth token type abbreviation, if one exists. 2113 Original Specification This contains a pointer to the public 2114 specification of the grant type, if one exists. 2116 8.6.1. Initial Registry Contents 2118 o Name: "Bearer" 2119 o Value: 1 2120 o Reference: [this document] 2121 o Original Specification: [RFC6749] 2123 o Name: "pop" 2124 o Value: 2 2125 o Reference: [this document] 2126 o Original Specification: [this document] 2128 8.7. ACE Profile Registry 2130 This specification establishes the IANA "ACE Profile" registry. The 2131 registry has been created to use the "Expert Review Required" 2132 registration procedure [RFC8126]. It should be noted that, in 2133 addition to the expert review, some portions of the registry require 2134 a specification, potentially a Standards Track RFC, be supplied as 2135 well. 2137 The columns of this registry are: 2139 Name The name of the profile, to be used as value of the profile 2140 attribute. 2141 Description Text giving an overview of the profile and the context 2142 it is developed for. 2143 CBOR Value CBOR abbreviation for this profile name. Different 2144 ranges of values use different registration policies [RFC8126]. 2145 Integer values from -256 to 255 are designated as Standards 2146 Action. Integer values from -65536 to -257 and from 256 to 65535 2147 are designated as Specification Required. Integer values greater 2148 than 65535 are designated as Expert Review. Integer values less 2149 than -65536 are marked as Private Use. 2150 Reference This contains a pointer to the public specification of the 2151 profile abbreviation, if one exists. 2153 This registry will be initially empty and will be populated by the 2154 registrations from the ACE framework profiles. 2156 8.8. OAuth Parameter Registration 2158 This specification registers the following parameter in the "OAuth 2159 Parameters" registry [IANA.OAuthParameters]: 2161 o Name: "profile" 2162 o Parameter Usage Location: token response 2163 o Change Controller: IESG 2164 o Reference: Section 5.6.4.3 of [this document] 2166 8.9. OAuth Parameters CBOR Mappings Registry 2168 This specification establishes the IANA "OAuth Parameters CBOR 2169 Mappings" registry. The registry has been created to use the "Expert 2170 Review Required" registration procedure [RFC8126]. It should be 2171 noted that, in addition to the expert review, some portions of the 2172 registry require a specification, potentially a Standards Track RFC, 2173 be supplied as well. 2175 The columns of this registry are: 2177 Name The OAuth Parameter name, refers to the name in the OAuth 2178 parameter registry, e.g., "client_id". 2179 CBOR Key CBOR map key for this parameter. Different ranges of 2180 values use different registration policies [RFC8126]. Integer 2181 values from -256 to 255 are designated as Standards Action. 2182 Integer values from -65536 to -257 and from 256 to 65535 are 2183 designated as Specification Required. Integer values greater than 2184 65535 are designated as Expert Review. Integer values less than 2185 -65536 are marked as Private Use. 2187 Value Type The allowable CBOR data types for values of this 2188 parameter. 2189 Reference This contains a pointer to the public specification of the 2190 parameter abbreviation, if one exists. 2192 This registry will be initially populated by the values in Figure 12. 2193 The Reference column for all of these entries will be this document. 2195 Note that the mappings of parameters corresponding to claim names 2196 intentionally coincide with the CWT claim name mappings from 2197 [RFC8392]. 2199 8.10. OAuth Introspection Response Parameter Registration 2201 This specification registers the following parameter in the OAuth 2202 Token Introspection Response registry 2203 [IANA.TokenIntrospectionResponse]. 2205 o Name: "profile" 2206 o Description: The communication and communication security profile 2207 used between client and RS, as defined in ACE profiles. 2208 o Change Controller: IESG 2209 o Reference: Section 5.7.2 of [this document] 2211 8.11. OAuth Token Introspection Response CBOR Mappings Registry 2213 This specification establishes the IANA "OAuth Token Introspection 2214 Response CBOR Mappings" registry. The registry has been created to 2215 use the "Expert Review Required" registration procedure [RFC8126]. 2216 It should be noted that, in addition to the expert review, some 2217 portions of the registry require a specification, potentially a 2218 Standards Track RFC, be supplied as well. 2220 The columns of this registry are: 2222 Name The OAuth Parameter name, refers to the name in the OAuth 2223 parameter registry, e.g., "client_id". 2224 CBOR Key CBOR map key for this parameter. Different ranges of 2225 values use different registration policies [RFC8126]. Integer 2226 values from -256 to 255 are designated as Standards Action. 2227 Integer values from -65536 to -257 and from 256 to 65535 are 2228 designated as Specification Required. Integer values greater than 2229 65535 are designated as Expert Review. Integer values less than 2230 -65536 are marked as Private Use. 2231 Value Type The allowable CBOR data types for values of this 2232 parameter. 2233 Reference This contains a pointer to the public specification of the 2234 grant type abbreviation, if one exists. 2236 This registry will be initially populated by the values in Figure 16. 2237 The Reference column for all of these entries will be this document. 2239 Note that the mappings of parameters corresponding to claim names 2240 intentionally coincide with the CWT claim name mappings from 2241 [RFC8392]. 2243 8.12. JSON Web Token Claims 2245 This specification registers the following new claims in the JSON Web 2246 Token (JWT) registry of JSON Web Token Claims 2247 [IANA.JsonWebTokenClaims]: 2249 o Claim Name: "scope" 2250 o Claim Description: The scope of an access token as defined in 2251 [RFC6749]. 2252 o Change Controller: IESG 2253 o Reference: Section 5.8 of [this document] 2255 o Claim Name: "profile" 2256 o Claim Description: The profile a token is supposed to be used 2257 with. 2258 o Change Controller: IESG 2259 o Reference: Section 5.8 of [this document] 2261 o Claim Name: "exi" 2262 o Claim Description: "Expires in". Lifetime of the token in seconds 2263 from the time the RS first sees it. Used to implement a weaker 2264 from of token expiration for devices that cannot synchronize their 2265 internal clocks. 2266 o Change Controller: IESG 2267 o Reference: Section 5.8.3 of [this document] 2269 8.13. CBOR Web Token Claims 2271 This specification registers the following new claims in the "CBOR 2272 Web Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. 2274 o Claim Name: "scope" 2275 o Claim Description: The scope of an access token as defined in 2276 [RFC6749]. 2277 o JWT Claim Name: scope 2278 o Claim Key: TBD (suggested: 9) 2279 o Claim Value Type(s): byte string or text string 2280 o Change Controller: IESG 2281 o Specification Document(s): Section 5.8 of [this document] 2283 o Claim Name: "profile" 2284 o Claim Description: The profile a token is supposed to be used 2285 with. 2286 o JWT Claim Name: profile 2287 o Claim Key: TBD (suggested: 39) 2288 o Claim Value Type(s): integer 2289 o Change Controller: IESG 2290 o Specification Document(s): Section 5.8 of [this document] 2292 o Claim Name: "exi" 2293 o Claim Description: The expiration time of a token measured from 2294 when it was received at the RS in seconds. 2295 o JWT Claim Name: exi 2296 o Claim Key: TBD (suggested: 41) 2297 o Claim Value Type(s): integer 2298 o Change Controller: IESG 2299 o Specification Document(s): Section 5.8 of [this document] 2301 8.14. Media Type Registrations 2303 This specification registers the 'application/ace+cbor' media type 2304 for messages of the protocols defined in this document carrying 2305 parameters encoded in CBOR. This registration follows the procedures 2306 specified in [RFC6838]. 2308 Type name: application 2310 Subtype name: ace+cbor 2312 Required parameters: none 2314 Optional parameters: none 2316 Encoding considerations: Must be encoded as CBOR map containing the 2317 protocol parameters defined in [this document]. 2319 Security considerations: See Section 6 of this document. 2321 Interoperability considerations: n/a 2323 Published specification: [this document] 2325 Applications that use this media type: The type is used by 2326 authorization servers, clients and resource servers that support the 2327 ACE framework as specified in [this document]. 2329 Additional information: 2331 Magic number(s): n/a 2332 File extension(s): .ace 2334 Macintosh file type code(s): n/a 2336 Person & email address to contact for further information: Ludwig 2337 Seitz 2339 Intended usage: COMMON 2341 Restrictions on usage: None 2343 Author: Ludwig Seitz 2345 Change controller: IESG 2347 8.15. CoAP Content-Format Registry 2349 This specification registers the following entry to the "CoAP 2350 Content-Formats" registry: 2352 Media Type: application/ace+cbor 2354 Encoding 2356 ID: 19 2358 Reference: [this document] 2360 8.16. Expert Review Instructions 2362 All of the IANA registries established in this document are defined 2363 as expert review. This section gives some general guidelines for 2364 what the experts should be looking for, but they are being designated 2365 as experts for a reason, so they should be given substantial 2366 latitude. 2368 Expert reviewers should take into consideration the following points: 2370 o Point squatting should be discouraged. Reviewers are encouraged 2371 to get sufficient information for registration requests to ensure 2372 that the usage is not going to duplicate one that is already 2373 registered, and that the point is likely to be used in 2374 deployments. The zones tagged as private use are intended for 2375 testing purposes and closed environments; code points in other 2376 ranges should not be assigned for testing. 2377 o Specifications are required for the standards track range of point 2378 assignment. Specifications should exist for specification 2379 required ranges, but early assignment before a specification is 2380 available is considered to be permissible. Specifications are 2381 needed for the first-come, first-serve range if they are expected 2382 to be used outside of closed environments in an interoperable way. 2383 When specifications are not provided, the description provided 2384 needs to have sufficient information to identify what the point is 2385 being used for. 2386 o Experts should take into account the expected usage of fields when 2387 approving point assignment. The fact that there is a range for 2388 standards track documents does not mean that a standards track 2389 document cannot have points assigned outside of that range. The 2390 length of the encoded value should be weighed against how many 2391 code points of that length are left, the size of device it will be 2392 used on, and the number of code points left that encode to that 2393 size. 2394 o Since a high degree of overlap is expected between these 2395 registries and the contents of the OAuth parameters 2396 [IANA.OAuthParameters] registries, experts should require new 2397 registrations to maintain a reasonable level of alignment with 2398 parameters from OAuth that have comparable functionality. 2400 9. Acknowledgments 2402 This document is a product of the ACE working group of the IETF. 2404 Thanks to Eve Maler for her contributions to the use of OAuth 2.0 and 2405 UMA in IoT scenarios, Robert Taylor for his discussion input, and 2406 Malisa Vucinic for his input on the predecessors of this proposal. 2408 Thanks to the authors of draft-ietf-oauth-pop-key-distribution, from 2409 where large parts of the security considerations where copied. 2411 Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten Bormann for 2412 contributing their work on AS discovery from draft-gerdes-ace-dcaf- 2413 authorize (see Section 5.1). 2415 Thanks to Jim Schaad and Mike Jones for their comprehensive reviews. 2417 Thanks to Benjamin Kaduk for his input on various questions related 2418 to this work. 2420 Ludwig Seitz and Goeran Selander worked on this document as part of 2421 the CelticPlus project CyberWI, with funding from Vinnova. 2423 10. References 2424 10.1. Normative References 2426 [I-D.ietf-ace-cwt-proof-of-possession] 2427 Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 2428 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 2429 Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- 2430 possession-05 (work in progress), November 2018. 2432 [I-D.ietf-ace-oauth-params] 2433 Seitz, L., "Additional OAuth Parameters for Authorization 2434 in Constrained Environments (ACE)", draft-ietf-ace-oauth- 2435 params-02 (work in progress), January 2019. 2437 [I-D.ietf-oauth-token-exchange] 2438 Jones, M., Nadalin, A., Campbell, B., Bradley, J., and C. 2439 Mortimore, "OAuth 2.0 Token Exchange", draft-ietf-oauth- 2440 token-exchange-16 (work in progress), October 2018. 2442 [IANA.CborWebTokenClaims] 2443 IANA, "CBOR Web Token (CWT) Claims", 2444 . 2447 [IANA.JsonWebTokenClaims] 2448 IANA, "JSON Web Token Claims", 2449 . 2451 [IANA.OAuthAccessTokenTypes] 2452 IANA, "OAuth Access Token Types", 2453 . 2456 [IANA.OAuthParameters] 2457 IANA, "OAuth Parameters", 2458 . 2461 [IANA.TokenIntrospectionResponse] 2462 IANA, "OAuth Token Introspection Response", 2463 . 2466 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2467 Requirement Levels", BCP 14, RFC 2119, 2468 DOI 10.17487/RFC2119, March 1997, 2469 . 2471 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2472 Resource Identifier (URI): Generic Syntax", STD 66, 2473 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2474 . 2476 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2477 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2478 January 2012, . 2480 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2481 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2482 . 2484 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2485 Framework: Bearer Token Usage", RFC 6750, 2486 DOI 10.17487/RFC6750, October 2012, 2487 . 2489 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 2490 Specifications and Registration Procedures", BCP 13, 2491 RFC 6838, DOI 10.17487/RFC6838, January 2013, 2492 . 2494 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 2495 Keranen, A., and P. Hallam-Baker, "Naming Things with 2496 Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013, 2497 . 2499 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2500 Application Protocol (CoAP)", RFC 7252, 2501 DOI 10.17487/RFC7252, June 2014, 2502 . 2504 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 2505 RFC 7662, DOI 10.17487/RFC7662, October 2015, 2506 . 2508 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2509 Writing an IANA Considerations Section in RFCs", BCP 26, 2510 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2511 . 2513 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2514 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2515 . 2517 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2518 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2519 May 2017, . 2521 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 2522 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 2523 May 2018, . 2525 10.2. Informative References 2527 [I-D.erdtman-ace-rpcc] 2528 Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared- 2529 Key as OAuth client credentials", draft-erdtman-ace- 2530 rpcc-02 (work in progress), October 2017. 2532 [I-D.ietf-core-object-security] 2533 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2534 "Object Security for Constrained RESTful Environments 2535 (OSCORE)", draft-ietf-core-object-security-15 (work in 2536 progress), August 2018. 2538 [I-D.ietf-oauth-device-flow] 2539 Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2540 "OAuth 2.0 Device Flow for Browserless and Input 2541 Constrained Devices", draft-ietf-oauth-device-flow-14 2542 (work in progress), January 2019. 2544 [I-D.ietf-tls-dtls13] 2545 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 2546 Datagram Transport Layer Security (DTLS) Protocol Version 2547 1.3", draft-ietf-tls-dtls13-30 (work in progress), 2548 November 2018. 2550 [Margi10impact] 2551 Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr, 2552 M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold, 2553 "Impact of Operating Systems on Wireless Sensor Networks 2554 (Security) Applications and Testbeds", Proceedings of 2555 the 19th International Conference on Computer 2556 Communications and Networks (ICCCN), August 2010. 2558 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2559 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2560 . 2562 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2563 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2564 . 2566 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 2567 Threat Model and Security Considerations", RFC 6819, 2568 DOI 10.17487/RFC6819, January 2013, 2569 . 2571 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2572 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2573 October 2013, . 2575 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2576 Constrained-Node Networks", RFC 7228, 2577 DOI 10.17487/RFC7228, May 2014, 2578 . 2580 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2581 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2582 DOI 10.17487/RFC7231, June 2014, 2583 . 2585 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2586 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2587 . 2589 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 2590 "Assertion Framework for OAuth 2.0 Client Authentication 2591 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 2592 May 2015, . 2594 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 2595 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 2596 RFC 7591, DOI 10.17487/RFC7591, July 2015, 2597 . 2599 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2600 Application Protocol (CoAP)", RFC 7641, 2601 DOI 10.17487/RFC7641, September 2015, 2602 . 2604 [RFC7744] Seitz, L., Ed., Gerdes, S., Ed., Selander, G., Mani, M., 2605 and S. Kumar, "Use Cases for Authentication and 2606 Authorization in Constrained Environments", RFC 7744, 2607 DOI 10.17487/RFC7744, January 2016, 2608 . 2610 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2611 the Constrained Application Protocol (CoAP)", RFC 7959, 2612 DOI 10.17487/RFC7959, August 2016, 2613 . 2615 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2616 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 2617 . 2619 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2620 Interchange Format", STD 90, RFC 8259, 2621 DOI 10.17487/RFC8259, December 2017, 2622 . 2624 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 2625 Authorization Server Metadata", RFC 8414, 2626 DOI 10.17487/RFC8414, June 2018, 2627 . 2629 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2630 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2631 . 2633 [RFC8516] Keraenen, A., ""Too Many Requests" Response Code for the 2634 Constrained Application Protocol", RFC 8516, 2635 DOI 10.17487/RFC8516, January 2019, 2636 . 2638 Appendix A. Design Justification 2640 This section provides further insight into the design decisions of 2641 the solution documented in this document. Section 3 lists several 2642 building blocks and briefly summarizes their importance. The 2643 justification for offering some of those building blocks, as opposed 2644 to using OAuth 2.0 as is, is given below. 2646 Common IoT constraints are: 2648 Low Power Radio: 2650 Many IoT devices are equipped with a small battery which needs to 2651 last for a long time. For many constrained wireless devices, the 2652 highest energy cost is associated to transmitting or receiving 2653 messages (roughly by a factor of 10 compared to AES) 2654 [Margi10impact]. It is therefore important to keep the total 2655 communication overhead low, including minimizing the number and 2656 size of messages sent and received, which has an impact of choice 2657 on the message format and protocol. By using CoAP over UDP and 2658 CBOR encoded messages, some of these aspects are addressed. 2659 Security protocols contribute to the communication overhead and 2660 can, in some cases, be optimized. For example, authentication and 2661 key establishment may, in certain cases where security 2662 requirements allow, be replaced by provisioning of security 2663 context by a trusted third party, using transport or application 2664 layer security. 2666 Low CPU Speed: 2668 Some IoT devices are equipped with processors that are 2669 significantly slower than those found in most current devices on 2670 the Internet. This typically has implications on what timely 2671 cryptographic operations a device is capable of performing, which 2672 in turn impacts, e.g., protocol latency. Symmetric key 2673 cryptography may be used instead of the computationally more 2674 expensive public key cryptography where the security requirements 2675 so allows, but this may also require support for trusted third 2676 party assisted secret key establishment using transport or 2677 application layer security. 2678 Small Amount of Memory: 2680 Microcontrollers embedded in IoT devices are often equipped with 2681 small amount of RAM and flash memory, which places limitations 2682 what kind of processing can be performed and how much code can be 2683 put on those devices. To reduce code size fewer and smaller 2684 protocol implementations can be put on the firmware of such a 2685 device. In this case, CoAP may be used instead of HTTP, symmetric 2686 key cryptography instead of public key cryptography, and CBOR 2687 instead of JSON. Authentication and key establishment protocol, 2688 e.g., the DTLS handshake, in comparison with assisted key 2689 establishment also has an impact on memory and code. 2691 User Interface Limitations: 2693 Protecting access to resources is both an important security as 2694 well as privacy feature. End users and enterprise customers may 2695 not want to give access to the data collected by their IoT device 2696 or to functions it may offer to third parties. Since the 2697 classical approach of requesting permissions from end users via a 2698 rich user interface does not work in many IoT deployment 2699 scenarios, these functions need to be delegated to user-controlled 2700 devices that are better suitable for such tasks, such as smart 2701 phones and tablets. 2703 Communication Constraints: 2705 In certain constrained settings an IoT device may not be able to 2706 communicate with a given device at all times. Devices may be 2707 sleeping, or just disconnected from the Internet because of 2708 general lack of connectivity in the area, for cost reasons, or for 2709 security reasons, e.g., to avoid an entry point for Denial-of- 2710 Service attacks. 2712 The communication interactions this framework builds upon (as 2713 shown graphically in Figure 1) may be accomplished using a variety 2714 of different protocols, and not all parts of the message flow are 2715 used in all applications due to the communication constraints. 2716 Deployments making use of CoAP are expected, but not limited to, 2717 other protocols such as HTTP, HTTP/2 or other specific protocols, 2718 such as Bluetooth Smart communication, that do not necessarily use 2719 IP could also be used. The latter raises the need for application 2720 layer security over the various interfaces. 2722 In the light of these constraints we have made the following design 2723 decisions: 2725 CBOR, COSE, CWT: 2727 This framework RECOMMENDS the use of CBOR [RFC7049] as data 2728 format. Where CBOR data needs to be protected, the use of COSE 2729 [RFC8152] is RECOMMENDED. Furthermore where self-contained tokens 2730 are needed, this framework RECOMMENDS the use of CWT [RFC8392]. 2731 These measures aim at reducing the size of messages sent over the 2732 wire, the RAM size of data objects that need to be kept in memory 2733 and the size of libraries that devices need to support. 2735 CoAP: 2737 This framework RECOMMENDS the use of CoAP [RFC7252] instead of 2738 HTTP. This does not preclude the use of other protocols 2739 specifically aimed at constrained devices, like, e.g., Bluetooth 2740 Low Energy (see Section 3.2). This aims again at reducing the 2741 size of messages sent over the wire, the RAM size of data objects 2742 that need to be kept in memory and the size of libraries that 2743 devices need to support. 2745 Access Information: 2747 This framework defines the name "Access Information" for data 2748 concerning the RS that the AS returns to the client in an access 2749 token response (see Section 5.6.2). This aims at enabling 2750 scenarios, where a powerful client, supporting multiple profiles, 2751 needs to interact with a RS for which it does not know the 2752 supported profiles and the raw public key. 2754 Proof-of-Possession: 2756 This framework makes use of proof-of-possession tokens, using the 2757 "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession]. A 2758 semantically and syntactically identical request and response 2759 parameter is defined for the token endpoint, to allow requesting 2760 and stating confirmation keys. This aims at making token theft 2761 harder. Token theft is specifically relevant in constrained use 2762 cases, as communication often passes through middle-boxes, which 2763 could be able to steal bearer tokens and use them to gain 2764 unauthorized access. 2766 Auth-Info endpoint: 2768 This framework introduces a new way of providing access tokens to 2769 a RS by exposing a authz-info endpoint, to which access tokens can 2770 be POSTed. This aims at reducing the size of the request message 2771 and the code complexity at the RS. The size of the request 2772 message is problematic, since many constrained protocols have 2773 severe message size limitations at the physical layer (e.g., in 2774 the order of 100 bytes). This means that larger packets get 2775 fragmented, which in turn combines badly with the high rate of 2776 packet loss, and the need to retransmit the whole message if one 2777 packet gets lost. Thus separating sending of the request and 2778 sending of the access tokens helps to reduce fragmentation. 2780 Client Credentials Grant: 2782 This framework RECOMMENDS the use of the client credentials grant 2783 for machine-to-machine communication use cases, where manual 2784 intervention of the resource owner to produce a grant token is not 2785 feasible. The intention is that the resource owner would instead 2786 pre-arrange authorization with the AS, based on the client's own 2787 credentials. The client can then (without manual intervention) 2788 obtain access tokens from the AS. 2790 Introspection: 2792 This framework RECOMMENDS the use of access token introspection in 2793 cases where the client is constrained in a way that it can not 2794 easily obtain new access tokens (i.e. it has connectivity issues 2795 that prevent it from communicating with the AS). In that case 2796 this framework RECOMMENDS the use of a long-term token, that could 2797 be a simple reference. The RS is assumed to be able to 2798 communicate with the AS, and can therefore perform introspection, 2799 in order to learn the claims associated with the token reference. 2800 The advantage of such an approach is that the resource owner can 2801 change the claims associated to the token reference without having 2802 to be in contact with the client, thus granting or revoking access 2803 rights. 2805 Appendix B. Roles and Responsibilities 2807 Resource Owner 2809 * Make sure that the RS is registered at the AS. This includes 2810 making known to the AS which profiles, token_types, scopes, and 2811 key types (symmetric/asymmetric) the RS supports. Also making 2812 it known to the AS which audience(s) the RS identifies itself 2813 with. 2814 * Make sure that clients can discover the AS that is in charge of 2815 the RS. 2816 * If the client-credentials grant is used, make sure that the AS 2817 has the necessary, up-to-date, access control policies for the 2818 RS. 2820 Requesting Party 2822 * Make sure that the client is provisioned the necessary 2823 credentials to authenticate to the AS. 2824 * Make sure that the client is configured to follow the security 2825 requirements of the Requesting Party when issuing requests 2826 (e.g., minimum communication security requirements, trust 2827 anchors). 2828 * Register the client at the AS. This includes making known to 2829 the AS which profiles, token_types, and key types (symmetric/ 2830 asymmetric) the client. 2832 Authorization Server 2834 * Register the RS and manage corresponding security contexts. 2835 * Register clients and authentication credentials. 2836 * Allow Resource Owners to configure and update access control 2837 policies related to their registered RSs. 2838 * Expose the token endpoint to allow clients to request tokens. 2839 * Authenticate clients that wish to request a token. 2840 * Process a token request using the authorization policies 2841 configured for the RS. 2842 * Optionally: Expose the introspection endpoint that allows RS's 2843 to submit token introspection requests. 2844 * If providing an introspection endpoint: Authenticate RSs that 2845 wish to get an introspection response. 2846 * If providing an introspection endpoint: Process token 2847 introspection requests. 2848 * Optionally: Handle token revocation. 2849 * Optionally: Provide discovery metadata. See [RFC8414] 2850 * Optionally: Handle refresh tokens. 2852 Client 2853 * Discover the AS in charge of the RS that is to be targeted with 2854 a request. 2855 * Submit the token request (see step (A) of Figure 1). 2857 + Authenticate to the AS. 2858 + Optionally (if not pre-configured): Specify which RS, which 2859 resource(s), and which action(s) the request(s) will target. 2860 + If raw public keys (rpk) or certificates are used, make sure 2861 the AS has the right rpk or certificate for this client. 2862 * Process the access token and Access Information (see step (B) 2863 of Figure 1). 2865 + Check that the Access Information provides the necessary 2866 security parameters (e.g., PoP key, information on 2867 communication security protocols supported by the RS). 2868 + Safely store the proof-of-possession key. 2869 + If provided by the AS: Safely store the refresh token. 2870 * Send the token and request to the RS (see step (C) of 2871 Figure 1). 2873 + Authenticate towards the RS (this could coincide with the 2874 proof of possession process). 2875 + Transmit the token as specified by the AS (default is to the 2876 authz-info endpoint, alternative options are specified by 2877 profiles). 2878 + Perform the proof-of-possession procedure as specified by 2879 the profile in use (this may already have been taken care of 2880 through the authentication procedure). 2881 * Process the RS response (see step (F) of Figure 1) of the RS. 2883 Resource Server 2885 * Expose a way to submit access tokens. By default this is the 2886 authz-info endpoint. 2887 * Process an access token. 2889 + Verify the token is from a recognized AS. 2890 + Verify that the token applies to this RS. 2891 + Check that the token has not expired (if the token provides 2892 expiration information). 2893 + Check the token's integrity. 2894 + Store the token so that it can be retrieved in the context 2895 of a matching request. 2896 * Process a request. 2898 + Set up communication security with the client. 2899 + Authenticate the client. 2900 + Match the client against existing tokens. 2902 + Check that tokens belonging to the client actually authorize 2903 the requested action. 2904 + Optionally: Check that the matching tokens are still valid, 2905 using introspection (if this is possible.) 2906 * Send a response following the agreed upon communication 2907 security. 2908 * Safely store credentials such as raw public keys for 2909 authentication or proof-of-possession keys linked to access 2910 tokens. 2912 Appendix C. Requirements on Profiles 2914 This section lists the requirements on profiles of this framework, 2915 for the convenience of profile designers. 2917 o Specify the communication protocol the client and RS the must use 2918 (e.g., CoAP). Section 5 and Section 5.6.4.3 2919 o Specify the security protocol the client and RS must use to 2920 protect their communication (e.g., OSCORE or DTLS over CoAP). 2921 This must provide encryption, integrity and replay protection. 2922 Section 5.6.4.3 2923 o Specify how the client and the RS mutually authenticate. 2924 Section 4 2925 o Specify the proof-of-possession protocol(s) and how to select one, 2926 if several are available. Also specify which key types (e.g., 2927 symmetric/asymmetric) are supported by a specific proof-of- 2928 possession protocol. Section 5.6.4.2 2929 o Specify a unique profile identifier. Section 5.6.4.3 2930 o If introspection is supported: Specify the communication and 2931 security protocol for introspection. Section 5.7 2932 o Specify the communication and security protocol for interactions 2933 between client and AS. This must provide encryption, integrity 2934 protection, replay protection and a binding between requests and 2935 responses. Section 5 and Section 5.6 2936 o Specify how/if the authz-info endpoint is protected, including how 2937 error responses are protected. Section 5.8.1 2938 o Optionally define other methods of token transport than the authz- 2939 info endpoint. Section 5.8.1 2941 Appendix D. Assumptions on AS knowledge about C and RS 2943 This section lists the assumptions on what an AS should know about a 2944 client and a RS in order to be able to respond to requests to the 2945 token and introspection endpoints. How this information is 2946 established is out of scope for this document. 2948 o The identifier of the client or RS. 2949 o The profiles that the client or RS supports. 2951 o The scopes that the RS supports. 2952 o The audiences that the RS identifies with. 2953 o The key types (e.g., pre-shared symmetric key, raw public key, key 2954 length, other key parameters) that the client or RS supports. 2955 o The types of access tokens the RS supports (e.g., CWT). 2956 o If the RS supports CWTs, the COSE parameters for the crypto 2957 wrapper (e.g., algorithm, key-wrap algorithm, key-length). 2958 o The expiration time for access tokens issued to this RS (unless 2959 the RS accepts a default time chosen by the AS). 2960 o The symmetric key shared between client or RS and AS (if any). 2961 o The raw public key of the client or RS (if any). 2962 o Whether the RS has synchronized time (and thus is able to use the 2963 'exp' claim) or not. 2965 Appendix E. Deployment Examples 2967 There is a large variety of IoT deployments, as is indicated in 2968 Appendix A, and this section highlights a few common variants. This 2969 section is not normative but illustrates how the framework can be 2970 applied. 2972 For each of the deployment variants, there are a number of possible 2973 security setups between clients, resource servers and authorization 2974 servers. The main focus in the following subsections is on how 2975 authorization of a client request for a resource hosted by a RS is 2976 performed. This requires the security of the requests and responses 2977 between the clients and the RS to consider. 2979 Note: CBOR diagnostic notation is used for examples of requests and 2980 responses. 2982 E.1. Local Token Validation 2984 In this scenario, the case where the resource server is offline is 2985 considered, i.e., it is not connected to the AS at the time of the 2986 access request. This access procedure involves steps A, B, C, and F 2987 of Figure 1. 2989 Since the resource server must be able to verify the access token 2990 locally, self-contained access tokens must be used. 2992 This example shows the interactions between a client, the 2993 authorization server and a temperature sensor acting as a resource 2994 server. Message exchanges A and B are shown in Figure 17. 2996 A: The client first generates a public-private key pair used for 2997 communication security with the RS. 2999 The client sends the POST request to the token endpoint at the AS. 3000 The security of this request can be transport or application 3001 layer. It is up the the communication security profile to define. 3002 In the example transport layer identification of the AS is done 3003 and the client identifies with client_id and client_secret as in 3004 classic OAuth. The request contains the public key of the client 3005 and the Audience parameter set to "tempSensorInLivingRoom", a 3006 value that the temperature sensor identifies itself with. The AS 3007 evaluates the request and authorizes the client to access the 3008 resource. 3009 B: The AS responds with a PoP access token and Access Information. 3010 The PoP access token contains the public key of the client, and 3011 the Access Information contains the public key of the RS. For 3012 communication security this example uses DTLS RawPublicKey between 3013 the client and the RS. The issued token will have a short 3014 validity time, i.e., "exp" close to "iat", to protect the RS from 3015 replay attacks. The token includes the claim such as "scope" with 3016 the authorized access that an owner of the temperature device can 3017 enjoy. In this example, the "scope" claim, issued by the AS, 3018 informs the RS that the owner of the token, that can prove the 3019 possession of a key is authorized to make a GET request against 3020 the /temperature resource and a POST request on the /firmware 3021 resource. Note that the syntax and semantics of the scope claim 3022 are application specific. 3023 Note: In this example it is assumed that the client knows what 3024 resource it wants to access, and is therefore able to request 3025 specific audience and scope claims for the access token. 3027 Authorization 3028 Client Server 3029 | | 3030 |<=======>| DTLS Connection Establishment 3031 | | to identify the AS 3032 | | 3033 A: +-------->| Header: POST (Code=0.02) 3034 | POST | Uri-Path:"token" 3035 | | Content-Format: application/ace+cbor 3036 | | Payload: 3037 | | 3038 B: |<--------+ Header: 2.05 Content 3039 | 2.05 | Content-Format: application/ace+cbor 3040 | | Payload: 3041 | | 3043 Figure 17: Token Request and Response Using Client Credentials. 3045 The information contained in the Request-Payload and the Response- 3046 Payload is shown in Figure 18 Note that the parameter "rs_cnf" from 3048 [I-D.ietf-ace-oauth-params] is used to inform the client about the 3049 resource server's public key. 3051 Request-Payload : 3052 { 3053 "audience" : "tempSensorInLivingRoom", 3054 "client_id" : "myclient", 3055 "client_secret" : "qwerty" 3056 "req_cnf" : { 3057 "COSE_Key" : { 3058 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 3059 "kty" : "EC", 3060 "crv" : "P-256", 3061 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 3062 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 3063 } 3064 } 3065 } 3067 Response-Payload : 3068 { 3069 "access_token" : b64'SlAV32hkKG ...', 3070 "rs_cnf" : { 3071 "COSE_Key" : { 3072 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 3073 "kty" : "EC", 3074 "crv" : "P-256", 3075 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 3076 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 3077 } 3078 } 3079 } 3081 Figure 18: Request and Response Payload Details. 3083 The content of the access token is shown in Figure 19. 3085 { 3086 "aud" : "tempSensorInLivingRoom", 3087 "iat" : "1360189224", 3088 "exp" : "1360289224", 3089 "scope" : "temperature_g firmware_p", 3090 "cnf" : { 3091 "COSE_Key" : { 3092 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 3093 "kty" : "EC", 3094 "crv" : "P-256", 3095 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 3096 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 3097 } 3098 } 3099 } 3101 Figure 19: Access Token including Public Key of the Client. 3103 Messages C and F are shown in Figure 20 - Figure 21. 3105 C: The client then sends the PoP access token to the authz-info 3106 endpoint at the RS. This is a plain CoAP request, i.e., no 3107 transport or application layer security is used between client and 3108 RS since the token is integrity protected between the AS and RS. 3109 The RS verifies that the PoP access token was created by a known 3110 and trusted AS, is valid, and has been issued to the client. The 3111 RS caches the security context together with authorization 3112 information about this client contained in the PoP access token. 3114 Resource 3115 Client Server 3116 | | 3117 C: +-------->| Header: POST (Code=0.02) 3118 | POST | Uri-Path:"authz-info" 3119 | | Payload: SlAV32hkKG ... 3120 | | 3121 |<--------+ Header: 2.04 Changed 3122 | 2.04 | 3123 | | 3125 Figure 20: Access Token provisioning to RS 3126 The client and the RS runs the DTLS handshake using the raw public 3127 keys established in step B and C. 3128 The client sends the CoAP request GET to /temperature on RS over 3129 DTLS. The RS verifies that the request is authorized, based on 3130 previously established security context. 3131 F: The RS responds with a resource representation over DTLS. 3133 Resource 3134 Client Server 3135 | | 3136 |<=======>| DTLS Connection Establishment 3137 | | using Raw Public Keys 3138 | | 3139 +-------->| Header: GET (Code=0.01) 3140 | GET | Uri-Path: "temperature" 3141 | | 3142 | | 3143 | | 3144 F: |<--------+ Header: 2.05 Content 3145 | 2.05 | Payload: 3146 | | 3148 Figure 21: Resource Request and Response protected by DTLS. 3150 E.2. Introspection Aided Token Validation 3152 In this deployment scenario it is assumed that a client is not able 3153 to access the AS at the time of the access request, whereas the RS is 3154 assumed to be connected to the back-end infrastructure. Thus the RS 3155 can make use of token introspection. This access procedure involves 3156 steps A-F of Figure 1, but assumes steps A and B have been carried 3157 out during a phase when the client had connectivity to AS. 3159 Since the client is assumed to be offline, at least for a certain 3160 period of time, a pre-provisioned access token has to be long-lived. 3161 Since the client is constrained, the token will not be self contained 3162 (i.e. not a CWT) but instead just a reference. The resource server 3163 uses its connectivity to learn about the claims associated to the 3164 access token by using introspection, which is shown in the example 3165 below. 3167 In the example interactions between an offline client (key fob), a RS 3168 (online lock), and an AS is shown. It is assumed that there is a 3169 provisioning step where the client has access to the AS. This 3170 corresponds to message exchanges A and B which are shown in 3171 Figure 22. 3173 Authorization consent from the resource owner can be pre-configured, 3174 but it can also be provided via an interactive flow with the resource 3175 owner. An example of this for the key fob case could be that the 3176 resource owner has a connected car, he buys a generic key that he 3177 wants to use with the car. To authorize the key fob he connects it 3178 to his computer that then provides the UI for the device. After that 3179 OAuth 2.0 implicit flow can used to authorize the key for his car at 3180 the the car manufacturers AS. 3182 Note: In this example the client does not know the exact door it will 3183 be used to access since the token request is not send at the time of 3184 access. So the scope and audience parameters are set quite wide to 3185 start with and new values different form the original once can be 3186 returned from introspection later on. 3188 A: The client sends the request using POST to the token endpoint 3189 at AS. The request contains the Audience parameter set to 3190 "PACS1337" (PACS, Physical Access System), a value the that the 3191 online door in question identifies itself with. The AS generates 3192 an access token as an opaque string, which it can match to the 3193 specific client, a targeted audience and a symmetric key. The 3194 security is provided by identifying the AS on transport layer 3195 using a pre shared security context (psk, rpk or certificate) and 3196 then the client is identified using client_id and client_secret as 3197 in classic OAuth. 3198 B: The AS responds with the an access token and Access 3199 Information, the latter containing a symmetric key. Communication 3200 security between C and RS will be DTLS and PreSharedKey. The PoP 3201 key is used as the PreSharedKey. 3203 Authorization 3204 Client Server 3205 | | 3206 | | 3207 A: +-------->| Header: POST (Code=0.02) 3208 | POST | Uri-Path:"token" 3209 | | Content-Format: application/ace+cbor 3210 | | Payload: 3211 | | 3212 B: |<--------+ Header: 2.05 Content 3213 | | Content-Format: application/ace+cbor 3214 | 2.05 | Payload: 3215 | | 3217 Figure 22: Token Request and Response using Client Credentials. 3219 The information contained in the Request-Payload and the Response- 3220 Payload is shown in Figure 23. 3222 Request-Payload: 3223 { 3224 "client_id" : "keyfob", 3225 "client_secret" : "qwerty" 3226 } 3228 Response-Payload: 3229 { 3230 "access_token" : b64'VGVzdCB0b2tlbg==', 3231 "cnf" : { 3232 "COSE_Key" : { 3233 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 3234 "kty" : "oct", 3235 "alg" : "HS256", 3236 "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' 3237 } 3238 } 3239 } 3241 Figure 23: Request and Response Payload for C offline 3243 The access token in this case is just an opaque byte string 3244 referencing the authorization information at the AS. 3246 C: Next, the client POSTs the access token to the authz-info 3247 endpoint in the RS. This is a plain CoAP request, i.e., no DTLS 3248 between client and RS. Since the token is an opaque string, the 3249 RS cannot verify it on its own, and thus defers to respond the 3250 client with a status code until after step E. 3251 D: The RS forwards the token to the introspection endpoint on the 3252 AS. Introspection assumes a secure connection between the AS and 3253 the RS, e.g., using transport of application layer security. In 3254 the example AS is identified using pre shared security context 3255 (psk, rpk or certificate) while RS is acting as client and is 3256 identified with client_id and client_secret. 3257 E: The AS provides the introspection response containing 3258 parameters about the token. This includes the confirmation key 3259 (cnf) parameter that allows the RS to verify the client's proof of 3260 possession in step F. 3261 After receiving message E, the RS responds to the client's POST in 3262 step C with the CoAP response code 2.01 (Created). 3264 Resource 3265 Client Server 3266 | | 3267 C: +-------->| Header: POST (T=CON, Code=0.02) 3268 | POST | Uri-Path:"authz-info" 3269 | | Payload: b64'VGVzdCB0b2tlbg==' 3270 | | 3271 | | Authorization 3272 | | Server 3273 | | | 3274 | D: +--------->| Header: POST (Code=0.02) 3275 | | POST | Uri-Path: "introspect" 3276 | | | Content-Format: "application/ace+cbor" 3277 | | | Payload: 3278 | | | 3279 | E: |<---------+ Header: 2.05 Content 3280 | | 2.05 | Content-Format: "application/ace+cbor" 3281 | | | Payload: 3282 | | | 3283 | | 3284 |<--------+ Header: 2.01 Created 3285 | 2.01 | 3286 | | 3288 Figure 24: Token Introspection for C offline 3289 The information contained in the Request-Payload and the Response- 3290 Payload is shown in Figure 25. 3292 Request-Payload: 3293 { 3294 "token" : b64'VGVzdCB0b2tlbg==', 3295 "client_id" : "FrontDoor", 3296 "client_secret" : "ytrewq" 3297 } 3299 Response-Payload: 3300 { 3301 "active" : true, 3302 "aud" : "lockOfDoor4711", 3303 "scope" : "open, close", 3304 "iat" : 1311280970, 3305 "cnf" : { 3306 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk' 3307 } 3308 } 3310 Figure 25: Request and Response Payload for Introspection 3312 The client uses the symmetric PoP key to establish a DTLS 3313 PreSharedKey secure connection to the RS. The CoAP request PUT is 3314 sent to the uri-path /state on the RS, changing the state of the 3315 door to locked. 3316 F: The RS responds with a appropriate over the secure DTLS 3317 channel. 3319 Resource 3320 Client Server 3321 | | 3322 |<=======>| DTLS Connection Establishment 3323 | | using Pre Shared Key 3324 | | 3325 +-------->| Header: PUT (Code=0.03) 3326 | PUT | Uri-Path: "state" 3327 | | Payload: 3328 | | 3329 F: |<--------+ Header: 2.04 Changed 3330 | 2.04 | Payload: 3331 | | 3333 Figure 26: Resource request and response protected by OSCORE 3335 Appendix F. Document Updates 3337 RFC EDITOR: PLEASE REMOVE THIS SECTION. 3339 F.1. Verion -19 to 20 3341 o Replaced "req_aud" with "audience" from the OAuth token exchange 3342 draft. 3343 o Updated examples to remove unnecessary elements. 3345 F.2. Version -18 to -19 3347 o Added definition of "Authorization Information". 3348 o Explicitly state that ACE allows encoding refresh tokens in binary 3349 format in addition to strings. 3350 o Renamed "AS Information" to "AS Request Creation Hints" and added 3351 the possibility to specify req_aud and scope as hints. 3352 o Added the "kid" parameter to AS Request Creation Hints. 3353 o Added security considerations about the integrity protection of 3354 tokens with multi-RS audiences. 3355 o Renamed IANA registries mapping OAuth parameters to reflect the 3356 mapped registry. 3357 o Added JWT claim names to CWT claim registrations. 3358 o Added expert review instructions. 3359 o Updated references to TLS from 1.2 to 1.3. 3361 F.3. Version -17 to -18 3363 o Added OSCORE options in examples involving OSCORE. 3364 o Removed requirement for the client to send application/cwt, since 3365 the client has no way to know. 3366 o Clarified verification of tokens by the RS. 3367 o Added exi claim CWT registration. 3369 F.4. Version -16 to -17 3371 o Added references to (D)TLS 1.3. 3372 o Added requirement that responses are bound to requests. 3373 o Specify that grant_type is OPTIONAL in C2AS requests (as opposed 3374 to REQUIRED in OAuth). 3375 o Replaced examples with hypothetical COSE profile with OSCORE. 3376 o Added requirement for content type application/ace+cbor in error 3377 responses for token and introspection requests and responses. 3378 o Reworked abbreviation space for claims, request and response 3379 parameters. 3380 o Added text that the RS may indicate that it is busy at the authz- 3381 info resource. 3382 o Added section that specifies how the RS verifies an access token. 3383 o Added section on the protection of the authz-info endpoint. 3384 o Removed the expiration mechanism based on sequence numbers. 3385 o Added reference to RFC7662 security considerations. 3386 o Added considerations on minimal security requirements for 3387 communication. 3388 o Added security considerations on unprotected information sent to 3389 authz-info and in the error responses. 3391 F.5. Version -15 to -16 3393 o Added text the RS using RFC6750 error codes. 3394 o Defined an error code for incompatible token request parameters. 3395 o Removed references to the actors draft. 3396 o Fixed errors in examples. 3398 F.6. Version -14 to -15 3400 o Added text about refresh tokens. 3401 o Added text about protection of credentials. 3402 o Rephrased introspection so that other entities than RS can do it. 3403 o Editorial improvements. 3405 F.7. Version -13 to -14 3407 o Split out the 'aud', 'cnf' and 'rs_cnf' parameters to 3408 [I-D.ietf-ace-oauth-params] 3409 o Introduced the "application/ace+cbor" Content-Type. 3410 o Added claim registrations from 'profile' and 'rs_cnf'. 3411 o Added note on schema part of AS Information Section 5.1.2 3412 o Realigned the parameter abbreviations to push rarely used ones to 3413 the 2-byte encoding size of CBOR integers. 3415 F.8. Version -12 to -13 3417 o Changed "Resource Information" to "Access Information" to avoid 3418 confusion. 3419 o Clarified section about AS discovery. 3420 o Editorial changes 3422 F.9. Version -11 to -12 3424 o Moved the Request error handling to a section of its own. 3425 o Require the use of the abbreviation for profile identifiers. 3426 o Added rs_cnf parameter in the introspection response, to inform 3427 RS' with several RPKs on which key to use. 3428 o Allowed use of rs_cnf as claim in the access token in order to 3429 inform an RS with several RPKs on which key to use. 3430 o Clarified that profiles must specify if/how error responses are 3431 protected. 3432 o Fixed label number range to align with COSE/CWT. 3433 o Clarified the requirements language in order to allow profiles to 3434 specify other payload formats than CBOR if they do not use CoAP. 3436 F.10. Version -10 to -11 3438 o Fixed some CBOR data type errors. 3439 o Updated boilerplate text 3441 F.11. Version -09 to -10 3443 o Removed CBOR major type numbers. 3444 o Removed the client token design. 3445 o Rephrased to clarify that other protocols than CoAP can be used. 3446 o Clarifications regarding the use of HTTP 3448 F.12. Version -08 to -09 3450 o Allowed scope to be byte strings. 3451 o Defined default names for endpoints. 3452 o Refactored the IANA section for briefness and consistency. 3454 o Refactored tables that define IANA registry contents for 3455 consistency. 3456 o Created IANA registry for CBOR mappings of error codes, grant 3457 types and Authorization Server Information. 3458 o Added references to other document sections defining IANA entries 3459 in the IANA section. 3461 F.13. Version -07 to -08 3463 o Moved AS discovery from the DTLS profile to the framework, see 3464 Section 5.1. 3465 o Made the use of CBOR mandatory. If you use JSON you can use 3466 vanilla OAuth. 3467 o Made it mandatory for profiles to specify C-AS security and RS-AS 3468 security (the latter only if introspection is supported). 3469 o Made the use of CBOR abbreviations mandatory. 3470 o Added text to clarify the use of token references as an 3471 alternative to CWTs. 3472 o Added text to clarify that introspection must not be delayed, in 3473 case the RS has to return a client token. 3474 o Added security considerations about leakage through unprotected AS 3475 discovery information, combining profiles and leakage through 3476 error responses. 3477 o Added privacy considerations about leakage through unprotected AS 3478 discovery. 3479 o Added text that clarifies that introspection is optional. 3480 o Made profile parameter optional since it can be implicit. 3481 o Clarified that CoAP is not mandatory and other protocols can be 3482 used. 3483 o Clarified the design justification for specific features of the 3484 framework in appendix A. 3485 o Clarified appendix E.2. 3486 o Removed specification of the "cnf" claim for CBOR/COSE, and 3487 replaced with references to [I-D.ietf-ace-cwt-proof-of-possession] 3489 F.14. Version -06 to -07 3491 o Various clarifications added. 3492 o Fixed erroneous author email. 3494 F.15. Version -05 to -06 3496 o Moved sections that define the ACE framework into a subsection of 3497 the framework Section 5. 3498 o Split section on client credentials and grant into two separate 3499 sections, Section 5.2, and Section 5.3. 3500 o Added Section 5.4 on AS authentication. 3501 o Added Section 5.5 on the Authorization endpoint. 3503 F.16. Version -04 to -05 3505 o Added RFC 2119 language to the specification of the required 3506 behavior of profile specifications. 3507 o Added Section 5.3 on the relation to the OAuth2 grant types. 3508 o Added CBOR abbreviations for error and the error codes defined in 3509 OAuth2. 3510 o Added clarification about token expiration and long-running 3511 requests in Section 5.8.3 3512 o Added security considerations about tokens with symmetric pop keys 3513 valid for more than one RS. 3514 o Added privacy considerations section. 3515 o Added IANA registry mapping the confirmation types from RFC 7800 3516 to equivalent COSE types. 3517 o Added appendix D, describing assumptions about what the AS knows 3518 about the client and the RS. 3520 F.17. Version -03 to -04 3522 o Added a description of the terms "framework" and "profiles" as 3523 used in this document. 3524 o Clarified protection of access tokens in section 3.1. 3525 o Clarified uses of the "cnf" parameter in section 6.4.5. 3526 o Clarified intended use of Client Token in section 7.4. 3528 F.18. Version -02 to -03 3530 o Removed references to draft-ietf-oauth-pop-key-distribution since 3531 the status of this draft is unclear. 3532 o Copied and adapted security considerations from draft-ietf-oauth- 3533 pop-key-distribution. 3534 o Renamed "client information" to "RS information" since it is 3535 information about the RS. 3536 o Clarified the requirements on profiles of this framework. 3537 o Clarified the token endpoint protocol and removed negotiation of 3538 "profile" and "alg" (section 6). 3539 o Renumbered the abbreviations for claims and parameters to get a 3540 consistent numbering across different endpoints. 3541 o Clarified the introspection endpoint. 3542 o Renamed token, introspection and authz-info to "endpoint" instead 3543 of "resource" to mirror the OAuth 2.0 terminology. 3544 o Updated the examples in the appendices. 3546 F.19. Version -01 to -02 3548 o Restructured to remove communication security parts. These shall 3549 now be defined in profiles. 3551 o Restructured section 5 to create new sections on the OAuth 3552 endpoints token, introspection and authz-info. 3553 o Pulled in material from draft-ietf-oauth-pop-key-distribution in 3554 order to define proof-of-possession key distribution. 3555 o Introduced the "cnf" parameter as defined in RFC7800 to reference 3556 or transport keys used for proof of possession. 3557 o Introduced the "client-token" to transport client information from 3558 the AS to the client via the RS in conjunction with introspection. 3559 o Expanded the IANA section to define parameters for token request, 3560 introspection and CWT claims. 3561 o Moved deployment scenarios to the appendix as examples. 3563 F.20. Version -00 to -01 3565 o Changed 5.1. from "Communication Security Protocol" to "Client 3566 Information". 3567 o Major rewrite of 5.1 to clarify the information exchanged between 3568 C and AS in the PoP access token request profile for IoT. 3570 * Allow the client to indicate preferences for the communication 3571 security protocol. 3572 * Defined the term "Client Information" for the additional 3573 information returned to the client in addition to the access 3574 token. 3575 * Require that the messages between AS and client are secured, 3576 either with (D)TLS or with COSE_Encrypted wrappers. 3577 * Removed dependency on OSCOAP and added generic text about 3578 object security instead. 3579 * Defined the "rpk" parameter in the client information to 3580 transmit the raw public key of the RS from AS to client. 3581 * (D)TLS MUST use the PoP key in the handshake (either as PSK or 3582 as client RPK with client authentication). 3583 * Defined the use of x5c, x5t and x5tS256 parameters when a 3584 client certificate is used for proof of possession. 3585 * Defined "tktn" parameter for signaling for how to transfer the 3586 access token. 3587 o Added 5.2. the CoAP Access-Token option for transferring access 3588 tokens in messages that do not have payload. 3589 o 5.3.2. Defined success and error responses from the RS when 3590 receiving an access token. 3591 o 5.6.:Added section giving guidance on how to handle token 3592 expiration in the absence of reliable time. 3593 o Appendix B Added list of roles and responsibilities for C, AS and 3594 RS. 3596 Authors' Addresses 3598 Ludwig Seitz 3599 RISE 3600 Scheelevaegen 17 3601 Lund 223 70 3602 Sweden 3604 Email: ludwig.seitz@ri.se 3606 Goeran Selander 3607 Ericsson 3608 Faroegatan 6 3609 Kista 164 80 3610 Sweden 3612 Email: goran.selander@ericsson.com 3614 Erik Wahlstroem 3615 Sweden 3617 Email: erik@wahlstromstekniska.se 3619 Samuel Erdtman 3620 Spotify AB 3621 Birger Jarlsgatan 61, 4tr 3622 Stockholm 113 56 3623 Sweden 3625 Email: erdtman@spotify.com 3627 Hannes Tschofenig 3628 Arm Ltd. 3629 Absam 6067 3630 Austria 3632 Email: Hannes.Tschofenig@arm.com