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