idnits 2.17.1 draft-ietf-ace-oauth-authz-04.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 seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (October 31, 2016) is 2734 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-15) exists of draft-ietf-ace-cbor-web-token-01 == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-23 ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-07) exists of draft-ietf-ace-actors-04 == Outdated reference: A later version (-15) exists of draft-ietf-oauth-device-flow-03 == Outdated reference: A later version (-12) exists of draft-ietf-oauth-native-apps-05 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group L. Seitz 3 Internet-Draft SICS 4 Intended status: Standards Track G. Selander 5 Expires: May 4, 2017 Ericsson 6 E. Wahlstroem 8 S. Erdtman 9 Spotify AB 10 H. Tschofenig 11 ARM Ltd. 12 October 31, 2016 14 Authentication and Authorization for Constrained Environments (ACE) 15 draft-ietf-ace-oauth-authz-04 17 Abstract 19 This specification defines a framework for authentication and 20 authorization in Internet of Things (IoT) environments. The 21 framework is based on a set of building blocks including OAuth 2.0 22 and CoAP, thus making a well-known and widely used authorization 23 solution suitable for IoT devices. Existing specifications are used 24 where possible, but where the constraints of IoT devices require it, 25 extensions are added and profiles are defined. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on May 4, 2017. 44 Copyright Notice 46 Copyright (c) 2016 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 65 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 9 67 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 6. The 'Token' Endpoint . . . . . . . . . . . . . . . . . . . . 14 69 6.1. Client-to-AS Request . . . . . . . . . . . . . . . . . . 15 70 6.2. AS-to-Client Response . . . . . . . . . . . . . . . . . . 17 71 6.3. Error Response . . . . . . . . . . . . . . . . . . . . . 19 72 6.4. New Request and Response Parameters . . . . . . . . . . . 19 73 6.4.1. Audience . . . . . . . . . . . . . . . . . . . . . . 19 74 6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . . . 19 75 6.4.3. Token Type . . . . . . . . . . . . . . . . . . . . . 19 76 6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . . . 20 77 6.4.5. Confirmation . . . . . . . . . . . . . . . . . . . . 20 78 6.5. Mapping parameters to CBOR . . . . . . . . . . . . . . . 22 79 7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . . . 23 80 7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . . . 24 81 7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . . . 24 82 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 25 83 7.4. Client Token . . . . . . . . . . . . . . . . . . . . . . 26 84 7.5. Mapping Introspection parameters to CBOR . . . . . . . . 28 85 8. The Access Token . . . . . . . . . . . . . . . . . . . . . . 28 86 8.1. The 'Authorization Information' Endpoint . . . . . . . . 29 87 8.2. Token Expiration . . . . . . . . . . . . . . . . . . . . 29 88 9. Security Considerations . . . . . . . . . . . . . . . . . . . 30 89 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 90 10.1. OAuth Introspection Response Parameter Registration . . 31 91 10.2. OAuth Parameter Registration . . . . . . . . . . . . . . 32 92 10.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 32 93 10.4. Token Type Mappings . . . . . . . . . . . . . . . . . . 33 94 10.4.1. Registration Template . . . . . . . . . . . . . . . 33 95 10.4.2. Initial Registry Contents . . . . . . . . . . . . . 33 96 10.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . 33 97 10.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 34 98 10.6.1. Registration Template . . . . . . . . . . . . . . . 34 99 10.7. OAuth Parameter Mappings Registry . . . . . . . . . . . 34 100 10.7.1. Registration Template . . . . . . . . . . . . . . . 34 101 10.7.2. Initial Registry Contents . . . . . . . . . . . . . 35 102 10.8. Introspection Endpoint CBOR Mappings Registry . . . . . 37 103 10.8.1. Registration Template . . . . . . . . . . . . . . . 37 104 10.8.2. Initial Registry Contents . . . . . . . . . . . . . 37 105 10.9. CoAP Option Number Registration . . . . . . . . . . . . 39 106 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40 107 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 108 12.1. Normative References . . . . . . . . . . . . . . . . . . 40 109 12.2. Informative References . . . . . . . . . . . . . . . . . 41 110 Appendix A. Design Justification . . . . . . . . . . . . . . . . 43 111 Appendix B. Roles and Responsibilites . . . . . . . . . . . . . 45 112 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 47 113 Appendix D. Deployment Examples . . . . . . . . . . . . . . . . 47 114 D.1. Local Token Validation . . . . . . . . . . . . . . . . . 48 115 D.2. Introspection Aided Token Validation . . . . . . . . . . 51 116 Appendix E. Document Updates . . . . . . . . . . . . . . . . . . 55 117 E.1. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 55 118 E.2. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 55 119 E.3. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 56 120 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57 122 1. Introduction 124 Authorization is the process for granting approval to an entity to 125 access a resource [RFC4949]. The authorization task itself can best 126 be described as granting access to a requesting client, for a 127 resource hosted on a device, the resource server (RS). This exchange 128 is mediated by one or multiple authorization servers (AS). Managing 129 authorization for a large number of devices and users is a complex 130 task. 132 While prior work on authorization solutions for the Web and for the 133 mobile environment also applies to the IoT environment many IoT 134 devices are constrained, for example in terms of processing 135 capabilities, available memory, etc. For web applications on 136 constrained nodes this specification makes use of CoAP [RFC7252]. 138 A detailed treatment of constraints can be found in [RFC7228], and 139 the different IoT deployments present a continuous range of device 140 and network capabilities. Taking energy consumption as an example: 141 At one end there are energy-harvesting or battery powered devices 142 which have a tight power budget, on the other end there are mains- 143 powered devices, and all levels in between. 145 Hence, IoT devices may be very different in terms of available 146 processing and message exchange capabilities and there is a need to 147 support many different authorization use cases [RFC7744]. 149 This specification describes a framework for authentication and 150 authorization in constrained environments (ACE) built on re-use of 151 OAuth 2.0 [RFC6749], thereby extending authorization to Internet of 152 Things devices. This specification contains the necessary building 153 blocks for adjusting OAuth 2.0 to IoT environments. 155 More detailed, interoperable specifications can be found in profiles. 156 Implementations may claim conformance with a specific profile, 157 whereby implementations utilizing the same profile interoperate while 158 implementations of different profiles are not expected to be 159 interoperable. Some devices, such as mobile phones and tablets, may 160 implement multiple profiles and will therefore be able to interact 161 with a wider range of low end devices. 163 2. Terminology 165 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 166 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 167 document are to be interpreted as described in [RFC2119]. 169 Certain security-related terms such as "authentication", 170 "authorization", "confidentiality", "(data) integrity", "message 171 authentication code", and "verify" are taken from [RFC4949]. 173 Since we describe exchanges as RESTful protocol interactions HTTP 174 [RFC7231] offers useful terminology. 176 Terminology for entities in the architecture is defined in OAuth 2.0 177 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 178 server (RS), and authorization server (AS). 180 Note that the term "endpoint" is used here following its OAuth 181 definition, which is to denote resources such as /token and 182 /introspect at the AS and /authz-info at the RS. The CoAP [RFC7252] 183 definition, which is "An entity participating in the CoAP protocol" 184 is not used in this memo. 186 Since this specification focuses on the problem of access control to 187 resources, we simplify the actors by assuming that the client 188 authorization server (CAS) functionality is not stand-alone but 189 subsumed by either the authorization server or the client (see 190 section 2.2 in [I-D.ietf-ace-actors]). 192 We call the specifications of this memo the "framework" or "ACE 193 framework". When referring to "profiles of this framework" we mean 194 additional memo's that define the use of this specification with 195 concrete transport, and communication security protocols (e.g. CoAP 196 over DTLS). 198 3. Overview 200 This specification defines the ACE framework for authorization in the 201 Internet of Things environment. It consists of a set of building 202 blocks. 204 The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys 205 widespread deployment. Many IoT devices can support OAuth 2.0 206 without any additional extensions, but for certain constrained 207 settings additional profiling is needed. 209 Another building block is the lightweight web transfer protocol CoAP 210 [RFC7252] for those communication environments where HTTP is not 211 appropriate. CoAP typically runs on top of UDP which further reduces 212 overhead and message exchanges. While this specification defines 213 extensions for the use of OAuth over CoAP, we do envision further 214 underlying protocols to be supported in the future, such as HTTP/2, 215 MQTT and QUIC. 217 A third building block is CBOR [RFC7049] for encodings where JSON 218 [RFC7159] is not sufficiently compact. CBOR is a binary encoding 219 designed for small code and message size, which may be used for 220 encoding of self contained tokens, and also for encoding CoAP POST 221 parameters and CoAP responses. 223 A fourth building block is the compact CBOR-based secure message 224 format COSE [I-D.ietf-cose-msg], which enables application layer 225 security as an alternative or complement to transport layer security 226 (DTLS [RFC6347] or TLS [RFC5246]). COSE is used to secure self 227 contained tokens such as proof-of-possession (PoP) tokens, which is 228 an extension to the OAuth access tokens, and "client tokens" which 229 are defined in this framework (see Section 7.4). The default access 230 token format is defined in CBOR web token (CWT) 231 [I-D.ietf-ace-cbor-web-token]. Application layer security for CoAP 232 using COSE can be provided with OSCOAP 233 [I-D.selander-ace-object-security]. 235 With the building blocks listed above, solutions satisfying various 236 IoT device and network constraints are possible. A list of 237 constraints is described in detail in RFC 7228 [RFC7228] and a 238 description of how the building blocks mentioned above relate to the 239 various constraints can be found in Appendix A. 241 Luckily, not every IoT device suffers from all constraints. The ACE 242 framework nevertheless takes all these aspects into account and 243 allows several different deployment variants to co-exist rather than 244 mandating a one-size-fits-all solution. We believe this is important 245 to cover the wide range of possible interworking use cases and the 246 different requirements from a security point of view. Once IoT 247 deployments mature, popular deployment variants will be documented in 248 form of ACE profiles. 250 In the subsections below we provide further details about the 251 different building blocks. 253 3.1. OAuth 2.0 255 The OAuth 2.0 authorization framework enables a client to obtain 256 limited access to a resource with the permission of a resource owner. 257 Authorization information, or references to it, is passed between the 258 nodes using access tokens. These access tokens are issued to clients 259 by an authorization server with the approval of the resource owner. 260 The client uses the access token to access the protected resources 261 hosted by the resource server. 263 A number of OAuth 2.0 terms are used within this specification: 265 The token and introspect Endpoints: 267 The AS hosts the /token endpoint that allows a client to request 268 access tokens. The client makes a POST request to the /token 269 endpoint on the AS and receives the access token in the response 270 (if the request was successful). 272 The token introspection endpoint, /introspect, is used by the RS 273 when requesting additional information regarding a received access 274 token. The RS makes a POST request to /introspect on the AS and 275 receives information about the access token in the response. (See 276 "Introspection" below.) 278 Access Tokens: 280 Access tokens are credentials needed to access protected 281 resources. An access token is a data structure representing 282 authorization permissions issued by the AS to the client. Access 283 tokens are generated by the authorization server and consumed by 284 the resource server. The access token content is opaque to the 285 client. 287 Access tokens can have different formats, and various methods of 288 utilization (e.g., cryptographic properties) based on the security 289 requirements of the given deployment. 291 Proof of Possession Tokens: 293 An access token may be bound to a cryptographic key, which is then 294 used by an RS to authenticate requests from a client. Such tokens 295 are called proof-of-possession tokens (or PoP tokens). 297 The proof-of-possession (PoP) security concept assumes that the AS 298 acts as a trusted third party that binds keys to access tokens. 299 These so called PoP keys are then used by the client to 300 demonstrate the possession of the secret to the RS when accessing 301 the resource. The RS, when receiving an access token, needs to 302 verify that the key used by the client matches the one bound to 303 the access token. When this specification uses the term "access 304 token" it is assumed to be a PoP token unless specifically stated 305 otherwise. 307 The key bound to the access token (aka PoP key) may be based on 308 symmetric as well as on asymmetric cryptography. The appropriate 309 choice of security depends on the constraints of the IoT devices 310 as well as on the security requirements of the use case. 312 Symmetric PoP key: The AS generates a random symmetric PoP key. 313 The key is either stored to be returned on introspection calls 314 or encrypted and included in the access token. The PoP key is 315 also encrypted for the client and sent together with the access 316 token to the client. 318 Asymmetric PoP key: An asymmetric key pair is generated on the 319 client and the public key is sent to the AS (if it does not 320 already have knowledge of the client's public key). 321 Information about the public key, which is the PoP key in this 322 case, is either stored to be returned on introspection calls or 323 included inside the access token and sent back to the 324 requesting client. The RS can identify the client's public key 325 from the information in the token, which allows the client to 326 use the corresponding private key for the proof of possession. 328 The access token is either a simple reference, or a structured 329 information object (e.g. CWT [I-D.ietf-ace-cbor-web-token]), 330 protected by a cryptographic wrapper (e.g. COSE 331 [I-D.ietf-cose-msg]). The choice of PoP key does not necessarily 332 imply a specific credential type for the integrity protection of 333 the token. 335 Scopes and Permissions: 337 In OAuth 2.0, the client specifies the type of permissions it is 338 seeking to obtain (via the scope parameter) in the access token 339 request. In turn, the AS may use the scope response parameter to 340 inform the client of the scope of the access token issued. As the 341 client could be a constrained device as well, this specification 342 uses CBOR encoded messages for CoAP, defined in Section 5, to 343 request scopes and to be informed what scopes the access token was 344 actually authorized for by the AS. 346 The values of the scope parameter are expressed as a list of 347 space- delimited, case-sensitive strings, with a semantic that is 348 well-known to the AS and the RS. More details about the concept 349 of scopes is found under Section 3.3 in [RFC6749]. 351 Claims: 353 Information carried in the access token or returned from 354 introspection, called claims, is in the form of type-value pairs. 355 An access token may, for example, include a claim identifying the 356 AS that issued the token (via the "iss" claim) and what audience 357 the access token is intended for (via the "aud" claim). The 358 audience of an access token can be a specific resource or one or 359 many resource servers. The resource owner policies influence what 360 claims are put into the access token by the authorization server. 362 While the structure and encoding of the access token varies 363 throughout deployments, a standardized format has been defined 364 with the JSON Web Token (JWT) [RFC7519] where claims are encoded 365 as a JSON object. In [I-D.ietf-ace-cbor-web-token] an equivalent 366 format using CBOR encoding (CWT) has been defined. 368 Introspection: 370 Introspection is a method for a resource server to query the 371 authorization server for the active state and content of a 372 received access token. This is particularly useful in those cases 373 where the authorization decisions are very dynamic and/or where 374 the received access token itself is a reference rather than a 375 self-contained token. More information about introspection in 376 OAuth 2.0 can be found in [RFC7662]. 378 3.2. CoAP 380 CoAP is an application layer protocol similar to HTTP, but 381 specifically designed for constrained environments. CoAP typically 382 uses datagram-oriented transport, such as UDP, where reordering and 383 loss of packets can occur. A security solution need to take the 384 latter aspects into account. 386 While HTTP uses headers and query-strings to convey additional 387 information about a request, CoAP encodes such information in so- 388 called 'options'. 390 CoAP supports application-layer fragmentation of the CoAP payloads 391 through blockwise transfers [RFC7959]. However, block-wise transfer 392 does not increase the size limits of CoAP options, therefore data 393 encoded in options has to be kept small. 395 Transport layer security for CoAP can be provided by DTLS 1.2 396 [RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy 397 operations which requires transport layer security to be terminated 398 at the proxy. One approach for protecting CoAP communication end-to- 399 end through proxies, and also to support security for CoAP over a 400 different transport in a uniform way, is to provide security on 401 application layer using an object-based security mechanism such as 402 COSE [I-D.ietf-cose-msg]. 404 One application of COSE is OSCOAP [I-D.selander-ace-object-security], 405 which provides end-to-end confidentiality, integrity and replay 406 protection, and a secure binding between CoAP request and response 407 messages. In OSCOAP, the CoAP messages are wrapped in COSE objects 408 and sent using CoAP. 410 4. Protocol Interactions 412 The ACE framework is based on the OAuth 2.0 protocol interactions 413 using the /token and /introspect endpoints. A client obtains an 414 access token from an AS using the /token endpoint and subsequently 415 presents the access token to a RS to gain access to a protected 416 resource. The RS, after receiving an access token, may present it to 417 the AS via the /introspect endpoint to get information about the 418 access token. In other deployments the RS may process the access 419 token locally without the need to contact an AS. These interactions 420 are shown in Figure 1. An overview of various OAuth concepts is 421 provided in Section 3.1. 423 The OAuth 2.0 framework defines a number of "protocol flows" via 424 grant types, which have been extended further with extensions to 425 OAuth 2.0 (such as RFC 7521 [RFC7521] and 426 [I-D.ietf-oauth-device-flow]). What grant types works best depends 427 on the usage scenario and RFC 7744 [RFC7744] describes many different 428 IoT use cases but there are two preferred grant types, namely the 429 Authorization Code Grant (described in Section 4.1 of RFC 7521) and 430 the Client Credentials Grant (described in Section 4.4 of RFC 7521). 432 The Authorization Code Grant is a good fit for use with apps running 433 on smart phones and tablets that request access to IoT devices, a 434 common scenario in the smart home environment, where users need to go 435 through an authentication and authorization phase (at least during 436 the initial setup phase). The native apps guidelines described in 437 [I-D.ietf-oauth-native-apps] are applicable to this use case. The 438 Client Credential Grant is a good fit for use with IoT devices where 439 the OAuth client itself is constrained. In such a case the resource 440 owner or another person on his or her behalf have arranged with the 441 authorization server out-of-band, which is often accomplished using a 442 commissioning tool. 444 The consent of the resource owner, for giving a client access to a 445 protected resource, can be provided dynamically as in the traditional 446 OAuth flows, or it could be pre-configured by the resource owner as 447 authorization policies at the AS, which the AS evaluates when a token 448 request arrives. The resource owner and the requesting party (i.e. 449 client owner) are not shown in Figure 1. 451 This framework supports a wide variety of communication security 452 mechanisms between the ACE entities, such as client, AS, and RS. We 453 assume that the client has been registered (also called enrolled or 454 onboarded) to an AS using a mechanism defined outside the scope of 455 this document. In practice, various techniques for onboarding have 456 been used, such as factory-based provisioning or the use of 457 commissioning tools. Regardless of the onboarding technique, this 458 registration procedure implies that the client and the AS share 459 credentials, and configuration parameters. These credentials are 460 used to mutually authenticate each other and to protect messages 461 exchanged between the client and the AS. 463 It is also assumed that the RS has been registered with the AS, 464 potentially in a similar way as the client has been registered with 465 the AS. Established keying material between the AS and the RS allows 466 the AS to apply cryptographic protection to the access token to 467 ensure that its content cannot be modified, and if needed, that the 468 content is confidentiality protected. 470 The keying material necessary for establishing communication security 471 between C and RS is dynamically established as part of the protocol 472 described in this document. 474 At the start of the protocol there is an optional discovery step 475 where the client discovers the resource server and the resources this 476 server hosts. In this step the client might also determine what 477 permissions are needed to access the protected resource. The 478 detailed procedures for this discovery process may be defined in an 479 ACE profile and depend on the protocols being used and the specific 480 deployment environment. 482 In Bluetooth Low Energy, for example, advertisements are broadcasted 483 by a peripheral, including information about the primary services. 484 In CoAP, as a second example, a client can make a request to "/.well- 485 known/core" to obtain information about available resources, which 486 are returned in a standardized format as described in [RFC6690]. 488 +--------+ +---------------+ 489 | |---(A)-- Token Request ------->| | 490 | | | Authorization | 491 | |<--(B)-- Access Token ---------| Server | 492 | | + RS Information | | 493 | | +---------------+ 494 | | ^ | 495 | | Introspection Request (D)| | 496 | Client | | | 497 | | Response + Client Token | |(E) 498 | | | v 499 | | +--------------+ 500 | |---(C)-- Token + Request ----->| | 501 | | | Resource | 502 | |<--(F)-- Protected Resource ---| Server | 503 | | | | 504 +--------+ +--------------+ 506 Figure 1: Basic Protocol Flow. 508 Requesting an Access Token (A): 510 The client makes an access token request to the /token endpoint at 511 the AS. This framework assumes the use of PoP tokens (see 512 Section 3.1 for a short description) wherein the AS binds a key to 513 an access token. The client may include permissions it seeks to 514 obtain, and information about the credentials it wants to use 515 (e.g., symmetric/asymmetric cryptography or a reference to a 516 specific credential). 518 Access Token Response (B): 520 If the AS successfully processes the request from the client, it 521 returns an access token. It also returns various parameters, 522 referred as "RS Information". In addition to the response 523 parameters defined by OAuth 2.0 and the PoP token extension, 524 further response parameters, such as information on which profile 525 the client should use with the resource server(s). More 526 information about these parameters can be found in Section 6.4. 528 Resource Request (C): 530 The client interacts with the RS to request access to the 531 protected resource and provides the access token. The protocol to 532 use between the client and the RS is not restricted to CoAP. 533 HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also 534 viable candidates. 536 Depending on the device limitations and the selected protocol this 537 exchange may be split up into two parts: 539 (1) the client sends the access token containing, or 540 referencing, the authorization information to the RS, that may 541 be used for subsequent resource requests by the client, and 542 (2) the client makes the resource access request, using the 543 communication security protocol and other RS Information 544 obtained from the AS. 546 The Client and the RS mutually authenticate using the security 547 protocol specified in the profile (see step B) and the keys 548 obtained in the access token or the RS Information or the client 549 token. The RS verifies that the token is integrity protected by 550 the AS and compares the claims contained in the access token with 551 the resource request. If the RS is online, validation can be 552 handed over to the AS using token introspection (see messages D 553 and E) over HTTP or CoAP, in which case the different parts of 554 step C may be interleaved with introspection. 556 Token Introspection Request (D): 558 A resource server may be configured to introspect the access token 559 by including it in a request to the /introspect endpoint at that 560 AS. Token introspection over CoAP is defined in Section 7 and for 561 HTTP in [RFC7662]. 563 Note that token introspection is an optional step and can be 564 omitted if the token is self-contained and the resource server is 565 prepared to perform the token validation on its own. 567 Token Introspection Response (E): 569 The AS validates the token and returns the most recent parameters, 570 such as scope, audience, validity etc. associated with it back to 571 the RS. The RS then uses the received parameters to process the 572 request to either accept or to deny it. The AS can additionally 573 return information that the RS needs to pass on to the client in 574 the form of a client token. The latter is used to establish keys 575 for mutual authentication between client and RS, when the client 576 has no direct connectivity to the AS, see Section 7.4 for details. 578 Protected Resource (F): 580 If the request from the client is authorized, the RS fulfills the 581 request and returns a response with the appropriate response code. 582 The RS uses the dynamically established keys to protect the 583 response, according to used communication security protocol. 585 5. Framework 587 The following sections detail the profiling and extensions of OAuth 588 2.0 for constrained environments which constitutes the ACE framework. 590 Credential Provisioning 592 For IoT we cannot generally assume that the client and RS are part 593 of a common key infrastructure, so the AS provisions credentials 594 or associated information to allow mutual authentication. These 595 credentials need to be provided to the parties before or during 596 the authentication protocol is executed, and may be re-used for 597 subsequent token requests. 599 Proof-of-Possession 601 The ACE framework by default implements proof-of-possession for 602 access tokens, i.e. that the token holder can prove being a holder 603 of the key bound to the token. The binding is provided by the 604 "cnf" claim indicating what key is used for mutual authentication. 605 If clients need to update a token, e.g. to get additional rights, 606 they can request that the AS binds the new access token to the 607 same credential as the previous token. 609 ACE Profiles 611 The client or RS may be limited in the encodings or protocols it 612 supports. To support a variety of different deployment settings, 613 specific interactions between client and RS are defined in an ACE 614 profile. In ACE framework the AS is expected to manage the 615 matching of compatible profile choices between a client and an RS. 616 The AS informs the client of the selected profile using the 617 "profile" parameter in the token request and token response. 619 OAuth 2.0 requires the use of TLS both to protect the communication 620 between AS and client when requesting an access token; between client 621 and RS when accessing a resource and between AS and RS for 622 introspection. In constrained settings TLS is not always feasible, 623 or desirable. Nevertheless it is REQUIRED that the data exchanged 624 with the AS is encrypted and integrity protected. It is furthermore 625 REQUIRED that the AS and the endpoint communicating with it (client 626 or RS) perform mutual authentication. 628 Profiles are expected to specify the details of how this is done, 629 depending e.g. on the communication protocol and the credentials used 630 by the client or the RS. 632 In OAuth 2.0 the communication with the Token and the Introspection 633 endpoints at the AS is assumed to be via HTTP and may use Uri-query 634 parameters. This framework RECOMMENDS to use CoAP instead and 635 RECOMMENDS the use of the following alternative instead of Uri-query 636 parameters: The sender (client or RS) encodes the parameters of its 637 request as a CBOR map and submits that map as the payload of the POST 638 request. The Content-format depends on the security applied to the 639 content and must be specified by the corresponding profile. 641 The OAuth 2.0 AS uses a JSON structure in the payload of its 642 responses both to client and RS. This framework RECOMMENDS the use 643 of CBOR [RFC7049] instead. The requesting device can explicitly 644 request this encoding by setting the CoAP Accept option in the 645 request to "application/cbor". Depending on the profile, the content 646 may arrive in a different format wrapping a CBOR payload. 648 6. The 'Token' Endpoint 650 In plain OAuth 2.0 the AS provides the /token endpoint for submitting 651 access token requests. This framework extends the functionality of 652 the /token endpoint, giving the AS the possibility to help client and 653 RS to establish shared keys or to exchange their public keys. 654 Furthermore this framework defines encodings using CoAP and CBOR, 655 instead of HTTP and JSON. 657 Communication between the client and the /token endpoint at the AS 658 MUST be integrity protected and encrypted. Furthermore AS and client 659 MUST perform mutual authentication. Profiles of this framework are 660 expected to specify how authentication and communication security is 661 implemented. 663 The figures of this section uses CBOR diagnostic notation without the 664 integer abbreviations for the parameters or their values for better 665 readability. 667 6.1. Client-to-AS Request 669 The client sends a CoAP POST request to the token endpoint at the AS, 670 the profile is expected to specify the Content-Type and wrapping of 671 the payload. The content of the request consists of the parameters 672 specified in section 4 of the OAuth 2.0 specification [RFC6749] 673 encoded as a CBOR map. 675 In addition to these parameters, this framework defines the following 676 parameters for requesting an access token from a /token endpoint: 678 aud 679 OPTIONAL. Specifies the audience for which the client is 680 requesting an access token. If this parameter is missing it is 681 assumed that the client and the AS have a pre-established 682 understanding of the audience that an access token should address. 683 If a client submits a request for an access token without 684 specifying an "aud" parameter, and the AS does not have a default 685 "aud" value for this client, then the AS MUST respond with an 686 error message with the CoAP response code 4.00 (Bad Request). 688 cnf 689 OPTIONAL. This field contains information about the key the 690 client would like to bind to the access token for proof-of- 691 possession. It is NOT RECOMMENDED that a client submits a 692 symmetric key value to the AS using this parameter. See 693 Section 6.4.5 for more details on the formatting of the 'cnf' 694 parameter. 696 The following examples illustrate different types of requests for 697 proof-of-possession tokens. 699 Figure 2 shows a request for a token with a symmetric proof-of- 700 possession key. Note that in this example we assume a DTLS-based 701 communication security profile, therefore the Content-Type is 702 "application/cbor". 704 Header: POST (Code=0.02) 705 Uri-Host: "server.example.com" 706 Uri-Path: "token" 707 Content-Type: "application/cbor" 708 Payload: 709 { 710 "grant_type" : "client_credentials", 711 "aud" : "tempSensor4711", 712 } 714 Figure 2: Example request for an access token bound to a symmetric 715 key. 717 Figure 3 shows a request for a token with an asymmetric proof-of- 718 possession key. Note that in this example we assume an object 719 security-based profile, therefore the Content-Type is "application/ 720 cose+cbor". 722 Header: POST (Code=0.02) 723 Uri-Host: "server.example.com" 724 Uri-Path: "token" 725 Content-Type: "application/cose+cbor" 726 Payload: 727 { 728 "grant_type" : "client_credentials", 729 "cnf" : { 730 "COSE_Key" : { 731 "kty" : "EC", 732 "kid" : h'11', 733 "crv" : "P-256", 734 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 735 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 736 } 737 } 738 } 740 Figure 3: Example request for an access token bound to an asymmetric 741 key. 743 Figure 4 shows a request for a token where a previously communicated 744 proof-of-possession key is only referenced. Note that we assume a 745 DTLS-based communication security profile for this example, therefore 746 the Content-Type is "application/cbor". Also note that the client 747 performs a password based authentication in this example by 748 submitting its client_secret (see section 2.3.1. of [RFC6749]). 750 Header: POST (Code=0.02) 751 Uri-Host: "server.example.com" 752 Uri-Path: "token" 753 Content-Type: "application/cbor" 754 Payload: 755 { 756 "grant_type" : "client_credentials", 757 "client_id" : "myclient", 758 "client_secret" : "mysecret234", 759 "aud" : "valve424", 760 "scope" : "read", 761 "cnf" : { 762 "kid" : b64'6kg0dXJM13U' 763 } 764 } 766 Figure 4: Example request for an access token bound to a key 767 reference. 769 6.2. AS-to-Client Response 771 If the access token request has been successfully verified by the AS 772 and the client is authorized to obtain an access token corresponding 773 to its access token request, the AS sends a response with the CoAP 774 response code 2.01 (Created). If client request was invalid, or not 775 authorized, the AS returns an error response as described in 776 Section 6.3. 778 Note that the AS decides which token type and profile to use when 779 issuing a successful response. It is assumed that the AS has prior 780 knowledge of the capabilities of the client, and the RS. This prior 781 knowledge may, for example, be set by the use of a dynamic client 782 registration protocol exchange [RFC7591]. 784 The content of the successful reply MUST be encoded as CBOR map, 785 containing parameters as speficied in section 5.1 of [RFC6749]. In 786 addition to these parameters, the following parameters are also part 787 of a successful response: 789 profile 790 REQUIRED. This indicates the profile that the client MUST use 791 towards the RS. See Section 6.4.4 for the formatting of this 792 parameter. 794 cnf 795 REQUIRED if the token type is 'pop'. OPTIONAL otherwise. If a 796 symmetric proof-of-possession algorithms was selected, this field 797 contains the proof-of-possession key. If an asymmetric algorithm 798 was selected, this field contains information about the public key 799 used by the RS to authenticate. See Section 6.4.5 for the 800 formatting of this parameter. 801 token_type 802 OPTIONAL. By default implementations of this framework SHOULD 803 assume that the token_type is 'pop'. If a specific use case 804 requires another token_type (e.g. 'Bearer') to be used then this 805 parameter is REQUIRED. 807 Note that if CBOR Web Tokens [I-D.ietf-ace-cbor-web-token] are used, 808 the access token can also contain a 'cnf' claim. This claim is 809 however consumed by a different party. The access token is created 810 by the AS and processed by the RS (and opaque to the client) whereas 811 the RS Information is created by the AS and processed by the client; 812 it is never forwarded to the resource server. 814 The following examples illustrate different types of responses for 815 proof-of-possession tokens. 817 Figure 5 shows a response containing a token and a 'cnf' parameter 818 with a symmetric proof-of-possession key. Note that we assume a 819 DTLS-based communication security profile for this example, therefore 820 the Content-Type is "application/cbor". 822 Header: Created (Code=2.01) 823 Content-Type: "application/cbor" 824 Payload: 825 { 826 "access_token" : b64'SlAV32hkKG ... 827 (remainder of CWT omitted for brevity; 828 CWT contains COSE_Key in the 'cnf' claim)', 829 "profile" : "coap_dtls", 830 "expires_in" : "3600", 831 "cnf" : { 832 "COSE_Key" : { 833 "kty" : "Symmetric", 834 "kid" : b64'39Gqlw', 835 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 836 } 837 } 838 } 840 Figure 5: Example AS response with an access token bound to a 841 symmetric key. 843 6.3. Error Response 845 The error responses for CoAP-based interactions with the AS are 846 equivalent to the ones for HTTP-based interactions as defined in 847 section 5.2 of [RFC6749], with the following differences: The 848 Content-Type is specified by the communication security profile used 849 between client and AS. The raw payload before being processed by the 850 communication security protocol MUST be encoded as a CBOR map and the 851 CoAP response code 4.00 (Bad Request) MUST be used unless specified 852 otherwise. 854 6.4. New Request and Response Parameters 856 This section provides more detail about the new parameters that can 857 be used in access token requests and responses, as well as 858 abbreviations for more compact encoding of existing parameters and 859 common parameter values. 861 6.4.1. Audience 863 This parameter specifies for which audience the client is requesting 864 a token. It should be encoded as CBOR text string (major type 3). 865 The formatting and semantics of these strings are application 866 specific. 868 6.4.2. Grant Type 870 The abbreviations in Figure 6 MAY be used in CBOR encodings instead 871 of the string values defined in [RFC6749]. 873 /--------------------+----------+--------------\ 874 | grant_type | CBOR Key | Major Type | 875 |--------------------+----------+--------------| 876 | password | 0 | 0 (uint) | 877 | authorization_code | 1 | 0 | 878 | client_credentials | 2 | 0 | 879 | refresh_token | 3 | 0 | 880 \--------------------+----------+--------------/ 882 Figure 6: CBOR abbreviations for common grant types 884 6.4.3. Token Type 886 The 'token_type' parameter allows the AS to indicate to the client 887 which type of access token it is receiving (e.g. a bearer token). 888 The 'pop' token type MUST be assumed by default if the AS does not 889 provide a different value. 891 This document registers the new value "pop" for the OAuth Access 892 Token Types registry, specifying a Proof-of-Possession token. How 893 the proof-of-possession is performed is specified by the profiles. 895 The values in the 'token_type' parameter are CBOR text strings (major 896 type 3). 898 6.4.4. Profile 900 Profiles of this framework are expected to define the communication 901 protocol and the communication security protocol between the client 902 and the RS. Furthermore profiles are expected to define proof-of- 903 possession methods, if they support proof-of-possession tokens. 905 A profile should specify an identifier that is used to uniquely 906 identify itself in the 'profile' parameter. 908 Profiles MAY define additional parameters for both the token request 909 and the RS Information in the access token response in order to 910 support negotioation or signalling of profile specific parameters. 912 6.4.5. Confirmation 914 The "cnf" parameter identifies or provides the key used for proof-of- 915 possession or for authenticating the RS depending on the proof-of- 916 possession algorithm and the context cnf is used in. This framework 917 extends the definition of 'cnf' from [RFC7800] by adding CBOR/COSE 918 encodings and the use of 'cnf' for transporting keys in the RS 919 Information. 921 The "cnf" parameter is used in the following contexts with the 922 following meaning: 924 o In the access token, to indicate the proof-of-possession key bound 925 to this token. 926 o In the token request C -> AS, to indicate the client's raw public 927 key, or the key-identifier of a previously established key between 928 C and RS. 929 o In the token response AS -> C, to indicate either the symmetric 930 key generated by the AS for proof-of-possession or the raw public 931 key used by the RS to authenticate. 932 o In the introspection response AS -> RS, to indicate the proof-of- 933 possession key bound to the introspected token. 934 o In the client token AS -> RS -> C, to indicate the proof-of- 935 possession key bound to the access token. 937 A CBOR encoded payload MAY contain the 'cnf' parameter with the 938 following contents: 940 COSE_Key In this case the 'cnf' parameter contains the proof-of- 941 possession key to be used by the client. An example is shown in 942 Figure 7. 944 "cnf" : { 945 "COSE_Key" : { 946 "kty" : "EC", 947 "kid" : h'11', 948 "crv" : "P-256", 949 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 950 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 951 } 952 } 954 Figure 7: Confirmation parameter containing a public key 956 Note that the COSE_Key structure may contain an "alg" or "key_ops" 957 parameter. If such parameters are present, a client MUST NOT use 958 a key that is not compatible with the profile or proof-of- 959 possession algorithm according to those parameters. 960 COSE_Encrypted In this case the 'cnf' parameter contains an 961 encrypted symmetric key destined for the client. The client is 962 assumed to be able to decrypt the cihpertext of this parameter. 963 The parameter is encoded as COSE_Encrypted object wrapping a 964 COSE_Key object. Figure 8 shows an example of this type of 965 encoding. 967 "cnf" : { 968 "COSE_Encrypted" : { 969 993( 970 [ h'a1010a' # protected header : {"alg" : "AES-CCM-16-64-128"} 971 "iv" : b64'ifUvZaHFgJM7UmGnjA', # unprotected header 972 b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext 973 ] 974 ) 975 } 976 } 978 Figure 8: Confirmation paramter containing an encrypted symmetric key 980 The ciphertext here could e.g. contain a symmetric key as in 981 Figure 9. 983 { 984 "kty" : "Symmetric", 985 "kid" : b64'39Gqlw', 986 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 987 } 989 Figure 9: Example plaintext of an encrypted cnf parameter 991 Key Identifier In this case the 'cnf' parameter references a key 992 that is assumed to be previously known by the recipient. This 993 allows clients that perform repeated requests for an access token 994 for the same audience but e.g. with different scopes to omit key 995 transport in the access token, token request and token response. 996 Figure 10 shows such an example. 998 "cnf" : { 999 "kid" : b64'39Gqlw' 1000 } 1002 Figure 10: A Confirmation parameter with just a key identifier 1004 6.5. Mapping parameters to CBOR 1006 All OAuth parameters in access token requests and responses are 1007 mapped to CBOR types as follows and are given an integer key value to 1008 save space. 1010 /-------------------+----------+-----------------\ 1011 | Parameter name | CBOR Key | Major Type | 1012 |-------------------+----------+-----------------| 1013 | aud | 3 | 3 | 1014 | client_id | 8 | 3 (text string) | 1015 | client_secret | 9 | 2 (byte string) | 1016 | response_type | 10 | 3 | 1017 | redirect_uri | 11 | 3 | 1018 | scope | 12 | 3 | 1019 | state | 13 | 3 | 1020 | code | 14 | 2 | 1021 | error_description | 15 | 3 | 1022 | error_uri | 16 | 3 | 1023 | grant_type | 17 | 0 (unit) | 1024 | access_token | 18 | 3 | 1025 | token_type | 19 | 0 | 1026 | expires_in | 20 | 0 | 1027 | username | 21 | 3 | 1028 | password | 22 | 3 | 1029 | refresh_token | 23 | 3 | 1030 | cnf | 24 | 5 (map) | 1031 | profile | 25 | 3 | 1032 \-------------------+----------+-----------------/ 1034 Figure 11: CBOR mappings used in token requests 1036 7. The 'Introspect' Endpoint 1038 Token introspection [RFC7662] is used by the RS and potentially the 1039 client to query the AS for metadata about a given token e.g. validity 1040 or scope. Analogous to the protocol defined in RFC 7662 [RFC7662] 1041 for HTTP and JSON, this section defines adaptations to more 1042 constrained environments using CoAP and CBOR. 1044 Communication between the RS and the introspection endpoint at the AS 1045 MUST be integrity protected and encrypted. Furthermore AS and RS 1046 MUST perform mutual authentication. Finally the AS SHOULD verify 1047 that the RS has the right to access introspection information about 1048 the provided token. Profiles of this framework are expected to 1049 specify how authentication and communication security is implemented. 1051 The figures of this section uses CBOR diagnostic notation without the 1052 integer abbreviations for the parameters or their values for better 1053 readability. 1055 7.1. RS-to-AS Request 1057 The RS sends a CoAP POST request to the introspection endpoint at the 1058 AS, the profile is expected to specify the Content-Type and wrapping 1059 of the payload. The payload MUST be encoded as a CBOR map with a 1060 'token' parameter containing the access token along with optional 1061 parameters representing additional context that is known by the RS to 1062 aid the AS in its response. 1064 The same parameters are required and optional as in section 2.1 of 1065 RFC 7662 [RFC7662]. 1067 For example, Figure 12 shows a RS calling the token introspection 1068 endpoint at the AS to query about an OAuth 2.0 proof-of-possession 1069 token. Note that we assume a object security-based communication 1070 security profile for this example, therefore the Content-Type is 1071 "application/cose+cbor". 1073 Header: POST (Code=0.02) 1074 Uri-Host: "server.example.com" 1075 Uri-Path: "introspect" 1076 Content-Type: "application/cose+cbor" 1077 Payload: 1078 { 1079 "token" : b64'7gj0dXJQ43U', 1080 "token_type_hint" : "pop" 1081 } 1083 Figure 12: Example introspection request. 1085 7.2. AS-to-RS Response 1087 If the introspection request is authorized and successfully 1088 processed, the AS sends a response with the CoAP response code 2.01 1089 (Created). If the introspection request was invalid, not authorized 1090 or couldn't be processed the AS returns an error response as 1091 described in Section 7.3. 1093 In a successful response, the AS encodes the response parameters in a 1094 CBOR map including with the same required and optional parameters as 1095 in section 2.2. of RFC 7662 [RFC7662] with the following additions: 1097 cnf 1098 OPTIONAL. This field contains information about the proof-of- 1099 possession key that binds the client to the access token. See 1100 Section 6.4.5 for more details on the formatting of the 'cnf' 1101 parameter. 1103 profile 1104 OPTIONAL. This indicates the profile that the RS MUST use with 1105 the client. See Section 6.4.4 for more details on the formatting 1106 of this parameter. 1108 client_token 1109 OPTIONAL. This parameter contains information that the RS MUST 1110 pass on to the client. See Section 7.4 for more details. 1112 For example, Figure 13 shows an AS response to the introspection 1113 request in Figure 12. Note that we assume a DTLS-based communication 1114 security profile for this example, therefore the Content-Type is 1115 "application/cbor". 1117 Header: Created Code=2.01) 1118 Content-Type: "application/cbor" 1119 Payload: 1120 { 1121 "active" : true, 1122 "scope" : "read", 1123 "profile" : "coap_dtls", 1124 "client_token" : b64'2QPhg0OhAQo ... 1125 (remainder of client token omitted for brevity)', 1126 "cnf" : { 1127 "COSE_Key" : { 1128 "kty" : "Symmetric", 1129 "kid" : b64'39Gqlw', 1130 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1131 } 1132 } 1133 } 1135 Figure 13: Example introspection response. 1137 7.3. Error Response 1139 The error responses for CoAP-based interactions with the AS are 1140 equivalent to the ones for HTTP-based interactions as defined in 1141 section 2.3 of [RFC7662], with the following differences: 1143 o If content is sent, the Content-Type MUST be set according to the 1144 specification of the communication security profile, and the 1145 content payload MUST be encoded as a CBOR map. 1146 o If the credentials used by the RS are invalid the AS MUST respond 1147 with the CoAP response code 4.01 (Unauthorized) and use the 1148 required and optional parameters from section 5.2 in RFC 6749 1149 [RFC6749]. 1151 o If the RS does not have the right to perform this introspection 1152 request, the AS MUST respond with the CoAP response code 4.03 1153 (Forbidden). In this case no payload is returned. 1155 Note that a properly formed and authorized query for an inactive or 1156 otherwise invalid token does not warrant an error response by this 1157 specification. In these cases, the authorization server MUST instead 1158 respond with an introspection response with the "active" field set to 1159 "false". 1161 7.4. Client Token 1163 EDITORIAL NOTE: We have tentatively introduced this concept and would 1164 specifically like feedback whether this is viewed as a useful 1165 addition to the framework. 1167 In cases where the client has limited connectivity and needs to get 1168 access to a previously unknown resource servers, this framework 1169 suggests the following approach: The client is pre-configured with a 1170 generic, long-term access token when it is commissioned. When the 1171 client then tries to access a RS it transmits this access token. The 1172 RS then performs token introspection to learn what access this token 1173 grants. In the introspection response, the AS also relays 1174 information for the client, such as the proof-of-possession key, 1175 through the RS. The RS passes on this Client Token to the client in 1176 response to the submission of the token. 1178 The client_token parameter is designed to carry such information, and 1179 is intended to be used as described in Figure 14. 1181 Resource Authorization 1182 Client Server Server 1183 | | | 1184 | | | 1185 C: +--------------->| | 1186 | POST | | 1187 | Access Token | | 1188 | D: +--------------->| 1189 | | Introspection | 1190 | | Request | 1191 | | | 1192 | E: +<---------------+ 1193 | | Introspection | 1194 | | Response | 1195 | | + Client Token | 1196 |<---------------+ | 1197 | 2.01 Created | | 1198 | + Client Token | 1200 Figure 14: Use of the client_token parameter. 1202 The client token is a COSE_Encrypted object, containing as payload a 1203 CBOR map with the following claims: 1205 cnf 1206 REQUIRED if the token type is 'pop', OPTIONAL otherwise. Contains 1207 information about the proof-of-possession key the client is to use 1208 with its access token. See Section 6.4.5. 1210 token_type 1211 OPTIONAL. See Section 6.4.3. 1213 profile 1214 REQUIRED. See Section 6.4.4. 1216 rs_cnf 1217 OPTIONAL. Contains information about the key that the RS uses to 1218 authenticate towards the client. If the key is symmetric then 1219 this claim MUST NOT be part of the Client Token, since this is the 1220 same key as the one specified through the 'cnf' claim. This claim 1221 uses the same encoding as the 'cnf' parameter. See Section 6.4.4. 1223 The AS encrypts this token using a key shared between the AS and the 1224 client, so that only the client can decrypt it and access its 1225 payload. How this key is established is out of scope of this 1226 framework. 1228 7.5. Mapping Introspection parameters to CBOR 1230 The introspection request and response parameters are mapped to CBOR 1231 types as follows and are given an integer key value to save space. 1233 /-----------------+----------+-----------------\ 1234 | Parameter name | CBOR Key | Major Type | 1235 |-----------------+----------+-----------------| 1236 | iss | 1 | 3 (text string) | 1237 | sub | 2 | 3 | 1238 | aud | 3 | 3 | 1239 | exp | 4 | 6 tag value 1 | 1240 | nbf | 5 | 6 tag value 1 | 1241 | iat | 6 | 6 tag value 1 | 1242 | cti | 7 | 2 (byte string) | 1243 | client_id | 8 | 3 | 1244 | scope | 12 | 3 | 1245 | token_type | 19 | 3 | 1246 | username | 21 | 3 | 1247 | cnf | 24 | 5 (map) | 1248 | profile | 25 | 0 (uint) | 1249 | token | 26 | 3 | 1250 | token_type_hint | 27 | 3 | 1251 | active | 28 | 0 | 1252 | client_token | 29 | 3 | 1253 | rs_cnf | 30 | 5 | 1254 \-----------------+----------+-----------------/ 1256 Figure 15: CBOR Mappings to Token Introspection Parameters. 1258 8. The Access Token 1260 This framework RECOMMENDS the use of CBOR web token (CWT) as 1261 specified in [I-D.ietf-ace-cbor-web-token]. 1263 In order to facilitate offline processing of access tokens, this 1264 draft specifies the "cnf" and "scope" claims for CBOR web tokens. 1266 The "scope" claim explicitly encodes the scope of a given access 1267 token. This claim follows the same encoding rules as defined in 1268 section 3.3 of [RFC6749]. The meaning of a specific scope value is 1269 application specific and expected to be known to the RS running that 1270 application. 1272 The "cnf" claim follows the same rules as specified for JSON web 1273 token in RFC7800 [RFC7800], except that it is encoded in CBOR in the 1274 same way as specified for the "cnf" parameter in Section 6.4.5. 1276 8.1. The 'Authorization Information' Endpoint 1278 The access token, containing authorization information and 1279 information of the key used by the client, needs to be transported to 1280 the RS so that the RS can authenticate and authorize the client 1281 request. 1283 This section defines a method for transporting the access token to 1284 the RS using CoAP. Profiles of this framework MAY define other 1285 methods for token transport. Implementations conforming to this 1286 framework MUST implement this method of token transportation. 1288 The method consists of a /authz-info endpoint, implemented by the RS. 1289 A client using this method MUST make a POST request to /authz-info at 1290 the RS with the access token in the payload. The RS receiving the 1291 token MUST verify the validity of the token. If the token is valid, 1292 the RS MUST respond to the POST request with 2.04 (Changed). 1294 If the token is not valid, the RS MUST respond with the CoAP response 1295 code 4.01 (Unauthorized). If the token is valid but the audience of 1296 the token does not match the RS, the RS MUST respond with the CoAP 1297 response code 4.03 (Forbidden). 1299 The RS MAY make an introspection request to validate the token before 1300 responding to the POST /authz-info request. If the introspection 1301 response contains a client token (Section 7.4) then this token SHALL 1302 be included in the payload of the 2.04 (Changed) response. 1304 Profiles are expected to specify how the /authz-info endpoint is 1305 protected. Note that since the token contains information that allow 1306 the client and the RS to establish a security context in the first 1307 place, mutual authentication may not be possible at this point. 1309 8.2. Token Expiration 1311 Depending on the capabilities of the RS, there are various ways in 1312 which it can verify the validity of a received access token. We list 1313 the possibilities here including what functionality they require of 1314 the RS. 1316 o The token is a CWT/JWT and includes a 'exp' claim and possibly the 1317 'nbf' claim. The RS verifies these by comparing them to values 1318 from its internal clock as defined in [RFC7519]. In this case the 1319 RS's internal clock must reflect the current date and time, or at 1320 least be synchronized with the AS's clock. How this clock 1321 synchronization would be performed is out of scope for this memo. 1322 o The RS verifies the validity of the token by performing an 1323 introspection request as specified in Section 7. This requires 1324 the RS to have a reliable network connection to the AS and to be 1325 able to handle two secure sessions in parallel (C to RS and AS to 1326 RS). 1327 o The RS and the AS both store a sequence number linked to their 1328 common security association. The AS increments this number for 1329 each access token it issues and includes it in the access token, 1330 which is a CWT/JWT. The RS keeps track of the most recently 1331 received sequence number, and only accepts tokens as valid, that 1332 are in a certain range around this number. This method does only 1333 require the RS to keep track of the sequence number. The method 1334 does not provide timely expiration, but it makes sure that older 1335 tokens cease to be valid after a certain number of newer ones got 1336 issued. For a constrained RS with no network connectivity and no 1337 means of reliably measuring time, this is the best that can be 1338 achieved. 1340 9. Security Considerations 1342 The entire document is about security. Security considerations 1343 applicable to authentication and authorization in RESTful 1344 environments provided in OAuth 2.0 [RFC6749] apply to this work, as 1345 well as the security considerations from [I-D.ietf-ace-actors]. 1346 Furthermore [RFC6819] provides additional security considerations for 1347 OAuth which apply to IoT deployments as well. 1349 A large range of threats can be mitigated by protecting the contents 1350 of the access token by using a digital signature or a keyed message 1351 digest. Consequently, the token integrity protection MUST be applied 1352 to prevent the token from being modified, particularly since it 1353 contains a reference to the symmetric key or the asymmetric key. If 1354 the access token contains the symmetric key, this symmetric key MUST 1355 be encrypted by the authorization server with a long-term key shared 1356 with the resource server. 1358 It is important for the authorization server to include the identity 1359 of the intended recipient (the audience), typically a single resource 1360 server (or a list of resource servers), in the token. Using a single 1361 shared secret with multiple resource servers to simplify key 1362 management is NOT RECOMMENDED since the benefit from using the proof- 1363 of-possession concept is significantly reduced. 1365 Token replay is also not possible since an eavesdropper will also 1366 have to obtain the corresponding private key or shared secret that is 1367 bound to the access token. Nevertheless, it is good practice to 1368 limit the lifetime of the access token and therefore the lifetime of 1369 associated key. 1371 The authorization server MUST offer confidentiality protection for 1372 any interactions with the client. This step is extremely important 1373 since the client will obtain the session key from the authorization 1374 server for use with a specific access token. Not using 1375 confidentiality protection exposes this secret (and the access token) 1376 to an eavesdropper thereby making the proof-of-possession security 1377 model completely insecure. This framework relies on profiles to 1378 define how confidentiality protection is provided, and additional 1379 protection can be applied by encrypting the CWT as specified in 1380 section 5.1 of [I-D.ietf-ace-cbor-web-token] to provide an additional 1381 layer of protection for cases where keying material is conveyed, for 1382 example, to a hardware security module. 1384 Developers MUST ensure that the ephemeral credentials (i.e., the 1385 private key or the session key) is not leaked to third parties. An 1386 adversary in possession of the ephemeral credentials bound to the 1387 access token will be able to impersonate the client. Be aware that 1388 this is a real risk with many constrained environments, since 1389 adversaries can often easily get physical access to the devices. 1391 Clients can at any time request a new proof-of-possession capable 1392 access token. Using a refresh token to regularly request new access 1393 tokens that are bound to fresh and unique keys is important if the 1394 client has this capability. Keeping the lifetime of the access token 1395 short allows the authorization server to use shorter key sizes, which 1396 translate to a performance benefit for the client and for the 1397 resource server. Shorter keys also lead to shorter messages 1398 (particularly with asymmetric keying material). 1400 When authorization servers bind symmetric keys to access tokens then 1401 they SHOULD scope these access tokens to a specific permissions. 1403 10. IANA Considerations 1405 This specification registers new parameters for OAuth and establishes 1406 registries for mappings to CBOR. 1408 10.1. OAuth Introspection Response Parameter Registration 1410 This specification registers the following parameters in the OAuth 1411 introspection response parameters 1413 o Name: "cnf" 1414 o Description: Key to prove the right to use an access token, as 1415 defined in [RFC7800]. 1416 o Change Controller: IESG 1417 o Specification Document(s): this document 1418 o Name: "aud" 1419 o Description: Reference to intended receiving RS, as defined in PoP 1420 token specification. 1421 o Change Controller: IESG 1422 o Specification Document(s): this document 1424 o Name: "profile" 1425 o Description: The communication and communication security profile 1426 used between client and RS, as defined in ACE profiles. 1427 o Change Controller: IESG 1428 o Specification Document(s): this document 1430 o Name: "client_token" 1431 o Description: Information that the RS MUST pass to the client e.g. 1432 about the proof-of-possession keys. 1433 o Change Controller: IESG 1434 o Specification Document(s): this document 1436 o Name: "rs_cnf" 1437 o Description: Describes the public key the RS uses to authenticate. 1438 o Change Controller: IESG 1439 o Specification Document(s): this document 1441 10.2. OAuth Parameter Registration 1443 This specification registers the following parameters in the OAuth 1444 Parameters Registry 1446 o Parameter name: "profile" 1447 o Parameter usage location: token request, and token response 1448 o Change Controller: IESG 1449 o Specification Document(s): this document 1451 o Name: "cnf" 1452 o Description: Key to prove the right to use an access token, as 1453 defined in [RFC7800]. 1454 o Change Controller: IESG 1455 o Specification Document(s): this document 1457 10.3. OAuth Access Token Types 1459 This specification registers the following new token type in the 1460 OAuth Access Token Types Registry 1462 o Name: "PoP" 1463 o Description: A proof-of-possession token. 1464 o Change Controller: IESG 1465 o Specification Document(s): this document 1467 10.4. Token Type Mappings 1469 A new registry will be requested from IANA, entitled "Token Type 1470 Mappings". The registry is to be created as Expert Review Required. 1472 10.4.1. Registration Template 1474 Token Type: 1475 Name of token type as registered in the OAuth token type registry 1476 e.g. "Bearer". 1477 Mapped value: 1478 Integer representation for the token type value. The key value 1479 MUST be an integer in the range of 1 to 65536. 1480 Change Controller: 1481 For Standards Track RFCs, list the "IESG". For others, give the 1482 name of the responsible party. Other details (e.g., postal 1483 address, email address, home page URI) may also be included. 1484 Specification Document(s): 1485 Reference to the document or documents that specify the 1486 parameter,preferably including URIs that can be used to retrieve 1487 copies of the documents. An indication of the relevant sections 1488 may also be included but is not required. 1490 10.4.2. Initial Registry Contents 1492 o Parameter name: "Bearer" 1493 o Mapped value: 1 1494 o Change Controller: IESG 1495 o Specification Document(s): this document 1497 o Parameter name: "pop" 1498 o Mapped value: 2 1499 o Change Controller: IESG 1500 o Specification Document(s): this document 1502 10.5. CBOR Web Token Claims 1504 This specification registers the following new claims in the CBOR Web 1505 Token (CWT) registry: 1507 o Claim Name: "scope" 1508 o Claim Description: The scope of an access token as defined in 1509 [RFC6749]. 1510 o Change Controller: IESG 1511 o Specification Document(s): this document 1513 o Claim Name: "cnf" 1514 o Claim Description: The proof-of-possession key of an access token 1515 as defined in [RFC7800]. 1516 o Change Controller: IESG 1517 o Specification Document(s): this document 1519 10.6. ACE Profile Registry 1521 A new registry will be requested from IANA, entitled "ACE Profile 1522 Registry". The registry is to be created as Expert Review Required. 1524 10.6.1. Registration Template 1526 Profile name: 1527 Name of the profile to be included in the profile attribute. 1528 Profile description: 1529 Text giving an overview of the profile and the context it is 1530 developed for. 1531 Profile ID: 1532 Integer value to identify the profile. The value MUST be an 1533 integer in the range of 1 to 65536. 1534 Change Controller: 1535 For Standards Track RFCs, list the "IESG". For others, give the 1536 name of the responsible party. Other details (e.g., postal 1537 address, email address, home page URI) may also be included. 1538 Specification Document(s): 1539 Reference to the document or documents that specify the 1540 parameter,preferably including URIs that can be used to retrieve 1541 copies of the documents. An indication of the relevant sections 1542 may also be included but is not required. 1544 10.7. OAuth Parameter Mappings Registry 1546 A new registry will be requested from IANA, entitled "Token Endpoint 1547 CBOR Mappings Registry". The registry is to be created as Expert 1548 Review Required. 1550 10.7.1. Registration Template 1552 Parameter name: 1553 OAuth Parameter name, refers to the name in the OAuth parameter 1554 registry e.g. "client_id". 1555 CBOR key value: 1556 Key value for the claim. The key value MUST be an integer in the 1557 range of 1 to 65536. 1558 Change Controller: 1559 For Standards Track RFCs, list the "IESG". For others, give the 1560 name of the responsible party. Other details (e.g., postal 1561 address, email address, home page URI) may also be included. 1563 Specification Document(s): 1564 Reference to the document or documents that specify the 1565 parameter,preferably including URIs that can be used to retrieve 1566 copies of the documents. An indication of the relevant sections 1567 may also be included but is not required. 1569 10.7.2. Initial Registry Contents 1571 o Parameter name: "aud" 1572 o CBOR key value: 3 1573 o Change Controller: IESG 1574 o Specification Document(s): this document 1576 o Parameter name: "client_id" 1577 o CBOR key value: 8 1578 o Change Controller: IESG 1579 o Specification Document(s): this document 1581 o Parameter name: "client_secret" 1582 o CBOR key value: 9 1583 o Change Controller: IESG 1584 o Specification Document(s): this document 1586 o Parameter name: "response_type" 1587 o CBOR key value: 10 1588 o Change Controller: IESG 1589 o Specification Document(s): this document 1591 o Parameter name: "redirect_uri" 1592 o CBOR key value: 11 1593 o Change Controller: IESG 1594 o Specification Document(s): this document 1596 o Parameter name: "scope" 1597 o CBOR key value: 12 1598 o Change Controller: IESG 1599 o Specification Document(s): this document 1601 o Parameter name: "state" 1602 o CBOR key value: 13 1603 o Change Controller: IESG 1604 o Specification Document(s): this document 1606 o Parameter name: "code" 1607 o CBOR key value: 14 1608 o Change Controller: IESG 1609 o Specification Document(s): this document 1610 o Parameter name: "error_description" 1611 o CBOR key value: 15 1612 o Change Controller: IESG 1613 o Specification Document(s): this document 1615 o Parameter name: "error_uri" 1616 o CBOR key value: 16 1617 o Change Controller: IESG 1618 o Specification Document(s): this document 1620 o Parameter name: "grant_type" 1621 o CBOR key value: 17 1622 o Change Controller: IESG 1623 o Specification Document(s): this document 1625 o Parameter name: "access_token" 1626 o CBOR key value: 18 1627 o Change Controller: IESG 1628 o Specification Document(s): this document 1630 o Parameter name: "token_type" 1631 o CBOR key value: 19 1632 o Change Controller: IESG 1633 o Specification Document(s): this document 1635 o Parameter name: "expires_in" 1636 o CBOR key value: 20 1637 o Change Controller: IESG 1638 o Specification Document(s): this document 1640 o Parameter name: "username" 1641 o CBOR key value: 21 1642 o Change Controller: IESG 1643 o Specification Document(s): this document 1645 o Parameter name: "password" 1646 o CBOR key value: 22 1647 o Change Controller: IESG 1648 o Specification Document(s): this document 1650 o Parameter name: "refresh_token" 1651 o CBOR key value: 23 1652 o Change Controller: IESG 1653 o Specification Document(s): this document 1655 o Parameter name: "cnf" 1656 o CBOR key value: 24 1657 o Change Controller: IESG 1658 o Specification Document(s): this document 1660 o Parameter name: "profile" 1661 o CBOR key value: 25 1662 o Change Controller: IESG 1663 o Specification Document(s): this document 1665 10.8. Introspection Endpoint CBOR Mappings Registry 1667 A new registry will be requested from IANA, entitled "Introspection 1668 Endpoint CBOR Mappings Registry". The registry is to be created as 1669 Expert Review Required. 1671 10.8.1. Registration Template 1673 Response parameter name: 1674 Name of the response parameter as defined in the "OAuth Token 1675 Introspection Response" registry e.g. "active". 1676 CBOR key value: 1677 Key value for the claim. The key value MUST be an integer in the 1678 range of 1 to 65536. 1679 Change Controller: 1680 For Standards Track RFCs, list the "IESG". For others, give the 1681 name of the responsible party. Other details (e.g., postal 1682 address, email address, home page URI) may also be included. 1683 Specification Document(s): 1684 Reference to the document or documents that specify the 1685 parameter,preferably including URIs that can be used to retrieve 1686 copies of the documents. An indication of the relevant sections 1687 may also be included but is not required. 1689 10.8.2. Initial Registry Contents 1691 o Response parameter name: "iss" 1692 o CBOR key value: 1 1693 o Change Controller: IESG 1694 o Specification Document(s): this document 1696 o Response parameter name: "sub" 1697 o CBOR key value: 2 1698 o Change Controller: IESG 1699 o Specification Document(s): this document 1701 o Response parameter name: "aud" 1702 o CBOR key value: 3 1703 o Change Controller: IESG 1704 o Specification Document(s): this document 1705 o Response parameter name: "exp" 1706 o CBOR key value: 4 1707 o Change Controller: IESG 1708 o Specification Document(s): this document 1710 o Response parameter name: "nbf" 1711 o CBOR key value: 5 1712 o Change Controller: IESG 1713 o Specification Document(s): this document 1715 o Response parameter name: "iat" 1716 o CBOR key value: 6 1717 o Change Controller: IESG 1718 o Specification Document(s): this document 1720 o Response parameter name: "cti" 1721 o CBOR key value: 7 1722 o Change Controller: IESG 1723 o Specification Document(s): this document 1725 o Response parameter name: "client_id" 1726 o CBOR key value: 8 1727 o Change Controller: IESG 1728 o Specification Document(s): this document 1730 o Response parameter name: "scope" 1731 o CBOR key value: 12 1732 o Change Controller: IESG 1733 o Specification Document(s): this document 1735 o Response parameter name: "token_type" 1736 o CBOR key value: 19 1737 o Change Controller: IESG 1738 o Specification Document(s): this document 1740 o Response parameter name: "username" 1741 o CBOR key value: 21 1742 o Change Controller: IESG 1743 o Specification Document(s): this document 1745 o Parameter name: "cnf" 1746 o CBOR key value: 24 1747 o Change Controller: IESG 1748 o Specification Document(s): this document 1750 o Parameter name: "profile" 1751 o CBOR key value: 25 1752 o Change Controller: IESG 1753 o Specification Document(s): this document 1755 o Response parameter name: "token" 1756 o CBOR key value: 26 1757 o Change Controller: IESG 1758 o Specification Document(s): this document 1760 o Response parameter name: "token_type_hint" 1761 o CBOR key value: 27 1762 o Change Controller: IESG 1763 o Specification Document(s): this document 1765 o Response parameter name: "active" 1766 o CBOR key value: 28 1767 o Change Controller: IESG 1768 o Specification Document(s): this document 1770 o Response parameter name: "client_token" 1771 o CBOR key value: 29 1772 o Change Controller: IESG 1773 o Specification Document(s): this document 1775 o Response parameter name: "rs_cnf" 1776 o CBOR key value: 30 1777 o Change Controller: IESG 1778 o Specification Document(s): this document 1780 10.9. CoAP Option Number Registration 1782 This section registers the "Access-Token" CoAP Option Number in the 1783 "CoRE Parameters" sub-registry "CoAP Option Numbers" in the manner 1784 described in [RFC7252]. 1786 Name 1788 Access-Token 1789 Number 1791 TBD 1792 Reference 1794 [This document]. 1795 Meaning in Request 1797 Contains an Access Token according to [This document] containing 1798 access permissions of the client. 1799 Meaning in Response 1800 Not used in response 1801 Safe-to-Forward 1803 Yes 1804 Format 1806 Based on the observer the format is perceived differently. Opaque 1807 data to the client and CWT or reference token to the RS. 1808 Length 1810 Less then 255 bytes 1812 11. Acknowledgments 1814 We would like to thank Eve Maler for her contributions to the use of 1815 OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion 1816 input, and Malisa Vucinic for his input on the ACRE proposal 1817 [I-D.seitz-ace-core-authz] which was one source of inspiration for 1818 this work. Finally, we would like to thank the ACE working group in 1819 general for their feedback. 1821 We would like to thank the authors of draft-ietf-oauth-pop-key- 1822 distribution, from where we copied large parts of our security 1823 considerations. 1825 Ludwig Seitz and Goeran Selander worked on this document as part of 1826 the CelticPlus project CyberWI, with funding from Vinnova. 1828 12. References 1830 12.1. Normative References 1832 [I-D.ietf-ace-cbor-web-token] 1833 Wahlstroem, E., Jones, M., Tschofenig, H., and S. Erdtman, 1834 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-01 1835 (work in progress), July 2016. 1837 [I-D.ietf-cose-msg] 1838 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1839 draft-ietf-cose-msg-23 (work in progress), October 2016. 1841 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1842 Requirement Levels", BCP 14, RFC 2119, 1843 DOI 10.17487/RFC2119, March 1997, 1844 . 1846 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1847 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1848 January 2012, . 1850 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1851 Application Protocol (CoAP)", RFC 7252, 1852 DOI 10.17487/RFC7252, June 2014, 1853 . 1855 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1856 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1857 . 1859 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1860 Possession Key Semantics for JSON Web Tokens (JWTs)", 1861 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1862 . 1864 12.2. Informative References 1866 [I-D.ietf-ace-actors] 1867 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 1868 architecture for authorization in constrained 1869 environments", draft-ietf-ace-actors-04 (work in 1870 progress), September 2016. 1872 [I-D.ietf-oauth-device-flow] 1873 Denniss, W., Myrseth, S., Bradley, J., Jones, M., and H. 1874 Tschofenig, "OAuth 2.0 Device Flow", draft-ietf-oauth- 1875 device-flow-03 (work in progress), July 2016. 1877 [I-D.ietf-oauth-native-apps] 1878 Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 1879 draft-ietf-oauth-native-apps-05 (work in progress), 1880 October 2016. 1882 [I-D.seitz-ace-core-authz] 1883 Seitz, L., Selander, G., and M. Vucinic, "Authorization 1884 for Constrained RESTful Environments", draft-seitz-ace- 1885 core-authz-00 (work in progress), June 2015. 1887 [I-D.selander-ace-object-security] 1888 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1889 "Object Security of CoAP (OSCOAP)", draft-selander-ace- 1890 object-security-06 (work in progress), October 2016. 1892 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1893 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1894 . 1896 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1897 (TLS) Protocol Version 1.2", RFC 5246, 1898 DOI 10.17487/RFC5246, August 2008, 1899 . 1901 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1902 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1903 . 1905 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1906 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1907 . 1909 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 1910 Threat Model and Security Considerations", RFC 6819, 1911 DOI 10.17487/RFC6819, January 2013, 1912 . 1914 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1915 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1916 October 2013, . 1918 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1919 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1920 2014, . 1922 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1923 Constrained-Node Networks", RFC 7228, 1924 DOI 10.17487/RFC7228, May 2014, 1925 . 1927 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1928 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1929 DOI 10.17487/RFC7231, June 2014, 1930 . 1932 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1933 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1934 . 1936 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 1937 "Assertion Framework for OAuth 2.0 Client Authentication 1938 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 1939 May 2015, . 1941 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 1942 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 1943 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1944 . 1946 [RFC7744] Seitz, L., Ed., Gerdes, S., Ed., Selander, G., Mani, M., 1947 and S. Kumar, "Use Cases for Authentication and 1948 Authorization in Constrained Environments", RFC 7744, 1949 DOI 10.17487/RFC7744, January 2016, 1950 . 1952 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1953 the Constrained Application Protocol (CoAP)", RFC 7959, 1954 DOI 10.17487/RFC7959, August 2016, 1955 . 1957 Appendix A. Design Justification 1959 This section provides further insight into the design decisions of 1960 the solution documented in this document. Section 3 lists several 1961 building blocks and briefly summarizes their importance. The 1962 justification for offering some of those building blocks, as opposed 1963 to using OAuth 2.0 as is, is given below. 1965 Common IoT constraints are: 1967 Low Power Radio: 1969 Many IoT devices are equipped with a small battery which needs to 1970 last for a long time. For many constrained wireless devices the 1971 highest energy cost is associated to transmitting or receiving 1972 messages. It is therefore important to keep the total 1973 communication overhead low, including minimizing the number and 1974 size of messages sent and received, which has an impact of choice 1975 on the message format and protocol. By using CoAP over UDP, and 1976 CBOR encoded messages some of these aspects are addressed. 1977 Security protocols contribute to the communication overhead and 1978 can in some cases be optimized. For example authentication and 1979 key establishment may in certain cases where security requirements 1980 so allows be replaced by provisioning of security context by a 1981 trusted third party, using transport or application layer 1982 security. 1984 Low CPU Speed: 1986 Some IoT devices are equipped with processors that are 1987 significantly slower than those found in most current devices on 1988 the Internet. This typically has implications on what timely 1989 cryptographic operations a device is capable to perform, which in 1990 turn impacts e.g. protocol latency. Symmetric key cryptography 1991 may be used instead of the computationally more expensive public 1992 key cryptography where the security requirements so allows, but 1993 this may also require support for trusted third party assisted 1994 secret key establishment using transport or application layer 1995 security. 1997 Small Amount of Memory: 1999 Microcontrollers embedded in IoT devices are often equipped with 2000 small amount of RAM and flash memory, which places limitations 2001 what kind of processing can be performed and how much code can be 2002 put on those devices. To reduce code size fewer and smaller 2003 protocol implementations can be put on the firmware of such a 2004 device. In this case, CoAP may be used instead of HTTP, symmetric 2005 key cryptography instead of public key cryptography, and CBOR 2006 instead of JSON. Authentication and key establishment protocol, 2007 e.g. the DTLS handshake, in comparison with assisted key 2008 establishment also has an impact on memory and code. 2010 User Interface Limitations: 2012 Protecting access to resources is both an important security as 2013 well as privacy feature. End users and enterprise customers do 2014 not want to give access to the data collected by their IoT device 2015 or to functions it may offer to third parties. Since the 2016 classical approach of requesting permissions from end users via a 2017 rich user interface does not work in many IoT deployment scenarios 2018 these functions need to be delegated to user controlled devices 2019 that are better suitable for such tasks, such as smart phones and 2020 tablets. 2021 Communication Constraints: 2023 In certain constrained settings an IoT device may not be able to 2024 communicate with a given device at all times. Devices may be 2025 sleeping, or just disconnected from the Internet because of 2026 general lack of connectivity in the area, for cost reasons, or for 2027 security reasons, e.g. to avoid an entry point for Denial-of- 2028 Service attacks. 2030 The communication interactions this framework builds upon (as 2031 shown graphically in Figure 1) may be accomplished using a variety 2032 of different protocols, and not all parts of the message flow are 2033 used in all applications due to the communication constraints. 2034 While we envision deployments to make use of CoAP we explicitly 2035 want to support HTTP, HTTP/2 or specific protocols, such as 2036 Bluetooth Smart communication, which does not necessarily use IP. 2038 The latter raises the need for application layer security over the 2039 various interfaces. 2041 Appendix B. Roles and Responsibilites 2043 Resource Owner 2045 * Make sure that the RS is registered at the AS. This includes 2046 making known to the AS which profiles, token_types, scopes, and 2047 key types (symmetric/asymmetric) the RS supports. Also making 2048 it known to the AS which audience(s) the RS identifies itself 2049 with. 2050 * Make sure that clients can discover the AS which is in charge 2051 of the RS. 2052 * Make sure that the AS has the necessary, up-to-date, access 2053 control policies for the RS. 2055 Requesting Party 2057 * Make sure that the client is provisioned the necessary 2058 credentials to authenticate to the AS. 2059 * Make sure that the client is configured to follow the security 2060 requirements of the Requesting Party, when issuing requests 2061 (e.g. minimum communication security requirements, trust 2062 anchors). 2063 * Register the client at the AS. This includes making known to 2064 the AS which profiles, token_types, and key types (symmetric/ 2065 asymmetric) the client. 2067 Authorization Server 2069 * Register RS and manage corresponding security contexts. 2070 * Register clients and including authentication credentials. 2071 * Allow Resource Owners to configure and update access control 2072 policies related to their registered RS' 2073 * Expose the /token endpoint to allow clients to request tokens. 2074 * Authenticate clients that wish to request a token. 2075 * Process a token request against the authorization policies 2076 configured for the RS. 2077 * Expose the /introspection endpoint that allows RS's to submit 2078 token introspection requests. 2079 * Authenticate RS's that wish to get an introspection response. 2080 * Process token introspection requests. 2081 * Optionally: Handle token revocation. 2083 Client 2084 * Discover the AS in charge of the RS that is to be targeted with 2085 a request. 2086 * Submit the token request (A). 2088 + Authenticate towards the AS. 2089 + Optionally (if not pre-configured): Specify which RS, which 2090 resource(s), and which action(s) the request(s) will target. 2091 + If raw public key (rpk) or certificate is used, make sure 2092 the AS has the right rpk or certificate for this client. 2093 * Process the access token and RS Information (B) 2095 + Check that the RS Information provides the necessary 2096 security parameters (e.g. PoP key, information on 2097 communication security protocols supported by the RS). 2098 * Send the token and request to the RS (C) 2100 + Authenticate towards the RS (this could coincide with the 2101 proof of possession process). 2102 + Transmit the token as specified by the AS (default is to the 2103 /authz-info endpoint, alternative options are specified by 2104 profiles). 2105 + Perform the proof-of-possession procedure as specified by 2106 the profile in use (this may already have been taken care of 2107 through the authentication procedure). 2108 * Process the RS response (F) requirements of the Requesting 2109 Party, when issuing requests (e.g. minimum communication 2110 security requirements, trust anchors). 2111 * Register the client at the AS. 2113 Resource Server 2115 * Expose a way to submit access tokens. By default this is the 2116 /authz-info endpoint. 2117 * Process an access token. 2119 + Verify the token is from the right AS. 2120 + Verify that the token applies to this RS. 2121 + Check that the token has not expired (if the token provides 2122 expiration information). 2123 + Check the token's integrity. 2124 + Store the token so that it can be retrieved in the context 2125 of a matching request. 2126 * Process a request. 2128 + Set up communication security with the client. 2129 + Authenticate the client. 2130 + Match the client against existing tokens. 2132 + Check that tokens belonging to the client actually authorize 2133 the requested action. 2134 + Optionally: Check that the matching tokens are still valid, 2135 using introspection (if this is possible.) 2136 * Send a response following the agreed upon communication 2137 security. 2139 Appendix C. Requirements on Profiles 2141 This section lists the requirements on profiles of this framework, 2142 for the convenience of a profile designer. All this information is 2143 also given in the appropriate sections of the main document, this is 2144 just meant as a checklist, to make it more easy to spot parts one 2145 might have missed. 2147 o Specify the discovery process of how the client finds the right AS 2148 for an RS it wants to send a request to. 2149 o Specify the communication protocol the client and RS the must use 2150 (e.g. CoAP). 2151 o Specify the security protocol the client and RS must use to 2152 protect their communication (e.g. OSCOAP or DTLS over CoAP). 2153 This must provide encryption and integrity protection. 2154 o Specify how the client and the RS mutually authenticate 2155 o Specify the Content-format of the protocol messages (e.g. 2156 "application/cbor" or "application/cose+cbor"). 2157 o Specify the proof-of-possession protocol(s) and how to select one, 2158 if several are available. Also specify which key types (e.g. 2159 symmetric/asymmetric) are supported by a specific proof-of- 2160 possession protocol. 2161 o Specify a unique profile identifier. 2162 o Optionally specify how the RS talks to the AS for introspection. 2163 o Optionally specify how the client talks to the AS for requesting a 2164 token. 2165 o Specify how/if the /authz-info endpoint is protected. 2166 o Optionally define other methods of token transport than the 2167 /authz-info endpoint. 2169 Appendix D. Deployment Examples 2171 There is a large variety of IoT deployments, as is indicated in 2172 Appendix A, and this section highlights a few common variants. This 2173 section is not normative but illustrates how the framework can be 2174 applied. 2176 For each of the deployment variants there are a number of possible 2177 security setups between clients, resource servers and authorization 2178 servers. The main focus in the following subsections is on how 2179 authorization of a client request for a resource hosted by a RS is 2180 performed. This requires the the security of the requests and 2181 responses between the clients and the RS to consider. 2183 Note: CBOR diagnostic notation is used for examples of requests and 2184 responses. 2186 D.1. Local Token Validation 2188 In this scenario we consider the case where the resource server is 2189 offline, i.e. it is not connected to the AS at the time of the access 2190 request. This access procedure involves steps A, B, C, and F of 2191 Figure 1. 2193 Since the resource server must be able to verify the access token 2194 locally, self-contained access tokens must be used. 2196 This example shows the interactions between a client, the 2197 authorization server and a temperature sensor acting as a resource 2198 server. Message exchanges A and B are shown in Figure 16. 2200 A: The client first generates a public-private key pair used for 2201 communication security with the RS. 2202 The client sends the POST request to /token at the AS. The 2203 security of this request can be transport or application layer, it 2204 is up the the comunication security profile to define. In the 2205 example trasport layer identification of the AS is done and the 2206 client identifies with client_id and client_secret as in classic 2207 OAuth. The request contains the public key of the client and the 2208 Audience parameter set to "tempSensorInLivingRoom", a value that 2209 the temperature sensor identifies itself with. The AS evaluates 2210 the request and authorizes the client to access the resource. 2211 B: The AS responds with a PoP token and RS Information. The PoP 2212 token contains the public key of the client, and the RS 2213 Information contains the public key of the RS. For communication 2214 security this example uses DTLS RawPublicKey between the client 2215 and the RS. The issued token will have a short validity time, 2216 i.e. 'exp' close to 'iat', to protect the RS from replay attacks. 2217 The token includes the claim such as "scope" with the authorized 2218 access that an owner of the temperature device can enjoy. In this 2219 example, the 'scope' claim, issued by the AS, informs the RS that 2220 the owner of the token, that can prove the possession of a key is 2221 authorized to make a GET request against the /temperature resource 2222 and a POST request on the /firmware resource. Note that the 2223 syntax and semantics of the scope claim are application specific. 2224 Note: In this example we assume that the client knows what 2225 resource it wants to access, and is therefore able to request 2226 specific audience and scope claims for the access token. 2228 Authorization 2229 Client Server 2230 | | 2231 |<=======>| DTLS Connection Establishment 2232 | | to identify the AS 2233 | | 2234 A: +-------->| Header: POST (Code=0.02) 2235 | POST | Uri-Path:"token" 2236 | | Content-Type: application/cbor 2237 | | Payload: 2238 | | 2239 B: |<--------+ Header: 2.05 Content 2240 | 2.05 | Content-Type: application/cbor 2241 | | Payload: 2242 | | 2244 Figure 16: Token Request and Response Using Client Credentials. 2246 The information contained in the Request-Payload and the Response- 2247 Payload is shown in Figure 17. Note that we assume a DTLS-based 2248 communication security profile for this example, therefore the 2249 Content-Type is "application/cbor". 2251 Request-Payload : 2252 { 2253 "grant_type" : "client_credentials", 2254 "aud" : "tempSensorInLivingRoom", 2255 "client_id" : "myclient", 2256 "client_secret" : "qwerty" 2257 } 2259 Response-Payload : 2260 { 2261 "access_token" : b64'SlAV32hkKG ...', 2262 "token_type" : "pop", 2263 "csp" : "DTLS", 2264 "cnf" : { 2265 "COSE_Key" : { 2266 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2267 "kty" : "EC", 2268 "crv" : "P-256", 2269 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 2270 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 2271 } 2272 } 2273 } 2275 Figure 17: Request and Response Payload Details. 2277 The content of the access token is shown in Figure 18. 2279 { 2280 "aud" : "tempSensorInLivingRoom", 2281 "iat" : "1360189224", 2282 "exp" : "1360289224", 2283 "scope" : "temperature_g firmware_p", 2284 "cnf" : { 2285 "jwk" : { 2286 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 2287 "kty" : "EC", 2288 "crv" : "P-256", 2289 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 2290 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 2291 } 2292 } 2293 } 2295 Figure 18: Access Token including Public Key of the Client. 2297 Messages C and F are shown in Figure 19 - Figure 20. 2299 C: The client then sends the PoP token to the /authz-info endpoint 2300 at the RS. This is a plain CoAP request, i.e. no transport or 2301 application layer security between client and RS, since the token 2302 is integrity protected between AS and RS. The RS verifies that 2303 the PoP token was created by a known and trusted AS, is valid, and 2304 responds to the client. The RS caches the security context 2305 together with authorization information about this client 2306 contained in the PoP token. 2308 Resource 2309 Client Server 2310 | | 2311 C: +-------->| Header: POST (Code=0.02) 2312 | POST | Uri-Path:"authz-info" 2313 | | Payload: SlAV32hkKG ... 2314 | | 2315 |<--------+ Header: 2.04 Changed 2316 | 2.04 | 2317 | | 2319 Figure 19: Access Token provisioning to RS 2320 The client and the RS runs the DTLS handshake using the raw public 2321 keys established in step B and C. 2323 The client sends the CoAP request GET to /temperature on RS over 2324 DTLS. The RS verifies that the request is authorized, based on 2325 previously established security context. 2326 F: The RS responds with a resource representation over DTLS. 2328 Resource 2329 Client Server 2330 | | 2331 |<=======>| DTLS Connection Establishment 2332 | | using Raw Public Keys 2333 | | 2334 +-------->| Header: GET (Code=0.01) 2335 | GET | Uri-Path: "temperature" 2336 | | 2337 | | 2338 | | 2339 F: |<--------+ Header: 2.05 Content 2340 | 2.05 | Payload: 2341 | | 2343 Figure 20: Resource Request and Response protected by DTLS. 2345 D.2. Introspection Aided Token Validation 2347 In this deployment scenario we assume that a client is not able to 2348 access the AS at the time of the access request. Since the RS is, 2349 however, connected to the back-end infrastructure it can make use of 2350 token introspection. This access procedure involves steps A-F of 2351 Figure 1, but assumes steps A and B have been carried out during a 2352 phase when the client had connectivity to AS. 2354 Since the client is assumed to be offline, at least for a certain 2355 period of time, a pre-provisioned access token has to be long-lived. 2356 The resource server may use its online connectivity to validate the 2357 access token with the authorization server, which is shown in the 2358 example below. 2360 In the example interactions between an offline client (key fob), a RS 2361 (online lock), and an AS is shown. We assume that there is a 2362 provisioning step where the client has access to the AS. This 2363 corresponds to message exchanges A and B which are shown in 2364 Figure 21. 2366 Authorization consent from the resource owner can be pre-configured, 2367 but it can also be provided via an interactive flow with the resource 2368 owner. An example of this for the key fob case could be that the 2369 resource owner has a connected car, he buys a generic key that he 2370 wants to use with the car. To authorize the key fob he connects it 2371 to his computer that then provides the UI for the device. After that 2372 OAuth 2.0 implicit flow can used to authorize the key for his car at 2373 the the car manufacturers AS. 2375 Note: In this example the client does not know the exact door it will 2376 be used to access since the token request is not send at the time of 2377 access. So the scope and audience parameters is set quite wide to 2378 start with and new values different form the original once can be 2379 returned from introspection later on. 2381 A: The client sends the request using POST to /token at AS. The 2382 request contains the Audience parameter set to "PACS1337" (PACS, 2383 Physical Access System), a value the that the online door in 2384 question identifies itself with. The AS generates an access token 2385 as on opaque string, which it can match to the specific client, a 2386 targeted audience and a symmetric key. The security is provided 2387 by identifying the AS on transport layer using a pre shared 2388 security context (psk, rpk or certificate) and then the client is 2389 identified using client_id and client_secret as in classic OAuth 2390 B: The AS responds with the an access token and RS Information, 2391 the latter containing a symmetric key. Communication security 2392 between C and RS will be DTLS and PreSharedKey. The PoP key being 2393 used as the PreSharedKey. 2395 Authorization 2396 Client Server 2397 | | 2398 | | 2399 A: +-------->| Header: POST (Code=0.02) 2400 | POST | Uri-Path:"token" 2401 | | Content-Type: application/cbor 2402 | | Payload: 2403 | | 2404 B: |<--------+ Header: 2.05 Content 2405 | | Content-Type: application/cbor 2406 | 2.05 | Payload: 2407 | | 2409 Figure 21: Token Request and Response using Client Credentials. 2411 The information contained in the Request-Payload and the Response- 2412 Payload is shown in Figure 22. 2414 Request-Payload: 2415 { 2416 "grant_type" : "client_credentials", 2417 "aud" : "lockOfDoor4711", 2418 "client_id" : "keyfob", 2419 "client_secret" : "qwerty" 2420 } 2422 Response-Payload: 2423 { 2424 "access_token" : b64'SlAV32hkKG ...' 2425 "token_type" : "pop", 2426 "csp" : "DTLS", 2427 "cnf" : { 2428 "COSE_Key" : { 2429 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2430 "kty" : "oct", 2431 "alg" : "HS256", 2432 "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' 2433 } 2434 } 2435 } 2437 Figure 22: Request and Response Payload for C offline 2439 The access token in this case is just an opaque string referencing 2440 the authorization information at the AS. 2442 C: Next, the client POSTs the access token to the /authz-info 2443 endpoint in the RS. This is a plain CoAP request, i.e. no DTLS 2444 between client and RS. Since the token is an opaque string, the 2445 RS cannot verify it on its own, and thus defers to respond the 2446 client with a status code until after step E. 2447 D: The RS forwards the token to the /introspect endpoint on the 2448 AS. Introspection assumes a secure connection between the AS and 2449 the RS, e.g. using transport of application layer security. In 2450 the example AS is identified using pre shared security context 2451 (psk, rpk or certificate) while RS is acting as client and is 2452 identified with client_id and client_secret. 2453 E: The AS provides the introspection response containing 2454 parameters about the token. This includes the confirmation key 2455 (cnf) parameter that allows the RS to verify the client's proof of 2456 possession in step F. 2457 After receiving message E, the RS responds to the client's POST in 2458 step C with the CoAP response code 2.01 (Created). 2460 Resource 2461 Client Server 2462 | | 2463 C: +-------->| Header: POST (T=CON, Code=0.02) 2464 | POST | Uri-Path:"authz-info" 2465 | | Content-Type: "application/cbor" 2466 | | Payload: b64'SlAV32hkKG ...'' 2467 | | 2468 | | Authorization 2469 | | Server 2470 | | | 2471 | D: +--------->| Header: POST (Code=0.02) 2472 | | POST | Uri-Path: "introspect" 2473 | | | Content-Type: "application/cbor" 2474 | | | Payload: 2475 | | | 2476 | E: |<---------+ Header: 2.05 Content 2477 | | 2.05 | Content-Type: "application/cbor" 2478 | | | Payload: 2479 | | | 2480 | | 2481 |<--------+ Header: 2.01 Created 2482 | 2.01 | 2483 | | 2485 Figure 23: Token Introspection for C offline 2486 The information contained in the Request-Payload and the Response- 2487 Payload is shown in Figure 24. 2489 Request-Payload: 2490 { 2491 "token" : b64'SlAV32hkKG...', 2492 "client_id" : "FrontDoor", 2493 "client_secret" : "ytrewq" 2494 } 2496 Response-Payload: 2497 { 2498 "active" : true, 2499 "aud" : "lockOfDoor4711", 2500 "scope" : "open, close", 2501 "iat" : 1311280970, 2502 "cnf" : { 2503 "kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 2504 } 2505 } 2507 Figure 24: Request and Response Payload for Introspection 2509 The client uses the symmetric PoP key to establish a DTLS 2510 PreSharedKey secure connection to the RS. The CoAP request PUT is 2511 sent to the uri-path /state on RS changing state of the door to 2512 locked. 2513 F: The RS responds with a appropriate over the secure DTLS 2514 channel. 2516 Resource 2517 Client Server 2518 | | 2519 |<=======>| DTLS Connection Establishment 2520 | | using Pre Shared Key 2521 | | 2522 +-------->| Header: PUT (Code=0.03) 2523 | PUT | Uri-Path: "state" 2524 | | Payload: 2525 | | 2526 F: |<--------+ Header: 2.04 Changed 2527 | 2.04 | Payload: 2528 | | 2530 Figure 25: Resource request and response protected by OSCOAP 2532 Appendix E. Document Updates 2534 E.1. Version -02 to -03 2536 o Removed references to draft-ietf-oauth-pop-key-distribution since 2537 the status of this draft is unclear. 2538 o Copied and adapted security considerations from draft-ietf-oauth- 2539 pop-key-distribution. 2540 o Renamed "client information" to "RS information" since it is 2541 information about the RS. 2542 o Clarified the requirements on profiles of this framework. 2543 o Clarified the token endpoint protocol and removed negotiation of 2544 'profile' and 'alg' (section 6). 2545 o Renumbered the abbreviations for claims and parameters to get a 2546 consistent numbering across different endpoints. 2547 o Clarified the introspection endpoint. 2548 o Renamed token, introspection and authz-info to 'endpoint' instead 2549 of 'resource' to mirror the OAuth 2.0 terminology. 2550 o Updated the examples in the appendices. 2552 E.2. Version -01 to -02 2554 o Restructured to remove communication security parts. These shall 2555 now be defined in profiles. 2557 o Restructured section 5 to create new sections on the OAuth 2558 endpoints /token, /introspect and /authz-info. 2559 o Pulled in material from draft-ietf-oauth-pop-key-distribution in 2560 order to define proof-of-possession key distribution. 2561 o Introduced the 'cnf' parameter as defined in RFC7800 to reference 2562 or transport keys used for proof of posession. 2563 o Introduced the 'client-token' to transport client information from 2564 the AS to the client via the RS in conjunction with introspection. 2565 o Expanded the IANA section to define parameters for token request, 2566 introspection and CWT claims. 2567 o Moved deployment scenarios to the appendix as examples. 2569 E.3. Version -00 to -01 2571 o Changed 5.1. from "Communication Security Protocol" to "Client 2572 Information". 2573 o Major rewrite of 5.1 to clarify the information exchanged between 2574 C and AS in the PoP token request profile for IoT. 2576 * Allow the client to indicate preferences for the communication 2577 security protocol. 2578 * Defined the term "Client Information" for the additional 2579 information returned to the client in addition to the access 2580 token. 2581 * Require that the messages between AS and client are secured, 2582 either with (D)TLS or with COSE_Encrypted wrappers. 2583 * Removed dependency on OSCoAP and added generic text about 2584 object security instead. 2585 * Defined the "rpk" parameter in the client information to 2586 transmit the raw public key of the RS from AS to client. 2587 * (D)TLS MUST use the PoP key in the handshake (either as PSK or 2588 as client RPK with client authentication). 2589 * Defined the use of x5c, x5t and x5tS256 parameters when a 2590 client certificate is used for proof of possession. 2591 * Defined "tktn" parameter for signaling for how to transfer the 2592 access token. 2593 o Added 5.2. the CoAP Access-Token option for transferring access 2594 tokens in messages that do not have payload. 2595 o 5.3.2. Defined success and error responses from the RS when 2596 receiving an access token. 2597 o 5.6.:Added section giving guidance on how to handle token 2598 expiration in the absence of reliable time. 2599 o Appendix B Added list of roles and responsibilities for C, AS and 2600 RS. 2602 Authors' Addresses 2604 Ludwig Seitz 2605 SICS 2606 Scheelevaegen 17 2607 Lund 223 70 2608 SWEDEN 2610 Email: ludwig@sics.se 2612 Goeran Selander 2613 Ericsson 2614 Faroegatan 6 2615 Kista 164 80 2616 SWEDEN 2618 Email: goran.selander@ericsson.com 2620 Erik Wahlstroem 2621 Sweden 2623 Email: erik@wahlstromtekniska.se 2625 Samuel Erdtman 2626 Spotify AB 2627 Birger Jarlsgatan 61, 4tr 2628 Stockholm 113 56 2629 Sweden 2631 Email: erdtman@spotify.com 2633 Hannes Tschofenig 2634 ARM Ltd. 2635 Hall in Tirol 6060 2636 Austria 2638 Email: Hannes.Tschofenig@arm.com