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