idnits 2.17.1 draft-ietf-ace-oauth-authz-06.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 (March 13, 2017) is 2601 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-05 == Outdated reference: A later version (-15) exists of draft-ietf-ace-cbor-web-token-03 == 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-04 == Outdated reference: A later version (-12) exists of draft-ietf-oauth-native-apps-09 -- 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 RISE SICS 4 Intended status: Standards Track G. Selander 5 Expires: September 14, 2017 Ericsson 6 E. Wahlstroem 7 (no affiliation) 8 S. Erdtman 9 Spotify AB 10 H. Tschofenig 11 ARM Ltd. 12 March 13, 2017 14 Authentication and Authorization for Constrained Environments (ACE) 15 draft-ietf-ace-oauth-authz-06 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 September 14, 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 5.1. Authorization Grants . . . . . . . . . . . . . . . . . . 14 69 5.2. Client Credentials . . . . . . . . . . . . . . . . . . . 15 70 5.3. AS Authentication . . . . . . . . . . . . . . . . . . . . 15 71 5.4. The 'Authorize' Endpoint . . . . . . . . . . . . . . . . 15 72 5.5. The 'Token' Endpoint . . . . . . . . . . . . . . . . . . 16 73 5.5.1. Client-to-AS Request . . . . . . . . . . . . . . . . 16 74 5.5.2. AS-to-Client Response . . . . . . . . . . . . . . . . 19 75 5.5.3. Error Response . . . . . . . . . . . . . . . . . . . 21 76 5.5.4. Request and Response Parameters . . . . . . . . . . . 21 77 5.5.4.1. Audience . . . . . . . . . . . . . . . . . . . . 21 78 5.5.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 22 79 5.5.4.3. Token Type . . . . . . . . . . . . . . . . . . . 22 80 5.5.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 22 81 5.5.4.5. Confirmation . . . . . . . . . . . . . . . . . . 23 82 5.5.5. Mapping parameters to CBOR . . . . . . . . . . . . . 25 83 5.6. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 25 84 5.6.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 26 85 5.6.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 26 86 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 28 87 5.6.4. Client Token . . . . . . . . . . . . . . . . . . . . 28 88 5.6.5. Mapping Introspection parameters to CBOR . . . . . . 30 89 5.7. The Access Token . . . . . . . . . . . . . . . . . . . . 30 90 5.7.1. The 'Authorization Information' Endpoint . . . . . . 31 91 5.7.2. Token Expiration . . . . . . . . . . . . . . . . . . 31 92 6. Security Considerations . . . . . . . . . . . . . . . . . . . 32 93 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 34 94 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 95 8.1. OAuth Introspection Response Parameter Registration . . . 34 96 8.2. OAuth Parameter Registration . . . . . . . . . . . . . . 35 97 8.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 35 98 8.4. Token Type Mappings . . . . . . . . . . . . . . . . . . . 36 99 8.4.1. Registration Template . . . . . . . . . . . . . . . . 36 100 8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 36 101 8.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 36 102 8.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 37 103 8.6.1. Registration Template . . . . . . . . . . . . . . . . 37 104 8.7. OAuth Parameter Mappings Registry . . . . . . . . . . . . 37 105 8.7.1. Registration Template . . . . . . . . . . . . . . . . 37 106 8.7.2. Initial Registry Contents . . . . . . . . . . . . . . 38 107 8.8. Introspection Endpoint CBOR Mappings Registry . . . . . . 40 108 8.8.1. Registration Template . . . . . . . . . . . . . . . . 40 109 8.8.2. Initial Registry Contents . . . . . . . . . . . . . . 40 110 8.9. CoAP Option Number Registration . . . . . . . . . . . . . 42 111 8.10. CWT Confirmation Methods Registry . . . . . . . . . . . . 43 112 8.10.1. Registration Template . . . . . . . . . . . . . . . 43 113 8.10.2. Initial Registry Contents . . . . . . . . . . . . . 44 114 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 115 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 116 10.1. Normative References . . . . . . . . . . . . . . . . . . 45 117 10.2. Informative References . . . . . . . . . . . . . . . . . 45 118 Appendix A. Design Justification . . . . . . . . . . . . . . . . 47 119 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 49 120 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 51 121 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 52 122 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 52 123 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 53 124 E.2. Introspection Aided Token Validation . . . . . . . . . . 56 125 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 60 126 F.1. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 60 127 F.2. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 60 128 F.3. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 61 129 F.4. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 61 130 F.5. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 61 131 F.6. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 62 132 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 62 134 1. Introduction 136 Authorization is the process for granting approval to an entity to 137 access a resource [RFC4949]. The authorization task itself can best 138 be described as granting access to a requesting client, for a 139 resource hosted on a device, the resource server (RS). This exchange 140 is mediated by one or multiple authorization servers (AS). Managing 141 authorization for a large number of devices and users is a complex 142 task. 144 While prior work on authorization solutions for the Web and for the 145 mobile environment also applies to the IoT environment many IoT 146 devices are constrained, for example in terms of processing 147 capabilities, available memory, etc. For web applications on 148 constrained nodes this specification makes use of CoAP [RFC7252]. 150 A detailed treatment of constraints can be found in [RFC7228], and 151 the different IoT deployments present a continuous range of device 152 and network capabilities. Taking energy consumption as an example: 153 At one end there are energy-harvesting or battery powered devices 154 which have a tight power budget, on the other end there are mains- 155 powered devices, and all levels in between. 157 Hence, IoT devices may be very different in terms of available 158 processing and message exchange capabilities and there is a need to 159 support many different authorization use cases [RFC7744]. 161 This specification describes a framework for authentication and 162 authorization in constrained environments (ACE) built on re-use of 163 OAuth 2.0 [RFC6749], thereby extending authorization to Internet of 164 Things devices. This specification contains the necessary building 165 blocks for adjusting OAuth 2.0 to IoT environments. 167 More detailed, interoperable specifications can be found in profiles. 168 Implementations may claim conformance with a specific profile, 169 whereby implementations utilizing the same profile interoperate while 170 implementations of different profiles are not expected to be 171 interoperable. Some devices, such as mobile phones and tablets, may 172 implement multiple profiles and will therefore be able to interact 173 with a wider range of low end devices. 175 2. Terminology 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 179 "OPTIONAL" in this document are to be interpreted as described in 180 [RFC2119]. 182 Certain security-related terms such as "authentication", 183 "authorization", "confidentiality", "(data) integrity", "message 184 authentication code", and "verify" are taken from [RFC4949]. 186 Since we describe exchanges as RESTful protocol interactions HTTP 187 [RFC7231] offers useful terminology. 189 Terminology for entities in the architecture is defined in OAuth 2.0 190 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 191 server (RS), and authorization server (AS). 193 Note that the term "endpoint" is used here following its OAuth 194 definition, which is to denote resources such as /token and 195 /introspect at the AS and /authz-info at the RS. The CoAP [RFC7252] 196 definition, which is "An entity participating in the CoAP protocol" 197 is not used in this memo. 199 Since this specification focuses on the problem of access control to 200 resources, we simplify the actors by assuming that the client 201 authorization server (CAS) functionality is not stand-alone but 202 subsumed by either the authorization server or the client (see 203 section 2.2 in [I-D.ietf-ace-actors]). 205 We call the specifications of this memo the "framework" or "ACE 206 framework". When referring to "profiles of this framework" we mean 207 additional memo's that define the use of this specification with 208 concrete transport, and communication security protocols (e.g. CoAP 209 over DTLS). 211 3. Overview 213 This specification defines the ACE framework for authorization in the 214 Internet of Things environment. It consists of a set of building 215 blocks. 217 The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys 218 widespread deployment. Many IoT devices can support OAuth 2.0 219 without any additional extensions, but for certain constrained 220 settings additional profiling is needed. 222 Another building block is the lightweight web transfer protocol CoAP 223 [RFC7252] for those communication environments where HTTP is not 224 appropriate. CoAP typically runs on top of UDP which further reduces 225 overhead and message exchanges. While this specification defines 226 extensions for the use of OAuth over CoAP, we do envision further 227 underlying protocols to be supported in the future, such as HTTP/2, 228 MQTT and QUIC. 230 A third building block is CBOR [RFC7049] for encodings where JSON 231 [RFC7159] is not sufficiently compact. CBOR is a binary encoding 232 designed for small code and message size, which may be used for 233 encoding of self contained tokens, and also for encoding CoAP POST 234 parameters and CoAP responses. 236 A fourth building block is the compact CBOR-based secure message 237 format COSE [I-D.ietf-cose-msg], which enables application layer 238 security as an alternative or complement to transport layer security 239 (DTLS [RFC6347] or TLS [RFC5246]). COSE is used to secure self 240 contained tokens such as proof-of-possession (PoP) tokens, which is 241 an extension to the OAuth access tokens, and "client tokens" which 242 are defined in this framework (see Section 5.6.4). The default 243 access token format is defined in CBOR web token (CWT) 244 [I-D.ietf-ace-cbor-web-token]. Application layer security for CoAP 245 using COSE can be provided with OSCOAP 246 [I-D.ietf-core-object-security]. 248 With the building blocks listed above, solutions satisfying various 249 IoT device and network constraints are possible. A list of 250 constraints is described in detail in RFC 7228 [RFC7228] and a 251 description of how the building blocks mentioned above relate to the 252 various constraints can be found in Appendix A. 254 Luckily, not every IoT device suffers from all constraints. The ACE 255 framework nevertheless takes all these aspects into account and 256 allows several different deployment variants to co-exist rather than 257 mandating a one-size-fits-all solution. We believe this is important 258 to cover the wide range of possible interworking use cases and the 259 different requirements from a security point of view. Once IoT 260 deployments mature, popular deployment variants will be documented in 261 form of ACE profiles. 263 In the subsections below we provide further details about the 264 different building blocks. 266 3.1. OAuth 2.0 268 The OAuth 2.0 authorization framework enables a client to obtain 269 limited access to a resource with the permission of a resource owner. 270 Authorization information, or references to it, is passed between the 271 nodes using access tokens. These access tokens are issued to clients 272 by an authorization server with the approval of the resource owner. 273 The client uses the access token to access the protected resources 274 hosted by the resource server. 276 A number of OAuth 2.0 terms are used within this specification: 278 The token and introspect Endpoints: 280 The AS hosts the /token endpoint that allows a client to request 281 access tokens. The client makes a POST request to the /token 282 endpoint on the AS and receives the access token in the response 283 (if the request was successful). 285 The token introspection endpoint, /introspect, is used by the RS 286 when requesting additional information regarding a received access 287 token. The RS makes a POST request to /introspect on the AS and 288 receives information about the access token in the response. (See 289 "Introspection" below.) 291 Access Tokens: 293 Access tokens are credentials needed to access protected 294 resources. An access token is a data structure representing 295 authorization permissions issued by the AS to the client. Access 296 tokens are generated by the authorization server and consumed by 297 the resource server. The access token content is opaque to the 298 client. 300 Access tokens can have different formats, and various methods of 301 utilization (e.g., cryptographic properties) based on the security 302 requirements of the given deployment. 304 Proof of Possession Tokens: 306 An access token may be bound to a cryptographic key, which is then 307 used by an RS to authenticate requests from a client. Such tokens 308 are called proof-of-possession tokens (or PoP tokens). 310 The proof-of-possession (PoP) security concept assumes that the AS 311 acts as a trusted third party that binds keys to access tokens. 312 These so called PoP keys are then used by the client to 313 demonstrate the possession of the secret to the RS when accessing 314 the resource. The RS, when receiving an access token, needs to 315 verify that the key used by the client matches the one bound to 316 the access token. When this specification uses the term "access 317 token" it is assumed to be a PoP token unless specifically stated 318 otherwise. 320 The key bound to the access token (aka PoP key) may be based on 321 symmetric as well as on asymmetric cryptography. The appropriate 322 choice of security depends on the constraints of the IoT devices 323 as well as on the security requirements of the use case. 325 Symmetric PoP key: The AS generates a random symmetric PoP key. 326 The key is either stored to be returned on introspection calls 327 or encrypted and included in the access token. The PoP key is 328 also encrypted for the client and sent together with the access 329 token to the client. 331 Asymmetric PoP key: An asymmetric key pair is generated on the 332 client and the public key is sent to the AS (if it does not 333 already have knowledge of the client's public key). 335 Information about the public key, which is the PoP key in this 336 case, is either stored to be returned on introspection calls or 337 included inside the access token and sent back to the 338 requesting client. The RS can identify the client's public key 339 from the information in the token, which allows the client to 340 use the corresponding private key for the proof of possession. 342 The access token is either a simple reference, or a structured 343 information object (e.g. CWT [I-D.ietf-ace-cbor-web-token]), 344 protected by a cryptographic wrapper (e.g. COSE 345 [I-D.ietf-cose-msg]). The choice of PoP key does not necessarily 346 imply a specific credential type for the integrity protection of 347 the token. 349 Scopes and Permissions: 351 In OAuth 2.0, the client specifies the type of permissions it is 352 seeking to obtain (via the scope parameter) in the access token 353 request. In turn, the AS may use the scope response parameter to 354 inform the client of the scope of the access token issued. As the 355 client could be a constrained device as well, this specification 356 uses CBOR encoded messages for CoAP, defined in Section 5, to 357 request scopes and to be informed what scopes the access token was 358 actually authorized for by the AS. 360 The values of the scope parameter are expressed as a list of 361 space- delimited, case-sensitive strings, with a semantic that is 362 well-known to the AS and the RS. More details about the concept 363 of scopes is found under Section 3.3 in [RFC6749]. 365 Claims: 367 Information carried in the access token or returned from 368 introspection, called claims, is in the form of type-value pairs. 369 An access token may, for example, include a claim identifying the 370 AS that issued the token (via the "iss" claim) and what audience 371 the access token is intended for (via the "aud" claim). The 372 audience of an access token can be a specific resource or one or 373 many resource servers. The resource owner policies influence what 374 claims are put into the access token by the authorization server. 376 While the structure and encoding of the access token varies 377 throughout deployments, a standardized format has been defined 378 with the JSON Web Token (JWT) [RFC7519] where claims are encoded 379 as a JSON object. In [I-D.ietf-ace-cbor-web-token] an equivalent 380 format using CBOR encoding (CWT) has been defined. 382 Introspection: 384 Introspection is a method for a resource server to query the 385 authorization server for the active state and content of a 386 received access token. This is particularly useful in those cases 387 where the authorization decisions are very dynamic and/or where 388 the received access token itself is a reference rather than a 389 self-contained token. More information about introspection in 390 OAuth 2.0 can be found in [RFC7662]. 392 3.2. CoAP 394 CoAP is an application layer protocol similar to HTTP, but 395 specifically designed for constrained environments. CoAP typically 396 uses datagram-oriented transport, such as UDP, where reordering and 397 loss of packets can occur. A security solution need to take the 398 latter aspects into account. 400 While HTTP uses headers and query-strings to convey additional 401 information about a request, CoAP encodes such information in so- 402 called 'options'. 404 CoAP supports application-layer fragmentation of the CoAP payloads 405 through blockwise transfers [RFC7959]. However, block-wise transfer 406 does not increase the size limits of CoAP options, therefore data 407 encoded in options has to be kept small. 409 Transport layer security for CoAP can be provided by DTLS 1.2 410 [RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy 411 operations which requires transport layer security to be terminated 412 at the proxy. One approach for protecting CoAP communication end-to- 413 end through proxies, and also to support security for CoAP over a 414 different transport in a uniform way, is to provide security on 415 application layer using an object-based security mechanism such as 416 COSE [I-D.ietf-cose-msg]. 418 One application of COSE is OSCOAP [I-D.ietf-core-object-security], 419 which provides end-to-end confidentiality, integrity and replay 420 protection, and a secure binding between CoAP request and response 421 messages. In OSCOAP, the CoAP messages are wrapped in COSE objects 422 and sent using CoAP. 424 4. Protocol Interactions 426 The ACE framework is based on the OAuth 2.0 protocol interactions 427 using the /token and /introspect endpoints. A client obtains an 428 access token from an AS using the /token endpoint and subsequently 429 presents the access token to a RS to gain access to a protected 430 resource. The RS, after receiving an access token, may present it to 431 the AS via the /introspect endpoint to get information about the 432 access token. In other deployments the RS may process the access 433 token locally without the need to contact an AS. These interactions 434 are shown in Figure 1. An overview of various OAuth concepts is 435 provided in Section 3.1. 437 The OAuth 2.0 framework defines a number of "protocol flows" via 438 grant types, which have been extended further with extensions to 439 OAuth 2.0 (such as RFC 7521 [RFC7521] and 440 [I-D.ietf-oauth-device-flow]). What grant types works best depends 441 on the usage scenario and RFC 7744 [RFC7744] describes many different 442 IoT use cases but there are two preferred grant types, namely the 443 Authorization Code Grant (described in Section 4.1 of RFC 7521) and 444 the Client Credentials Grant (described in Section 4.4 of RFC 7521). 445 The Authorization Code Grant is a good fit for use with apps running 446 on smart phones and tablets that request access to IoT devices, a 447 common scenario in the smart home environment, where users need to go 448 through an authentication and authorization phase (at least during 449 the initial setup phase). The native apps guidelines described in 450 [I-D.ietf-oauth-native-apps] are applicable to this use case. The 451 Client Credential Grant is a good fit for use with IoT devices where 452 the OAuth client itself is constrained. In such a case the resource 453 owner or another person on his or her behalf have arranged with the 454 authorization server out-of-band, which is often accomplished using a 455 commissioning tool. 457 The consent of the resource owner, for giving a client access to a 458 protected resource, can be provided dynamically as in the traditional 459 OAuth flows, or it could be pre-configured by the resource owner as 460 authorization policies at the AS, which the AS evaluates when a token 461 request arrives. The resource owner and the requesting party (i.e. 462 client owner) are not shown in Figure 1. 464 This framework supports a wide variety of communication security 465 mechanisms between the ACE entities, such as client, AS, and RS. We 466 assume that the client has been registered (also called enrolled or 467 onboarded) to an AS using a mechanism defined outside the scope of 468 this document. In practice, various techniques for onboarding have 469 been used, such as factory-based provisioning or the use of 470 commissioning tools. Regardless of the onboarding technique, this 471 registration procedure implies that the client and the AS share 472 credentials, and configuration parameters. These credentials are 473 used to mutually authenticate each other and to protect messages 474 exchanged between the client and the AS. 476 It is also assumed that the RS has been registered with the AS, 477 potentially in a similar way as the client has been registered with 478 the AS. Established keying material between the AS and the RS allows 479 the AS to apply cryptographic protection to the access token to 480 ensure that its content cannot be modified, and if needed, that the 481 content is confidentiality protected. 483 The keying material necessary for establishing communication security 484 between C and RS is dynamically established as part of the protocol 485 described in this document. 487 At the start of the protocol there is an optional discovery step 488 where the client discovers the resource server and the resources this 489 server hosts. In this step the client might also determine what 490 permissions are needed to access the protected resource. The 491 detailed procedures for this discovery process may be defined in an 492 ACE profile and depend on the protocols being used and the specific 493 deployment environment. 495 In Bluetooth Low Energy, for example, advertisements are broadcasted 496 by a peripheral, including information about the primary services. 497 In CoAP, as a second example, a client can make a request to "/.well- 498 known/core" to obtain information about available resources, which 499 are returned in a standardized format as described in [RFC6690]. 501 +--------+ +---------------+ 502 | |---(A)-- Token Request ------->| | 503 | | | Authorization | 504 | |<--(B)-- Access Token ---------| Server | 505 | | + RS Information | | 506 | | +---------------+ 507 | | ^ | 508 | | Introspection Request (D)| | 509 | Client | | | 510 | | Response + Client Token | |(E) 511 | | | v 512 | | +--------------+ 513 | |---(C)-- Token + Request ----->| | 514 | | | Resource | 515 | |<--(F)-- Protected Resource ---| Server | 516 | | | | 517 +--------+ +--------------+ 519 Figure 1: Basic Protocol Flow. 521 Requesting an Access Token (A): 523 The client makes an access token request to the /token endpoint at 524 the AS. This framework assumes the use of PoP tokens (see 525 Section 3.1 for a short description) wherein the AS binds a key to 526 an access token. The client may include permissions it seeks to 527 obtain, and information about the credentials it wants to use 528 (e.g., symmetric/asymmetric cryptography or a reference to a 529 specific credential). 531 Access Token Response (B): 533 If the AS successfully processes the request from the client, it 534 returns an access token. It also returns various parameters, 535 referred as "RS Information". In addition to the response 536 parameters defined by OAuth 2.0 and the PoP token extension, 537 further response parameters, such as information on which profile 538 the client should use with the resource server(s). More 539 information about these parameters can be found in Section 5.5.4. 541 Resource Request (C): 543 The client interacts with the RS to request access to the 544 protected resource and provides the access token. The protocol to 545 use between the client and the RS is not restricted to CoAP. 546 HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also 547 viable candidates. 549 Depending on the device limitations and the selected protocol this 550 exchange may be split up into two parts: 552 (1) the client sends the access token containing, or 553 referencing, the authorization information to the RS, that may 554 be used for subsequent resource requests by the client, and 555 (2) the client makes the resource access request, using the 556 communication security protocol and other RS Information 557 obtained from the AS. 559 The Client and the RS mutually authenticate using the security 560 protocol specified in the profile (see step B) and the keys 561 obtained in the access token or the RS Information or the client 562 token. The RS verifies that the token is integrity protected by 563 the AS and compares the claims contained in the access token with 564 the resource request. If the RS is online, validation can be 565 handed over to the AS using token introspection (see messages D 566 and E) over HTTP or CoAP, in which case the different parts of 567 step C may be interleaved with introspection. 569 Token Introspection Request (D): 571 A resource server may be configured to introspect the access token 572 by including it in a request to the /introspect endpoint at that 573 AS. Token introspection over CoAP is defined in Section 5.6 and 574 for HTTP in [RFC7662]. 576 Note that token introspection is an optional step and can be 577 omitted if the token is self-contained and the resource server is 578 prepared to perform the token validation on its own. 580 Token Introspection Response (E): 582 The AS validates the token and returns the most recent parameters, 583 such as scope, audience, validity etc. associated with it back to 584 the RS. The RS then uses the received parameters to process the 585 request to either accept or to deny it. The AS can additionally 586 return information that the RS needs to pass on to the client in 587 the form of a client token. The latter is used to establish keys 588 for mutual authentication between client and RS, when the client 589 has no direct connectivity to the AS, see Section 5.6.4 for 590 details. 592 Protected Resource (F): 594 If the request from the client is authorized, the RS fulfills the 595 request and returns a response with the appropriate response code. 596 The RS uses the dynamically established keys to protect the 597 response, according to used communication security protocol. 599 5. Framework 601 The following sections detail the profiling and extensions of OAuth 602 2.0 for constrained environments which constitutes the ACE framework. 604 Credential Provisioning 606 For IoT we cannot generally assume that the client and RS are part 607 of a common key infrastructure, so the AS provisions credentials 608 or associated information to allow mutual authentication. These 609 credentials need to be provided to the parties before or during 610 the authentication protocol is executed, and may be re-used for 611 subsequent token requests. 613 Proof-of-Possession 615 The ACE framework by default implements proof-of-possession for 616 access tokens, i.e. that the token holder can prove being a holder 617 of the key bound to the token. The binding is provided by the 618 "cnf" claim indicating what key is used for proof-of-possession. 619 If clients need to update a token, e.g. to get additional rights, 620 they can request that the AS binds the new access token to the 621 same key as the previous token. 623 ACE Profiles 624 The client or RS may be limited in the encodings or protocols it 625 supports. To support a variety of different deployment settings, 626 specific interactions between client and RS are defined in an ACE 627 profile. In ACE framework the AS is expected to manage the 628 matching of compatible profile choices between a client and an RS. 629 The AS informs the client of the selected profile using the 630 "profile" parameter in the token response. 632 OAuth 2.0 requires the use of TLS both to protect the communication 633 between AS and client when requesting an access token; between client 634 and RS when accessing a resource and between AS and RS for 635 introspection. In constrained settings TLS is not always feasible, 636 or desirable. Nevertheless it is REQUIRED that the data exchanged 637 with the AS is encrypted and integrity protected. It is furthermore 638 REQUIRED that the AS and the endpoint communicating with it (client 639 or RS) perform mutual authentication. 641 Profiles MUST specify how mutual authentication is done, depending 642 e.g. on the communication protocol and the credentials used by the 643 client or the RS. 645 In OAuth 2.0 the communication with the Token and the Introspection 646 endpoints at the AS is assumed to be via HTTP and may use Uri-query 647 parameters. This framework RECOMMENDS to use CoAP instead and 648 RECOMMENDS the use of the following alternative instead of Uri-query 649 parameters: The sender (client or RS) encodes the parameters of its 650 request as a CBOR map and submits that map as the payload of the POST 651 request. The Content-format depends on the security applied to the 652 content and MUST be specified by the profile that is used. 654 The OAuth 2.0 AS uses a JSON structure in the payload of its 655 responses both to client and RS. This framework RECOMMENDS the use 656 of CBOR [RFC7049] instead. The requesting device can explicitly 657 request this encoding by setting the CoAP Accept option in the 658 request to "application/cbor". Depending on the profile, the content 659 MAY arrive in a different format wrapping a CBOR payload. 661 5.1. Authorization Grants 663 To request an access token, the client obtains authorization from the 664 resource owner or uses its client credentials as grant. The 665 authorization is expressed in the form of an authorization grant. 667 The OAuth framework defines four grant types. The grant types can be 668 split up into two groups, those granted on behalf of the resource 669 owner (password, authorization code, implicit) and those for the 670 client (client credentials). 672 The grant type selected depending based on the use case. In cases 673 where the client will act on behalf of the resource owner, 674 authorization code grant is recommended. If the client should to act 675 on be half of the user but does not have any display or very limited 676 interaction possibilities it is recommended to use the device code 677 grant defined in [I-D.ietf-oauth-device-flow]. In cases where the 678 client will not act on be half of the resource owner, client 679 credentials grant is recommended. 681 For details on the different grant types see the OAuth 2.0 framework. 682 The OAuth 2.0 framework provides an extension mechanism for defining 683 additional grant types so profiles of this framework MAY define 684 additional grant types if needed. 686 5.2. Client Credentials 688 Authentication of the client is mandatory independent of the grant 689 type when requesting the access token from the token endpoint. In 690 the case of client credentials grant type the authentication and 691 grant coincides. 693 Client registration and provisioning of client credentials to the 694 client is out of scope for this specification. 696 The OAuth framework, [RFC6749], defines one client credential type, 697 client id and client secret. Profiles of this framework MAY extend 698 with additional client credentials such as DTLS pre-shared keys or 699 client certificates. 701 5.3. AS Authentication 703 Client credential does not by default authenticate the AS that the 704 client connects to. In classic OAuth the AS is authenticated with a 705 TLS server certificate. 707 Profiles of this framework SHOULD specify how clients authenticate 708 the AS and how communication security is implemented, otherwise 709 server side TLS certificates as defined by OAuth 2.0 is required. 711 5.4. The 'Authorize' Endpoint 713 The authorization endpoint is used to interact with the resource 714 owner and obtain an authorization grant. It is used for 715 authorization code and implicit grant, flows that requires online 716 user consent. In the most common implementation a users-agent is 717 used and redirected from the client to the AS. The AS shows a 718 consent dialog and directs back to the client, with the approved 719 grant or an error message. 721 The grant types defined in OAuth 2.0, that use the authorization 722 endpoint, require the use of a user agent (i.e. a browser). This 723 endpoint is therefore out of scope for this specification. 724 Implementations should use the definition and recommendations of 725 [RFC6749] and [RFC6819]. 727 If clients involved cannot support HTTP and TLS profiles MAY define 728 mappings for the authorization endpoint. 730 5.5. The 'Token' Endpoint 732 In plain OAuth 2.0 the AS provides the /token endpoint for submitting 733 access token requests. This framework extends the functionality of 734 the /token endpoint, giving the AS the possibility to help client and 735 RS to establish shared keys or to exchange their public keys. 736 Furthermore this framework defines encodings using CoAP and CBOR, in 737 addition to HTTP and JSON. 739 For the AS to be able to issue a token the client MUST be 740 authenticated and present a valid grant for the scopes requested. 742 The figures of this section uses CBOR diagnostic notation without the 743 integer abbreviations for the parameters or their values for better 744 readability. 746 5.5.1. Client-to-AS Request 748 The client sends a CoAP POST request to the token endpoint at the AS, 749 the profile MUST specify the Content-Type and wrapping of the 750 payload. The content of the request consists of the parameters 751 specified in section 4 of the OAuth 2.0 specification [RFC6749] 752 encoded as a CBOR map. 754 In addition to these parameters, this framework defines the following 755 parameters for requesting an access token from a /token endpoint: 757 aud 758 OPTIONAL. Specifies the audience for which the client is 759 requesting an access token. If this parameter is missing it is 760 assumed that the client and the AS have a pre-established 761 understanding of the audience that an access token should address. 762 If a client submits a request for an access token without 763 specifying an "aud" parameter, and the AS does not have a default 764 "aud" value for this client, then the AS MUST respond with an 765 error message with the CoAP response code 4.00 (Bad Request). 767 cnf 768 OPTIONAL. This field contains information about the key the 769 client would like to bind to the access token for proof-of- 770 possession. It is NOT RECOMMENDED that a client submits a 771 symmetric key value to the AS using this parameter. See 772 Section 5.5.4.5 for more details on the formatting of the 'cnf' 773 parameter. 775 The following examples illustrate different types of requests for 776 proof-of-possession tokens. 778 Figure 2 shows a request for a token with a symmetric proof-of- 779 possession key. Note that in this example we assume a DTLS-based 780 communication security profile, therefore the Content-Type is 781 "application/cbor". The content is displayed in CBOR diagnostic 782 notation, without abbreviations for better readability. 784 Header: POST (Code=0.02) 785 Uri-Host: "server.example.com" 786 Uri-Path: "token" 787 Content-Type: "application/cbor" 788 Payload: 789 { 790 "grant_type" : "client_credentials", 791 "aud" : "tempSensor4711", 792 } 794 Figure 2: Example request for an access token bound to a symmetric 795 key. 797 Figure 3 shows a request for a token with an asymmetric proof-of- 798 possession key. Note that in this example we assume an object 799 security-based profile, therefore the Content-Type is "application/ 800 cose+cbor". 802 Header: POST (Code=0.02) 803 Uri-Host: "server.example.com" 804 Uri-Path: "token" 805 Content-Type: "application/cose+cbor" 806 Payload: 807 { 808 "grant_type" : "client_credentials", 809 "client_id" : "myclient", 810 "client_secret" : "mysecret234", 811 "cnf" : { 812 "COSE_Key" : { 813 "kty" : "EC", 814 "kid" : h'11', 815 "crv" : "P-256", 816 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 817 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 818 } 819 } 820 } 822 Figure 3: Example request for an access token bound to an asymmetric 823 key. 825 Figure 4 shows a request for a token where a previously communicated 826 proof-of-possession key is only referenced. Note that we assume a 827 DTLS-based communication security profile for this example, therefore 828 the Content-Type is "application/cbor". Also note that the client 829 performs a password based authentication in this example by 830 submitting its client_secret (see section 2.3.1. of [RFC6749]). 832 Header: POST (Code=0.02) 833 Uri-Host: "server.example.com" 834 Uri-Path: "token" 835 Content-Type: "application/cbor" 836 Payload: 837 { 838 "grant_type" : "client_credentials", 839 "client_id" : "myclient", 840 "client_secret" : "mysecret234", 841 "aud" : "valve424", 842 "scope" : "read", 843 "cnf" : { 844 "kid" : b64'6kg0dXJM13U' 845 } 846 } 848 Figure 4: Example request for an access token bound to a key 849 reference. 851 5.5.2. AS-to-Client Response 853 If the access token request has been successfully verified by the AS 854 and the client is authorized to obtain an access token corresponding 855 to its access token request, the AS sends a response with the CoAP 856 response code 2.01 (Created). If client request was invalid, or not 857 authorized, the AS returns an error response as described in 858 Section 5.5.3. 860 Note that the AS decides which token type and profile to use when 861 issuing a successful response. It is assumed that the AS has prior 862 knowledge of the capabilities of the client, and the RS (see 863 Appendix D. This prior knowledge may, for example, be set by the use 864 of a dynamic client registration protocol exchange [RFC7591]. 866 The content of the successful reply is the RS Information. It MUST 867 be encoded as CBOR map, containing parameters as specified in section 868 5.1 of [RFC6749]. In addition to these parameters, the following 869 parameters are also part of a successful response: 871 profile 872 REQUIRED. This indicates the profile that the client MUST use 873 towards the RS. See Section 5.5.4.4 for the formatting of this 874 parameter. 876 cnf 877 REQUIRED if the token type is 'pop'. OPTIONAL otherwise. If a 878 symmetric proof-of-possession algorithms was selected, this field 879 contains the proof-of-possession key. If an asymmetric algorithm 880 was selected, this field contains information about the public key 881 used by the RS to authenticate. See Section 5.5.4.5 for the 882 formatting of this parameter. 883 token_type 884 OPTIONAL. By default implementations of this framework SHOULD 885 assume that the token_type is 'pop'. If a specific use case 886 requires another token_type (e.g. 'Bearer') to be used then this 887 parameter is REQUIRED. 889 Note that if CBOR Web Tokens [I-D.ietf-ace-cbor-web-token] are used, 890 the access token can also contain a 'cnf' claim. This claim is 891 however consumed by a different party. The access token is created 892 by the AS and processed by the RS (and opaque to the client) whereas 893 the RS Information is created by the AS and processed by the client; 894 it is never forwarded to the resource server. 896 Figure Figure 5 summarizes the parameters that may be part of the RS 897 Information. 899 /-------------------+--------------------------\ 900 | Parameter name | Specified in | 901 |-------------------+--------------------------| 902 | access_token | RFC 6749 | 903 | token_type | RFC 6749 | 904 | expires_in | RFC 6749 | 905 | refresh_token | RFC 6749 | 906 | scope | RFC 6749 | 907 | state | RFC 6749 | 908 | profile | [[ this specification ]] | 909 | cnf | [[ this specification ]] | 910 \-------------------+--------------------------/ 912 Figure 5: RS Information parameters 914 The following examples illustrate different types of responses for 915 proof-of-possession tokens. 917 Figure 6 shows a response containing a token and a 'cnf' parameter 918 with a symmetric proof-of-possession key. Note that we assume a 919 DTLS-based communication security profile for this example, therefore 920 the Content-Type is "application/cbor". 922 Header: Created (Code=2.01) 923 Content-Type: "application/cbor" 924 Payload: 925 { 926 "access_token" : b64'SlAV32hkKG ... 927 (remainder of CWT omitted for brevity; 928 CWT contains COSE_Key in the 'cnf' claim)', 929 "profile" : "coap_dtls", 930 "expires_in" : "3600", 931 "cnf" : { 932 "COSE_Key" : { 933 "kty" : "Symmetric", 934 "kid" : b64'39Gqlw', 935 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 936 } 937 } 938 } 940 Figure 6: Example AS response with an access token bound to a 941 symmetric key. 943 5.5.3. Error Response 945 The error responses for CoAP-based interactions with the AS are 946 equivalent to the ones for HTTP-based interactions as defined in 947 section 5.2 of [RFC6749], with the following differences: 949 o The Content-Type MUST be specified by the communication security 950 profile used between client and AS. The raw payload before being 951 processed by the communication security protocol MUST be encoded 952 as a CBOR map. 953 o The CoAP response code 4.00 (Bad Request) MUST be used for all 954 error responses, except for invalid_client where the CoAP response 955 code 4.01 (Unauthorized) MAY be used under the same conditions as 956 specified in section 5.2 of [RFC6749]. 957 o The parameters "error", "error_description" and "error_uri" MAY be 958 abbreviated using the codes specified in table Figure 13. 959 o The error codes MAY be abbreviated using the codes specified in 960 table Figure 7. 962 /------------------------+----------+--------------\ 963 | error code | CBOR Key | Major Type | 964 |------------------------+----------+--------------| 965 | invalid_request | 0 | 0 (uint) | 966 | invalid_client | 1 | 0 | 967 | invalid_grant | 2 | 0 | 968 | unauthorized_client | 3 | 0 | 969 | unsupported_grant_type | 4 | 0 | 970 | invalid_scope | 5 | 0 | 971 \------------------------+----------+--------------/ 973 Figure 7: CBOR abbreviations for common error codes 975 5.5.4. Request and Response Parameters 977 This section provides more detail about the new parameters that can 978 be used in access token requests and responses, as well as 979 abbreviations for more compact encoding of existing parameters and 980 common parameter values. 982 5.5.4.1. Audience 984 This parameter specifies for which audience the client is requesting 985 a token. It should be encoded as CBOR text string (major type 3). 986 The formatting and semantics of these strings are application 987 specific. 989 5.5.4.2. Grant Type 991 The abbreviations in Figure 8 MAY be used in CBOR encodings instead 992 of the string values defined in [RFC6749]. 994 /--------------------+----------+--------------\ 995 | grant_type | CBOR Key | Major Type | 996 |--------------------+----------+--------------| 997 | password | 0 | 0 (uint) | 998 | authorization_code | 1 | 0 | 999 | client_credentials | 2 | 0 | 1000 | refresh_token | 3 | 0 | 1001 \--------------------+----------+--------------/ 1003 Figure 8: CBOR abbreviations for common grant types 1005 5.5.4.3. Token Type 1007 The token_type parameter is defined in [RFC6749], allowing the AS to 1008 indicate to the client which type of access token it is receiving 1009 (e.g. a bearer token). 1011 This document registers the new value "pop" for the OAuth Access 1012 Token Types registry, specifying a Proof-of-Possession token. How 1013 the proof-of-possession is performed MUST be specified by the 1014 profiles. 1016 The values in the 'token_type' parameter MUST be CBOR text strings 1017 (major type 3). 1019 In this framework token type 'pop' MUST be assumed by default if the 1020 AS does not provide a different value. 1022 5.5.4.4. Profile 1024 Profiles of this framework MUST define the communication protocol and 1025 the communication security protocol between the client and the RS. 1026 Furthermore profiles MUST define proof-of-possession methods, if they 1027 support proof-of-possession tokens. 1029 A profile MUST specify an identifier that is used to uniquely 1030 identify itself in the 'profile' parameter. 1032 Profiles MAY define additional parameters for both the token request 1033 and the RS Information in the access token response in order to 1034 support negotiation or signalling of profile specific parameters. 1036 5.5.4.5. Confirmation 1038 The "cnf" parameter identifies or provides the key used for proof-of- 1039 possession or for authenticating the RS depending on the proof-of- 1040 possession algorithm and the context cnf is used in. This framework 1041 extends the definition of 'cnf' from [RFC7800] by adding CBOR/COSE 1042 encodings and the use of 'cnf' for transporting keys in the RS 1043 Information. 1045 The "cnf" parameter is used in the following contexts with the 1046 following meaning: 1048 o In the access token, to indicate the proof-of-possession key bound 1049 to this token. 1050 o In the token request C -> AS, to indicate the client's raw public 1051 key, or the key-identifier of a previously established key between 1052 C and RS. 1053 o In the token response AS -> C, to indicate either the symmetric 1054 key generated by the AS for proof-of-possession or the raw public 1055 key used by the RS to authenticate. 1056 o In the introspection response AS -> RS, to indicate the proof-of- 1057 possession key bound to the introspected token. 1058 o In the client token AS -> RS -> C, to indicate the proof-of- 1059 possession key bound to the access token. 1061 A CBOR encoded payload MAY contain the 'cnf' parameter with the 1062 following contents: 1064 COSE_Key In this case the 'cnf' parameter contains the proof-of- 1065 possession key to be used by the client. An example is shown in 1066 Figure 9. 1068 "cnf" : { 1069 "COSE_Key" : { 1070 "kty" : "EC", 1071 "kid" : h'11', 1072 "crv" : "P-256", 1073 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 1074 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 1075 } 1076 } 1078 Figure 9: Confirmation parameter containing a public key 1080 Note that the COSE_Key structure may contain an "alg" or "key_ops" 1081 parameter. If such parameters are present, a client MUST NOT use 1082 a key that is not compatible with the profile or proof-of- 1083 possession algorithm according to those parameters. 1085 COSE_Encrypted In this case the 'cnf' parameter contains an 1086 encrypted symmetric key destined for the client. The client is 1087 assumed to be able to decrypt the ciphertext of this parameter. 1088 The parameter is encoded as COSE_Encrypted object wrapping a 1089 COSE_Key object. Figure 10 shows an example of this type of 1090 encoding. 1092 "cnf" : { 1093 "COSE_Encrypted" : { 1094 993( 1095 [ h'a1010a' # protected header : {"alg" : "AES-CCM-16-64-128"} 1096 "iv" : b64'ifUvZaHFgJM7UmGnjA', # unprotected header 1097 b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext 1098 ] 1099 ) 1100 } 1101 } 1103 Figure 10: Confirmation parameter containing an encrypted symmetric 1104 key 1106 The ciphertext here could e.g. contain a symmetric key as in 1107 Figure 11. 1109 { 1110 "kty" : "Symmetric", 1111 "kid" : b64'39Gqlw', 1112 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1113 } 1115 Figure 11: Example plaintext of an encrypted cnf parameter 1117 Key Identifier In this case the 'cnf' parameter references a key 1118 that is assumed to be previously known by the recipient. This 1119 allows clients that perform repeated requests for an access token 1120 for the same audience but e.g. with different scopes to omit key 1121 transport in the access token, token request and token response. 1122 Figure 12 shows such an example. 1124 "cnf" : { 1125 "kid" : b64'39Gqlw' 1126 } 1128 Figure 12: A Confirmation parameter with just a key identifier 1130 This specification establishes the IANA "CWT Confirmation Methods" 1131 registry for these types of confirmation methods in Section 8.10 and 1132 registers the methods defined by this specification. Other 1133 specifications can register other methods used for confirmation. The 1134 registry is meant to be analogous to the "JWT Confirmation Methods" 1135 registry defined by [RFC7800]. 1137 5.5.5. Mapping parameters to CBOR 1139 All OAuth parameters in access token requests and responses are 1140 mapped to CBOR types as follows and are given an integer key value to 1141 save space. 1143 /-------------------+----------+-----------------\ 1144 | Parameter name | CBOR Key | Major Type | 1145 |-------------------+----------+-----------------| 1146 | aud | 3 | 3 | 1147 | client_id | 8 | 3 (text string) | 1148 | client_secret | 9 | 2 (byte string) | 1149 | response_type | 10 | 3 | 1150 | redirect_uri | 11 | 3 | 1151 | scope | 12 | 3 | 1152 | state | 13 | 3 | 1153 | code | 14 | 2 | 1154 | error | 15 | 3 | 1155 | error_description | 16 | 3 | 1156 | error_uri | 17 | 3 | 1157 | grant_type | 18 | 0 | 1158 | access_token | 19 | 3 | 1159 | token_type | 20 | 0 | 1160 | expires_in | 21 | 0 | 1161 | username | 22 | 3 | 1162 | password | 23 | 3 | 1163 | refresh_token | 24 | 3 | 1164 | cnf | 25 | 5 (map) | 1165 | profile | 26 | 3 | 1166 \-------------------+----------+-----------------/ 1168 Figure 13: CBOR mappings used in token requests 1170 5.6. The 'Introspect' Endpoint 1172 Token introspection [RFC7662] is used by the RS and potentially the 1173 client to query the AS for metadata about a given token e.g. validity 1174 or scope. Analogous to the protocol defined in RFC 7662 [RFC7662] 1175 for HTTP and JSON, this section defines adaptations to more 1176 constrained environments using CoAP and CBOR. 1178 Communication between the RS and the introspection endpoint at the AS 1179 MUST be integrity protected and encrypted. Furthermore AS and RS 1180 MUST perform mutual authentication. Finally the AS SHOULD verify 1181 that the RS has the right to access introspection information about 1182 the provided token. Profiles of this framework that support 1183 introspection MUST specify how authentication and communication 1184 security between RS and AS is implemented. 1186 The figures of this section uses CBOR diagnostic notation without the 1187 integer abbreviations for the parameters or their values for better 1188 readability. 1190 5.6.1. RS-to-AS Request 1192 The RS sends a CoAP POST request to the introspection endpoint at the 1193 AS, the profile MUST specify the Content-Type and wrapping of the 1194 payload. The payload MUST be encoded as a CBOR map with a 'token' 1195 parameter containing the access token along with optional parameters 1196 representing additional context that is known by the RS to aid the AS 1197 in its response. 1199 The same parameters are required and optional as in section 2.1 of 1200 RFC 7662 [RFC7662]. 1202 For example, Figure 14 shows a RS calling the token introspection 1203 endpoint at the AS to query about an OAuth 2.0 proof-of-possession 1204 token. Note that we assume a object security-based communication 1205 security profile for this example, therefore the Content-Type is 1206 "application/cose+cbor". 1208 Header: POST (Code=0.02) 1209 Uri-Host: "server.example.com" 1210 Uri-Path: "introspect" 1211 Content-Type: "application/cose+cbor" 1212 Payload: 1213 { 1214 "token" : b64'7gj0dXJQ43U', 1215 "token_type_hint" : "pop" 1216 } 1218 Figure 14: Example introspection request. 1220 5.6.2. AS-to-RS Response 1222 If the introspection request is authorized and successfully 1223 processed, the AS sends a response with the CoAP response code 2.01 1224 (Created). If the introspection request was invalid, not authorized 1225 or couldn't be processed the AS returns an error response as 1226 described in Section 5.6.3. 1228 In a successful response, the AS encodes the response parameters in a 1229 CBOR map including with the same required and optional parameters as 1230 in section 2.2. of RFC 7662 [RFC7662] with the following additions: 1232 cnf 1233 OPTIONAL. This field contains information about the proof-of- 1234 possession key that binds the client to the access token. See 1235 Section 5.5.4.5 for more details on the formatting of the 'cnf' 1236 parameter. 1238 profile 1239 OPTIONAL. This indicates the profile that the RS MUST use with 1240 the client. See Section 5.5.4.4 for more details on the 1241 formatting of this parameter. 1243 client_token 1244 OPTIONAL. This parameter contains information that the RS MUST 1245 pass on to the client. See Section 5.6.4 for more details. 1247 For example, Figure 15 shows an AS response to the introspection 1248 request in Figure 14. Note that we assume a DTLS-based communication 1249 security profile for this example, therefore the Content-Type is 1250 "application/cbor". 1252 Header: Created Code=2.01) 1253 Content-Type: "application/cbor" 1254 Payload: 1255 { 1256 "active" : true, 1257 "scope" : "read", 1258 "profile" : "coap_dtls", 1259 "client_token" : b64'2QPhg0OhAQo ... 1260 (remainder of client token omitted for brevity)', 1261 "cnf" : { 1262 "COSE_Key" : { 1263 "kty" : "Symmetric", 1264 "kid" : b64'39Gqlw', 1265 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1266 } 1267 } 1268 } 1270 Figure 15: Example introspection response. 1272 5.6.3. Error Response 1274 The error responses for CoAP-based interactions with the AS are 1275 equivalent to the ones for HTTP-based interactions as defined in 1276 section 2.3 of [RFC7662], with the following differences: 1278 o If content is sent, the Content-Type MUST be set according to the 1279 specification of the communication security profile, and the 1280 content payload MUST be encoded as a CBOR map. 1281 o If the credentials used by the RS are invalid the AS MUST respond 1282 with the CoAP response code 4.01 (Unauthorized) and use the 1283 required and optional parameters from section 5.2 in RFC 6749 1284 [RFC6749]. 1285 o If the RS does not have the right to perform this introspection 1286 request, the AS MUST respond with the CoAP response code 4.03 1287 (Forbidden). In this case no payload is returned. 1288 o The parameters "error", "error_description" and "error_uri" MAY be 1289 abbreviated using the codes specified in table Figure 13. 1290 o The error codes MAY be abbreviated using the codes specified in 1291 table Figure 7. 1293 Note that a properly formed and authorized query for an inactive or 1294 otherwise invalid token does not warrant an error response by this 1295 specification. In these cases, the authorization server MUST instead 1296 respond with an introspection response with the "active" field set to 1297 "false". 1299 5.6.4. Client Token 1301 EDITORIAL NOTE: We have tentatively introduced this concept and would 1302 specifically like feedback whether this is viewed as a useful 1303 addition to the framework. 1305 In cases where the client has limited connectivity and needs to get 1306 access to a previously unknown resource servers, this framework 1307 suggests the following approach: The client is pre-configured with a 1308 generic, long-term access token when it is commissioned. When the 1309 client then tries to access a RS it transmits this access token. The 1310 RS then performs token introspection to learn what access this token 1311 grants. In the introspection response, the AS also relays 1312 information for the client, such as the proof-of-possession key, 1313 through the RS. The RS passes on this Client Token to the client in 1314 response to the submission of the token. 1316 The client_token parameter is designed to carry such information, and 1317 is intended to be used as described in Figure 16. 1319 Resource Authorization 1320 Client Server Server 1321 | | | 1322 | | | 1323 C: +--------------->| | 1324 | POST | | 1325 | Access Token | | 1326 | D: +--------------->| 1327 | | Introspection | 1328 | | Request | 1329 | | | 1330 | E: +<---------------+ 1331 | | Introspection | 1332 | | Response | 1333 | | + Client Token | 1334 |<---------------+ | 1335 | 2.01 Created | | 1336 | + Client Token | 1338 Figure 16: Use of the client_token parameter. 1340 The client token is a COSE_Encrypted object, containing as payload a 1341 CBOR map with the following claims: 1343 cnf 1344 REQUIRED if the token type is 'pop', OPTIONAL otherwise. Contains 1345 information about the proof-of-possession key the client is to use 1346 with its access token. See Section 5.5.4.5. 1348 token_type 1349 OPTIONAL. See Section 5.5.4.3. 1351 profile 1352 REQUIRED. See Section 5.5.4.4. 1354 rs_cnf 1355 OPTIONAL. Contains information about the key that the RS uses to 1356 authenticate towards the client. If the key is symmetric then 1357 this claim MUST NOT be part of the Client Token, since this is the 1358 same key as the one specified through the 'cnf' claim. This claim 1359 uses the same encoding as the 'cnf' parameter. See 1360 Section 5.5.4.4. 1362 The AS encrypts this token using a key shared between the AS and the 1363 client, so that only the client can decrypt it and access its 1364 payload. How this key is established is out of scope of this 1365 framework. 1367 5.6.5. Mapping Introspection parameters to CBOR 1369 The introspection request and response parameters are mapped to CBOR 1370 types as follows and are given an integer key value to save space. 1372 /-----------------+----------+-----------------\ 1373 | Parameter name | CBOR Key | Major Type | 1374 |-----------------+----------+-----------------| 1375 | iss | 1 | 3 (text string) | 1376 | sub | 2 | 3 | 1377 | aud | 3 | 3 | 1378 | exp | 4 | 6 tag value 1 | 1379 | nbf | 5 | 6 tag value 1 | 1380 | iat | 6 | 6 tag value 1 | 1381 | cti | 7 | 2 (byte string) | 1382 | client_id | 8 | 3 | 1383 | scope | 12 | 3 | 1384 | token_type | 20 | 3 | 1385 | username | 22 | 3 | 1386 | cnf | 25 | 5 (map) | 1387 | profile | 26 | 0 (uint) | 1388 | token | 27 | 3 | 1389 | token_type_hint | 28 | 3 | 1390 | active | 29 | 0 | 1391 | client_token | 30 | 3 | 1392 | rs_cnf | 31 | 5 | 1393 \-----------------+----------+-----------------/ 1395 Figure 17: CBOR Mappings to Token Introspection Parameters. 1397 5.7. The Access Token 1399 This framework RECOMMENDS the use of CBOR web token (CWT) as 1400 specified in [I-D.ietf-ace-cbor-web-token]. 1402 In order to facilitate offline processing of access tokens, this 1403 draft specifies the "cnf" and "scope" claims for CBOR web tokens. 1405 The "scope" claim explicitly encodes the scope of a given access 1406 token. This claim follows the same encoding rules as defined in 1407 section 3.3 of [RFC6749]. The meaning of a specific scope value is 1408 application specific and expected to be known to the RS running that 1409 application. 1411 The "cnf" claim follows the same rules as specified for JSON web 1412 token in RFC7800 [RFC7800], except that it is encoded in CBOR in the 1413 same way as specified for the "cnf" parameter in Section 5.5.4.5. 1415 5.7.1. The 'Authorization Information' Endpoint 1417 The access token, containing authorization information and 1418 information about the key used by the client, needs to be transported 1419 to the RS so that the RS can authenticate and authorize the client 1420 request. 1422 This section defines a method for transporting the access token to 1423 the RS using CoAP. Profiles of this framework MAY define other 1424 methods for token transport. 1426 The method consists of an /authz-info endpoint, implemented by the 1427 RS. A client using this method MUST make a POST request to /authz- 1428 info at the RS with the access token in the payload. The RS 1429 receiving the token MUST verify the validity of the token. If the 1430 token is valid, the RS MUST respond to the POST request with 2.01 1431 (Created). This response MAY contain the identifier of the token 1432 (e.g. the cti for a CWT) as a payload. 1434 If the token is not valid, the RS MUST respond with the CoAP response 1435 code 4.01 (Unauthorized). If the token is valid but the audience of 1436 the token does not match the RS, the RS MUST respond with the CoAP 1437 response code 4.03 (Forbidden). If the token is valid but is 1438 associated to claims that the RS cannot process (e.g. an unknown 1439 scope) the RS MUST respond with the CoAP response code 4.00 (Bad 1440 Request). In the latter case the RS MAY provide additional 1441 information in the error response, in order to clarify what went 1442 wrong. 1444 The RS MAY make an introspection request to validate the token before 1445 responding to the POST /authz-info request. If the introspection 1446 response contains a client token (Section 5.6.4) then this token 1447 SHALL be included in the payload of the 2.01 (Created) response. 1449 Profiles MUST specify how the /authz-info endpoint is protected. 1450 Note that since the token contains information that allow the client 1451 and the RS to establish a security context in the first place, mutual 1452 authentication may not be possible at this point. 1454 The RS MUST be prepared to store more than one token for each client, 1455 and MUST apply the combined permissions granted by all applicable, 1456 valid tokens to client requests. 1458 5.7.2. Token Expiration 1460 Depending on the capabilities of the RS, there are various ways in 1461 which it can verify the validity of a received access token. We list 1462 the possibilities here including what functionality they require of 1463 the RS. 1465 o The token is a CWT/JWT and includes a 'exp' claim and possibly the 1466 'nbf' claim. The RS verifies these by comparing them to values 1467 from its internal clock as defined in [RFC7519]. In this case the 1468 RS's internal clock must reflect the current date and time, or at 1469 least be synchronized with the AS's clock. How this clock 1470 synchronization would be performed is out of scope for this memo. 1471 o The RS verifies the validity of the token by performing an 1472 introspection request as specified in Section 5.6. This requires 1473 the RS to have a reliable network connection to the AS and to be 1474 able to handle two secure sessions in parallel (C to RS and AS to 1475 RS). 1476 o The RS and the AS both store a sequence number linked to their 1477 common security association. The AS increments this number for 1478 each access token it issues and includes it in the access token, 1479 which is a CWT. The RS keeps track of the most recently received 1480 sequence number, and only accepts tokens as valid, that are in a 1481 certain range around this number. This method does only require 1482 the RS to keep track of the sequence number. The method does not 1483 provide timely expiration, but it makes sure that older tokens 1484 cease to be valid after a certain number of newer ones got issued. 1485 For a constrained RS with no network connectivity and no means of 1486 reliably measuring time, this is the best that can be achieved. 1488 If a token, that authorizes a long running request such as e.g. a 1489 CoAP Observe [RFC7641], expires, the RS MUST send an error response 1490 with the response code 4.01 Unauthorized to the client and then 1491 terminate processing the long running request. 1493 6. Security Considerations 1495 The entire document is about security. Security considerations 1496 applicable to authentication and authorization in RESTful 1497 environments provided in OAuth 2.0 [RFC6749] apply to this work, as 1498 well as the security considerations from [I-D.ietf-ace-actors]. 1499 Furthermore [RFC6819] provides additional security considerations for 1500 OAuth which apply to IoT deployments as well. 1502 A large range of threats can be mitigated by protecting the contents 1503 of the access token by using a digital signature or a keyed message 1504 digest. Consequently, the token integrity protection MUST be applied 1505 to prevent the token from being modified, particularly since it 1506 contains a reference to the symmetric key or the asymmetric key. If 1507 the access token contains the symmetric key, this symmetric key MUST 1508 be encrypted by the authorization server with a long-term key shared 1509 with the resource server. 1511 It is important for the authorization server to include the identity 1512 of the intended recipient (the audience), typically a single resource 1513 server (or a list of resource servers), in the token. Using a single 1514 shared secret with multiple resource servers to simplify key 1515 management is NOT RECOMMENDED since the benefit from using the proof- 1516 of-possession concept is significantly reduced. 1518 Token replay is also more difficult since an eavesdropper will have 1519 to obtain the token and the corresponding private key or shared 1520 secret that is bound to the access token. Nevertheless, it is good 1521 practice to limit the lifetime of the access token and therefore the 1522 lifetime of associated key. 1524 The authorization server MUST offer confidentiality protection for 1525 any interactions with the client. This step is extremely important 1526 since the client will obtain the session key from the authorization 1527 server for use with a specific access token. Not using 1528 confidentiality protection exposes this secret (and the access token) 1529 to an eavesdropper thereby completely negating proof-of-possession 1530 security. Profiles MUST specify how confidentiality protection is 1531 provided, and additional protection can be applied by encrypting the 1532 token, for example encryption of CWTs is specified in section 5.1 of 1533 [I-D.ietf-ace-cbor-web-token]. 1535 Developers MUST ensure that the ephemeral credentials (i.e., the 1536 private key or the session key) are not leaked to third parties. An 1537 adversary in possession of the ephemeral credentials bound to the 1538 access token will be able to impersonate the client. Be aware that 1539 this is a real risk with many constrained environments, since 1540 adversaries can often easily get physical access to the devices. 1542 Clients can at any time request a new proof-of-possession capable 1543 access token. Using a refresh token to regularly request new access 1544 tokens that are bound to fresh and unique keys is important if the 1545 client has this capability. Keeping the lifetime of the access token 1546 short allows the authorization server to use shorter key sizes, which 1547 translate to a performance benefit for the client and for the 1548 resource server. Shorter keys also lead to shorter messages 1549 (particularly with asymmetric keying material). 1551 When authorization servers bind symmetric keys to access tokens, they 1552 SHOULD scope these access tokens to a specific permissions. 1553 Furthermore access tokens SHOULD NOT apply to an audience that 1554 comprises more than one RS, since otherwise any RS in the audience 1555 can impersonate the client towards the other members of the audience. 1557 Clients using an asymmetric key pair for proof-of-possession towards 1558 several different RS should be aware that they will need to rotate 1559 that key pair more frequently than if it was only used towards a 1560 single RS. 1562 7. Privacy Considerations 1564 Implementers and users should be aware of the privacy implications of 1565 the different possible deployments of this framework. 1567 The AS is in a very central position can potentially learn sensitive 1568 information about the clients requesting access tokens. If the 1569 client credentials grant is used, the AS can track what kind of 1570 access the client intends to perform. With other grants, the 1571 Resource Owner can bind the grants to anonymous (rotating) 1572 credentials, that do not allow the AS to link different access token 1573 requests by the same client. 1575 If access tokens are only integrity protected and not encrypted, they 1576 may reveal information to attackers listening on the wire, or able to 1577 acquire the access tokens in some other way. In the case of CWTs or 1578 JWTs the token may e.g. reveal the audience, the scope and the 1579 confirmation method used by the client. The latter may reveal the 1580 client's identity. 1582 Clients using asymmetric keys for proof-of-possession should be aware 1583 of the consequences of using the same key pair for proof-of- 1584 possession towards different RS. A set of colluding RS or an 1585 attacker able to obtain the access tokens will be able to link the 1586 requests, or even to determine the client's identity. 1588 8. IANA Considerations 1590 This specification registers new parameters for OAuth and establishes 1591 registries for mappings to CBOR. 1593 8.1. OAuth Introspection Response Parameter Registration 1595 This specification registers the following parameters in the OAuth 1596 introspection response parameters 1598 o Name: "cnf" 1599 o Description: Key to prove the right to use an access token, as 1600 defined in [RFC7800]. 1601 o Change Controller: IESG 1602 o Specification Document(s): this document 1604 o Name: "aud" 1605 o Description: Reference to intended receiving RS, as defined in PoP 1606 token specification. 1608 o Change Controller: IESG 1609 o Specification Document(s): this document 1611 o Name: "profile" 1612 o Description: The communication and communication security profile 1613 used between client and RS, as defined in ACE profiles. 1614 o Change Controller: IESG 1615 o Specification Document(s): this document 1617 o Name: "client_token" 1618 o Description: Information that the RS MUST pass to the client e.g. 1619 about the proof-of-possession keys. 1620 o Change Controller: IESG 1621 o Specification Document(s): this document 1623 o Name: "rs_cnf" 1624 o Description: Describes the public key the RS uses to authenticate. 1625 o Change Controller: IESG 1626 o Specification Document(s): this document 1628 8.2. OAuth Parameter Registration 1630 This specification registers the following parameters in the OAuth 1631 Parameters Registry 1633 o Parameter name: "profile" 1634 o Parameter usage location: token request, and token response 1635 o Change Controller: IESG 1636 o Specification Document(s): this document 1638 o Name: "cnf" 1639 o Description: Key to prove the right to use an access token, as 1640 defined in [RFC7800]. 1641 o Change Controller: IESG 1642 o Specification Document(s): this document 1644 8.3. OAuth Access Token Types 1646 This specification registers the following new token type in the 1647 OAuth Access Token Types Registry 1649 o Name: "PoP" 1650 o Description: A proof-of-possession token. 1651 o Change Controller: IESG 1652 o Specification Document(s): this document 1654 8.4. Token Type Mappings 1656 A new registry will be requested from IANA, entitled "Token Type 1657 Mappings". The registry is to be created as Expert Review Required. 1659 8.4.1. Registration Template 1661 Token Type: 1662 Name of token type as registered in the OAuth token type registry 1663 e.g. "Bearer". 1664 Mapped value: 1665 Integer representation for the token type value. The key value 1666 MUST be an integer in the range of 1 to 65536. 1667 Change Controller: 1668 For Standards Track RFCs, list the "IESG". For others, give the 1669 name of the responsible party. Other details (e.g., postal 1670 address, email address, home page URI) may also be included. 1671 Specification Document(s): 1672 Reference to the document or documents that specify the 1673 parameter,preferably including URIs that can be used to retrieve 1674 copies of the documents. An indication of the relevant sections 1675 may also be included but is not required. 1677 8.4.2. Initial Registry Contents 1679 o Parameter name: "Bearer" 1680 o Mapped value: 1 1681 o Change Controller: IESG 1682 o Specification Document(s): this document 1684 o Parameter name: "pop" 1685 o Mapped value: 2 1686 o Change Controller: IESG 1687 o Specification Document(s): this document 1689 8.5. CBOR Web Token Claims 1691 This specification registers the following new claims in the CBOR Web 1692 Token (CWT) registry: 1694 o Claim Name: "scope" 1695 o Claim Description: The scope of an access token as defined in 1696 [RFC6749]. 1697 o Change Controller: IESG 1698 o Specification Document(s): this document 1700 o Claim Name: "cnf" 1701 o Claim Description: The proof-of-possession key of an access token 1702 as defined in [RFC7800]. 1703 o Change Controller: IESG 1704 o Specification Document(s): this document 1706 8.6. ACE Profile Registry 1708 A new registry will be requested from IANA, entitled "ACE Profile 1709 Registry". The registry is to be created as Expert Review Required. 1711 8.6.1. Registration Template 1713 Profile name: 1714 Name of the profile to be included in the profile attribute. 1715 Profile description: 1716 Text giving an overview of the profile and the context it is 1717 developed for. 1718 Profile ID: 1719 Integer value to identify the profile. The value MUST be an 1720 integer in the range of 1 to 65536. 1721 Change Controller: 1722 For Standards Track RFCs, list the "IESG". For others, give the 1723 name of the responsible party. Other details (e.g., postal 1724 address, email address, home page URI) may also be included. 1725 Specification Document(s): 1726 Reference to the document or documents that specify the 1727 parameter,preferably including URIs that can be used to retrieve 1728 copies of the documents. An indication of the relevant sections 1729 may also be included but is not required. 1731 8.7. OAuth Parameter Mappings Registry 1733 A new registry will be requested from IANA, entitled "Token Endpoint 1734 CBOR Mappings Registry". The registry is to be created as Expert 1735 Review Required. 1737 8.7.1. Registration Template 1739 Parameter name: 1740 OAuth Parameter name, refers to the name in the OAuth parameter 1741 registry e.g. "client_id". 1742 CBOR key value: 1743 Key value for the claim. The key value MUST be an integer in the 1744 range of 1 to 65536. 1745 Change Controller: 1746 For Standards Track RFCs, list the "IESG". For others, give the 1747 name of the responsible party. Other details (e.g., postal 1748 address, email address, home page URI) may also be included. 1750 Specification Document(s): 1751 Reference to the document or documents that specify the 1752 parameter,preferably including URIs that can be used to retrieve 1753 copies of the documents. An indication of the relevant sections 1754 may also be included but is not required. 1756 8.7.2. Initial Registry Contents 1758 o Parameter name: "aud" 1759 o CBOR key value: 3 1760 o Change Controller: IESG 1761 o Specification Document(s): this document 1763 o Parameter name: "client_id" 1764 o CBOR key value: 8 1765 o Change Controller: IESG 1766 o Specification Document(s): this document 1768 o Parameter name: "client_secret" 1769 o CBOR key value: 9 1770 o Change Controller: IESG 1771 o Specification Document(s): this document 1773 o Parameter name: "response_type" 1774 o CBOR key value: 10 1775 o Change Controller: IESG 1776 o Specification Document(s): this document 1778 o Parameter name: "redirect_uri" 1779 o CBOR key value: 11 1780 o Change Controller: IESG 1781 o Specification Document(s): this document 1783 o Parameter name: "scope" 1784 o CBOR key value: 12 1785 o Change Controller: IESG 1786 o Specification Document(s): this document 1788 o Parameter name: "state" 1789 o CBOR key value: 13 1790 o Change Controller: IESG 1791 o Specification Document(s): this document 1793 o Parameter name: "code" 1794 o CBOR key value: 14 1795 o Change Controller: IESG 1796 o Specification Document(s): this document 1797 o Parameter name: "error" 1798 o CBOR key value: 15 1799 o Change Controller: IESG 1800 o Specification Document(s): this document 1802 o Parameter name: "error_description" 1803 o CBOR key value: 16 1804 o Change Controller: IESG 1805 o Specification Document(s): this document 1807 o Parameter name: "error_uri" 1808 o CBOR key value: 17 1809 o Change Controller: IESG 1810 o Specification Document(s): this document 1812 o Parameter name: "grant_type" 1813 o CBOR key value: 18 1814 o Change Controller: IESG 1815 o Specification Document(s): this document 1817 o Parameter name: "access_token" 1818 o CBOR key value: 19 1819 o Change Controller: IESG 1820 o Specification Document(s): this document 1822 o Parameter name: "token_type" 1823 o CBOR key value: 20 1824 o Change Controller: IESG 1825 o Specification Document(s): this document 1827 o Parameter name: "expires_in" 1828 o CBOR key value: 21 1829 o Change Controller: IESG 1830 o Specification Document(s): this document 1832 o Parameter name: "username" 1833 o CBOR key value: 22 1834 o Change Controller: IESG 1835 o Specification Document(s): this document 1837 o Parameter name: "password" 1838 o CBOR key value: 23 1839 o Change Controller: IESG 1840 o Specification Document(s): this document 1842 o Parameter name: "refresh_token" 1843 o CBOR key value: 24 1844 o Change Controller: IESG 1845 o Specification Document(s): this document 1847 o Parameter name: "cnf" 1848 o CBOR key value: 25 1849 o Change Controller: IESG 1850 o Specification Document(s): this document 1852 o Parameter name: "profile" 1853 o CBOR key value: 26 1854 o Change Controller: IESG 1855 o Specification Document(s): this document 1857 8.8. Introspection Endpoint CBOR Mappings Registry 1859 A new registry will be requested from IANA, entitled "Introspection 1860 Endpoint CBOR Mappings Registry". The registry is to be created as 1861 Expert Review Required. 1863 8.8.1. Registration Template 1865 Response parameter name: 1866 Name of the response parameter as defined in the "OAuth Token 1867 Introspection Response" registry e.g. "active". 1868 CBOR key value: 1869 Key value for the claim. The key value MUST be an integer in the 1870 range of 1 to 65536. 1871 Change Controller: 1872 For Standards Track RFCs, list the "IESG". For others, give the 1873 name of the responsible party. Other details (e.g., postal 1874 address, email address, home page URI) may also be included. 1875 Specification Document(s): 1876 Reference to the document or documents that specify the 1877 parameter,preferably including URIs that can be used to retrieve 1878 copies of the documents. An indication of the relevant sections 1879 may also be included but is not required. 1881 8.8.2. Initial Registry Contents 1883 o Response parameter name: "iss" 1884 o CBOR key value: 1 1885 o Change Controller: IESG 1886 o Specification Document(s): this document 1888 o Response parameter name: "sub" 1889 o CBOR key value: 2 1890 o Change Controller: IESG 1891 o Specification Document(s): this document 1892 o Response parameter name: "aud" 1893 o CBOR key value: 3 1894 o Change Controller: IESG 1895 o Specification Document(s): this document 1897 o Response parameter name: "exp" 1898 o CBOR key value: 4 1899 o Change Controller: IESG 1900 o Specification Document(s): this document 1902 o Response parameter name: "nbf" 1903 o CBOR key value: 5 1904 o Change Controller: IESG 1905 o Specification Document(s): this document 1907 o Response parameter name: "iat" 1908 o CBOR key value: 6 1909 o Change Controller: IESG 1910 o Specification Document(s): this document 1912 o Response parameter name: "cti" 1913 o CBOR key value: 7 1914 o Change Controller: IESG 1915 o Specification Document(s): this document 1917 o Response parameter name: "client_id" 1918 o CBOR key value: 8 1919 o Change Controller: IESG 1920 o Specification Document(s): this document 1922 o Response parameter name: "scope" 1923 o CBOR key value: 12 1924 o Change Controller: IESG 1925 o Specification Document(s): this document 1927 o Response parameter name: "token_type" 1928 o CBOR key value: 20 1929 o Change Controller: IESG 1930 o Specification Document(s): this document 1932 o Response parameter name: "username" 1933 o CBOR key value: 22 1934 o Change Controller: IESG 1935 o Specification Document(s): this document 1937 o Parameter name: "cnf" 1938 o CBOR key value: 25 1939 o Change Controller: IESG 1940 o Specification Document(s): this document 1942 o Parameter name: "profile" 1943 o CBOR key value: 26 1944 o Change Controller: IESG 1945 o Specification Document(s): this document 1947 o Response parameter name: "token" 1948 o CBOR key value: 27 1949 o Change Controller: IESG 1950 o Specification Document(s): this document 1952 o Response parameter name: "token_type_hint" 1953 o CBOR key value: 28 1954 o Change Controller: IESG 1955 o Specification Document(s): this document 1957 o Response parameter name: "active" 1958 o CBOR key value: 29 1959 o Change Controller: IESG 1960 o Specification Document(s): this document 1962 o Response parameter name: "client_token" 1963 o CBOR key value: 30 1964 o Change Controller: IESG 1965 o Specification Document(s): this document 1967 o Response parameter name: "rs_cnf" 1968 o CBOR key value: 31 1969 o Change Controller: IESG 1970 o Specification Document(s): this document 1972 8.9. CoAP Option Number Registration 1974 This section registers the "Access-Token" CoAP Option Number in the 1975 "CoRE Parameters" sub-registry "CoAP Option Numbers" in the manner 1976 described in [RFC7252]. 1978 Name 1980 Access-Token 1981 Number 1983 TBD 1984 Reference 1986 [This document]. 1987 Meaning in Request 1988 Contains an Access Token according to [This document] containing 1989 access permissions of the client. 1990 Meaning in Response 1992 Not used in response 1993 Safe-to-Forward 1995 Yes 1996 Format 1998 Based on the observer the format is perceived differently. Opaque 1999 data to the client and CWT or reference token to the RS. 2000 Length 2002 Less then 255 bytes 2004 8.10. CWT Confirmation Methods Registry 2006 This specification establishes the IANA "CWT Confirmation Methods" 2007 registry for CWT "cnf" member values. The registry records the 2008 confirmation method member and a reference to the specification that 2009 defines it. 2011 8.10.1. Registration Template 2013 Confirmation Method Name: 2014 The name requested (e.g., "kid"). This name is intended to be 2015 human readable and be used for debugging purposes. It is case 2016 sensitive. Names may not match other registered names in a case- 2017 insensitive manner unless the Designated Experts state that there 2018 is a compelling reason to allow an exception. 2020 Confirmation Method Value: 2021 Integer representation for the confirmation method value. 2022 Intended for use to uniquely identify the confirmation method. 2023 The value MUST be an integer in the range of 1 to 65536. 2025 Confirmation Method Description: 2026 Brief description of the confirmation method (e.g. "Key 2027 Identifier"). 2029 Change Controller: 2030 For Standards Track RFCs, list the "IESG". For others, give the 2031 name of the responsible party. Other details (e.g., postal 2032 address, email address, home page URI) may also be included. 2034 Specification Document(s): 2036 Reference to the document or documents that specify the parameter, 2037 preferably including URIs that can be used to retrieve copies of 2038 the documents. An indication of the relevant sections may also be 2039 included but is not required. 2041 8.10.2. Initial Registry Contents 2043 o Confirmation Method Name: "COSE_Key" 2044 o Confirmation Method Value: 1 2045 o Confirmation Method Description: A COSE_Key that is either a 2046 public key or a symmetric key. 2047 o Change Controller: IESG 2048 o Specification Document(s): this document 2050 o Confirmation Method Name: "COSE_Encrypted" 2051 o Confirmation Method Value: 2 2052 o Confirmation Method Description: A COSE_Encrypted structure that 2053 wraps a COSE_Key containing a symmetric key. 2054 o Change Controller: IESG 2055 o Specification Document(s): this document 2057 o Confirmation Method Name: "Key Identifier" 2058 o Confirmation Method Value: 3 2059 o Confirmation Method Description: A key identifier. 2060 o Change Controller: IESG 2061 o Specification Document(s): this document 2063 9. Acknowledgments 2065 We would like to thank Eve Maler for her contributions to the use of 2066 OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion 2067 input, and Malisa Vucinic for his input on the predecessors of this 2068 proposal. Finally, we would like to thank the ACE working group in 2069 general for their feedback. 2071 We would like to thank the authors of draft-ietf-oauth-pop-key- 2072 distribution, from where we copied large parts of our security 2073 considerations. 2075 Ludwig Seitz and Goeran Selander worked on this document as part of 2076 the CelticPlus project CyberWI, with funding from Vinnova. 2078 10. References 2079 10.1. Normative References 2081 [I-D.ietf-cose-msg] 2082 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2083 draft-ietf-cose-msg-24 (work in progress), November 2016. 2085 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2086 Requirement Levels", BCP 14, RFC 2119, 2087 DOI 10.17487/RFC2119, March 1997, 2088 . 2090 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2091 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2092 January 2012, . 2094 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2095 Application Protocol (CoAP)", RFC 7252, 2096 DOI 10.17487/RFC7252, June 2014, 2097 . 2099 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 2100 RFC 7662, DOI 10.17487/RFC7662, October 2015, 2101 . 2103 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 2104 Possession Key Semantics for JSON Web Tokens (JWTs)", 2105 RFC 7800, DOI 10.17487/RFC7800, April 2016, 2106 . 2108 10.2. Informative References 2110 [I-D.ietf-ace-actors] 2111 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 2112 architecture for authorization in constrained 2113 environments", draft-ietf-ace-actors-05 (work in 2114 progress), March 2017. 2116 [I-D.ietf-ace-cbor-web-token] 2117 Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 2118 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-03 2119 (work in progress), March 2017. 2121 [I-D.ietf-core-object-security] 2122 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2123 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 2124 object-security-01 (work in progress), December 2016. 2126 [I-D.ietf-oauth-device-flow] 2127 Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2128 "OAuth 2.0 Device Flow for Browserless and Input 2129 Constrained Devices", draft-ietf-oauth-device-flow-04 2130 (work in progress), February 2017. 2132 [I-D.ietf-oauth-native-apps] 2133 Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2134 draft-ietf-oauth-native-apps-09 (work in progress), March 2135 2017. 2137 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2138 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2139 . 2141 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2142 (TLS) Protocol Version 1.2", RFC 5246, 2143 DOI 10.17487/RFC5246, August 2008, 2144 . 2146 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2147 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2148 . 2150 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2151 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2152 . 2154 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 2155 Threat Model and Security Considerations", RFC 6819, 2156 DOI 10.17487/RFC6819, January 2013, 2157 . 2159 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2160 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2161 October 2013, . 2163 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2164 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2165 2014, . 2167 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2168 Constrained-Node Networks", RFC 7228, 2169 DOI 10.17487/RFC7228, May 2014, 2170 . 2172 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2173 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2174 DOI 10.17487/RFC7231, June 2014, 2175 . 2177 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2178 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2179 . 2181 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 2182 "Assertion Framework for OAuth 2.0 Client Authentication 2183 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 2184 May 2015, . 2186 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 2187 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 2188 RFC 7591, DOI 10.17487/RFC7591, July 2015, 2189 . 2191 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2192 Application Protocol (CoAP)", RFC 7641, 2193 DOI 10.17487/RFC7641, September 2015, 2194 . 2196 [RFC7744] Seitz, L., Ed., Gerdes, S., Ed., Selander, G., Mani, M., 2197 and S. Kumar, "Use Cases for Authentication and 2198 Authorization in Constrained Environments", RFC 7744, 2199 DOI 10.17487/RFC7744, January 2016, 2200 . 2202 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2203 the Constrained Application Protocol (CoAP)", RFC 7959, 2204 DOI 10.17487/RFC7959, August 2016, 2205 . 2207 Appendix A. Design Justification 2209 This section provides further insight into the design decisions of 2210 the solution documented in this document. Section 3 lists several 2211 building blocks and briefly summarizes their importance. The 2212 justification for offering some of those building blocks, as opposed 2213 to using OAuth 2.0 as is, is given below. 2215 Common IoT constraints are: 2217 Low Power Radio: 2219 Many IoT devices are equipped with a small battery which needs to 2220 last for a long time. For many constrained wireless devices the 2221 highest energy cost is associated to transmitting or receiving 2222 messages. It is therefore important to keep the total 2223 communication overhead low, including minimizing the number and 2224 size of messages sent and received, which has an impact of choice 2225 on the message format and protocol. By using CoAP over UDP, and 2226 CBOR encoded messages some of these aspects are addressed. 2227 Security protocols contribute to the communication overhead and 2228 can in some cases be optimized. For example authentication and 2229 key establishment may in certain cases where security requirements 2230 so allows be replaced by provisioning of security context by a 2231 trusted third party, using transport or application layer 2232 security. 2234 Low CPU Speed: 2236 Some IoT devices are equipped with processors that are 2237 significantly slower than those found in most current devices on 2238 the Internet. This typically has implications on what timely 2239 cryptographic operations a device is capable to perform, which in 2240 turn impacts e.g. protocol latency. Symmetric key cryptography 2241 may be used instead of the computationally more expensive public 2242 key cryptography where the security requirements so allows, but 2243 this may also require support for trusted third party assisted 2244 secret key establishment using transport or application layer 2245 security. 2247 Small Amount of Memory: 2249 Microcontrollers embedded in IoT devices are often equipped with 2250 small amount of RAM and flash memory, which places limitations 2251 what kind of processing can be performed and how much code can be 2252 put on those devices. To reduce code size fewer and smaller 2253 protocol implementations can be put on the firmware of such a 2254 device. In this case, CoAP may be used instead of HTTP, symmetric 2255 key cryptography instead of public key cryptography, and CBOR 2256 instead of JSON. Authentication and key establishment protocol, 2257 e.g. the DTLS handshake, in comparison with assisted key 2258 establishment also has an impact on memory and code. 2260 User Interface Limitations: 2262 Protecting access to resources is both an important security as 2263 well as privacy feature. End users and enterprise customers do 2264 not want to give access to the data collected by their IoT device 2265 or to functions it may offer to third parties. Since the 2266 classical approach of requesting permissions from end users via a 2267 rich user interface does not work in many IoT deployment scenarios 2268 these functions need to be delegated to user controlled devices 2269 that are better suitable for such tasks, such as smart phones and 2270 tablets. 2271 Communication Constraints: 2273 In certain constrained settings an IoT device may not be able to 2274 communicate with a given device at all times. Devices may be 2275 sleeping, or just disconnected from the Internet because of 2276 general lack of connectivity in the area, for cost reasons, or for 2277 security reasons, e.g. to avoid an entry point for Denial-of- 2278 Service attacks. 2280 The communication interactions this framework builds upon (as 2281 shown graphically in Figure 1) may be accomplished using a variety 2282 of different protocols, and not all parts of the message flow are 2283 used in all applications due to the communication constraints. 2284 While we envision deployments to make use of CoAP we explicitly 2285 want to support HTTP, HTTP/2 or specific protocols, such as 2286 Bluetooth Smart communication, which does not necessarily use IP. 2287 The latter raises the need for application layer security over the 2288 various interfaces. 2290 Appendix B. Roles and Responsibilities 2292 Resource Owner 2294 * Make sure that the RS is registered at the AS. This includes 2295 making known to the AS which profiles, token_types, scopes, and 2296 key types (symmetric/asymmetric) the RS supports. Also making 2297 it known to the AS which audience(s) the RS identifies itself 2298 with. 2299 * Make sure that clients can discover the AS which is in charge 2300 of the RS. 2301 * If the client-credentials grant is used, make sure that the AS 2302 has the necessary, up-to-date, access control policies for the 2303 RS. 2305 Requesting Party 2307 * Make sure that the client is provisioned the necessary 2308 credentials to authenticate to the AS. 2309 * Make sure that the client is configured to follow the security 2310 requirements of the Requesting Party, when issuing requests 2311 (e.g. minimum communication security requirements, trust 2312 anchors). 2314 * Register the client at the AS. This includes making known to 2315 the AS which profiles, token_types, and key types (symmetric/ 2316 asymmetric) the client. 2318 Authorization Server 2320 * Register RS and manage corresponding security contexts. 2321 * Register clients and including authentication credentials. 2322 * Allow Resource Owners to configure and update access control 2323 policies related to their registered RS' 2324 * Expose the /token endpoint to allow clients to request tokens. 2325 * Authenticate clients that wish to request a token. 2326 * Process a token request against the authorization policies 2327 configured for the RS. 2328 * Optionally: Expose the /introspection endpoint that allows RS's 2329 to submit token introspection requests. 2330 * If providing an introspection endpoint: Authenticate RS's that 2331 wish to get an introspection response. 2332 * If providing an introspection endpoint: Process token 2333 introspection requests. 2334 * Optionally: Handle token revocation. 2336 Client 2338 * Discover the AS in charge of the RS that is to be targeted with 2339 a request. 2340 * Submit the token request (A). 2342 + Authenticate towards the AS. 2343 + Optionally (if not pre-configured): Specify which RS, which 2344 resource(s), and which action(s) the request(s) will target. 2345 + If raw public key (rpk) or certificate is used, make sure 2346 the AS has the right rpk or certificate for this client. 2347 * Process the access token and RS Information (B) 2349 + Check that the RS Information provides the necessary 2350 security parameters (e.g. PoP key, information on 2351 communication security protocols supported by the RS). 2352 * Send the token and request to the RS (C) 2354 + Authenticate towards the RS (this could coincide with the 2355 proof of possession process). 2356 + Transmit the token as specified by the AS (default is to the 2357 /authz-info endpoint, alternative options are specified by 2358 profiles). 2359 + Perform the proof-of-possession procedure as specified by 2360 the profile in use (this may already have been taken care of 2361 through the authentication procedure). 2363 * Process the RS response (F) requirements of the Requesting 2364 Party, when issuing requests (e.g. minimum communication 2365 security requirements, trust anchors). 2366 * Register the client at the AS. 2368 Resource Server 2370 * Expose a way to submit access tokens. By default this is the 2371 /authz-info endpoint. 2372 * Process an access token. 2374 + Verify the token is from the right AS. 2375 + Verify that the token applies to this RS. 2376 + Check that the token has not expired (if the token provides 2377 expiration information). 2378 + Check the token's integrity. 2379 + Store the token so that it can be retrieved in the context 2380 of a matching request. 2381 * Process a request. 2383 + Set up communication security with the client. 2384 + Authenticate the client. 2385 + Match the client against existing tokens. 2386 + Check that tokens belonging to the client actually authorize 2387 the requested action. 2388 + Optionally: Check that the matching tokens are still valid, 2389 using introspection (if this is possible.) 2390 * Send a response following the agreed upon communication 2391 security. 2393 Appendix C. Requirements on Profiles 2395 This section lists the requirements on profiles of this framework, 2396 for the convenience of a profile designer. 2398 o Optionally Specify the discovery process of how the client finds 2399 the right AS for an RS it wants to send a request to. Section 4 2400 o Specify the communication protocol the client and RS the must use 2401 (e.g. CoAP). Section 5 and Section 5.5.4.4 2402 o Specify the security protocol the client and RS must use to 2403 protect their communication (e.g. OSCOAP or DTLS over CoAP). 2404 This must provide encryption and integrity protection. 2405 Section 5.5.4.4 2406 o Specify how the client and the RS mutually authenticate. 2407 Section 4 2408 o Specify the Content-format of the protocol messages (e.g. 2409 "application/cbor" or "application/cose+cbor"). Section 4 2411 o Specify the proof-of-possession protocol(s) and how to select one, 2412 if several are available. Also specify which key types (e.g. 2413 symmetric/asymmetric) are supported by a specific proof-of- 2414 possession protocol. Section 5.5.4.3 2415 o Specify a unique profile identifier. Section 5.5.4.4 2416 o Optionally specify how the RS talks to the AS for 2417 introspection.Section 5.6 2418 o Optionally specify how the client talks to the AS for requesting a 2419 token. Section 5.5 2420 o Specify how/if the /authz-info endpoint is protected. 2421 Section 5.7.1 2422 o Optionally define other methods of token transport than the 2423 /authz-info endpoint. Section 5.7.1 2425 Appendix D. Assumptions on AS knowledge about C and RS 2427 This section lists the assumptions on what an AS should know about a 2428 client and a RS in order to be able to respond to requests to the 2429 /token and /introspect endpoints. How this information is 2430 established is out of scope for this document. 2432 o The identifier of the client or RS. 2433 o The profiles that the client or RS supports. 2434 o The scopes that the RS supports. 2435 o The audiences that the RS identifies with. 2436 o The key types (e.g. pre-shared symmetric key, raw public key, key 2437 length, other key parameters) that the client or RS supports. 2438 o The types of access tokens the RS supports (e.g. CWT). 2439 o If the RS supports CWTs, the COSE parameters for the crypto 2440 wrapper (e.g. algorithm, key-wrap algorithm, key-length). 2441 o The expiration time for access tokens issued to this RS (unless 2442 the RS accepts a default time chosen by the AS). 2443 o The symmetric key shared between client or RS and AS (if any). 2444 o The raw public key of the client or RS (if any). 2446 Appendix E. Deployment Examples 2448 There is a large variety of IoT deployments, as is indicated in 2449 Appendix A, and this section highlights a few common variants. This 2450 section is not normative but illustrates how the framework can be 2451 applied. 2453 For each of the deployment variants there are a number of possible 2454 security setups between clients, resource servers and authorization 2455 servers. The main focus in the following subsections is on how 2456 authorization of a client request for a resource hosted by a RS is 2457 performed. This requires the the security of the requests and 2458 responses between the clients and the RS to consider. 2460 Note: CBOR diagnostic notation is used for examples of requests and 2461 responses. 2463 E.1. Local Token Validation 2465 In this scenario we consider the case where the resource server is 2466 offline, i.e. it is not connected to the AS at the time of the access 2467 request. This access procedure involves steps A, B, C, and F of 2468 Figure 1. 2470 Since the resource server must be able to verify the access token 2471 locally, self-contained access tokens must be used. 2473 This example shows the interactions between a client, the 2474 authorization server and a temperature sensor acting as a resource 2475 server. Message exchanges A and B are shown in Figure 18. 2477 A: The client first generates a public-private key pair used for 2478 communication security with the RS. 2479 The client sends the POST request to /token at the AS. The 2480 security of this request can be transport or application layer, it 2481 is up the the communication security profile to define. In the 2482 example transport layer identification of the AS is done and the 2483 client identifies with client_id and client_secret as in classic 2484 OAuth. The request contains the public key of the client and the 2485 Audience parameter set to "tempSensorInLivingRoom", a value that 2486 the temperature sensor identifies itself with. The AS evaluates 2487 the request and authorizes the client to access the resource. 2488 B: The AS responds with a PoP token and RS Information. The PoP 2489 token contains the public key of the client, and the RS 2490 Information contains the public key of the RS. For communication 2491 security this example uses DTLS RawPublicKey between the client 2492 and the RS. The issued token will have a short validity time, 2493 i.e. 'exp' close to 'iat', to protect the RS from replay attacks. 2494 The token includes the claim such as "scope" with the authorized 2495 access that an owner of the temperature device can enjoy. In this 2496 example, the 'scope' claim, issued by the AS, informs the RS that 2497 the owner of the token, that can prove the possession of a key is 2498 authorized to make a GET request against the /temperature resource 2499 and a POST request on the /firmware resource. Note that the 2500 syntax and semantics of the scope claim are application specific. 2501 Note: In this example we assume that the client knows what 2502 resource it wants to access, and is therefore able to request 2503 specific audience and scope claims for the access token. 2505 Authorization 2506 Client Server 2507 | | 2508 |<=======>| DTLS Connection Establishment 2509 | | to identify the AS 2510 | | 2511 A: +-------->| Header: POST (Code=0.02) 2512 | POST | Uri-Path:"token" 2513 | | Content-Type: application/cbor 2514 | | Payload: 2515 | | 2516 B: |<--------+ Header: 2.05 Content 2517 | 2.05 | Content-Type: application/cbor 2518 | | Payload: 2519 | | 2521 Figure 18: Token Request and Response Using Client Credentials. 2523 The information contained in the Request-Payload and the Response- 2524 Payload is shown in Figure 19. Note that we assume a DTLS-based 2525 communication security profile for this example, therefore the 2526 Content-Type is "application/cbor". 2528 Request-Payload : 2529 { 2530 "grant_type" : "client_credentials", 2531 "aud" : "tempSensorInLivingRoom", 2532 "client_id" : "myclient", 2533 "client_secret" : "qwerty" 2534 } 2536 Response-Payload : 2537 { 2538 "access_token" : b64'SlAV32hkKG ...', 2539 "token_type" : "pop", 2540 "csp" : "DTLS", 2541 "cnf" : { 2542 "COSE_Key" : { 2543 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2544 "kty" : "EC", 2545 "crv" : "P-256", 2546 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 2547 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 2548 } 2549 } 2550 } 2552 Figure 19: Request and Response Payload Details. 2554 The content of the access token is shown in Figure 20. 2556 { 2557 "aud" : "tempSensorInLivingRoom", 2558 "iat" : "1360189224", 2559 "exp" : "1360289224", 2560 "scope" : "temperature_g firmware_p", 2561 "cnf" : { 2562 "jwk" : { 2563 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 2564 "kty" : "EC", 2565 "crv" : "P-256", 2566 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 2567 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 2568 } 2569 } 2570 } 2572 Figure 20: Access Token including Public Key of the Client. 2574 Messages C and F are shown in Figure 21 - Figure 22. 2576 C: The client then sends the PoP token to the /authz-info endpoint 2577 at the RS. This is a plain CoAP request, i.e. no transport or 2578 application layer security between client and RS, since the token 2579 is integrity protected between AS and RS. The RS verifies that 2580 the PoP token was created by a known and trusted AS, is valid, and 2581 responds to the client. The RS caches the security context 2582 together with authorization information about this client 2583 contained in the PoP token. 2585 Resource 2586 Client Server 2587 | | 2588 C: +-------->| Header: POST (Code=0.02) 2589 | POST | Uri-Path:"authz-info" 2590 | | Payload: SlAV32hkKG ... 2591 | | 2592 |<--------+ Header: 2.04 Changed 2593 | 2.04 | 2594 | | 2596 Figure 21: Access Token provisioning to RS 2597 The client and the RS runs the DTLS handshake using the raw public 2598 keys established in step B and C. 2600 The client sends the CoAP request GET to /temperature on RS over 2601 DTLS. The RS verifies that the request is authorized, based on 2602 previously established security context. 2603 F: The RS responds with a resource representation over DTLS. 2605 Resource 2606 Client Server 2607 | | 2608 |<=======>| DTLS Connection Establishment 2609 | | using Raw Public Keys 2610 | | 2611 +-------->| Header: GET (Code=0.01) 2612 | GET | Uri-Path: "temperature" 2613 | | 2614 | | 2615 | | 2616 F: |<--------+ Header: 2.05 Content 2617 | 2.05 | Payload: 2618 | | 2620 Figure 22: Resource Request and Response protected by DTLS. 2622 E.2. Introspection Aided Token Validation 2624 In this deployment scenario we assume that a client is not able to 2625 access the AS at the time of the access request. Since the RS is, 2626 however, connected to the back-end infrastructure it can make use of 2627 token introspection. This access procedure involves steps A-F of 2628 Figure 1, but assumes steps A and B have been carried out during a 2629 phase when the client had connectivity to AS. 2631 Since the client is assumed to be offline, at least for a certain 2632 period of time, a pre-provisioned access token has to be long-lived. 2633 The resource server may use its online connectivity to validate the 2634 access token with the authorization server, which is shown in the 2635 example below. 2637 In the example interactions between an offline client (key fob), a RS 2638 (online lock), and an AS is shown. We assume that there is a 2639 provisioning step where the client has access to the AS. This 2640 corresponds to message exchanges A and B which are shown in 2641 Figure 23. 2643 Authorization consent from the resource owner can be pre-configured, 2644 but it can also be provided via an interactive flow with the resource 2645 owner. An example of this for the key fob case could be that the 2646 resource owner has a connected car, he buys a generic key that he 2647 wants to use with the car. To authorize the key fob he connects it 2648 to his computer that then provides the UI for the device. After that 2649 OAuth 2.0 implicit flow can used to authorize the key for his car at 2650 the the car manufacturers AS. 2652 Note: In this example the client does not know the exact door it will 2653 be used to access since the token request is not send at the time of 2654 access. So the scope and audience parameters is set quite wide to 2655 start with and new values different form the original once can be 2656 returned from introspection later on. 2658 A: The client sends the request using POST to /token at AS. The 2659 request contains the Audience parameter set to "PACS1337" (PACS, 2660 Physical Access System), a value the that the online door in 2661 question identifies itself with. The AS generates an access token 2662 as on opaque string, which it can match to the specific client, a 2663 targeted audience and a symmetric key. The security is provided 2664 by identifying the AS on transport layer using a pre shared 2665 security context (psk, rpk or certificate) and then the client is 2666 identified using client_id and client_secret as in classic OAuth 2667 B: The AS responds with the an access token and RS Information, 2668 the latter containing a symmetric key. Communication security 2669 between C and RS will be DTLS and PreSharedKey. The PoP key being 2670 used as the PreSharedKey. 2672 Authorization 2673 Client Server 2674 | | 2675 | | 2676 A: +-------->| Header: POST (Code=0.02) 2677 | POST | Uri-Path:"token" 2678 | | Content-Type: application/cbor 2679 | | Payload: 2680 | | 2681 B: |<--------+ Header: 2.05 Content 2682 | | Content-Type: application/cbor 2683 | 2.05 | Payload: 2684 | | 2686 Figure 23: Token Request and Response using Client Credentials. 2688 The information contained in the Request-Payload and the Response- 2689 Payload is shown in Figure 24. 2691 Request-Payload: 2692 { 2693 "grant_type" : "client_credentials", 2694 "aud" : "lockOfDoor4711", 2695 "client_id" : "keyfob", 2696 "client_secret" : "qwerty" 2697 } 2699 Response-Payload: 2700 { 2701 "access_token" : b64'SlAV32hkKG ...' 2702 "token_type" : "pop", 2703 "csp" : "DTLS", 2704 "cnf" : { 2705 "COSE_Key" : { 2706 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2707 "kty" : "oct", 2708 "alg" : "HS256", 2709 "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' 2710 } 2711 } 2712 } 2714 Figure 24: Request and Response Payload for C offline 2716 The access token in this case is just an opaque string referencing 2717 the authorization information at the AS. 2719 C: Next, the client POSTs the access token to the /authz-info 2720 endpoint in the RS. This is a plain CoAP request, i.e. no DTLS 2721 between client and RS. Since the token is an opaque string, the 2722 RS cannot verify it on its own, and thus defers to respond the 2723 client with a status code until after step E. 2724 D: The RS forwards the token to the /introspect endpoint on the 2725 AS. Introspection assumes a secure connection between the AS and 2726 the RS, e.g. using transport of application layer security. In 2727 the example AS is identified using pre shared security context 2728 (psk, rpk or certificate) while RS is acting as client and is 2729 identified with client_id and client_secret. 2730 E: The AS provides the introspection response containing 2731 parameters about the token. This includes the confirmation key 2732 (cnf) parameter that allows the RS to verify the client's proof of 2733 possession in step F. 2734 After receiving message E, the RS responds to the client's POST in 2735 step C with the CoAP response code 2.01 (Created). 2737 Resource 2738 Client Server 2739 | | 2740 C: +-------->| Header: POST (T=CON, Code=0.02) 2741 | POST | Uri-Path:"authz-info" 2742 | | Content-Type: "application/cbor" 2743 | | Payload: b64'SlAV32hkKG ...'' 2744 | | 2745 | | Authorization 2746 | | Server 2747 | | | 2748 | D: +--------->| Header: POST (Code=0.02) 2749 | | POST | Uri-Path: "introspect" 2750 | | | Content-Type: "application/cbor" 2751 | | | Payload: 2752 | | | 2753 | E: |<---------+ Header: 2.05 Content 2754 | | 2.05 | Content-Type: "application/cbor" 2755 | | | Payload: 2756 | | | 2757 | | 2758 |<--------+ Header: 2.01 Created 2759 | 2.01 | 2760 | | 2762 Figure 25: Token Introspection for C offline 2763 The information contained in the Request-Payload and the Response- 2764 Payload is shown in Figure 26. 2766 Request-Payload: 2767 { 2768 "token" : b64'SlAV32hkKG...', 2769 "client_id" : "FrontDoor", 2770 "client_secret" : "ytrewq" 2771 } 2773 Response-Payload: 2774 { 2775 "active" : true, 2776 "aud" : "lockOfDoor4711", 2777 "scope" : "open, close", 2778 "iat" : 1311280970, 2779 "cnf" : { 2780 "kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 2781 } 2782 } 2784 Figure 26: Request and Response Payload for Introspection 2786 The client uses the symmetric PoP key to establish a DTLS 2787 PreSharedKey secure connection to the RS. The CoAP request PUT is 2788 sent to the uri-path /state on RS changing state of the door to 2789 locked. 2790 F: The RS responds with a appropriate over the secure DTLS 2791 channel. 2793 Resource 2794 Client Server 2795 | | 2796 |<=======>| DTLS Connection Establishment 2797 | | using Pre Shared Key 2798 | | 2799 +-------->| Header: PUT (Code=0.03) 2800 | PUT | Uri-Path: "state" 2801 | | Payload: 2802 | | 2803 F: |<--------+ Header: 2.04 Changed 2804 | 2.04 | Payload: 2805 | | 2807 Figure 27: Resource request and response protected by OSCOAP 2809 Appendix F. Document Updates 2811 F.1. Version -05 to -06 2813 o Moved sections that define the ACE framework into a subsection of 2814 the framework Section 5. 2815 o Split section on client credentials and grant into two separate 2816 sections, Section 5.1, and Section 5.2. 2817 o Added Section 5.3 on AS authentication. 2818 o Added Section 5.4 on the Authorize endpoint. 2820 F.2. Version -04 to -05 2822 o Added RFC 2119 language to the specification of the required 2823 behavior of profile specifications. 2824 o Added Section 5.2 on the relation to the OAuth2 grant types. 2825 o Added CBOR abbreviations for error and the error codes defined in 2826 OAuth2. 2827 o Added clarification about token expiration and long-running 2828 requests in Section 5.7.2 2829 o Added security considerations about tokens with symmetric pop keys 2830 valid for more than one RS. 2831 o Added privacy considerations section. 2832 o Added IANA registry mapping the confirmation types from RFC 7800 2833 to equivalent COSE types. 2835 o Added appendix D, describing assumptions about what the AS knows 2836 about the client and the RS. 2838 F.3. Version -03 to -04 2840 o Added a description of the terms "framework" and "profiles" as 2841 used in this document. 2842 o Clarified protection of access tokens in section 3.1. 2843 o Clarified uses of the 'cnf' parameter in section 6.4.5. 2844 o Clarified intended use of Client Token in section 7.4. 2846 F.4. Version -02 to -03 2848 o Removed references to draft-ietf-oauth-pop-key-distribution since 2849 the status of this draft is unclear. 2850 o Copied and adapted security considerations from draft-ietf-oauth- 2851 pop-key-distribution. 2852 o Renamed "client information" to "RS information" since it is 2853 information about the RS. 2854 o Clarified the requirements on profiles of this framework. 2855 o Clarified the token endpoint protocol and removed negotiation of 2856 'profile' and 'alg' (section 6). 2857 o Renumbered the abbreviations for claims and parameters to get a 2858 consistent numbering across different endpoints. 2859 o Clarified the introspection endpoint. 2860 o Renamed token, introspection and authz-info to 'endpoint' instead 2861 of 'resource' to mirror the OAuth 2.0 terminology. 2862 o Updated the examples in the appendices. 2864 F.5. Version -01 to -02 2866 o Restructured to remove communication security parts. These shall 2867 now be defined in profiles. 2868 o Restructured section 5 to create new sections on the OAuth 2869 endpoints /token, /introspect and /authz-info. 2870 o Pulled in material from draft-ietf-oauth-pop-key-distribution in 2871 order to define proof-of-possession key distribution. 2872 o Introduced the 'cnf' parameter as defined in RFC7800 to reference 2873 or transport keys used for proof of possession. 2874 o Introduced the 'client-token' to transport client information from 2875 the AS to the client via the RS in conjunction with introspection. 2876 o Expanded the IANA section to define parameters for token request, 2877 introspection and CWT claims. 2878 o Moved deployment scenarios to the appendix as examples. 2880 F.6. Version -00 to -01 2882 o Changed 5.1. from "Communication Security Protocol" to "Client 2883 Information". 2884 o Major rewrite of 5.1 to clarify the information exchanged between 2885 C and AS in the PoP token request profile for IoT. 2887 * Allow the client to indicate preferences for the communication 2888 security protocol. 2889 * Defined the term "Client Information" for the additional 2890 information returned to the client in addition to the access 2891 token. 2892 * Require that the messages between AS and client are secured, 2893 either with (D)TLS or with COSE_Encrypted wrappers. 2894 * Removed dependency on OSCOAP and added generic text about 2895 object security instead. 2896 * Defined the "rpk" parameter in the client information to 2897 transmit the raw public key of the RS from AS to client. 2898 * (D)TLS MUST use the PoP key in the handshake (either as PSK or 2899 as client RPK with client authentication). 2900 * Defined the use of x5c, x5t and x5tS256 parameters when a 2901 client certificate is used for proof of possession. 2902 * Defined "tktn" parameter for signaling for how to transfer the 2903 access token. 2904 o Added 5.2. the CoAP Access-Token option for transferring access 2905 tokens in messages that do not have payload. 2906 o 5.3.2. Defined success and error responses from the RS when 2907 receiving an access token. 2908 o 5.6.:Added section giving guidance on how to handle token 2909 expiration in the absence of reliable time. 2910 o Appendix B Added list of roles and responsibilities for C, AS and 2911 RS. 2913 Authors' Addresses 2915 Ludwig Seitz 2916 RISE SICS 2917 Scheelevaegen 17 2918 Lund 223 70 2919 SWEDEN 2921 Email: ludwig@ri.se 2922 Goeran Selander 2923 Ericsson 2924 Faroegatan 6 2925 Kista 164 80 2926 SWEDEN 2928 Email: goran.selander@ericsson.com 2930 Erik Wahlstroem 2931 (no affiliation) 2932 Sweden 2934 Email: erik@wahlstromtekniska.se 2936 Samuel Erdtman 2937 Spotify AB 2938 Birger Jarlsgatan 61, 4tr 2939 Stockholm 113 56 2940 Sweden 2942 Email: erdtman@spotify.com 2944 Hannes Tschofenig 2945 ARM Ltd. 2946 Hall in Tirol 6060 2947 Austria 2949 Email: Hannes.Tschofenig@arm.com