idnits 2.17.1 draft-ietf-ace-oauth-authz-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 3, 2017) is 2636 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) ** 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-ace-cbor-web-token-02 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-01 == 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-07 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 6 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: August 7, 2017 Ericsson 6 E. Wahlstroem 8 S. Erdtman 9 Spotify AB 10 H. Tschofenig 11 ARM Ltd. 12 February 3, 2017 14 Authentication and Authorization for Constrained Environments (ACE) 15 draft-ietf-ace-oauth-authz-05 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 August 7, 2017. 44 Copyright Notice 46 Copyright (c) 2017 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 65 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 66 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 9 67 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 6. The 'Token' Endpoint . . . . . . . . . . . . . . . . . . . . 14 69 6.1. Client Credentials and Grants . . . . . . . . . . . . . . 15 70 6.2. Client-to-AS Request . . . . . . . . . . . . . . . . . . 15 71 6.3. AS-to-Client Response . . . . . . . . . . . . . . . . . . 18 72 6.4. Error Response . . . . . . . . . . . . . . . . . . . . . 20 73 6.5. Request and Response Parameters . . . . . . . . . . . . . 20 74 6.5.1. Audience . . . . . . . . . . . . . . . . . . . . . . 20 75 6.5.2. Grant Type . . . . . . . . . . . . . . . . . . . . . 21 76 6.5.3. Token Type . . . . . . . . . . . . . . . . . . . . . 21 77 6.5.4. Profile . . . . . . . . . . . . . . . . . . . . . . . 21 78 6.5.5. Confirmation . . . . . . . . . . . . . . . . . . . . 22 79 6.6. Mapping parameters to CBOR . . . . . . . . . . . . . . . 24 80 7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . . . 24 81 7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . . . 25 82 7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . . . 25 83 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 27 84 7.4. Client Token . . . . . . . . . . . . . . . . . . . . . . 27 85 7.5. Mapping Introspection parameters to CBOR . . . . . . . . 29 86 8. The Access Token . . . . . . . . . . . . . . . . . . . . . . 29 87 8.1. The 'Authorization Information' Endpoint . . . . . . . . 30 88 8.2. Token Expiration . . . . . . . . . . . . . . . . . . . . 30 89 9. Security Considerations . . . . . . . . . . . . . . . . . . . 31 90 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 33 91 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 92 11.1. OAuth Introspection Response Parameter Registration . . 33 93 11.2. OAuth Parameter Registration . . . . . . . . . . . . . . 34 94 11.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 34 95 11.4. Token Type Mappings . . . . . . . . . . . . . . . . . . 35 96 11.4.1. Registration Template . . . . . . . . . . . . . . . 35 97 11.4.2. Initial Registry Contents . . . . . . . . . . . . . 35 98 11.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . 35 99 11.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 36 100 11.6.1. Registration Template . . . . . . . . . . . . . . . 36 101 11.7. OAuth Parameter Mappings Registry . . . . . . . . . . . 36 102 11.7.1. Registration Template . . . . . . . . . . . . . . . 36 103 11.7.2. Initial Registry Contents . . . . . . . . . . . . . 37 104 11.8. Introspection Endpoint CBOR Mappings Registry . . . . . 39 105 11.8.1. Registration Template . . . . . . . . . . . . . . . 39 106 11.8.2. Initial Registry Contents . . . . . . . . . . . . . 39 107 11.9. CoAP Option Number Registration . . . . . . . . . . . . 41 108 11.10. CWT Confirmation Methods Registry . . . . . . . . . . . 42 109 11.10.1. Registration Template . . . . . . . . . . . . . . . 42 110 11.10.2. Initial Registry Contents . . . . . . . . . . . . . 43 111 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 112 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 113 13.1. Normative References . . . . . . . . . . . . . . . . . . 44 114 13.2. Informative References . . . . . . . . . . . . . . . . . 44 115 Appendix A. Design Justification . . . . . . . . . . . . . . . . 46 116 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 48 117 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 50 118 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 51 119 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 51 120 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 52 121 E.2. Introspection Aided Token Validation . . . . . . . . . . 55 122 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 59 123 F.1. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 59 124 F.2. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 59 125 F.3. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 60 126 F.4. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 60 127 F.5. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 60 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 61 130 1. Introduction 132 Authorization is the process for granting approval to an entity to 133 access a resource [RFC4949]. The authorization task itself can best 134 be described as granting access to a requesting client, for a 135 resource hosted on a device, the resource server (RS). This exchange 136 is mediated by one or multiple authorization servers (AS). Managing 137 authorization for a large number of devices and users is a complex 138 task. 140 While prior work on authorization solutions for the Web and for the 141 mobile environment also applies to the IoT environment many IoT 142 devices are constrained, for example in terms of processing 143 capabilities, available memory, etc. For web applications on 144 constrained nodes this specification makes use of CoAP [RFC7252]. 146 A detailed treatment of constraints can be found in [RFC7228], and 147 the different IoT deployments present a continuous range of device 148 and network capabilities. Taking energy consumption as an example: 149 At one end there are energy-harvesting or battery powered devices 150 which have a tight power budget, on the other end there are mains- 151 powered devices, and all levels in between. 153 Hence, IoT devices may be very different in terms of available 154 processing and message exchange capabilities and there is a need to 155 support many different authorization use cases [RFC7744]. 157 This specification describes a framework for authentication and 158 authorization in constrained environments (ACE) built on re-use of 159 OAuth 2.0 [RFC6749], thereby extending authorization to Internet of 160 Things devices. This specification contains the necessary building 161 blocks for adjusting OAuth 2.0 to IoT environments. 163 More detailed, interoperable specifications can be found in profiles. 164 Implementations may claim conformance with a specific profile, 165 whereby implementations utilizing the same profile interoperate while 166 implementations of different profiles are not expected to be 167 interoperable. Some devices, such as mobile phones and tablets, may 168 implement multiple profiles and will therefore be able to interact 169 with a wider range of low end devices. 171 2. Terminology 173 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 174 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 175 "OPTIONAL" in this document are to be interpreted as described in 176 [RFC2119]. 178 Certain security-related terms such as "authentication", 179 "authorization", "confidentiality", "(data) integrity", "message 180 authentication code", and "verify" are taken from [RFC4949]. 182 Since we describe exchanges as RESTful protocol interactions HTTP 183 [RFC7231] offers useful terminology. 185 Terminology for entities in the architecture is defined in OAuth 2.0 186 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 187 server (RS), and authorization server (AS). 189 Note that the term "endpoint" is used here following its OAuth 190 definition, which is to denote resources such as /token and 191 /introspect at the AS and /authz-info at the RS. The CoAP [RFC7252] 192 definition, which is "An entity participating in the CoAP protocol" 193 is not used in this memo. 195 Since this specification focuses on the problem of access control to 196 resources, we simplify the actors by assuming that the client 197 authorization server (CAS) functionality is not stand-alone but 198 subsumed by either the authorization server or the client (see 199 section 2.2 in [I-D.ietf-ace-actors]). 201 We call the specifications of this memo the "framework" or "ACE 202 framework". When referring to "profiles of this framework" we mean 203 additional memo's that define the use of this specification with 204 concrete transport, and communication security protocols (e.g. CoAP 205 over DTLS). 207 3. Overview 209 This specification defines the ACE framework for authorization in the 210 Internet of Things environment. It consists of a set of building 211 blocks. 213 The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys 214 widespread deployment. Many IoT devices can support OAuth 2.0 215 without any additional extensions, but for certain constrained 216 settings additional profiling is needed. 218 Another building block is the lightweight web transfer protocol CoAP 219 [RFC7252] for those communication environments where HTTP is not 220 appropriate. CoAP typically runs on top of UDP which further reduces 221 overhead and message exchanges. While this specification defines 222 extensions for the use of OAuth over CoAP, we do envision further 223 underlying protocols to be supported in the future, such as HTTP/2, 224 MQTT and QUIC. 226 A third building block is CBOR [RFC7049] for encodings where JSON 227 [RFC7159] is not sufficiently compact. CBOR is a binary encoding 228 designed for small code and message size, which may be used for 229 encoding of self contained tokens, and also for encoding CoAP POST 230 parameters and CoAP responses. 232 A fourth building block is the compact CBOR-based secure message 233 format COSE [I-D.ietf-cose-msg], which enables application layer 234 security as an alternative or complement to transport layer security 235 (DTLS [RFC6347] or TLS [RFC5246]). COSE is used to secure self 236 contained tokens such as proof-of-possession (PoP) tokens, which is 237 an extension to the OAuth access tokens, and "client tokens" which 238 are defined in this framework (see Section 7.4). The default access 239 token format is defined in CBOR web token (CWT) 240 [I-D.ietf-ace-cbor-web-token]. Application layer security for CoAP 241 using COSE can be provided with OSCOAP 242 [I-D.ietf-core-object-security]. 244 With the building blocks listed above, solutions satisfying various 245 IoT device and network constraints are possible. A list of 246 constraints is described in detail in RFC 7228 [RFC7228] and a 247 description of how the building blocks mentioned above relate to the 248 various constraints can be found in Appendix A. 250 Luckily, not every IoT device suffers from all constraints. The ACE 251 framework nevertheless takes all these aspects into account and 252 allows several different deployment variants to co-exist rather than 253 mandating a one-size-fits-all solution. We believe this is important 254 to cover the wide range of possible interworking use cases and the 255 different requirements from a security point of view. Once IoT 256 deployments mature, popular deployment variants will be documented in 257 form of ACE profiles. 259 In the subsections below we provide further details about the 260 different building blocks. 262 3.1. OAuth 2.0 264 The OAuth 2.0 authorization framework enables a client to obtain 265 limited access to a resource with the permission of a resource owner. 266 Authorization information, or references to it, is passed between the 267 nodes using access tokens. These access tokens are issued to clients 268 by an authorization server with the approval of the resource owner. 269 The client uses the access token to access the protected resources 270 hosted by the resource server. 272 A number of OAuth 2.0 terms are used within this specification: 274 The token and introspect Endpoints: 276 The AS hosts the /token endpoint that allows a client to request 277 access tokens. The client makes a POST request to the /token 278 endpoint on the AS and receives the access token in the response 279 (if the request was successful). 281 The token introspection endpoint, /introspect, is used by the RS 282 when requesting additional information regarding a received access 283 token. The RS makes a POST request to /introspect on the AS and 284 receives information about the access token in the response. (See 285 "Introspection" below.) 287 Access Tokens: 289 Access tokens are credentials needed to access protected 290 resources. An access token is a data structure representing 291 authorization permissions issued by the AS to the client. Access 292 tokens are generated by the authorization server and consumed by 293 the resource server. The access token content is opaque to the 294 client. 296 Access tokens can have different formats, and various methods of 297 utilization (e.g., cryptographic properties) based on the security 298 requirements of the given deployment. 300 Proof of Possession Tokens: 302 An access token may be bound to a cryptographic key, which is then 303 used by an RS to authenticate requests from a client. Such tokens 304 are called proof-of-possession tokens (or PoP tokens). 306 The proof-of-possession (PoP) security concept assumes that the AS 307 acts as a trusted third party that binds keys to access tokens. 308 These so called PoP keys are then used by the client to 309 demonstrate the possession of the secret to the RS when accessing 310 the resource. The RS, when receiving an access token, needs to 311 verify that the key used by the client matches the one bound to 312 the access token. When this specification uses the term "access 313 token" it is assumed to be a PoP token unless specifically stated 314 otherwise. 316 The key bound to the access token (aka PoP key) may be based on 317 symmetric as well as on asymmetric cryptography. The appropriate 318 choice of security depends on the constraints of the IoT devices 319 as well as on the security requirements of the use case. 321 Symmetric PoP key: The AS generates a random symmetric PoP key. 322 The key is either stored to be returned on introspection calls 323 or encrypted and included in the access token. The PoP key is 324 also encrypted for the client and sent together with the access 325 token to the client. 327 Asymmetric PoP key: An asymmetric key pair is generated on the 328 client and the public key is sent to the AS (if it does not 329 already have knowledge of the client's public key). 330 Information about the public key, which is the PoP key in this 331 case, is either stored to be returned on introspection calls or 332 included inside the access token and sent back to the 333 requesting client. The RS can identify the client's public key 334 from the information in the token, which allows the client to 335 use the corresponding private key for the proof of possession. 337 The access token is either a simple reference, or a structured 338 information object (e.g. CWT [I-D.ietf-ace-cbor-web-token]), 339 protected by a cryptographic wrapper (e.g. COSE 340 [I-D.ietf-cose-msg]). The choice of PoP key does not necessarily 341 imply a specific credential type for the integrity protection of 342 the token. 344 Scopes and Permissions: 346 In OAuth 2.0, the client specifies the type of permissions it is 347 seeking to obtain (via the scope parameter) in the access token 348 request. In turn, the AS may use the scope response parameter to 349 inform the client of the scope of the access token issued. As the 350 client could be a constrained device as well, this specification 351 uses CBOR encoded messages for CoAP, defined in Section 5, to 352 request scopes and to be informed what scopes the access token was 353 actually authorized for by the AS. 355 The values of the scope parameter are expressed as a list of 356 space- delimited, case-sensitive strings, with a semantic that is 357 well-known to the AS and the RS. More details about the concept 358 of scopes is found under Section 3.3 in [RFC6749]. 360 Claims: 362 Information carried in the access token or returned from 363 introspection, called claims, is in the form of type-value pairs. 364 An access token may, for example, include a claim identifying the 365 AS that issued the token (via the "iss" claim) and what audience 366 the access token is intended for (via the "aud" claim). The 367 audience of an access token can be a specific resource or one or 368 many resource servers. The resource owner policies influence what 369 claims are put into the access token by the authorization server. 371 While the structure and encoding of the access token varies 372 throughout deployments, a standardized format has been defined 373 with the JSON Web Token (JWT) [RFC7519] where claims are encoded 374 as a JSON object. In [I-D.ietf-ace-cbor-web-token] an equivalent 375 format using CBOR encoding (CWT) has been defined. 377 Introspection: 379 Introspection is a method for a resource server to query the 380 authorization server for the active state and content of a 381 received access token. This is particularly useful in those cases 382 where the authorization decisions are very dynamic and/or where 383 the received access token itself is a reference rather than a 384 self-contained token. More information about introspection in 385 OAuth 2.0 can be found in [RFC7662]. 387 3.2. CoAP 389 CoAP is an application layer protocol similar to HTTP, but 390 specifically designed for constrained environments. CoAP typically 391 uses datagram-oriented transport, such as UDP, where reordering and 392 loss of packets can occur. A security solution need to take the 393 latter aspects into account. 395 While HTTP uses headers and query-strings to convey additional 396 information about a request, CoAP encodes such information in so- 397 called 'options'. 399 CoAP supports application-layer fragmentation of the CoAP payloads 400 through blockwise transfers [RFC7959]. However, block-wise transfer 401 does not increase the size limits of CoAP options, therefore data 402 encoded in options has to be kept small. 404 Transport layer security for CoAP can be provided by DTLS 1.2 405 [RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy 406 operations which requires transport layer security to be terminated 407 at the proxy. One approach for protecting CoAP communication end-to- 408 end through proxies, and also to support security for CoAP over a 409 different transport in a uniform way, is to provide security on 410 application layer using an object-based security mechanism such as 411 COSE [I-D.ietf-cose-msg]. 413 One application of COSE is OSCOAP [I-D.ietf-core-object-security], 414 which provides end-to-end confidentiality, integrity and replay 415 protection, and a secure binding between CoAP request and response 416 messages. In OSCOAP, the CoAP messages are wrapped in COSE objects 417 and sent using CoAP. 419 4. Protocol Interactions 421 The ACE framework is based on the OAuth 2.0 protocol interactions 422 using the /token and /introspect endpoints. A client obtains an 423 access token from an AS using the /token endpoint and subsequently 424 presents the access token to a RS to gain access to a protected 425 resource. The RS, after receiving an access token, may present it to 426 the AS via the /introspect endpoint to get information about the 427 access token. In other deployments the RS may process the access 428 token locally without the need to contact an AS. These interactions 429 are shown in Figure 1. An overview of various OAuth concepts is 430 provided in Section 3.1. 432 The OAuth 2.0 framework defines a number of "protocol flows" via 433 grant types, which have been extended further with extensions to 434 OAuth 2.0 (such as RFC 7521 [RFC7521] and 435 [I-D.ietf-oauth-device-flow]). What grant types works best depends 436 on the usage scenario and RFC 7744 [RFC7744] describes many different 437 IoT use cases but there are two preferred grant types, namely the 438 Authorization Code Grant (described in Section 4.1 of RFC 7521) and 439 the Client Credentials Grant (described in Section 4.4 of RFC 7521). 440 The Authorization Code Grant is a good fit for use with apps running 441 on smart phones and tablets that request access to IoT devices, a 442 common scenario in the smart home environment, where users need to go 443 through an authentication and authorization phase (at least during 444 the initial setup phase). The native apps guidelines described in 445 [I-D.ietf-oauth-native-apps] are applicable to this use case. The 446 Client Credential Grant is a good fit for use with IoT devices where 447 the OAuth client itself is constrained. In such a case the resource 448 owner or another person on his or her behalf have arranged with the 449 authorization server out-of-band, which is often accomplished using a 450 commissioning tool. 452 The consent of the resource owner, for giving a client access to a 453 protected resource, can be provided dynamically as in the traditional 454 OAuth flows, or it could be pre-configured by the resource owner as 455 authorization policies at the AS, which the AS evaluates when a token 456 request arrives. The resource owner and the requesting party (i.e. 457 client owner) are not shown in Figure 1. 459 This framework supports a wide variety of communication security 460 mechanisms between the ACE entities, such as client, AS, and RS. We 461 assume that the client has been registered (also called enrolled or 462 onboarded) to an AS using a mechanism defined outside the scope of 463 this document. In practice, various techniques for onboarding have 464 been used, such as factory-based provisioning or the use of 465 commissioning tools. Regardless of the onboarding technique, this 466 registration procedure implies that the client and the AS share 467 credentials, and configuration parameters. These credentials are 468 used to mutually authenticate each other and to protect messages 469 exchanged between the client and the AS. 471 It is also assumed that the RS has been registered with the AS, 472 potentially in a similar way as the client has been registered with 473 the AS. Established keying material between the AS and the RS allows 474 the AS to apply cryptographic protection to the access token to 475 ensure that its content cannot be modified, and if needed, that the 476 content is confidentiality protected. 478 The keying material necessary for establishing communication security 479 between C and RS is dynamically established as part of the protocol 480 described in this document. 482 At the start of the protocol there is an optional discovery step 483 where the client discovers the resource server and the resources this 484 server hosts. In this step the client might also determine what 485 permissions are needed to access the protected resource. The 486 detailed procedures for this discovery process may be defined in an 487 ACE profile and depend on the protocols being used and the specific 488 deployment environment. 490 In Bluetooth Low Energy, for example, advertisements are broadcasted 491 by a peripheral, including information about the primary services. 492 In CoAP, as a second example, a client can make a request to "/.well- 493 known/core" to obtain information about available resources, which 494 are returned in a standardized format as described in [RFC6690]. 496 +--------+ +---------------+ 497 | |---(A)-- Token Request ------->| | 498 | | | Authorization | 499 | |<--(B)-- Access Token ---------| Server | 500 | | + RS Information | | 501 | | +---------------+ 502 | | ^ | 503 | | Introspection Request (D)| | 504 | Client | | | 505 | | Response + Client Token | |(E) 506 | | | v 507 | | +--------------+ 508 | |---(C)-- Token + Request ----->| | 509 | | | Resource | 510 | |<--(F)-- Protected Resource ---| Server | 511 | | | | 512 +--------+ +--------------+ 514 Figure 1: Basic Protocol Flow. 516 Requesting an Access Token (A): 518 The client makes an access token request to the /token endpoint at 519 the AS. This framework assumes the use of PoP tokens (see 520 Section 3.1 for a short description) wherein the AS binds a key to 521 an access token. The client may include permissions it seeks to 522 obtain, and information about the credentials it wants to use 523 (e.g., symmetric/asymmetric cryptography or a reference to a 524 specific credential). 526 Access Token Response (B): 528 If the AS successfully processes the request from the client, it 529 returns an access token. It also returns various parameters, 530 referred as "RS Information". In addition to the response 531 parameters defined by OAuth 2.0 and the PoP token extension, 532 further response parameters, such as information on which profile 533 the client should use with the resource server(s). More 534 information about these parameters can be found in Section 6.5. 536 Resource Request (C): 538 The client interacts with the RS to request access to the 539 protected resource and provides the access token. The protocol to 540 use between the client and the RS is not restricted to CoAP. 541 HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also 542 viable candidates. 544 Depending on the device limitations and the selected protocol this 545 exchange may be split up into two parts: 547 (1) the client sends the access token containing, or 548 referencing, the authorization information to the RS, that may 549 be used for subsequent resource requests by the client, and 550 (2) the client makes the resource access request, using the 551 communication security protocol and other RS Information 552 obtained from the AS. 554 The Client and the RS mutually authenticate using the security 555 protocol specified in the profile (see step B) and the keys 556 obtained in the access token or the RS Information or the client 557 token. The RS verifies that the token is integrity protected by 558 the AS and compares the claims contained in the access token with 559 the resource request. If the RS is online, validation can be 560 handed over to the AS using token introspection (see messages D 561 and E) over HTTP or CoAP, in which case the different parts of 562 step C may be interleaved with introspection. 564 Token Introspection Request (D): 566 A resource server may be configured to introspect the access token 567 by including it in a request to the /introspect endpoint at that 568 AS. Token introspection over CoAP is defined in Section 7 and for 569 HTTP in [RFC7662]. 571 Note that token introspection is an optional step and can be 572 omitted if the token is self-contained and the resource server is 573 prepared to perform the token validation on its own. 575 Token Introspection Response (E): 577 The AS validates the token and returns the most recent parameters, 578 such as scope, audience, validity etc. associated with it back to 579 the RS. The RS then uses the received parameters to process the 580 request to either accept or to deny it. The AS can additionally 581 return information that the RS needs to pass on to the client in 582 the form of a client token. The latter is used to establish keys 583 for mutual authentication between client and RS, when the client 584 has no direct connectivity to the AS, see Section 7.4 for details. 586 Protected Resource (F): 588 If the request from the client is authorized, the RS fulfills the 589 request and returns a response with the appropriate response code. 590 The RS uses the dynamically established keys to protect the 591 response, according to used communication security protocol. 593 5. Framework 595 The following sections detail the profiling and extensions of OAuth 596 2.0 for constrained environments which constitutes the ACE framework. 598 Credential Provisioning 600 For IoT we cannot generally assume that the client and RS are part 601 of a common key infrastructure, so the AS provisions credentials 602 or associated information to allow mutual authentication. These 603 credentials need to be provided to the parties before or during 604 the authentication protocol is executed, and may be re-used for 605 subsequent token requests. 607 Proof-of-Possession 609 The ACE framework by default implements proof-of-possession for 610 access tokens, i.e. that the token holder can prove being a holder 611 of the key bound to the token. The binding is provided by the 612 "cnf" claim indicating what key is used for proof-of-possession. 613 If clients need to update a token, e.g. to get additional rights, 614 they can request that the AS binds the new access token to the 615 same key as the previous token. 617 ACE Profiles 619 The client or RS may be limited in the encodings or protocols it 620 supports. To support a variety of different deployment settings, 621 specific interactions between client and RS are defined in an ACE 622 profile. In ACE framework the AS is expected to manage the 623 matching of compatible profile choices between a client and an RS. 624 The AS informs the client of the selected profile using the 625 "profile" parameter in the token response. 627 OAuth 2.0 requires the use of TLS both to protect the communication 628 between AS and client when requesting an access token; between client 629 and RS when accessing a resource and between AS and RS for 630 introspection. In constrained settings TLS is not always feasible, 631 or desirable. Nevertheless it is REQUIRED that the data exchanged 632 with the AS is encrypted and integrity protected. It is furthermore 633 REQUIRED that the AS and the endpoint communicating with it (client 634 or RS) perform mutual authentication. 636 Profiles MUST specify how mutual authentication is done, depending 637 e.g. on the communication protocol and the credentials used by the 638 client or the RS. 640 In OAuth 2.0 the communication with the Token and the Introspection 641 endpoints at the AS is assumed to be via HTTP and may use Uri-query 642 parameters. This framework RECOMMENDS to use CoAP instead and 643 RECOMMENDS the use of the following alternative instead of Uri-query 644 parameters: The sender (client or RS) encodes the parameters of its 645 request as a CBOR map and submits that map as the payload of the POST 646 request. The Content-format depends on the security applied to the 647 content and MUST be specified by the profile that is used. 649 The OAuth 2.0 AS uses a JSON structure in the payload of its 650 responses both to client and RS. This framework RECOMMENDS the use 651 of CBOR [RFC7049] instead. The requesting device can explicitly 652 request this encoding by setting the CoAP Accept option in the 653 request to "application/cbor". Depending on the profile, the content 654 MAY arrive in a different format wrapping a CBOR payload. 656 6. The 'Token' Endpoint 658 In plain OAuth 2.0 the AS provides the /token endpoint for submitting 659 access token requests. This framework extends the functionality of 660 the /token endpoint, giving the AS the possibility to help client and 661 RS to establish shared keys or to exchange their public keys. 662 Furthermore this framework defines encodings using CoAP and CBOR, in 663 addition to HTTP and JSON. 665 Authentication of the requesting client is done using client 666 credentials as defined by OAuth 2.0. A profile MAY specify new 667 client credentials types for the authentication of the client. 669 Profiles of this framework SHOULD specify how authentication of the 670 AS is done and how communication security is implemented. If nothing 671 is specified TLS with server certificate is assumed as defined by 672 OAuth 2.0. 674 When requesting a token the client is authenticated with client 675 credentials and then a grant is presented that gives the client the 676 right to get a token. 678 The figures of this section uses CBOR diagnostic notation without the 679 integer abbreviations for the parameters or their values for better 680 readability. 682 6.1. Client Credentials and Grants 684 To issue a token the client MUST be authenticated and present a valid 685 grant for the scopes requested. 687 The OAuth framework, [RFC6749], defines one client credential type, 688 client id and client secret. Profiles of this framework MAY extend 689 with additional client credentials such as DTLS pre-shared keys or 690 client certificates. 692 In the OAuth framework five grant types are defined. The grant types 693 can be split up into three groups, those granted on behalf of the 694 resource owner (password, authorization code, implicit), those for 695 the client (client_credentials), and those used to prolong a grant 696 (refresh token). 698 profiles MAY define additional grant types if needed, e.g. a proof of 699 possession refresh token. 701 6.2. Client-to-AS Request 703 The client sends a CoAP POST request to the token endpoint at the AS, 704 the profile MUST specify the Content-Type and wrapping of the 705 payload. The content of the request consists of the parameters 706 specified in section 4 of the OAuth 2.0 specification [RFC6749] 707 encoded as a CBOR map. 709 In addition to these parameters, this framework defines the following 710 parameters for requesting an access token from a /token endpoint: 712 aud 713 OPTIONAL. Specifies the audience for which the client is 714 requesting an access token. If this parameter is missing it is 715 assumed that the client and the AS have a pre-established 716 understanding of the audience that an access token should address. 718 If a client submits a request for an access token without 719 specifying an "aud" parameter, and the AS does not have a default 720 "aud" value for this client, then the AS MUST respond with an 721 error message with the CoAP response code 4.00 (Bad Request). 723 cnf 724 OPTIONAL. This field contains information about the key the 725 client would like to bind to the access token for proof-of- 726 possession. It is NOT RECOMMENDED that a client submits a 727 symmetric key value to the AS using this parameter. See 728 Section 6.5.5 for more details on the formatting of the 'cnf' 729 parameter. 731 The following examples illustrate different types of requests for 732 proof-of-possession tokens. 734 Figure 2 shows a request for a token with a symmetric proof-of- 735 possession key. Note that in this example we assume a DTLS-based 736 communication security profile, therefore the Content-Type is 737 "application/cbor". The content is displayed in CBOR diagnostic 738 notation, without abbreviations for better readability. 740 Header: POST (Code=0.02) 741 Uri-Host: "server.example.com" 742 Uri-Path: "token" 743 Content-Type: "application/cbor" 744 Payload: 745 { 746 "grant_type" : "client_credentials", 747 "aud" : "tempSensor4711", 748 } 750 Figure 2: Example request for an access token bound to a symmetric 751 key. 753 Figure 3 shows a request for a token with an asymmetric proof-of- 754 possession key. Note that in this example we assume an object 755 security-based profile, therefore the Content-Type is "application/ 756 cose+cbor". 758 Header: POST (Code=0.02) 759 Uri-Host: "server.example.com" 760 Uri-Path: "token" 761 Content-Type: "application/cose+cbor" 762 Payload: 763 { 764 "grant_type" : "client_credentials", 765 "client_id" : "myclient", 766 "client_secret" : "mysecret234", 767 "cnf" : { 768 "COSE_Key" : { 769 "kty" : "EC", 770 "kid" : h'11', 771 "crv" : "P-256", 772 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 773 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 774 } 775 } 776 } 778 Figure 3: Example request for an access token bound to an asymmetric 779 key. 781 Figure 4 shows a request for a token where a previously communicated 782 proof-of-possession key is only referenced. Note that we assume a 783 DTLS-based communication security profile for this example, therefore 784 the Content-Type is "application/cbor". Also note that the client 785 performs a password based authentication in this example by 786 submitting its client_secret (see section 2.3.1. of [RFC6749]). 788 Header: POST (Code=0.02) 789 Uri-Host: "server.example.com" 790 Uri-Path: "token" 791 Content-Type: "application/cbor" 792 Payload: 793 { 794 "grant_type" : "client_credentials", 795 "client_id" : "myclient", 796 "client_secret" : "mysecret234", 797 "aud" : "valve424", 798 "scope" : "read", 799 "cnf" : { 800 "kid" : b64'6kg0dXJM13U' 801 } 802 } 804 Figure 4: Example request for an access token bound to a key 805 reference. 807 6.3. AS-to-Client Response 809 If the access token request has been successfully verified by the AS 810 and the client is authorized to obtain an access token corresponding 811 to its access token request, the AS sends a response with the CoAP 812 response code 2.01 (Created). If client request was invalid, or not 813 authorized, the AS returns an error response as described in 814 Section 6.4. 816 Note that the AS decides which token type and profile to use when 817 issuing a successful response. It is assumed that the AS has prior 818 knowledge of the capabilities of the client, and the RS (see 819 Appendix D. This prior knowledge may, for example, be set by the use 820 of a dynamic client registration protocol exchange [RFC7591]. 822 The content of the successful reply is the RS Information. It MUST 823 be encoded as CBOR map, containing parameters as specified in section 824 5.1 of [RFC6749]. In addition to these parameters, the following 825 parameters are also part of a successful response: 827 profile 828 REQUIRED. This indicates the profile that the client MUST use 829 towards the RS. See Section 6.5.4 for the formatting of this 830 parameter. 832 cnf 833 REQUIRED if the token type is 'pop'. OPTIONAL otherwise. If a 834 symmetric proof-of-possession algorithms was selected, this field 835 contains the proof-of-possession key. If an asymmetric algorithm 836 was selected, this field contains information about the public key 837 used by the RS to authenticate. See Section 6.5.5 for the 838 formatting of this parameter. 839 token_type 840 OPTIONAL. By default implementations of this framework SHOULD 841 assume that the token_type is 'pop'. If a specific use case 842 requires another token_type (e.g. 'Bearer') to be used then this 843 parameter is REQUIRED. 845 Note that if CBOR Web Tokens [I-D.ietf-ace-cbor-web-token] are used, 846 the access token can also contain a 'cnf' claim. This claim is 847 however consumed by a different party. The access token is created 848 by the AS and processed by the RS (and opaque to the client) whereas 849 the RS Information is created by the AS and processed by the client; 850 it is never forwarded to the resource server. 852 Figure Figure 5 summarizes the parameters that may be part of the RS 853 Information. 855 /-------------------+--------------------------\ 856 | Parameter name | Specified in | 857 |-------------------+--------------------------| 858 | access_token | RFC 6749 | 859 | token_type | RFC 6749 | 860 | expires_in | RFC 6749 | 861 | refresh_token | RFC 6749 | 862 | scope | RFC 6749 | 863 | state | RFC 6749 | 864 | profile | [[ this specification ]] | 865 | cnf | [[ this specification ]] | 866 \-------------------+--------------------------/ 868 Figure 5: RS Information parameters 870 The following examples illustrate different types of responses for 871 proof-of-possession tokens. 873 Figure 6 shows a response containing a token and a 'cnf' parameter 874 with a symmetric proof-of-possession key. Note that we assume a 875 DTLS-based communication security profile for this example, therefore 876 the Content-Type is "application/cbor". 878 Header: Created (Code=2.01) 879 Content-Type: "application/cbor" 880 Payload: 881 { 882 "access_token" : b64'SlAV32hkKG ... 883 (remainder of CWT omitted for brevity; 884 CWT contains COSE_Key in the 'cnf' claim)', 885 "profile" : "coap_dtls", 886 "expires_in" : "3600", 887 "cnf" : { 888 "COSE_Key" : { 889 "kty" : "Symmetric", 890 "kid" : b64'39Gqlw', 891 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 892 } 893 } 894 } 896 Figure 6: Example AS response with an access token bound to a 897 symmetric key. 899 6.4. Error Response 901 The error responses for CoAP-based interactions with the AS are 902 equivalent to the ones for HTTP-based interactions as defined in 903 section 5.2 of [RFC6749], with the following differences: 905 o The Content-Type MUST be specified by the communication security 906 profile used between client and AS. The raw payload before being 907 processed by the communication security protocol MUST be encoded 908 as a CBOR map. 909 o The CoAP response code 4.00 (Bad Request) MUST be used for all 910 error responses, except for invalid_client where the CoAP response 911 code 4.01 (Unauthorized) MAY be used under the same conditions as 912 specified in section 5.2 of [RFC6749]. 913 o The parameters "error", "error_description" and "error_uri" MAY be 914 abbreviated using the codes specified in table Figure 13. 915 o The error codes MAY be abbreviated using the codes specified in 916 table Figure 7. 918 /------------------------+----------+--------------\ 919 | error code | CBOR Key | Major Type | 920 |------------------------+----------+--------------| 921 | invalid_request | 0 | 0 (uint) | 922 | invalid_client | 1 | 0 | 923 | invalid_grant | 2 | 0 | 924 | unauthorized_client | 3 | 0 | 925 | unsupported_grant_type | 4 | 0 | 926 | invalid_scope | 5 | 0 | 927 \------------------------+----------+--------------/ 929 Figure 7: CBOR abbreviations for common error codes 931 6.5. Request and Response Parameters 933 This section provides more detail about the new parameters that can 934 be used in access token requests and responses, as well as 935 abbreviations for more compact encoding of existing parameters and 936 common parameter values. 938 6.5.1. Audience 940 This parameter specifies for which audience the client is requesting 941 a token. It should be encoded as CBOR text string (major type 3). 942 The formatting and semantics of these strings are application 943 specific. 945 6.5.2. Grant Type 947 The abbreviations in Figure 8 MAY be used in CBOR encodings instead 948 of the string values defined in [RFC6749]. 950 /--------------------+----------+--------------\ 951 | grant_type | CBOR Key | Major Type | 952 |--------------------+----------+--------------| 953 | password | 0 | 0 (uint) | 954 | authorization_code | 1 | 0 | 955 | client_credentials | 2 | 0 | 956 | refresh_token | 3 | 0 | 957 \--------------------+----------+--------------/ 959 Figure 8: CBOR abbreviations for common grant types 961 6.5.3. Token Type 963 The toke_type parameter is defined in [RFC6749], allowing the AS to 964 indicate to the client which type of access token it is receiving 965 (e.g. a bearer token). 967 This document registers the new value "pop" for the OAuth Access 968 Token Types registry, specifying a Proof-of-Possession token. How 969 the proof-of-possession is performed MUST be specified by the 970 profiles. 972 The values in the 'token_type' parameter MUST be CBOR text strings 973 (major type 3). 975 In this framework token type 'pop' MUST be assumed by default if the 976 AS does not provide a different value. 978 6.5.4. Profile 980 Profiles of this framework MUST define the communication protocol and 981 the communication security protocol between the client and the RS. 982 Furthermore profiles MUST define proof-of-possession methods, if they 983 support proof-of-possession tokens. 985 A profile MUST specify an identifier that is used to uniquely 986 identify itself in the 'profile' parameter. 988 Profiles MAY define additional parameters for both the token request 989 and the RS Information in the access token response in order to 990 support negotiation or signalling of profile specific parameters. 992 6.5.5. Confirmation 994 The "cnf" parameter identifies or provides the key used for proof-of- 995 possession or for authenticating the RS depending on the proof-of- 996 possession algorithm and the context cnf is used in. This framework 997 extends the definition of 'cnf' from [RFC7800] by adding CBOR/COSE 998 encodings and the use of 'cnf' for transporting keys in the RS 999 Information. 1001 The "cnf" parameter is used in the following contexts with the 1002 following meaning: 1004 o In the access token, to indicate the proof-of-possession key bound 1005 to this token. 1006 o In the token request C -> AS, to indicate the client's raw public 1007 key, or the key-identifier of a previously established key between 1008 C and RS. 1009 o In the token response AS -> C, to indicate either the symmetric 1010 key generated by the AS for proof-of-possession or the raw public 1011 key used by the RS to authenticate. 1012 o In the introspection response AS -> RS, to indicate the proof-of- 1013 possession key bound to the introspected token. 1014 o In the client token AS -> RS -> C, to indicate the proof-of- 1015 possession key bound to the access token. 1017 A CBOR encoded payload MAY contain the 'cnf' parameter with the 1018 following contents: 1020 COSE_Key In this case the 'cnf' parameter contains the proof-of- 1021 possession key to be used by the client. An example is shown in 1022 Figure 9. 1024 "cnf" : { 1025 "COSE_Key" : { 1026 "kty" : "EC", 1027 "kid" : h'11', 1028 "crv" : "P-256", 1029 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 1030 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 1031 } 1032 } 1034 Figure 9: Confirmation parameter containing a public key 1036 Note that the COSE_Key structure may contain an "alg" or "key_ops" 1037 parameter. If such parameters are present, a client MUST NOT use 1038 a key that is not compatible with the profile or proof-of- 1039 possession algorithm according to those parameters. 1041 COSE_Encrypted In this case the 'cnf' parameter contains an 1042 encrypted symmetric key destined for the client. The client is 1043 assumed to be able to decrypt the ciphertext of this parameter. 1044 The parameter is encoded as COSE_Encrypted object wrapping a 1045 COSE_Key object. Figure 10 shows an example of this type of 1046 encoding. 1048 "cnf" : { 1049 "COSE_Encrypted" : { 1050 993( 1051 [ h'a1010a' # protected header : {"alg" : "AES-CCM-16-64-128"} 1052 "iv" : b64'ifUvZaHFgJM7UmGnjA', # unprotected header 1053 b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext 1054 ] 1055 ) 1056 } 1057 } 1059 Figure 10: Confirmation parameter containing an encrypted symmetric 1060 key 1062 The ciphertext here could e.g. contain a symmetric key as in 1063 Figure 11. 1065 { 1066 "kty" : "Symmetric", 1067 "kid" : b64'39Gqlw', 1068 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1069 } 1071 Figure 11: Example plaintext of an encrypted cnf parameter 1073 Key Identifier In this case the 'cnf' parameter references a key 1074 that is assumed to be previously known by the recipient. This 1075 allows clients that perform repeated requests for an access token 1076 for the same audience but e.g. with different scopes to omit key 1077 transport in the access token, token request and token response. 1078 Figure 12 shows such an example. 1080 "cnf" : { 1081 "kid" : b64'39Gqlw' 1082 } 1084 Figure 12: A Confirmation parameter with just a key identifier 1086 This specification establishes the IANA "CWT Confirmation Methods" 1087 registry for these types of confirmation methods in Section 11.10 and 1088 registers the methods defined by this specification. Other 1089 specifications can register other methods used for confirmation. The 1090 registry is meant to be analogous to the "JWT Confirmation Methods" 1091 registry defined by [RFC7800]. 1093 6.6. Mapping parameters to CBOR 1095 All OAuth parameters in access token requests and responses are 1096 mapped to CBOR types as follows and are given an integer key value to 1097 save space. 1099 /-------------------+----------+-----------------\ 1100 | Parameter name | CBOR Key | Major Type | 1101 |-------------------+----------+-----------------| 1102 | aud | 3 | 3 | 1103 | client_id | 8 | 3 (text string) | 1104 | client_secret | 9 | 2 (byte string) | 1105 | response_type | 10 | 3 | 1106 | redirect_uri | 11 | 3 | 1107 | scope | 12 | 3 | 1108 | state | 13 | 3 | 1109 | code | 14 | 2 | 1110 | error | 15 | 3 | 1111 | error_description | 16 | 3 | 1112 | error_uri | 17 | 3 | 1113 | grant_type | 18 | 0 | 1114 | access_token | 19 | 3 | 1115 | token_type | 20 | 0 | 1116 | expires_in | 21 | 0 | 1117 | username | 22 | 3 | 1118 | password | 23 | 3 | 1119 | refresh_token | 24 | 3 | 1120 | cnf | 25 | 5 (map) | 1121 | profile | 26 | 3 | 1122 \-------------------+----------+-----------------/ 1124 Figure 13: CBOR mappings used in token requests 1126 7. The 'Introspect' Endpoint 1128 Token introspection [RFC7662] is used by the RS and potentially the 1129 client to query the AS for metadata about a given token e.g. validity 1130 or scope. Analogous to the protocol defined in RFC 7662 [RFC7662] 1131 for HTTP and JSON, this section defines adaptations to more 1132 constrained environments using CoAP and CBOR. 1134 Communication between the RS and the introspection endpoint at the AS 1135 MUST be integrity protected and encrypted. Furthermore AS and RS 1136 MUST perform mutual authentication. Finally the AS SHOULD verify 1137 that the RS has the right to access introspection information about 1138 the provided token. Profiles of this framework that support 1139 introspection MUST specify how authentication and communication 1140 security between RS and AS is implemented. 1142 The figures of this section uses CBOR diagnostic notation without the 1143 integer abbreviations for the parameters or their values for better 1144 readability. 1146 7.1. RS-to-AS Request 1148 The RS sends a CoAP POST request to the introspection endpoint at the 1149 AS, the profile MUST specify the Content-Type and wrapping of the 1150 payload. The payload MUST be encoded as a CBOR map with a 'token' 1151 parameter containing the access token along with optional parameters 1152 representing additional context that is known by the RS to aid the AS 1153 in its response. 1155 The same parameters are required and optional as in section 2.1 of 1156 RFC 7662 [RFC7662]. 1158 For example, Figure 14 shows a RS calling the token introspection 1159 endpoint at the AS to query about an OAuth 2.0 proof-of-possession 1160 token. Note that we assume a object security-based communication 1161 security profile for this example, therefore the Content-Type is 1162 "application/cose+cbor". 1164 Header: POST (Code=0.02) 1165 Uri-Host: "server.example.com" 1166 Uri-Path: "introspect" 1167 Content-Type: "application/cose+cbor" 1168 Payload: 1169 { 1170 "token" : b64'7gj0dXJQ43U', 1171 "token_type_hint" : "pop" 1172 } 1174 Figure 14: Example introspection request. 1176 7.2. AS-to-RS Response 1178 If the introspection request is authorized and successfully 1179 processed, the AS sends a response with the CoAP response code 2.01 1180 (Created). If the introspection request was invalid, not authorized 1181 or couldn't be processed the AS returns an error response as 1182 described in Section 7.3. 1184 In a successful response, the AS encodes the response parameters in a 1185 CBOR map including with the same required and optional parameters as 1186 in section 2.2. of RFC 7662 [RFC7662] with the following additions: 1188 cnf 1189 OPTIONAL. This field contains information about the proof-of- 1190 possession key that binds the client to the access token. See 1191 Section 6.5.5 for more details on the formatting of the 'cnf' 1192 parameter. 1194 profile 1195 OPTIONAL. This indicates the profile that the RS MUST use with 1196 the client. See Section 6.5.4 for more details on the formatting 1197 of this parameter. 1199 client_token 1200 OPTIONAL. This parameter contains information that the RS MUST 1201 pass on to the client. See Section 7.4 for more details. 1203 For example, Figure 15 shows an AS response to the introspection 1204 request in Figure 14. Note that we assume a DTLS-based communication 1205 security profile for this example, therefore the Content-Type is 1206 "application/cbor". 1208 Header: Created Code=2.01) 1209 Content-Type: "application/cbor" 1210 Payload: 1211 { 1212 "active" : true, 1213 "scope" : "read", 1214 "profile" : "coap_dtls", 1215 "client_token" : b64'2QPhg0OhAQo ... 1216 (remainder of client token omitted for brevity)', 1217 "cnf" : { 1218 "COSE_Key" : { 1219 "kty" : "Symmetric", 1220 "kid" : b64'39Gqlw', 1221 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1222 } 1223 } 1224 } 1226 Figure 15: Example introspection response. 1228 7.3. Error Response 1230 The error responses for CoAP-based interactions with the AS are 1231 equivalent to the ones for HTTP-based interactions as defined in 1232 section 2.3 of [RFC7662], with the following differences: 1234 o If content is sent, the Content-Type MUST be set according to the 1235 specification of the communication security profile, and the 1236 content payload MUST be encoded as a CBOR map. 1237 o If the credentials used by the RS are invalid the AS MUST respond 1238 with the CoAP response code 4.01 (Unauthorized) and use the 1239 required and optional parameters from section 5.2 in RFC 6749 1240 [RFC6749]. 1241 o If the RS does not have the right to perform this introspection 1242 request, the AS MUST respond with the CoAP response code 4.03 1243 (Forbidden). In this case no payload is returned. 1244 o The parameters "error", "error_description" and "error_uri" MAY be 1245 abbreviated using the codes specified in table Figure 13. 1246 o The error codes MAY be abbreviated using the codes specified in 1247 table Figure 7. 1249 Note that a properly formed and authorized query for an inactive or 1250 otherwise invalid token does not warrant an error response by this 1251 specification. In these cases, the authorization server MUST instead 1252 respond with an introspection response with the "active" field set to 1253 "false". 1255 7.4. Client Token 1257 EDITORIAL NOTE: We have tentatively introduced this concept and would 1258 specifically like feedback whether this is viewed as a useful 1259 addition to the framework. 1261 In cases where the client has limited connectivity and needs to get 1262 access to a previously unknown resource servers, this framework 1263 suggests the following approach: The client is pre-configured with a 1264 generic, long-term access token when it is commissioned. When the 1265 client then tries to access a RS it transmits this access token. The 1266 RS then performs token introspection to learn what access this token 1267 grants. In the introspection response, the AS also relays 1268 information for the client, such as the proof-of-possession key, 1269 through the RS. The RS passes on this Client Token to the client in 1270 response to the submission of the token. 1272 The client_token parameter is designed to carry such information, and 1273 is intended to be used as described in Figure 16. 1275 Resource Authorization 1276 Client Server Server 1277 | | | 1278 | | | 1279 C: +--------------->| | 1280 | POST | | 1281 | Access Token | | 1282 | D: +--------------->| 1283 | | Introspection | 1284 | | Request | 1285 | | | 1286 | E: +<---------------+ 1287 | | Introspection | 1288 | | Response | 1289 | | + Client Token | 1290 |<---------------+ | 1291 | 2.01 Created | | 1292 | + Client Token | 1294 Figure 16: Use of the client_token parameter. 1296 The client token is a COSE_Encrypted object, containing as payload a 1297 CBOR map with the following claims: 1299 cnf 1300 REQUIRED if the token type is 'pop', OPTIONAL otherwise. Contains 1301 information about the proof-of-possession key the client is to use 1302 with its access token. See Section 6.5.5. 1304 token_type 1305 OPTIONAL. See Section 6.5.3. 1307 profile 1308 REQUIRED. See Section 6.5.4. 1310 rs_cnf 1311 OPTIONAL. Contains information about the key that the RS uses to 1312 authenticate towards the client. If the key is symmetric then 1313 this claim MUST NOT be part of the Client Token, since this is the 1314 same key as the one specified through the 'cnf' claim. This claim 1315 uses the same encoding as the 'cnf' parameter. See Section 6.5.4. 1317 The AS encrypts this token using a key shared between the AS and the 1318 client, so that only the client can decrypt it and access its 1319 payload. How this key is established is out of scope of this 1320 framework. 1322 7.5. Mapping Introspection parameters to CBOR 1324 The introspection request and response parameters are mapped to CBOR 1325 types as follows and are given an integer key value to save space. 1327 /-----------------+----------+-----------------\ 1328 | Parameter name | CBOR Key | Major Type | 1329 |-----------------+----------+-----------------| 1330 | iss | 1 | 3 (text string) | 1331 | sub | 2 | 3 | 1332 | aud | 3 | 3 | 1333 | exp | 4 | 6 tag value 1 | 1334 | nbf | 5 | 6 tag value 1 | 1335 | iat | 6 | 6 tag value 1 | 1336 | cti | 7 | 2 (byte string) | 1337 | client_id | 8 | 3 | 1338 | scope | 12 | 3 | 1339 | token_type | 20 | 3 | 1340 | username | 22 | 3 | 1341 | cnf | 25 | 5 (map) | 1342 | profile | 26 | 0 (uint) | 1343 | token | 27 | 3 | 1344 | token_type_hint | 28 | 3 | 1345 | active | 29 | 0 | 1346 | client_token | 30 | 3 | 1347 | rs_cnf | 31 | 5 | 1348 \-----------------+----------+-----------------/ 1350 Figure 17: CBOR Mappings to Token Introspection Parameters. 1352 8. The Access Token 1354 This framework RECOMMENDS the use of CBOR web token (CWT) as 1355 specified in [I-D.ietf-ace-cbor-web-token]. 1357 In order to facilitate offline processing of access tokens, this 1358 draft specifies the "cnf" and "scope" claims for CBOR web tokens. 1360 The "scope" claim explicitly encodes the scope of a given access 1361 token. This claim follows the same encoding rules as defined in 1362 section 3.3 of [RFC6749]. The meaning of a specific scope value is 1363 application specific and expected to be known to the RS running that 1364 application. 1366 The "cnf" claim follows the same rules as specified for JSON web 1367 token in RFC7800 [RFC7800], except that it is encoded in CBOR in the 1368 same way as specified for the "cnf" parameter in Section 6.5.5. 1370 8.1. The 'Authorization Information' Endpoint 1372 The access token, containing authorization information and 1373 information about the key used by the client, needs to be transported 1374 to the RS so that the RS can authenticate and authorize the client 1375 request. 1377 This section defines a method for transporting the access token to 1378 the RS using CoAP. Profiles of this framework MAY define other 1379 methods for token transport. 1381 The method consists of an /authz-info endpoint, implemented by the 1382 RS. A client using this method MUST make a POST request to /authz- 1383 info at the RS with the access token in the payload. The RS 1384 receiving the token MUST verify the validity of the token. If the 1385 token is valid, the RS MUST respond to the POST request with 2.01 1386 (Created). This response MAY contain the identifier of the token 1387 (e.g. the cti for a CWT) as a payload. 1389 If the token is not valid, the RS MUST respond with the CoAP response 1390 code 4.01 (Unauthorized). If the token is valid but the audience of 1391 the token does not match the RS, the RS MUST respond with the CoAP 1392 response code 4.03 (Forbidden). If the token is valid but is 1393 associated to claims that the RS cannot process (e.g. an unknown 1394 scope) the RS MUST respond with the CoAP response code 4.00 (Bad 1395 Request). In the latter case the RS MAY provide additional 1396 information in the error response, in order to clarify what went 1397 wrong. 1399 The RS MAY make an introspection request to validate the token before 1400 responding to the POST /authz-info request. If the introspection 1401 response contains a client token (Section 7.4) then this token SHALL 1402 be included in the payload of the 2.01 (Created) response. 1404 Profiles MUST specify how the /authz-info endpoint is protected. 1405 Note that since the token contains information that allow the client 1406 and the RS to establish a security context in the first place, mutual 1407 authentication may not be possible at this point. 1409 The RS MUST be prepared to store more than one token for each client, 1410 and MUST apply the combined permissions granted by all applicable, 1411 valid tokens to client requests. 1413 8.2. Token Expiration 1415 Depending on the capabilities of the RS, there are various ways in 1416 which it can verify the validity of a received access token. We list 1417 the possibilities here including what functionality they require of 1418 the RS. 1420 o The token is a CWT/JWT and includes a 'exp' claim and possibly the 1421 'nbf' claim. The RS verifies these by comparing them to values 1422 from its internal clock as defined in [RFC7519]. In this case the 1423 RS's internal clock must reflect the current date and time, or at 1424 least be synchronized with the AS's clock. How this clock 1425 synchronization would be performed is out of scope for this memo. 1426 o The RS verifies the validity of the token by performing an 1427 introspection request as specified in Section 7. This requires 1428 the RS to have a reliable network connection to the AS and to be 1429 able to handle two secure sessions in parallel (C to RS and AS to 1430 RS). 1431 o The RS and the AS both store a sequence number linked to their 1432 common security association. The AS increments this number for 1433 each access token it issues and includes it in the access token, 1434 which is a CWT/JWT. The RS keeps track of the most recently 1435 received sequence number, and only accepts tokens as valid, that 1436 are in a certain range around this number. This method does only 1437 require the RS to keep track of the sequence number. The method 1438 does not provide timely expiration, but it makes sure that older 1439 tokens cease to be valid after a certain number of newer ones got 1440 issued. For a constrained RS with no network connectivity and no 1441 means of reliably measuring time, this is the best that can be 1442 achieved. 1444 If a token, that authorizes a long running request such as e.g. a 1445 CoAP Observe [RFC7641], expires, the RS MUST send an error response 1446 with the response code 4.01 Unauthorized to the client and then 1447 terminate processing the long running request. 1449 9. Security Considerations 1451 The entire document is about security. Security considerations 1452 applicable to authentication and authorization in RESTful 1453 environments provided in OAuth 2.0 [RFC6749] apply to this work, as 1454 well as the security considerations from [I-D.ietf-ace-actors]. 1455 Furthermore [RFC6819] provides additional security considerations for 1456 OAuth which apply to IoT deployments as well. 1458 A large range of threats can be mitigated by protecting the contents 1459 of the access token by using a digital signature or a keyed message 1460 digest. Consequently, the token integrity protection MUST be applied 1461 to prevent the token from being modified, particularly since it 1462 contains a reference to the symmetric key or the asymmetric key. If 1463 the access token contains the symmetric key, this symmetric key MUST 1464 be encrypted by the authorization server with a long-term key shared 1465 with the resource server. 1467 It is important for the authorization server to include the identity 1468 of the intended recipient (the audience), typically a single resource 1469 server (or a list of resource servers), in the token. Using a single 1470 shared secret with multiple resource servers to simplify key 1471 management is NOT RECOMMENDED since the benefit from using the proof- 1472 of-possession concept is significantly reduced. 1474 Token replay is also more difficult since an eavesdropper will have 1475 to obtain the token and the corresponding private key or shared 1476 secret that is bound to the access token. Nevertheless, it is good 1477 practice to limit the lifetime of the access token and therefore the 1478 lifetime of associated key. 1480 The authorization server MUST offer confidentiality protection for 1481 any interactions with the client. This step is extremely important 1482 since the client will obtain the session key from the authorization 1483 server for use with a specific access token. Not using 1484 confidentiality protection exposes this secret (and the access token) 1485 to an eavesdropper thereby completely negating proof-of-possession 1486 security. Profiles MUST specify how confidentiality protection is 1487 provided, and additional protection can be applied by encrypting the 1488 token, for example encryption of CWTs is specified in section 5.1 of 1489 [I-D.ietf-ace-cbor-web-token]. 1491 Developers MUST ensure that the ephemeral credentials (i.e., the 1492 private key or the session key) are not leaked to third parties. An 1493 adversary in possession of the ephemeral credentials bound to the 1494 access token will be able to impersonate the client. Be aware that 1495 this is a real risk with many constrained environments, since 1496 adversaries can often easily get physical access to the devices. 1498 Clients can at any time request a new proof-of-possession capable 1499 access token. Using a refresh token to regularly request new access 1500 tokens that are bound to fresh and unique keys is important if the 1501 client has this capability. Keeping the lifetime of the access token 1502 short allows the authorization server to use shorter key sizes, which 1503 translate to a performance benefit for the client and for the 1504 resource server. Shorter keys also lead to shorter messages 1505 (particularly with asymmetric keying material). 1507 When authorization servers bind symmetric keys to access tokens, they 1508 SHOULD scope these access tokens to a specific permissions. 1509 Furthermore access tokens SHOULD NOT apply to an audience that 1510 comprises more than one RS, since otherwise any RS in the audience 1511 can impersonate the client towards the other members of the audience. 1513 Clients using an asymmetric key pair for proof-of-possession towards 1514 several different RS should be aware that they will need to rotate 1515 that key pair more frequently than if it was only used towards a 1516 single RS. 1518 10. Privacy Considerations 1520 Implementers and users should be aware of the privacy implications of 1521 the different possible deployments of this framework. 1523 The AS is in a very central position can potentially learn sensitive 1524 information about the clients requesting access tokens. If the 1525 client credentials grant is used, the AS can track what kind of 1526 access the client intends to perform. With other grants, the 1527 Resource Owner can bind the grants to anonymous (rotating) 1528 credentials, that do not allow the AS to link different access token 1529 requests by the same client. 1531 If access tokens are only integrity protected and not encrypted, they 1532 may reveal information to attackers listening on the wire, or able to 1533 acquire the access tokens in some other way. In the case of CWTs or 1534 JWTs the token may e.g. reveal the audience, the scope and the 1535 confirmation method used by the client. The latter may reveal the 1536 client's identity. 1538 Clients using asymmetric keys for proof-of-possession should be aware 1539 of the consequences of using the same key pair for proof-of- 1540 possession towards different RS. A set of colluding RS or an 1541 attacker able to obtain the access tokens will be able to link the 1542 requests, or even to determine the client's identity. 1544 11. IANA Considerations 1546 This specification registers new parameters for OAuth and establishes 1547 registries for mappings to CBOR. 1549 11.1. OAuth Introspection Response Parameter Registration 1551 This specification registers the following parameters in the OAuth 1552 introspection response parameters 1554 o Name: "cnf" 1555 o Description: Key to prove the right to use an access token, as 1556 defined in [RFC7800]. 1557 o Change Controller: IESG 1558 o Specification Document(s): this document 1560 o Name: "aud" 1561 o Description: Reference to intended receiving RS, as defined in PoP 1562 token specification. 1563 o Change Controller: IESG 1564 o Specification Document(s): this document 1566 o Name: "profile" 1567 o Description: The communication and communication security profile 1568 used between client and RS, as defined in ACE profiles. 1569 o Change Controller: IESG 1570 o Specification Document(s): this document 1572 o Name: "client_token" 1573 o Description: Information that the RS MUST pass to the client e.g. 1574 about the proof-of-possession keys. 1575 o Change Controller: IESG 1576 o Specification Document(s): this document 1578 o Name: "rs_cnf" 1579 o Description: Describes the public key the RS uses to authenticate. 1580 o Change Controller: IESG 1581 o Specification Document(s): this document 1583 11.2. OAuth Parameter Registration 1585 This specification registers the following parameters in the OAuth 1586 Parameters Registry 1588 o Parameter name: "profile" 1589 o Parameter usage location: token request, and token response 1590 o Change Controller: IESG 1591 o Specification Document(s): this document 1593 o Name: "cnf" 1594 o Description: Key to prove the right to use an access token, as 1595 defined in [RFC7800]. 1596 o Change Controller: IESG 1597 o Specification Document(s): this document 1599 11.3. OAuth Access Token Types 1601 This specification registers the following new token type in the 1602 OAuth Access Token Types Registry 1604 o Name: "PoP" 1605 o Description: A proof-of-possession token. 1606 o Change Controller: IESG 1607 o Specification Document(s): this document 1609 11.4. Token Type Mappings 1611 A new registry will be requested from IANA, entitled "Token Type 1612 Mappings". The registry is to be created as Expert Review Required. 1614 11.4.1. Registration Template 1616 Token Type: 1617 Name of token type as registered in the OAuth token type registry 1618 e.g. "Bearer". 1619 Mapped value: 1620 Integer representation for the token type value. The key value 1621 MUST be an integer in the range of 1 to 65536. 1622 Change Controller: 1623 For Standards Track RFCs, list the "IESG". For others, give the 1624 name of the responsible party. Other details (e.g., postal 1625 address, email address, home page URI) may also be included. 1626 Specification Document(s): 1627 Reference to the document or documents that specify the 1628 parameter,preferably including URIs that can be used to retrieve 1629 copies of the documents. An indication of the relevant sections 1630 may also be included but is not required. 1632 11.4.2. Initial Registry Contents 1634 o Parameter name: "Bearer" 1635 o Mapped value: 1 1636 o Change Controller: IESG 1637 o Specification Document(s): this document 1639 o Parameter name: "pop" 1640 o Mapped value: 2 1641 o Change Controller: IESG 1642 o Specification Document(s): this document 1644 11.5. CBOR Web Token Claims 1646 This specification registers the following new claims in the CBOR Web 1647 Token (CWT) registry: 1649 o Claim Name: "scope" 1650 o Claim Description: The scope of an access token as defined in 1651 [RFC6749]. 1652 o Change Controller: IESG 1653 o Specification Document(s): this document 1655 o Claim Name: "cnf" 1656 o Claim Description: The proof-of-possession key of an access token 1657 as defined in [RFC7800]. 1658 o Change Controller: IESG 1659 o Specification Document(s): this document 1661 11.6. ACE Profile Registry 1663 A new registry will be requested from IANA, entitled "ACE Profile 1664 Registry". The registry is to be created as Expert Review Required. 1666 11.6.1. Registration Template 1668 Profile name: 1669 Name of the profile to be included in the profile attribute. 1670 Profile description: 1671 Text giving an overview of the profile and the context it is 1672 developed for. 1673 Profile ID: 1674 Integer value to identify the profile. The value MUST be an 1675 integer in the range of 1 to 65536. 1676 Change Controller: 1677 For Standards Track RFCs, list the "IESG". For others, give the 1678 name of the responsible party. Other details (e.g., postal 1679 address, email address, home page URI) may also be included. 1680 Specification Document(s): 1681 Reference to the document or documents that specify the 1682 parameter,preferably including URIs that can be used to retrieve 1683 copies of the documents. An indication of the relevant sections 1684 may also be included but is not required. 1686 11.7. OAuth Parameter Mappings Registry 1688 A new registry will be requested from IANA, entitled "Token Endpoint 1689 CBOR Mappings Registry". The registry is to be created as Expert 1690 Review Required. 1692 11.7.1. Registration Template 1694 Parameter name: 1695 OAuth Parameter name, refers to the name in the OAuth parameter 1696 registry e.g. "client_id". 1697 CBOR key value: 1698 Key value for the claim. The key value MUST be an integer in the 1699 range of 1 to 65536. 1700 Change Controller: 1701 For Standards Track RFCs, list the "IESG". For others, give the 1702 name of the responsible party. Other details (e.g., postal 1703 address, email address, home page URI) may also be included. 1705 Specification Document(s): 1706 Reference to the document or documents that specify the 1707 parameter,preferably including URIs that can be used to retrieve 1708 copies of the documents. An indication of the relevant sections 1709 may also be included but is not required. 1711 11.7.2. Initial Registry Contents 1713 o Parameter name: "aud" 1714 o CBOR key value: 3 1715 o Change Controller: IESG 1716 o Specification Document(s): this document 1718 o Parameter name: "client_id" 1719 o CBOR key value: 8 1720 o Change Controller: IESG 1721 o Specification Document(s): this document 1723 o Parameter name: "client_secret" 1724 o CBOR key value: 9 1725 o Change Controller: IESG 1726 o Specification Document(s): this document 1728 o Parameter name: "response_type" 1729 o CBOR key value: 10 1730 o Change Controller: IESG 1731 o Specification Document(s): this document 1733 o Parameter name: "redirect_uri" 1734 o CBOR key value: 11 1735 o Change Controller: IESG 1736 o Specification Document(s): this document 1738 o Parameter name: "scope" 1739 o CBOR key value: 12 1740 o Change Controller: IESG 1741 o Specification Document(s): this document 1743 o Parameter name: "state" 1744 o CBOR key value: 13 1745 o Change Controller: IESG 1746 o Specification Document(s): this document 1748 o Parameter name: "code" 1749 o CBOR key value: 14 1750 o Change Controller: IESG 1751 o Specification Document(s): this document 1752 o Parameter name: "error" 1753 o CBOR key value: 15 1754 o Change Controller: IESG 1755 o Specification Document(s): this document 1757 o Parameter name: "error_description" 1758 o CBOR key value: 16 1759 o Change Controller: IESG 1760 o Specification Document(s): this document 1762 o Parameter name: "error_uri" 1763 o CBOR key value: 17 1764 o Change Controller: IESG 1765 o Specification Document(s): this document 1767 o Parameter name: "grant_type" 1768 o CBOR key value: 18 1769 o Change Controller: IESG 1770 o Specification Document(s): this document 1772 o Parameter name: "access_token" 1773 o CBOR key value: 19 1774 o Change Controller: IESG 1775 o Specification Document(s): this document 1777 o Parameter name: "token_type" 1778 o CBOR key value: 20 1779 o Change Controller: IESG 1780 o Specification Document(s): this document 1782 o Parameter name: "expires_in" 1783 o CBOR key value: 21 1784 o Change Controller: IESG 1785 o Specification Document(s): this document 1787 o Parameter name: "username" 1788 o CBOR key value: 22 1789 o Change Controller: IESG 1790 o Specification Document(s): this document 1792 o Parameter name: "password" 1793 o CBOR key value: 23 1794 o Change Controller: IESG 1795 o Specification Document(s): this document 1797 o Parameter name: "refresh_token" 1798 o CBOR key value: 24 1799 o Change Controller: IESG 1800 o Specification Document(s): this document 1802 o Parameter name: "cnf" 1803 o CBOR key value: 25 1804 o Change Controller: IESG 1805 o Specification Document(s): this document 1807 o Parameter name: "profile" 1808 o CBOR key value: 26 1809 o Change Controller: IESG 1810 o Specification Document(s): this document 1812 11.8. Introspection Endpoint CBOR Mappings Registry 1814 A new registry will be requested from IANA, entitled "Introspection 1815 Endpoint CBOR Mappings Registry". The registry is to be created as 1816 Expert Review Required. 1818 11.8.1. Registration Template 1820 Response parameter name: 1821 Name of the response parameter as defined in the "OAuth Token 1822 Introspection Response" registry e.g. "active". 1823 CBOR key value: 1824 Key value for the claim. The key value MUST be an integer in the 1825 range of 1 to 65536. 1826 Change Controller: 1827 For Standards Track RFCs, list the "IESG". For others, give the 1828 name of the responsible party. Other details (e.g., postal 1829 address, email address, home page URI) may also be included. 1830 Specification Document(s): 1831 Reference to the document or documents that specify the 1832 parameter,preferably including URIs that can be used to retrieve 1833 copies of the documents. An indication of the relevant sections 1834 may also be included but is not required. 1836 11.8.2. Initial Registry Contents 1838 o Response parameter name: "iss" 1839 o CBOR key value: 1 1840 o Change Controller: IESG 1841 o Specification Document(s): this document 1843 o Response parameter name: "sub" 1844 o CBOR key value: 2 1845 o Change Controller: IESG 1846 o Specification Document(s): this document 1847 o Response parameter name: "aud" 1848 o CBOR key value: 3 1849 o Change Controller: IESG 1850 o Specification Document(s): this document 1852 o Response parameter name: "exp" 1853 o CBOR key value: 4 1854 o Change Controller: IESG 1855 o Specification Document(s): this document 1857 o Response parameter name: "nbf" 1858 o CBOR key value: 5 1859 o Change Controller: IESG 1860 o Specification Document(s): this document 1862 o Response parameter name: "iat" 1863 o CBOR key value: 6 1864 o Change Controller: IESG 1865 o Specification Document(s): this document 1867 o Response parameter name: "cti" 1868 o CBOR key value: 7 1869 o Change Controller: IESG 1870 o Specification Document(s): this document 1872 o Response parameter name: "client_id" 1873 o CBOR key value: 8 1874 o Change Controller: IESG 1875 o Specification Document(s): this document 1877 o Response parameter name: "scope" 1878 o CBOR key value: 12 1879 o Change Controller: IESG 1880 o Specification Document(s): this document 1882 o Response parameter name: "token_type" 1883 o CBOR key value: 20 1884 o Change Controller: IESG 1885 o Specification Document(s): this document 1887 o Response parameter name: "username" 1888 o CBOR key value: 22 1889 o Change Controller: IESG 1890 o Specification Document(s): this document 1892 o Parameter name: "cnf" 1893 o CBOR key value: 25 1894 o Change Controller: IESG 1895 o Specification Document(s): this document 1897 o Parameter name: "profile" 1898 o CBOR key value: 26 1899 o Change Controller: IESG 1900 o Specification Document(s): this document 1902 o Response parameter name: "token" 1903 o CBOR key value: 27 1904 o Change Controller: IESG 1905 o Specification Document(s): this document 1907 o Response parameter name: "token_type_hint" 1908 o CBOR key value: 28 1909 o Change Controller: IESG 1910 o Specification Document(s): this document 1912 o Response parameter name: "active" 1913 o CBOR key value: 29 1914 o Change Controller: IESG 1915 o Specification Document(s): this document 1917 o Response parameter name: "client_token" 1918 o CBOR key value: 30 1919 o Change Controller: IESG 1920 o Specification Document(s): this document 1922 o Response parameter name: "rs_cnf" 1923 o CBOR key value: 31 1924 o Change Controller: IESG 1925 o Specification Document(s): this document 1927 11.9. CoAP Option Number Registration 1929 This section registers the "Access-Token" CoAP Option Number in the 1930 "CoRE Parameters" sub-registry "CoAP Option Numbers" in the manner 1931 described in [RFC7252]. 1933 Name 1935 Access-Token 1936 Number 1938 TBD 1939 Reference 1941 [This document]. 1942 Meaning in Request 1943 Contains an Access Token according to [This document] containing 1944 access permissions of the client. 1945 Meaning in Response 1947 Not used in response 1948 Safe-to-Forward 1950 Yes 1951 Format 1953 Based on the observer the format is perceived differently. Opaque 1954 data to the client and CWT or reference token to the RS. 1955 Length 1957 Less then 255 bytes 1959 11.10. CWT Confirmation Methods Registry 1961 This specification establishes the IANA "CWT Confirmation Methods" 1962 registry for CWT "cnf" member values. The registry records the 1963 confirmation method member and a reference to the specification that 1964 defines it. 1966 11.10.1. Registration Template 1968 Confirmation Method Name: 1969 The name requested (e.g., "kid"). This name is intended to be 1970 human readable and be used for debugging purposes. It is case 1971 sensitive. Names may not match other registered names in a case- 1972 insensitive manner unless the Designated Experts state that there 1973 is a compelling reason to allow an exception. 1975 Confirmation Method Value: 1976 Integer representation for the confirmation method value. 1977 Intended for use to uniquely identify the confirmation method. 1978 The value MUST be an integer in the range of 1 to 65536. 1980 Confirmation Method Description: 1981 Brief description of the confirmation method (e.g. "Key 1982 Identifier"). 1984 Change Controller: 1985 For Standards Track RFCs, list the "IESG". For others, give the 1986 name of the responsible party. Other details (e.g., postal 1987 address, email address, home page URI) may also be included. 1989 Specification Document(s): 1991 Reference to the document or documents that specify the parameter, 1992 preferably including URIs that can be used to retrieve copies of 1993 the documents. An indication of the relevant sections may also be 1994 included but is not required. 1996 11.10.2. Initial Registry Contents 1998 o Confirmation Method Name: "COSE_Key" 1999 o Confirmation Method Value: 1 2000 o Confirmation Method Description: A COSE_Key that is either a 2001 public key or a symmetric key. 2002 o Change Controller: IESG 2003 o Specification Document(s): this document 2005 o Confirmation Method Name: "COSE_Encrypted" 2006 o Confirmation Method Value: 2 2007 o Confirmation Method Description: A COSE_Encrypted structure that 2008 wraps a COSE_Key containing a symmetric key. 2009 o Change Controller: IESG 2010 o Specification Document(s): this document 2012 o Confirmation Method Name: "Key Identifier" 2013 o Confirmation Method Value: 3 2014 o Confirmation Method Description: A key identifier. 2015 o Change Controller: IESG 2016 o Specification Document(s): this document 2018 12. Acknowledgments 2020 We would like to thank Eve Maler for her contributions to the use of 2021 OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion 2022 input, and Malisa Vucinic for his input on the predecessors of this 2023 proposal. Finally, we would like to thank the ACE working group in 2024 general for their feedback. 2026 We would like to thank the authors of draft-ietf-oauth-pop-key- 2027 distribution, from where we copied large parts of our security 2028 considerations. 2030 Ludwig Seitz and Goeran Selander worked on this document as part of 2031 the CelticPlus project CyberWI, with funding from Vinnova. 2033 13. References 2034 13.1. Normative References 2036 [I-D.ietf-cose-msg] 2037 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2038 draft-ietf-cose-msg-24 (work in progress), November 2016. 2040 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2041 Requirement Levels", BCP 14, RFC 2119, 2042 DOI 10.17487/RFC2119, March 1997, 2043 . 2045 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2046 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2047 January 2012, . 2049 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2050 Application Protocol (CoAP)", RFC 7252, 2051 DOI 10.17487/RFC7252, June 2014, 2052 . 2054 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 2055 RFC 7662, DOI 10.17487/RFC7662, October 2015, 2056 . 2058 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 2059 Possession Key Semantics for JSON Web Tokens (JWTs)", 2060 RFC 7800, DOI 10.17487/RFC7800, April 2016, 2061 . 2063 13.2. Informative References 2065 [I-D.ietf-ace-actors] 2066 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 2067 architecture for authorization in constrained 2068 environments", draft-ietf-ace-actors-04 (work in 2069 progress), September 2016. 2071 [I-D.ietf-ace-cbor-web-token] 2072 Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 2073 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-02 2074 (work in progress), January 2017. 2076 [I-D.ietf-core-object-security] 2077 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2078 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 2079 object-security-01 (work in progress), December 2016. 2081 [I-D.ietf-oauth-device-flow] 2082 Denniss, W., Myrseth, S., Bradley, J., Jones, M., and H. 2083 Tschofenig, "OAuth 2.0 Device Flow", draft-ietf-oauth- 2084 device-flow-03 (work in progress), July 2016. 2086 [I-D.ietf-oauth-native-apps] 2087 Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2088 draft-ietf-oauth-native-apps-07 (work in progress), 2089 January 2017. 2091 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2092 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2093 . 2095 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2096 (TLS) Protocol Version 1.2", RFC 5246, 2097 DOI 10.17487/RFC5246, August 2008, 2098 . 2100 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2101 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2102 . 2104 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2105 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2106 . 2108 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 2109 Threat Model and Security Considerations", RFC 6819, 2110 DOI 10.17487/RFC6819, January 2013, 2111 . 2113 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2114 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2115 October 2013, . 2117 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2118 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2119 2014, . 2121 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2122 Constrained-Node Networks", RFC 7228, 2123 DOI 10.17487/RFC7228, May 2014, 2124 . 2126 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2127 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2128 DOI 10.17487/RFC7231, June 2014, 2129 . 2131 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2132 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2133 . 2135 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 2136 "Assertion Framework for OAuth 2.0 Client Authentication 2137 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 2138 May 2015, . 2140 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 2141 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 2142 RFC 7591, DOI 10.17487/RFC7591, July 2015, 2143 . 2145 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2146 Application Protocol (CoAP)", RFC 7641, 2147 DOI 10.17487/RFC7641, September 2015, 2148 . 2150 [RFC7744] Seitz, L., Ed., Gerdes, S., Ed., Selander, G., Mani, M., 2151 and S. Kumar, "Use Cases for Authentication and 2152 Authorization in Constrained Environments", RFC 7744, 2153 DOI 10.17487/RFC7744, January 2016, 2154 . 2156 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2157 the Constrained Application Protocol (CoAP)", RFC 7959, 2158 DOI 10.17487/RFC7959, August 2016, 2159 . 2161 Appendix A. Design Justification 2163 This section provides further insight into the design decisions of 2164 the solution documented in this document. Section 3 lists several 2165 building blocks and briefly summarizes their importance. The 2166 justification for offering some of those building blocks, as opposed 2167 to using OAuth 2.0 as is, is given below. 2169 Common IoT constraints are: 2171 Low Power Radio: 2173 Many IoT devices are equipped with a small battery which needs to 2174 last for a long time. For many constrained wireless devices the 2175 highest energy cost is associated to transmitting or receiving 2176 messages. It is therefore important to keep the total 2177 communication overhead low, including minimizing the number and 2178 size of messages sent and received, which has an impact of choice 2179 on the message format and protocol. By using CoAP over UDP, and 2180 CBOR encoded messages some of these aspects are addressed. 2181 Security protocols contribute to the communication overhead and 2182 can in some cases be optimized. For example authentication and 2183 key establishment may in certain cases where security requirements 2184 so allows be replaced by provisioning of security context by a 2185 trusted third party, using transport or application layer 2186 security. 2188 Low CPU Speed: 2190 Some IoT devices are equipped with processors that are 2191 significantly slower than those found in most current devices on 2192 the Internet. This typically has implications on what timely 2193 cryptographic operations a device is capable to perform, which in 2194 turn impacts e.g. protocol latency. Symmetric key cryptography 2195 may be used instead of the computationally more expensive public 2196 key cryptography where the security requirements so allows, but 2197 this may also require support for trusted third party assisted 2198 secret key establishment using transport or application layer 2199 security. 2201 Small Amount of Memory: 2203 Microcontrollers embedded in IoT devices are often equipped with 2204 small amount of RAM and flash memory, which places limitations 2205 what kind of processing can be performed and how much code can be 2206 put on those devices. To reduce code size fewer and smaller 2207 protocol implementations can be put on the firmware of such a 2208 device. In this case, CoAP may be used instead of HTTP, symmetric 2209 key cryptography instead of public key cryptography, and CBOR 2210 instead of JSON. Authentication and key establishment protocol, 2211 e.g. the DTLS handshake, in comparison with assisted key 2212 establishment also has an impact on memory and code. 2214 User Interface Limitations: 2216 Protecting access to resources is both an important security as 2217 well as privacy feature. End users and enterprise customers do 2218 not want to give access to the data collected by their IoT device 2219 or to functions it may offer to third parties. Since the 2220 classical approach of requesting permissions from end users via a 2221 rich user interface does not work in many IoT deployment scenarios 2222 these functions need to be delegated to user controlled devices 2223 that are better suitable for such tasks, such as smart phones and 2224 tablets. 2225 Communication Constraints: 2227 In certain constrained settings an IoT device may not be able to 2228 communicate with a given device at all times. Devices may be 2229 sleeping, or just disconnected from the Internet because of 2230 general lack of connectivity in the area, for cost reasons, or for 2231 security reasons, e.g. to avoid an entry point for Denial-of- 2232 Service attacks. 2234 The communication interactions this framework builds upon (as 2235 shown graphically in Figure 1) may be accomplished using a variety 2236 of different protocols, and not all parts of the message flow are 2237 used in all applications due to the communication constraints. 2238 While we envision deployments to make use of CoAP we explicitly 2239 want to support HTTP, HTTP/2 or specific protocols, such as 2240 Bluetooth Smart communication, which does not necessarily use IP. 2241 The latter raises the need for application layer security over the 2242 various interfaces. 2244 Appendix B. Roles and Responsibilities 2246 Resource Owner 2248 * Make sure that the RS is registered at the AS. This includes 2249 making known to the AS which profiles, token_types, scopes, and 2250 key types (symmetric/asymmetric) the RS supports. Also making 2251 it known to the AS which audience(s) the RS identifies itself 2252 with. 2253 * Make sure that clients can discover the AS which is in charge 2254 of the RS. 2255 * If the client-credentials grant is used, make sure that the AS 2256 has the necessary, up-to-date, access control policies for the 2257 RS. 2259 Requesting Party 2261 * Make sure that the client is provisioned the necessary 2262 credentials to authenticate to the AS. 2263 * Make sure that the client is configured to follow the security 2264 requirements of the Requesting Party, when issuing requests 2265 (e.g. minimum communication security requirements, trust 2266 anchors). 2268 * Register the client at the AS. This includes making known to 2269 the AS which profiles, token_types, and key types (symmetric/ 2270 asymmetric) the client. 2272 Authorization Server 2274 * Register RS and manage corresponding security contexts. 2275 * Register clients and including authentication credentials. 2276 * Allow Resource Owners to configure and update access control 2277 policies related to their registered RS' 2278 * Expose the /token endpoint to allow clients to request tokens. 2279 * Authenticate clients that wish to request a token. 2280 * Process a token request against the authorization policies 2281 configured for the RS. 2282 * Optionally: Expose the /introspection endpoint that allows RS's 2283 to submit token introspection requests. 2284 * If providing an introspection endpoint: Authenticate RS's that 2285 wish to get an introspection response. 2286 * If providing an introspection endpoint: Process token 2287 introspection requests. 2288 * Optionally: Handle token revocation. 2290 Client 2292 * Discover the AS in charge of the RS that is to be targeted with 2293 a request. 2294 * Submit the token request (A). 2296 + Authenticate towards the AS. 2297 + Optionally (if not pre-configured): Specify which RS, which 2298 resource(s), and which action(s) the request(s) will target. 2299 + If raw public key (rpk) or certificate is used, make sure 2300 the AS has the right rpk or certificate for this client. 2301 * Process the access token and RS Information (B) 2303 + Check that the RS Information provides the necessary 2304 security parameters (e.g. PoP key, information on 2305 communication security protocols supported by the RS). 2306 * Send the token and request to the RS (C) 2308 + Authenticate towards the RS (this could coincide with the 2309 proof of possession process). 2310 + Transmit the token as specified by the AS (default is to the 2311 /authz-info endpoint, alternative options are specified by 2312 profiles). 2313 + Perform the proof-of-possession procedure as specified by 2314 the profile in use (this may already have been taken care of 2315 through the authentication procedure). 2317 * Process the RS response (F) requirements of the Requesting 2318 Party, when issuing requests (e.g. minimum communication 2319 security requirements, trust anchors). 2320 * Register the client at the AS. 2322 Resource Server 2324 * Expose a way to submit access tokens. By default this is the 2325 /authz-info endpoint. 2326 * Process an access token. 2328 + Verify the token is from the right AS. 2329 + Verify that the token applies to this RS. 2330 + Check that the token has not expired (if the token provides 2331 expiration information). 2332 + Check the token's integrity. 2333 + Store the token so that it can be retrieved in the context 2334 of a matching request. 2335 * Process a request. 2337 + Set up communication security with the client. 2338 + Authenticate the client. 2339 + Match the client against existing tokens. 2340 + Check that tokens belonging to the client actually authorize 2341 the requested action. 2342 + Optionally: Check that the matching tokens are still valid, 2343 using introspection (if this is possible.) 2344 * Send a response following the agreed upon communication 2345 security. 2347 Appendix C. Requirements on Profiles 2349 This section lists the requirements on profiles of this framework, 2350 for the convenience of a profile designer. 2352 o Optionally Specify the discovery process of how the client finds 2353 the right AS for an RS it wants to send a request to. Section 4 2354 o Specify the communication protocol the client and RS the must use 2355 (e.g. CoAP). Section 5 and Section 6.5.4 2356 o Specify the security protocol the client and RS must use to 2357 protect their communication (e.g. OSCOAP or DTLS over CoAP). 2358 This must provide encryption and integrity protection. 2359 Section 6.5.4 2360 o Specify how the client and the RS mutually authenticate. 2361 Section 4 2362 o Specify the Content-format of the protocol messages (e.g. 2363 "application/cbor" or "application/cose+cbor"). Section 4 2365 o Specify the proof-of-possession protocol(s) and how to select one, 2366 if several are available. Also specify which key types (e.g. 2367 symmetric/asymmetric) are supported by a specific proof-of- 2368 possession protocol. Section 6.5.3 2369 o Specify a unique profile identifier. Section 6.5.4 2370 o Optionally specify how the RS talks to the AS for 2371 introspection.Section 7 2372 o Optionally specify how the client talks to the AS for requesting a 2373 token. Section 6 2374 o Specify how/if the /authz-info endpoint is protected. Section 8.1 2375 o Optionally define other methods of token transport than the 2376 /authz-info endpoint. Section 8.1 2378 Appendix D. Assumptions on AS knowledge about C and RS 2380 This section lists the assumptions on what an AS should know about a 2381 client and a RS in order to be able to respond to requests to the 2382 /token and /introspect endpoints. How this information is 2383 established is out of scope for this document. 2385 o The identifier of the client or RS. 2386 o The profiles that the client or RS supports. 2387 o The scopes that the RS supports. 2388 o The audiences that the RS identifies with. 2389 o The key types (e.g. pre-shared symmetric key, raw public key, key 2390 length, other key parameters) that the client or RS supports. 2391 o The types of access tokens the RS supports (e.g. CWT). 2392 o If the RS supports CWTs, the COSE parameters for the crypto 2393 wrapper (e.g. algorithm, key-wrap algorithm, key-length). 2394 o The expiration time for access tokens issued to this RS (unless 2395 the RS accepts a default time chosen by the AS). 2396 o The symmetric key shared between client or RS and AS (if any). 2397 o The raw public key of the client or RS (if any). 2399 Appendix E. Deployment Examples 2401 There is a large variety of IoT deployments, as is indicated in 2402 Appendix A, and this section highlights a few common variants. This 2403 section is not normative but illustrates how the framework can be 2404 applied. 2406 For each of the deployment variants there are a number of possible 2407 security setups between clients, resource servers and authorization 2408 servers. The main focus in the following subsections is on how 2409 authorization of a client request for a resource hosted by a RS is 2410 performed. This requires the the security of the requests and 2411 responses between the clients and the RS to consider. 2413 Note: CBOR diagnostic notation is used for examples of requests and 2414 responses. 2416 E.1. Local Token Validation 2418 In this scenario we consider the case where the resource server is 2419 offline, i.e. it is not connected to the AS at the time of the access 2420 request. This access procedure involves steps A, B, C, and F of 2421 Figure 1. 2423 Since the resource server must be able to verify the access token 2424 locally, self-contained access tokens must be used. 2426 This example shows the interactions between a client, the 2427 authorization server and a temperature sensor acting as a resource 2428 server. Message exchanges A and B are shown in Figure 18. 2430 A: The client first generates a public-private key pair used for 2431 communication security with the RS. 2432 The client sends the POST request to /token at the AS. The 2433 security of this request can be transport or application layer, it 2434 is up the the communication security profile to define. In the 2435 example transport layer identification of the AS is done and the 2436 client identifies with client_id and client_secret as in classic 2437 OAuth. The request contains the public key of the client and the 2438 Audience parameter set to "tempSensorInLivingRoom", a value that 2439 the temperature sensor identifies itself with. The AS evaluates 2440 the request and authorizes the client to access the resource. 2441 B: The AS responds with a PoP token and RS Information. The PoP 2442 token contains the public key of the client, and the RS 2443 Information contains the public key of the RS. For communication 2444 security this example uses DTLS RawPublicKey between the client 2445 and the RS. The issued token will have a short validity time, 2446 i.e. 'exp' close to 'iat', to protect the RS from replay attacks. 2447 The token includes the claim such as "scope" with the authorized 2448 access that an owner of the temperature device can enjoy. In this 2449 example, the 'scope' claim, issued by the AS, informs the RS that 2450 the owner of the token, that can prove the possession of a key is 2451 authorized to make a GET request against the /temperature resource 2452 and a POST request on the /firmware resource. Note that the 2453 syntax and semantics of the scope claim are application specific. 2454 Note: In this example we assume that the client knows what 2455 resource it wants to access, and is therefore able to request 2456 specific audience and scope claims for the access token. 2458 Authorization 2459 Client Server 2460 | | 2461 |<=======>| DTLS Connection Establishment 2462 | | to identify the AS 2463 | | 2464 A: +-------->| Header: POST (Code=0.02) 2465 | POST | Uri-Path:"token" 2466 | | Content-Type: application/cbor 2467 | | Payload: 2468 | | 2469 B: |<--------+ Header: 2.05 Content 2470 | 2.05 | Content-Type: application/cbor 2471 | | Payload: 2472 | | 2474 Figure 18: Token Request and Response Using Client Credentials. 2476 The information contained in the Request-Payload and the Response- 2477 Payload is shown in Figure 19. Note that we assume a DTLS-based 2478 communication security profile for this example, therefore the 2479 Content-Type is "application/cbor". 2481 Request-Payload : 2482 { 2483 "grant_type" : "client_credentials", 2484 "aud" : "tempSensorInLivingRoom", 2485 "client_id" : "myclient", 2486 "client_secret" : "qwerty" 2487 } 2489 Response-Payload : 2490 { 2491 "access_token" : b64'SlAV32hkKG ...', 2492 "token_type" : "pop", 2493 "csp" : "DTLS", 2494 "cnf" : { 2495 "COSE_Key" : { 2496 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2497 "kty" : "EC", 2498 "crv" : "P-256", 2499 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 2500 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 2501 } 2502 } 2503 } 2505 Figure 19: Request and Response Payload Details. 2507 The content of the access token is shown in Figure 20. 2509 { 2510 "aud" : "tempSensorInLivingRoom", 2511 "iat" : "1360189224", 2512 "exp" : "1360289224", 2513 "scope" : "temperature_g firmware_p", 2514 "cnf" : { 2515 "jwk" : { 2516 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 2517 "kty" : "EC", 2518 "crv" : "P-256", 2519 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 2520 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 2521 } 2522 } 2523 } 2525 Figure 20: Access Token including Public Key of the Client. 2527 Messages C and F are shown in Figure 21 - Figure 22. 2529 C: The client then sends the PoP token to the /authz-info endpoint 2530 at the RS. This is a plain CoAP request, i.e. no transport or 2531 application layer security between client and RS, since the token 2532 is integrity protected between AS and RS. The RS verifies that 2533 the PoP token was created by a known and trusted AS, is valid, and 2534 responds to the client. The RS caches the security context 2535 together with authorization information about this client 2536 contained in the PoP token. 2538 Resource 2539 Client Server 2540 | | 2541 C: +-------->| Header: POST (Code=0.02) 2542 | POST | Uri-Path:"authz-info" 2543 | | Payload: SlAV32hkKG ... 2544 | | 2545 |<--------+ Header: 2.04 Changed 2546 | 2.04 | 2547 | | 2549 Figure 21: Access Token provisioning to RS 2550 The client and the RS runs the DTLS handshake using the raw public 2551 keys established in step B and C. 2553 The client sends the CoAP request GET to /temperature on RS over 2554 DTLS. The RS verifies that the request is authorized, based on 2555 previously established security context. 2556 F: The RS responds with a resource representation over DTLS. 2558 Resource 2559 Client Server 2560 | | 2561 |<=======>| DTLS Connection Establishment 2562 | | using Raw Public Keys 2563 | | 2564 +-------->| Header: GET (Code=0.01) 2565 | GET | Uri-Path: "temperature" 2566 | | 2567 | | 2568 | | 2569 F: |<--------+ Header: 2.05 Content 2570 | 2.05 | Payload: 2571 | | 2573 Figure 22: Resource Request and Response protected by DTLS. 2575 E.2. Introspection Aided Token Validation 2577 In this deployment scenario we assume that a client is not able to 2578 access the AS at the time of the access request. Since the RS is, 2579 however, connected to the back-end infrastructure it can make use of 2580 token introspection. This access procedure involves steps A-F of 2581 Figure 1, but assumes steps A and B have been carried out during a 2582 phase when the client had connectivity to AS. 2584 Since the client is assumed to be offline, at least for a certain 2585 period of time, a pre-provisioned access token has to be long-lived. 2586 The resource server may use its online connectivity to validate the 2587 access token with the authorization server, which is shown in the 2588 example below. 2590 In the example interactions between an offline client (key fob), a RS 2591 (online lock), and an AS is shown. We assume that there is a 2592 provisioning step where the client has access to the AS. This 2593 corresponds to message exchanges A and B which are shown in 2594 Figure 23. 2596 Authorization consent from the resource owner can be pre-configured, 2597 but it can also be provided via an interactive flow with the resource 2598 owner. An example of this for the key fob case could be that the 2599 resource owner has a connected car, he buys a generic key that he 2600 wants to use with the car. To authorize the key fob he connects it 2601 to his computer that then provides the UI for the device. After that 2602 OAuth 2.0 implicit flow can used to authorize the key for his car at 2603 the the car manufacturers AS. 2605 Note: In this example the client does not know the exact door it will 2606 be used to access since the token request is not send at the time of 2607 access. So the scope and audience parameters is set quite wide to 2608 start with and new values different form the original once can be 2609 returned from introspection later on. 2611 A: The client sends the request using POST to /token at AS. The 2612 request contains the Audience parameter set to "PACS1337" (PACS, 2613 Physical Access System), a value the that the online door in 2614 question identifies itself with. The AS generates an access token 2615 as on opaque string, which it can match to the specific client, a 2616 targeted audience and a symmetric key. The security is provided 2617 by identifying the AS on transport layer using a pre shared 2618 security context (psk, rpk or certificate) and then the client is 2619 identified using client_id and client_secret as in classic OAuth 2620 B: The AS responds with the an access token and RS Information, 2621 the latter containing a symmetric key. Communication security 2622 between C and RS will be DTLS and PreSharedKey. The PoP key being 2623 used as the PreSharedKey. 2625 Authorization 2626 Client Server 2627 | | 2628 | | 2629 A: +-------->| Header: POST (Code=0.02) 2630 | POST | Uri-Path:"token" 2631 | | Content-Type: application/cbor 2632 | | Payload: 2633 | | 2634 B: |<--------+ Header: 2.05 Content 2635 | | Content-Type: application/cbor 2636 | 2.05 | Payload: 2637 | | 2639 Figure 23: Token Request and Response using Client Credentials. 2641 The information contained in the Request-Payload and the Response- 2642 Payload is shown in Figure 24. 2644 Request-Payload: 2645 { 2646 "grant_type" : "client_credentials", 2647 "aud" : "lockOfDoor4711", 2648 "client_id" : "keyfob", 2649 "client_secret" : "qwerty" 2650 } 2652 Response-Payload: 2653 { 2654 "access_token" : b64'SlAV32hkKG ...' 2655 "token_type" : "pop", 2656 "csp" : "DTLS", 2657 "cnf" : { 2658 "COSE_Key" : { 2659 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2660 "kty" : "oct", 2661 "alg" : "HS256", 2662 "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' 2663 } 2664 } 2665 } 2667 Figure 24: Request and Response Payload for C offline 2669 The access token in this case is just an opaque string referencing 2670 the authorization information at the AS. 2672 C: Next, the client POSTs the access token to the /authz-info 2673 endpoint in the RS. This is a plain CoAP request, i.e. no DTLS 2674 between client and RS. Since the token is an opaque string, the 2675 RS cannot verify it on its own, and thus defers to respond the 2676 client with a status code until after step E. 2677 D: The RS forwards the token to the /introspect endpoint on the 2678 AS. Introspection assumes a secure connection between the AS and 2679 the RS, e.g. using transport of application layer security. In 2680 the example AS is identified using pre shared security context 2681 (psk, rpk or certificate) while RS is acting as client and is 2682 identified with client_id and client_secret. 2683 E: The AS provides the introspection response containing 2684 parameters about the token. This includes the confirmation key 2685 (cnf) parameter that allows the RS to verify the client's proof of 2686 possession in step F. 2687 After receiving message E, the RS responds to the client's POST in 2688 step C with the CoAP response code 2.01 (Created). 2690 Resource 2691 Client Server 2692 | | 2693 C: +-------->| Header: POST (T=CON, Code=0.02) 2694 | POST | Uri-Path:"authz-info" 2695 | | Content-Type: "application/cbor" 2696 | | Payload: b64'SlAV32hkKG ...'' 2697 | | 2698 | | Authorization 2699 | | Server 2700 | | | 2701 | D: +--------->| Header: POST (Code=0.02) 2702 | | POST | Uri-Path: "introspect" 2703 | | | Content-Type: "application/cbor" 2704 | | | Payload: 2705 | | | 2706 | E: |<---------+ Header: 2.05 Content 2707 | | 2.05 | Content-Type: "application/cbor" 2708 | | | Payload: 2709 | | | 2710 | | 2711 |<--------+ Header: 2.01 Created 2712 | 2.01 | 2713 | | 2715 Figure 25: Token Introspection for C offline 2716 The information contained in the Request-Payload and the Response- 2717 Payload is shown in Figure 26. 2719 Request-Payload: 2720 { 2721 "token" : b64'SlAV32hkKG...', 2722 "client_id" : "FrontDoor", 2723 "client_secret" : "ytrewq" 2724 } 2726 Response-Payload: 2727 { 2728 "active" : true, 2729 "aud" : "lockOfDoor4711", 2730 "scope" : "open, close", 2731 "iat" : 1311280970, 2732 "cnf" : { 2733 "kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 2734 } 2735 } 2737 Figure 26: Request and Response Payload for Introspection 2739 The client uses the symmetric PoP key to establish a DTLS 2740 PreSharedKey secure connection to the RS. The CoAP request PUT is 2741 sent to the uri-path /state on RS changing state of the door to 2742 locked. 2743 F: The RS responds with a appropriate over the secure DTLS 2744 channel. 2746 Resource 2747 Client Server 2748 | | 2749 |<=======>| DTLS Connection Establishment 2750 | | using Pre Shared Key 2751 | | 2752 +-------->| Header: PUT (Code=0.03) 2753 | PUT | Uri-Path: "state" 2754 | | Payload: 2755 | | 2756 F: |<--------+ Header: 2.04 Changed 2757 | 2.04 | Payload: 2758 | | 2760 Figure 27: Resource request and response protected by OSCOAP 2762 Appendix F. Document Updates 2764 F.1. Version -04 to -05 2766 o Added RFC 2119 language to the specification of the required 2767 behavior of profile specifications. 2768 o Added section 6.1 on the relation to the OAuth2 grant types. 2769 o Added CBOR abbreviations for error and the error codes defined in 2770 OAuth2. 2771 o Added clarification about token expiration and long-running 2772 requests in section 8.2. 2773 o Added security considerations about tokens with symmetric pop keys 2774 valid for more than one RS. 2775 o Added privacy considerations section. 2776 o Added IANA registry mapping the confirmation types from RFC 7800 2777 to equivalent COSE types. 2778 o Added appendix D, describing assumptions about what the AS knows 2779 about the client and the RS. 2781 F.2. Version -03 to -04 2783 o Added a description of the terms "framework" and "profiles" as 2784 used in this document. 2785 o Clarified protection of access tokens in section 3.1. 2786 o Clarified uses of the 'cnf' parameter in section 6.4.5. 2788 o Clarified intended use of Client Token in section 7.4. 2790 F.3. Version -02 to -03 2792 o Removed references to draft-ietf-oauth-pop-key-distribution since 2793 the status of this draft is unclear. 2794 o Copied and adapted security considerations from draft-ietf-oauth- 2795 pop-key-distribution. 2796 o Renamed "client information" to "RS information" since it is 2797 information about the RS. 2798 o Clarified the requirements on profiles of this framework. 2799 o Clarified the token endpoint protocol and removed negotiation of 2800 'profile' and 'alg' (section 6). 2801 o Renumbered the abbreviations for claims and parameters to get a 2802 consistent numbering across different endpoints. 2803 o Clarified the introspection endpoint. 2804 o Renamed token, introspection and authz-info to 'endpoint' instead 2805 of 'resource' to mirror the OAuth 2.0 terminology. 2806 o Updated the examples in the appendices. 2808 F.4. Version -01 to -02 2810 o Restructured to remove communication security parts. These shall 2811 now be defined in profiles. 2812 o Restructured section 5 to create new sections on the OAuth 2813 endpoints /token, /introspect and /authz-info. 2814 o Pulled in material from draft-ietf-oauth-pop-key-distribution in 2815 order to define proof-of-possession key distribution. 2816 o Introduced the 'cnf' parameter as defined in RFC7800 to reference 2817 or transport keys used for proof of possession. 2818 o Introduced the 'client-token' to transport client information from 2819 the AS to the client via the RS in conjunction with introspection. 2820 o Expanded the IANA section to define parameters for token request, 2821 introspection and CWT claims. 2822 o Moved deployment scenarios to the appendix as examples. 2824 F.5. Version -00 to -01 2826 o Changed 5.1. from "Communication Security Protocol" to "Client 2827 Information". 2828 o Major rewrite of 5.1 to clarify the information exchanged between 2829 C and AS in the PoP token request profile for IoT. 2831 * Allow the client to indicate preferences for the communication 2832 security protocol. 2833 * Defined the term "Client Information" for the additional 2834 information returned to the client in addition to the access 2835 token. 2837 * Require that the messages between AS and client are secured, 2838 either with (D)TLS or with COSE_Encrypted wrappers. 2839 * Removed dependency on OSCoAP and added generic text about 2840 object security instead. 2841 * Defined the "rpk" parameter in the client information to 2842 transmit the raw public key of the RS from AS to client. 2843 * (D)TLS MUST use the PoP key in the handshake (either as PSK or 2844 as client RPK with client authentication). 2845 * Defined the use of x5c, x5t and x5tS256 parameters when a 2846 client certificate is used for proof of possession. 2847 * Defined "tktn" parameter for signaling for how to transfer the 2848 access token. 2849 o Added 5.2. the CoAP Access-Token option for transferring access 2850 tokens in messages that do not have payload. 2851 o 5.3.2. Defined success and error responses from the RS when 2852 receiving an access token. 2853 o 5.6.:Added section giving guidance on how to handle token 2854 expiration in the absence of reliable time. 2855 o Appendix B Added list of roles and responsibilities for C, AS and 2856 RS. 2858 Authors' Addresses 2860 Ludwig Seitz 2861 SICS 2862 Scheelevaegen 17 2863 Lund 223 70 2864 SWEDEN 2866 Email: ludwig@sics.se 2868 Goeran Selander 2869 Ericsson 2870 Faroegatan 6 2871 Kista 164 80 2872 SWEDEN 2874 Email: goran.selander@ericsson.com 2876 Erik Wahlstroem 2877 Sweden 2879 Email: erik@wahlstromtekniska.se 2880 Samuel Erdtman 2881 Spotify AB 2882 Birger Jarlsgatan 61, 4tr 2883 Stockholm 113 56 2884 Sweden 2886 Email: erdtman@spotify.com 2888 Hannes Tschofenig 2889 ARM Ltd. 2890 Hall in Tirol 6060 2891 Austria 2893 Email: Hannes.Tschofenig@arm.com