idnits 2.17.1 draft-ietf-ace-oauth-authz-07.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 (August 8, 2017) is 2446 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) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == 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-07 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-04 == Outdated reference: A later version (-15) exists of draft-ietf-oauth-device-flow-06 -- 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: 2 errors (**), 0 flaws (~~), 5 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: February 9, 2018 Ericsson 6 E. Wahlstroem 7 (no affiliation) 8 S. Erdtman 9 Spotify AB 10 H. Tschofenig 11 ARM Ltd. 12 August 8, 2017 14 Authentication and Authorization for Constrained Environments (ACE) 15 draft-ietf-ace-oauth-authz-07 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 February 9, 2018. 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 . . . . . . . . . . . . . . . . 16 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 . . . . . . . . . . . 22 77 5.5.4.1. Audience . . . . . . . . . . . . . . . . . . . . 22 78 5.5.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 22 79 5.5.4.3. Token Type . . . . . . . . . . . . . . . . . . . 23 80 5.5.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 23 81 5.5.4.5. Confirmation . . . . . . . . . . . . . . . . . . 23 82 5.5.5. Mapping parameters to CBOR . . . . . . . . . . . . . 26 83 5.6. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 26 84 5.6.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 27 85 5.6.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 27 86 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 28 87 5.6.4. Client Token . . . . . . . . . . . . . . . . . . . . 29 88 5.6.5. Mapping Introspection parameters to CBOR . . . . . . 31 89 5.7. The Access Token . . . . . . . . . . . . . . . . . . . . 31 90 5.7.1. The 'Authorization Information' Endpoint . . . . . . 32 91 5.7.2. Token Expiration . . . . . . . . . . . . . . . . . . 32 92 6. Security Considerations . . . . . . . . . . . . . . . . . . . 33 93 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 35 94 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 95 8.1. OAuth Introspection Response Parameter Registration . . . 35 96 8.2. OAuth Parameter Registration . . . . . . . . . . . . . . 36 97 8.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 36 98 8.4. Token Type Mappings . . . . . . . . . . . . . . . . . . . 36 99 8.4.1. Registration Template . . . . . . . . . . . . . . . . 37 100 8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 37 101 8.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 37 102 8.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 38 103 8.6.1. Registration Template . . . . . . . . . . . . . . . . 38 104 8.7. OAuth Parameter Mappings Registry . . . . . . . . . . . . 38 105 8.7.1. Registration Template . . . . . . . . . . . . . . . . 38 106 8.7.2. Initial Registry Contents . . . . . . . . . . . . . . 39 107 8.8. Introspection Endpoint CBOR Mappings Registry . . . . . . 41 108 8.8.1. Registration Template . . . . . . . . . . . . . . . . 41 109 8.8.2. Initial Registry Contents . . . . . . . . . . . . . . 41 110 8.9. CoAP Option Number Registration . . . . . . . . . . . . . 43 111 8.10. CWT Confirmation Methods Registry . . . . . . . . . . . . 44 112 8.10.1. Registration Template . . . . . . . . . . . . . . . 44 113 8.10.2. Initial Registry Contents . . . . . . . . . . . . . 45 114 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 45 115 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 116 10.1. Normative References . . . . . . . . . . . . . . . . . . 45 117 10.2. Informative References . . . . . . . . . . . . . . . . . 46 118 Appendix A. Design Justification . . . . . . . . . . . . . . . . 48 119 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 50 120 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 52 121 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 53 122 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 53 123 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 53 124 E.2. Introspection Aided Token Validation . . . . . . . . . . 57 125 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 61 126 F.1. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 61 127 F.2. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 61 128 F.3. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 61 129 F.4. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 62 130 F.5. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 62 131 F.6. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 62 132 F.7. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 63 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 63 135 1. Introduction 137 Authorization is the process for granting approval to an entity to 138 access a resource [RFC4949]. The authorization task itself can best 139 be described as granting access to a requesting client, for a 140 resource hosted on a device, the resource server (RS). This exchange 141 is mediated by one or multiple authorization servers (AS). Managing 142 authorization for a large number of devices and users is a complex 143 task. 145 While prior work on authorization solutions for the Web and for the 146 mobile environment also applies to the IoT environment many IoT 147 devices are constrained, for example in terms of processing 148 capabilities, available memory, etc. For web applications on 149 constrained nodes this specification makes use of CoAP [RFC7252]. 151 A detailed treatment of constraints can be found in [RFC7228], and 152 the different IoT deployments present a continuous range of device 153 and network capabilities. Taking energy consumption as an example: 154 At one end there are energy-harvesting or battery powered devices 155 which have a tight power budget, on the other end there are mains- 156 powered devices, and all levels in between. 158 Hence, IoT devices may be very different in terms of available 159 processing and message exchange capabilities and there is a need to 160 support many different authorization use cases [RFC7744]. 162 This specification describes a framework for authentication and 163 authorization in constrained environments (ACE) built on re-use of 164 OAuth 2.0 [RFC6749], thereby extending authorization to Internet of 165 Things devices. This specification contains the necessary building 166 blocks for adjusting OAuth 2.0 to IoT environments. 168 More detailed, interoperable specifications can be found in profiles. 169 Implementations may claim conformance with a specific profile, 170 whereby implementations utilizing the same profile interoperate while 171 implementations of different profiles are not expected to be 172 interoperable. Some devices, such as mobile phones and tablets, may 173 implement multiple profiles and will therefore be able to interact 174 with a wider range of low end devices. Requirements on profiles are 175 described at contextually appropriate places througout this memo, and 176 also summarized in Appendix C. 178 2. Terminology 180 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 181 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 182 "OPTIONAL" in this document are to be interpreted as described in 183 [RFC2119]. 185 Certain security-related terms such as "authentication", 186 "authorization", "confidentiality", "(data) integrity", "message 187 authentication code", and "verify" are taken from [RFC4949]. 189 Since we describe exchanges as RESTful protocol interactions HTTP 190 [RFC7231] offers useful terminology. 192 Terminology for entities in the architecture is defined in OAuth 2.0 193 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 194 server (RS), and authorization server (AS). 196 Note that the term "endpoint" is used here following its OAuth 197 definition, which is to denote resources such as /token and 198 /introspect at the AS and /authz-info at the RS. The CoAP [RFC7252] 199 definition, which is "An entity participating in the CoAP protocol" 200 is not used in this memo. 202 Since this specification focuses on the problem of access control to 203 resources, we simplify the actors by assuming that the client 204 authorization server (CAS) functionality is not stand-alone but 205 subsumed by either the authorization server or the client (see 206 section 2.2 in [I-D.ietf-ace-actors]). 208 We call the specifications of this memo the "framework" or "ACE 209 framework". When referring to "profiles of this framework" we mean 210 additional memo's that define the use of this specification with 211 concrete transport, and communication security protocols (e.g. CoAP 212 over DTLS). 214 3. Overview 216 This specification defines the ACE framework for authorization in the 217 Internet of Things environment. It consists of a set of building 218 blocks. 220 The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys 221 widespread deployment. Many IoT devices can support OAuth 2.0 222 without any additional extensions, but for certain constrained 223 settings additional profiling is needed. 225 Another building block is the lightweight web transfer protocol CoAP 226 [RFC7252] for those communication environments where HTTP is not 227 appropriate. CoAP typically runs on top of UDP which further reduces 228 overhead and message exchanges. While this specification defines 229 extensions for the use of OAuth over CoAP, we do envision further 230 underlying protocols to be supported in the future, such as HTTP/2, 231 MQTT and QUIC. 233 A third building block is CBOR [RFC7049] for encodings where JSON 234 [RFC7159] is not sufficiently compact. CBOR is a binary encoding 235 designed for small code and message size, which may be used for 236 encoding of self contained tokens, and also for encoding CoAP POST 237 parameters and CoAP responses. 239 A fourth building block is the compact CBOR-based secure message 240 format COSE [RFC8152], which enables application layer security as an 241 alternative or complement to transport layer security (DTLS [RFC6347] 242 or TLS [RFC5246]). COSE is used to secure self contained tokens such 243 as proof-of-possession (PoP) tokens, which is an extension to the 244 OAuth access tokens, and "client tokens" which are defined in this 245 framework (see Section 5.6.4). The default access token format is 246 defined in CBOR web token (CWT) [I-D.ietf-ace-cbor-web-token]. 247 Application layer security for CoAP using COSE can be provided with 248 OSCOAP [I-D.ietf-core-object-security]. 250 With the building blocks listed above, solutions satisfying various 251 IoT device and network constraints are possible. A list of 252 constraints is described in detail in RFC 7228 [RFC7228] and a 253 description of how the building blocks mentioned above relate to the 254 various constraints can be found in Appendix A. 256 Luckily, not every IoT device suffers from all constraints. The ACE 257 framework nevertheless takes all these aspects into account and 258 allows several different deployment variants to co-exist rather than 259 mandating a one-size-fits-all solution. We believe this is important 260 to cover the wide range of possible interworking use cases and the 261 different requirements from a security point of view. Once IoT 262 deployments mature, popular deployment variants will be documented in 263 form of ACE profiles. 265 In the subsections below we provide further details about the 266 different building blocks. 268 3.1. OAuth 2.0 270 The OAuth 2.0 authorization framework enables a client to obtain 271 limited access to a resource with the permission of a resource owner. 272 Authorization information, or references to it, is passed between the 273 nodes using access tokens. These access tokens are issued to clients 274 by an authorization server with the approval of the resource owner. 275 The client uses the access token to access the protected resources 276 hosted by the resource server. 278 A number of OAuth 2.0 terms are used within this specification: 280 The token and introspect Endpoints: 282 The AS hosts the /token endpoint that allows a client to request 283 access tokens. The client makes a POST request to the /token 284 endpoint on the AS and receives the access token in the response 285 (if the request was successful). 287 The token introspection endpoint, /introspect, is used by the RS 288 when requesting additional information regarding a received access 289 token. The RS makes a POST request to /introspect on the AS and 290 receives information about the access token in the response. (See 291 "Introspection" below.) 293 Access Tokens: 295 Access tokens are credentials needed to access protected 296 resources. An access token is a data structure representing 297 authorization permissions issued by the AS to the client. Access 298 tokens are generated by the authorization server and consumed by 299 the resource server. The access token content is opaque to the 300 client. 302 Access tokens can have different formats, and various methods of 303 utilization (e.g., cryptographic properties) based on the security 304 requirements of the given deployment. 306 Proof of Possession Tokens: 308 An access token may be bound to a cryptographic key, which is then 309 used by an RS to authenticate requests from a client. Such tokens 310 are called proof-of-possession tokens (or PoP tokens). 312 The proof-of-possession (PoP) security concept assumes that the AS 313 acts as a trusted third party that binds keys to access tokens. 314 These so called PoP keys are then used by the client to 315 demonstrate the possession of the secret to the RS when accessing 316 the resource. The RS, when receiving an access token, needs to 317 verify that the key used by the client matches the one bound to 318 the access token. When this specification uses the term "access 319 token" it is assumed to be a PoP token unless specifically stated 320 otherwise. 322 The key bound to the access token (aka PoP key) may be based on 323 symmetric as well as on asymmetric cryptography. The appropriate 324 choice of security depends on the constraints of the IoT devices 325 as well as on the security requirements of the use case. 327 Symmetric PoP key: The AS generates a random symmetric PoP key. 328 The key is either stored to be returned on introspection calls 329 or encrypted and included in the access token. The PoP key is 330 also encrypted for the client and sent together with the access 331 token to the client. 333 Asymmetric PoP key: An asymmetric key pair is generated on the 334 client and the public key is sent to the AS (if it does not 335 already have knowledge of the client's public key). 336 Information about the public key, which is the PoP key in this 337 case, is either stored to be returned on introspection calls or 338 included inside the access token and sent back to the 339 requesting client. The RS can identify the client's public key 340 from the information in the token, which allows the client to 341 use the corresponding private key for the proof of possession. 343 The access token is either a simple reference, or a structured 344 information object (e.g. CWT [I-D.ietf-ace-cbor-web-token]), 345 protected by a cryptographic wrapper (e.g. COSE [RFC8152]). The 346 choice of PoP key does not necessarily imply a specific credential 347 type for the integrity protection of 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 358 actually authorizes. 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 [RFC8152]. 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 [RFC7521]) and 444 the Client Credentials Grant (described in Section 4.4 of [RFC7521]). 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 625 The client or RS may be limited in the encodings or protocols it 626 supports. To support a variety of different deployment settings, 627 specific interactions between client and RS are defined in an ACE 628 profile. In ACE framework the AS is expected to manage the 629 matching of compatible profile choices between a client and an RS. 630 The AS informs the client of the selected profile using the 631 "profile" parameter in the token response. 633 OAuth 2.0 requires the use of TLS both to protect the communication 634 between AS and client when requesting an access token; between client 635 and RS when accessing a resource and between AS and RS for 636 introspection. In constrained settings TLS is not always feasible, 637 or desirable. Nevertheless it is REQUIRED that the data exchanged 638 with the AS is encrypted and integrity protected. It is furthermore 639 REQUIRED that the AS and the endpoint communicating with it (client 640 or RS) perform mutual authentication. 642 Profiles MUST specify how mutual authentication is done, depending 643 e.g. on the communication protocol and the credentials used by the 644 client or the RS. 646 In OAuth 2.0 the communication with the Token and the Introspection 647 endpoints at the AS is assumed to be via HTTP and may use Uri-query 648 parameters. This framework RECOMMENDS to use CoAP instead and 649 RECOMMENDS the use of the following alternative instead of Uri-query 650 parameters: The sender (client or RS) encodes the parameters of its 651 request as a CBOR map and submits that map as the payload of the POST 652 request. The Content-format depends on the security applied to the 653 content and MUST be specified by the profile that is used. 655 The OAuth 2.0 AS uses a JSON structure in the payload of its 656 responses both to client and RS. This framework RECOMMENDS the use 657 of CBOR [RFC7049] instead. The requesting device can explicitly 658 request this encoding by setting the CoAP Accept option in the 659 request to "application/cbor". Depending on the profile, the content 660 MAY arrive in a different format wrapping a CBOR payload. 662 5.1. Authorization Grants 664 To request an access token, the client obtains authorization from the 665 resource owner or uses its client credentials as grant. The 666 authorization is expressed in the form of an authorization grant. 668 The OAuth framework defines four grant types. The grant types can be 669 split up into two groups, those granted on behalf of the resource 670 owner (password, authorization code, implicit) and those for the 671 client (client credentials). 673 The grant type is selected depending on the use case. In cases where 674 the client acts on behalf of the resource owner, authorization code 675 grant is recommended. If the client acts on behalf of the resource 676 owner, but does not have any display or very limited interaction 677 possibilities it is recommended to use the device code grant defined 678 in [I-D.ietf-oauth-device-flow]. In cases where the client does not 679 act on behalf of the resource owner, client credentials grant is 680 recommended. 682 For details on the different grant types see the OAuth 2.0 framework. 683 The OAuth 2.0 framework provides an extension mechanism for defining 684 additional grant types so profiles of this framework MAY define 685 additional grant types if needed. 687 5.2. Client Credentials 689 Authentication of the client is mandatory independent of the grant 690 type when requesting the access token from the token endpoint. In 691 the case of client credentials grant type the authentication and 692 grant coincides. 694 Client registration and provisioning of client credentials to the 695 client is out of scope for this specification. 697 The OAuth framework, [RFC6749], defines one client credential type, 698 client id and client secret. Profiles of this framework MAY extend 699 with additional client credentials such as DTLS pre-shared keys or 700 client certificates. 702 5.3. AS Authentication 704 Client credential does not by default authenticate the AS that the 705 client connects to. In classic OAuth the AS is authenticated with a 706 TLS server certificate. 708 Profiles of this framework SHOULD specify how clients authenticate 709 the AS and how communication security is implemented, otherwise 710 server side TLS certificates as defined by OAuth 2.0 is required. 712 5.4. The 'Authorize' Endpoint 714 The authorization endpoint is used to interact with the resource 715 owner and obtain an authorization grant in certain grant flows. 716 Since it requires the use of a user agent (i.e. browser), it is not 717 expected that these types of grant flow will be used by constrained 718 clients. This endpoint is therefore out of scope for this 719 specification. Implementations should use the definition and 720 recommendations of [RFC6749] and [RFC6819]. 722 If clients involved cannot support HTTP and TLS profiles MAY define 723 mappings for the authorization endpoint. 725 5.5. The 'Token' Endpoint 727 In plain OAuth 2.0 the AS provides the /token endpoint for submitting 728 access token requests. This framework extends the functionality of 729 the /token endpoint, giving the AS the possibility to help client and 730 RS to establish shared keys or to exchange their public keys. 731 Furthermore this framework defines encodings using CoAP and CBOR, in 732 addition to HTTP and JSON. 734 For the AS to be able to issue a token the client MUST be 735 authenticated and present a valid grant for the scopes requested. 737 The figures of this section uses CBOR diagnostic notation without the 738 integer abbreviations for the parameters or their values for better 739 readability. 741 5.5.1. Client-to-AS Request 743 The client sends a CoAP POST request to the token endpoint at the AS, 744 the profile MUST specify the Content-Type and wrapping of the 745 payload. The content of the request consists of the parameters 746 specified in section 4 of the OAuth 2.0 specification [RFC6749] 747 encoded as a CBOR map. 749 In addition to these parameters, this framework defines the following 750 parameters for requesting an access token from a /token endpoint: 752 aud 753 OPTIONAL. Specifies the audience for which the client is 754 requesting an access token. If this parameter is missing it is 755 assumed that the client and the AS have a pre-established 756 understanding of the audience that an access token should address. 757 If a client submits a request for an access token without 758 specifying an "aud" parameter, and the AS does not have a default 759 "aud" value for this client, then the AS MUST respond with an 760 error message with the CoAP response code 4.00 (Bad Request). 762 cnf 763 OPTIONAL. This field contains information about the key the 764 client would like to bind to the access token for proof-of- 765 possession. It is RECOMMENDED that an AS reject a request 766 containing a symmetric key value in the 'cnf' field. See 767 Section 5.5.4.5 for more details on the formatting of the 'cnf' 768 parameter. 770 The following examples illustrate different types of requests for 771 proof-of-possession tokens. 773 Figure 2 shows a request for a token with a symmetric proof-of- 774 possession key. Note that in this example we assume a DTLS-based 775 communication security profile, therefore the Content-Type is 776 "application/cbor". The content is displayed in CBOR diagnostic 777 notation, without abbreviations for better readability. 779 Header: POST (Code=0.02) 780 Uri-Host: "server.example.com" 781 Uri-Path: "token" 782 Content-Type: "application/cbor" 783 Payload: 784 { 785 "grant_type" : "client_credentials", 786 "aud" : "tempSensor4711", 787 } 789 Figure 2: Example request for an access token bound to a symmetric 790 key. 792 Figure 3 shows a request for a token with an asymmetric proof-of- 793 possession key. Note that in this example we assume an object 794 security-based profile, therefore the Content-Type is "application/ 795 cose". 797 Header: POST (Code=0.02) 798 Uri-Host: "server.example.com" 799 Uri-Path: "token" 800 Content-Type: "application/cose" 801 Payload: 802 "COSE_Encrypted" : { 803 16( 804 [ h'a1010a', # protected header: {"alg" : "AES-CCM-16-64-128"} 805 {5 : b64'ifUvZaHFgJM7UmGnjA'}, # unprotected header, IV 806 b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext 807 ] 808 ) 809 } 811 Decrypted payload: 812 { 813 "grant_type" : "client_credentials", 814 "cnf" : { 815 "COSE_Key" : { 816 "kty" : "EC", 817 "kid" : h'11', 818 "crv" : "P-256", 819 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 820 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 821 } 822 } 823 } 825 Figure 3: Example token request bound to an asymmetric key. 827 Figure 4 shows a request for a token where a previously communicated 828 proof-of-possession key is only referenced. Note that we assume a 829 DTLS-based communication security profile for this example, therefore 830 the Content-Type is "application/cbor". Also note that the client 831 performs a password based authentication in this example by 832 submitting its client_secret (see section 2.3.1. of [RFC6749]). 834 Header: POST (Code=0.02) 835 Uri-Host: "server.example.com" 836 Uri-Path: "token" 837 Content-Type: "application/cbor" 838 Payload: 839 { 840 "grant_type" : "client_credentials", 841 "client_id" : "myclient", 842 "client_secret" : "mysecret234", 843 "aud" : "valve424", 844 "scope" : "read", 845 "cnf" : { 846 "kid" : b64'6kg0dXJM13U' 847 } 848 } 850 Figure 4: Example request for an access token bound to a key 851 reference. 853 5.5.2. AS-to-Client Response 855 If the access token request has been successfully verified by the AS 856 and the client is authorized to obtain an access token corresponding 857 to its access token request, the AS sends a response with the CoAP 858 response code 2.01 (Created). If client request was invalid, or not 859 authorized, the AS returns an error response as described in 860 Section 5.5.3. 862 Note that the AS decides which token type and profile to use when 863 issuing a successful response. It is assumed that the AS has prior 864 knowledge of the capabilities of the client, and the RS (see 865 Appendix D. This prior knowledge may, for example, be set by the use 866 of a dynamic client registration protocol exchange [RFC7591]. 868 The content of the successful reply is the RS Information. It MUST 869 be encoded as CBOR map, containing parameters as specified in section 870 5.1 of [RFC6749]. In addition to these parameters, the following 871 parameters are also part of a successful response: 873 profile 874 REQUIRED. This indicates the profile that the client MUST use 875 towards the RS. See Section 5.5.4.4 for the formatting of this 876 parameter. 878 cnf 879 REQUIRED if the token type is 'pop'. OPTIONAL otherwise. If a 880 symmetric proof-of-possession algorithms was selected, this field 881 contains the proof-of-possession key. If an asymmetric algorithm 882 was selected, this field contains information about the public key 883 used by the RS to authenticate. See Section 5.5.4.5 for the 884 formatting of this parameter. 885 token_type 886 OPTIONAL. By default implementations of this framework SHOULD 887 assume that the token_type is 'pop'. If a specific use case 888 requires another token_type (e.g. 'Bearer') to be used then this 889 parameter is REQUIRED. 891 Note that if CBOR Web Tokens [I-D.ietf-ace-cbor-web-token] are used, 892 the access token can also contain a 'cnf' claim. This claim is 893 however consumed by a different party. The access token is created 894 by the AS and processed by the RS (and opaque to the client) whereas 895 the RS Information is created by the AS and processed by the client; 896 it is never forwarded to the resource server. 898 Figure Figure 5 summarizes the parameters that may be part of the RS 899 Information. 901 /-------------------+--------------------------\ 902 | Parameter name | Specified in | 903 |-------------------+--------------------------| 904 | access_token | RFC 6749 | 905 | token_type | RFC 6749 | 906 | expires_in | RFC 6749 | 907 | refresh_token | RFC 6749 | 908 | scope | RFC 6749 | 909 | state | RFC 6749 | 910 | profile | [[ this specification ]] | 911 | cnf | [[ this specification ]] | 912 \-------------------+--------------------------/ 914 Figure 5: RS Information parameters 916 Figure 6 shows a response containing a token and a 'cnf' parameter 917 with a symmetric proof-of-possession key. Note that we assume a 918 DTLS-based communication security profile for this example, therefore 919 the Content-Type is "application/cbor". 921 Header: Created (Code=2.01) 922 Content-Type: "application/cbor" 923 Payload: 924 { 925 "access_token" : b64'SlAV32hkKG ... 926 (remainder of CWT omitted for brevity; 927 CWT contains COSE_Key in the 'cnf' claim)', 928 "profile" : "coap_dtls", 929 "expires_in" : "3600", 930 "cnf" : { 931 "COSE_Key" : { 932 "kty" : "Symmetric", 933 "kid" : b64'39Gqlw', 934 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 935 } 936 } 937 } 939 Figure 6: Example AS response with an access token bound to a 940 symmetric key. 942 5.5.3. Error Response 944 The error responses for CoAP-based interactions with the AS are 945 equivalent to the ones for HTTP-based interactions as defined in 946 section 5.2 of [RFC6749], with the following differences: 948 o The Content-Type MUST be specified by the communication security 949 profile used between client and AS. The raw payload before being 950 processed by the communication security protocol MUST be encoded 951 as a CBOR map. 952 o The CoAP response code 4.00 (Bad Request) MUST be used for all 953 error responses, except for invalid_client where the CoAP response 954 code 4.01 (Unauthorized) MAY be used under the same conditions as 955 specified in section 5.2 of [RFC6749]. 956 o The parameters "error", "error_description" and "error_uri" MAY be 957 abbreviated using the codes specified in table Figure 13. 958 o The error codes MAY be abbreviated using the codes specified in 959 table Figure 7. 961 /------------------------+----------+--------------\ 962 | error code | CBOR Key | Major Type | 963 |------------------------+----------+--------------| 964 | invalid_request | 0 | 0 (uint) | 965 | invalid_client | 1 | 0 | 966 | invalid_grant | 2 | 0 | 967 | unauthorized_client | 3 | 0 | 968 | unsupported_grant_type | 4 | 0 | 969 | invalid_scope | 5 | 0 | 970 | unsupported_pop_key | 6 | 0 | 971 \------------------------+----------+--------------/ 973 Figure 7: CBOR abbreviations for common error codes 975 In addition to the error responses defined in OAuth 2.0, the 976 follwoing behaviour MUST be implemented by the AS: If the client 977 submits an asymmetric key in the token request that the RS cannot 978 process, the AS MUST reject that request with the CoAP response code 979 4.00 (Bad Request) with the error code "unsupported_pop_key" defined 980 in figure Figure 7. 982 5.5.4. Request and Response Parameters 984 This section provides more detail about the new parameters that can 985 be used in access token requests and responses, as well as 986 abbreviations for more compact encoding of existing parameters and 987 common parameter values. 989 5.5.4.1. Audience 991 This parameter specifies for which audience the client is requesting 992 a token. It should be encoded as CBOR text string (major type 3). 993 The formatting and semantics of these strings are application 994 specific. 996 5.5.4.2. Grant Type 998 The abbreviations in Figure 8 MAY be used in CBOR encodings instead 999 of the string values defined in [RFC6749]. 1001 /--------------------+----------+--------------\ 1002 | grant_type | CBOR Key | Major Type | 1003 |--------------------+----------+--------------| 1004 | password | 0 | 0 (uint) | 1005 | authorization_code | 1 | 0 | 1006 | client_credentials | 2 | 0 | 1007 | refresh_token | 3 | 0 | 1008 \--------------------+----------+--------------/ 1010 Figure 8: CBOR abbreviations for common grant types 1012 5.5.4.3. Token Type 1014 The token_type parameter is defined in [RFC6749], allowing the AS to 1015 indicate to the client which type of access token it is receiving 1016 (e.g. a bearer token). 1018 This document registers the new value "pop" for the OAuth Access 1019 Token Types registry, specifying a Proof-of-Possession token. How 1020 the proof-of-possession is performed MUST be specified by the 1021 profiles. 1023 The values in the 'token_type' parameter MUST be CBOR text strings 1024 (major type 3). 1026 In this framework token type 'pop' MUST be assumed by default if the 1027 AS does not provide a different value. 1029 5.5.4.4. Profile 1031 Profiles of this framework MUST define the communication protocol and 1032 the communication security protocol between the client and the RS. 1033 Furthermore profiles MUST define proof-of-possession methods, if they 1034 support proof-of-possession tokens. 1036 A profile MUST specify an identifier that is used to uniquely 1037 identify itself in the 'profile' parameter. 1039 Profiles MAY define additional parameters for both the token request 1040 and the RS Information in the access token response in order to 1041 support negotiation or signalling of profile specific parameters. 1043 5.5.4.5. Confirmation 1045 The "cnf" parameter identifies or provides the key used for proof-of- 1046 possession or for authenticating the RS depending on the proof-of- 1047 possession algorithm and the context cnf is used in. This framework 1048 extends the definition of 'cnf' from [RFC7800] by adding CBOR/COSE 1049 encodings and the use of 'cnf' for transporting keys in the RS 1050 Information. 1052 The "cnf" parameter is used in the following contexts with the 1053 following meaning: 1055 o In the access token, to indicate the proof-of-possession key bound 1056 to this token. 1057 o In the token request C -> AS, to indicate the client's raw public 1058 key, or the key-identifier of a previously established key between 1059 C and RS. 1060 o In the token response AS -> C, to indicate either the symmetric 1061 key generated by the AS for proof-of-possession or the raw public 1062 key used by the RS to authenticate. 1063 o In the introspection response AS -> RS, to indicate the proof-of- 1064 possession key bound to the introspected token. 1065 o In the client token AS -> RS -> C, to indicate the proof-of- 1066 possession key bound to the access token. 1068 A CBOR encoded payload MAY contain the 'cnf' parameter with the 1069 following contents: 1071 COSE_Key In this case the 'cnf' parameter contains the proof-of- 1072 possession key to be used by the client. An example is shown in 1073 Figure 9. 1075 "cnf" : { 1076 "COSE_Key" : { 1077 "kty" : "EC", 1078 "kid" : h'11', 1079 "crv" : "P-256", 1080 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 1081 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 1082 } 1083 } 1085 Figure 9: Confirmation parameter containing a public key 1087 Note that the COSE_Key structure may contain an "alg" or "key_ops" 1088 parameter. If such parameters are present, a client MUST NOT use 1089 a key that is not compatible with the profile or proof-of- 1090 possession algorithm according to those parameters. 1091 COSE_Encrypted In this case the 'cnf' parameter contains an 1092 encrypted symmetric key destined for the client. The client is 1093 assumed to be able to decrypt the ciphertext of this parameter. 1094 The parameter is encoded as COSE_Encrypted object wrapping a 1095 COSE_Key object. Figure 10 shows an example of this type of 1096 encoding. 1098 "cnf" : { 1099 "COSE_Encrypted" : { 1100 993( 1101 [ h'a1010a' # protected header : {"alg" : "AES-CCM-16-64-128"} 1102 "iv" : b64'ifUvZaHFgJM7UmGnjA', # unprotected header 1103 b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext 1104 ] 1105 ) 1106 } 1107 } 1109 Figure 10: Confirmation parameter containing an encrypted symmetric 1110 key 1112 The ciphertext here could e.g. contain a symmetric key as in 1113 Figure 11. 1115 { 1116 "kty" : "Symmetric", 1117 "kid" : b64'39Gqlw', 1118 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1119 } 1121 Figure 11: Example plaintext of an encrypted cnf parameter 1123 Key Identifier In this case the 'cnf' parameter references a key 1124 that is assumed to be previously known by the recipient. This 1125 allows clients that perform repeated requests for an access token 1126 for the same audience but e.g. with different scopes to omit key 1127 transport in the access token, token request and token response. 1128 Figure 12 shows such an example. 1130 "cnf" : { 1131 "kid" : b64'39Gqlw' 1132 } 1134 Figure 12: A Confirmation parameter with just a key identifier 1136 This specification establishes the IANA "CWT Confirmation Methods" 1137 registry for these types of confirmation methods in Section 8.10 and 1138 registers the methods defined by this specification. Other 1139 specifications can register other methods used for confirmation. The 1140 registry is meant to be analogous to the "JWT Confirmation Methods" 1141 registry defined by [RFC7800]. 1143 5.5.5. Mapping parameters to CBOR 1145 All OAuth parameters in access token requests and responses are 1146 mapped to CBOR types as follows and are given an integer key value to 1147 save space. 1149 /-------------------+----------+-----------------\ 1150 | Parameter name | CBOR Key | Major Type | 1151 |-------------------+----------+-----------------| 1152 | aud | 3 | 3 | 1153 | client_id | 8 | 3 (text string) | 1154 | client_secret | 9 | 2 (byte string) | 1155 | response_type | 10 | 3 | 1156 | redirect_uri | 11 | 3 | 1157 | scope | 12 | 3 | 1158 | state | 13 | 3 | 1159 | code | 14 | 2 | 1160 | error | 15 | 3 | 1161 | error_description | 16 | 3 | 1162 | error_uri | 17 | 3 | 1163 | grant_type | 18 | 0 | 1164 | access_token | 19 | 3 | 1165 | token_type | 20 | 0 | 1166 | expires_in | 21 | 0 | 1167 | username | 22 | 3 | 1168 | password | 23 | 3 | 1169 | refresh_token | 24 | 3 | 1170 | cnf | 25 | 5 (map) | 1171 | profile | 26 | 3 | 1172 \-------------------+----------+-----------------/ 1174 Figure 13: CBOR mappings used in token requests 1176 5.6. The 'Introspect' Endpoint 1178 Token introspection [RFC7662] is used by the RS and potentially the 1179 client to query the AS for metadata about a given token e.g. validity 1180 or scope. Analogous to the protocol defined in RFC 7662 [RFC7662] 1181 for HTTP and JSON, this section defines adaptations to more 1182 constrained environments using CoAP and CBOR. 1184 Communication between the RS and the introspection endpoint at the AS 1185 MUST be integrity protected and encrypted. Furthermore AS and RS 1186 MUST perform mutual authentication. Finally the AS SHOULD verify 1187 that the RS has the right to access introspection information about 1188 the provided token. Profiles of this framework that support 1189 introspection MUST specify how authentication and communication 1190 security between RS and AS is implemented. 1192 The figures of this section uses CBOR diagnostic notation without the 1193 integer abbreviations for the parameters or their values for better 1194 readability. 1196 5.6.1. RS-to-AS Request 1198 The RS sends a CoAP POST request to the introspection endpoint at the 1199 AS, the profile MUST specify the Content-Type and wrapping of the 1200 payload. The payload MUST be encoded as a CBOR map with a 'token' 1201 parameter containing the access token along with optional parameters 1202 representing additional context that is known by the RS to aid the AS 1203 in its response. 1205 The same parameters are required and optional as in section 2.1 of 1206 RFC 7662 [RFC7662]. 1208 For example, Figure 14 shows a RS calling the token introspection 1209 endpoint at the AS to query about an OAuth 2.0 proof-of-possession 1210 token. Note that we assume a object security-based communication 1211 security profile for this example, therefore the Content-Type is 1212 "application/cose+cbor". 1214 Header: POST (Code=0.02) 1215 Uri-Host: "server.example.com" 1216 Uri-Path: "introspect" 1217 Content-Type: "application/cose+cbor" 1218 Payload: 1219 { 1220 "token" : b64'7gj0dXJQ43U', 1221 "token_type_hint" : "pop" 1222 } 1224 Figure 14: Example introspection request. 1226 5.6.2. AS-to-RS Response 1228 If the introspection request is authorized and successfully 1229 processed, the AS sends a response with the CoAP response code 2.01 1230 (Created). If the introspection request was invalid, not authorized 1231 or couldn't be processed the AS returns an error response as 1232 described in Section 5.6.3. 1234 In a successful response, the AS encodes the response parameters in a 1235 CBOR map including with the same required and optional parameters as 1236 in section 2.2. of RFC 7662 [RFC7662] with the following additions: 1238 cnf 1239 OPTIONAL. This field contains information about the proof-of- 1240 possession key that binds the client to the access token. See 1241 Section 5.5.4.5 for more details on the formatting of the 'cnf' 1242 parameter. 1244 profile 1245 OPTIONAL. This indicates the profile that the RS MUST use with 1246 the client. See Section 5.5.4.4 for more details on the 1247 formatting of this parameter. 1249 client_token 1250 OPTIONAL. This parameter contains information that the RS MUST 1251 pass on to the client. See Section 5.6.4 for more details. 1253 For example, Figure 15 shows an AS response to the introspection 1254 request in Figure 14. Note that we assume a DTLS-based communication 1255 security profile for this example, therefore the Content-Type is 1256 "application/cbor". 1258 Header: Created Code=2.01) 1259 Content-Type: "application/cbor" 1260 Payload: 1261 { 1262 "active" : true, 1263 "scope" : "read", 1264 "profile" : "coap_dtls", 1265 "client_token" : b64'2QPhg0OhAQo ... 1266 (remainder of client token omitted for brevity)', 1267 "cnf" : { 1268 "COSE_Key" : { 1269 "kty" : "Symmetric", 1270 "kid" : b64'39Gqlw', 1271 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1272 } 1273 } 1274 } 1276 Figure 15: Example introspection response. 1278 5.6.3. Error Response 1280 The error responses for CoAP-based interactions with the AS are 1281 equivalent to the ones for HTTP-based interactions as defined in 1282 section 2.3 of [RFC7662], with the following differences: 1284 o If content is sent, the Content-Type MUST be set according to the 1285 specification of the communication security profile, and the 1286 content payload MUST be encoded as a CBOR map. 1288 o If the credentials used by the RS are invalid the AS MUST respond 1289 with the CoAP response code 4.01 (Unauthorized) and use the 1290 required and optional parameters from section 5.2 in RFC 6749 1291 [RFC6749]. 1292 o If the RS does not have the right to perform this introspection 1293 request, the AS MUST respond with the CoAP response code 4.03 1294 (Forbidden). In this case no payload is returned. 1295 o The parameters "error", "error_description" and "error_uri" MAY be 1296 abbreviated using the codes specified in table Figure 13. 1297 o The error codes MAY be abbreviated using the codes specified in 1298 table Figure 7. 1300 Note that a properly formed and authorized query for an inactive or 1301 otherwise invalid token does not warrant an error response by this 1302 specification. In these cases, the authorization server MUST instead 1303 respond with an introspection response with the "active" field set to 1304 "false". 1306 5.6.4. Client Token 1308 EDITORIAL NOTE: We have tentatively introduced this concept and would 1309 specifically like feedback whether this is viewed as a useful 1310 addition to the framework. 1312 In cases where the client has limited connectivity and needs to get 1313 access to a previously unknown resource servers, this framework 1314 suggests the following approach: The client is pre-configured with a 1315 generic, long-term access token when it is commissioned. When the 1316 client then tries to access a RS it transmits this access token. The 1317 RS then performs token introspection to learn what access this token 1318 grants. In the introspection response, the AS also relays 1319 information for the client, such as the proof-of-possession key, 1320 through the RS. The RS passes on this Client Token to the client in 1321 response to the submission of the token. 1323 The client_token parameter is designed to carry such information, and 1324 is intended to be used as described in Figure 16. 1326 Resource Authorization 1327 Client Server Server 1328 | | | 1329 | | | 1330 C: +--------------->| | 1331 | POST | | 1332 | Access Token | | 1333 | D: +--------------->| 1334 | | Introspection | 1335 | | Request | 1336 | | | 1337 | E: +<---------------+ 1338 | | Introspection | 1339 | | Response | 1340 | | + Client Token | 1341 |<---------------+ | 1342 | 2.01 Created | | 1343 | + Client Token | 1345 Figure 16: Use of the client_token parameter. 1347 The client token is a COSE_Encrypted object, containing as payload a 1348 CBOR map with the following claims: 1350 cnf 1351 REQUIRED if the token type is 'pop', OPTIONAL otherwise. Contains 1352 information about the proof-of-possession key the client is to use 1353 with its access token. See Section 5.5.4.5. 1355 token_type 1356 OPTIONAL. See Section 5.5.4.3. 1358 profile 1359 REQUIRED. See Section 5.5.4.4. 1361 rs_cnf 1362 OPTIONAL. Contains information about the key that the RS uses to 1363 authenticate towards the client. If the key is symmetric then 1364 this claim MUST NOT be part of the Client Token, since this is the 1365 same key as the one specified through the 'cnf' claim. This claim 1366 uses the same encoding as the 'cnf' parameter. See 1367 Section 5.5.4.4. 1369 The AS encrypts this token using a key shared between the AS and the 1370 client, so that only the client can decrypt it and access its 1371 payload. How this key is established is out of scope of this 1372 framework, however it can be established at the same time at which 1373 the client's long term token is created. 1375 5.6.5. Mapping Introspection parameters to CBOR 1377 The introspection request and response parameters are mapped to CBOR 1378 types as follows and are given an integer key value to save space. 1380 /-----------------+----------+-----------------\ 1381 | Parameter name | CBOR Key | Major Type | 1382 |-----------------+----------+-----------------| 1383 | iss | 1 | 3 (text string) | 1384 | sub | 2 | 3 | 1385 | aud | 3 | 3 | 1386 | exp | 4 | 6 tag value 1 | 1387 | nbf | 5 | 6 tag value 1 | 1388 | iat | 6 | 6 tag value 1 | 1389 | cti | 7 | 2 (byte string) | 1390 | client_id | 8 | 3 | 1391 | scope | 12 | 3 | 1392 | token_type | 20 | 3 | 1393 | username | 22 | 3 | 1394 | cnf | 25 | 5 (map) | 1395 | profile | 26 | 0 (uint) | 1396 | token | 27 | 3 | 1397 | token_type_hint | 28 | 3 | 1398 | active | 29 | 0 | 1399 | client_token | 30 | 3 | 1400 | rs_cnf | 31 | 5 | 1401 \-----------------+----------+-----------------/ 1403 Figure 17: CBOR Mappings to Token Introspection Parameters. 1405 5.7. The Access Token 1407 This framework RECOMMENDS the use of CBOR web token (CWT) as 1408 specified in [I-D.ietf-ace-cbor-web-token]. 1410 In order to facilitate offline processing of access tokens, this 1411 draft specifies the "cnf" and "scope" claims for CBOR web tokens. 1413 The "scope" claim explicitly encodes the scope of a given access 1414 token. This claim follows the same encoding rules as defined in 1415 section 3.3 of [RFC6749]. The meaning of a specific scope value is 1416 application specific and expected to be known to the RS running that 1417 application. 1419 The "cnf" claim follows the same rules as specified for JOSE web 1420 token in RFC7800 [RFC7800], except that it is encoded in COSE in the 1421 same way as specified for the "cnf" parameter in Section 5.5.4.5. 1423 5.7.1. The 'Authorization Information' Endpoint 1425 The access token, containing authorization information and 1426 information about the key used by the client, needs to be transported 1427 to the RS so that the RS can authenticate and authorize the client 1428 request. 1430 This section defines a method for transporting the access token to 1431 the RS using CoAP. Profiles of this framework MAY define other 1432 methods for token transport. 1434 The method consists of an /authz-info endpoint, implemented by the 1435 RS. A client using this method MUST make a POST request to /authz- 1436 info at the RS with the access token in the payload. The RS 1437 receiving the token MUST verify the validity of the token. If the 1438 token is valid, the RS MUST respond to the POST request with 2.01 1439 (Created). This response MAY contain the identifier of the token 1440 (e.g. the cti for a CWT) as a payload. 1442 If the token is not valid, the RS MUST respond with the CoAP response 1443 code 4.01 (Unauthorized). If the token is valid but the audience of 1444 the token does not match the RS, the RS MUST respond with the CoAP 1445 response code 4.03 (Forbidden). If the token is valid but is 1446 associated to claims that the RS cannot process (e.g. an unknown 1447 scope) the RS MUST respond with the CoAP response code 4.00 (Bad 1448 Request). In the latter case the RS MAY provide additional 1449 information in the error response, in order to clarify what went 1450 wrong. 1452 The RS MAY make an introspection request to validate the token before 1453 responding to the POST /authz-info request. If the introspection 1454 response contains a client token (Section 5.6.4) then this token 1455 SHALL be included in the payload of the 2.01 (Created) response. 1457 Profiles MUST specify how the /authz-info endpoint is protected. 1458 Note that since the token contains information that allow the client 1459 and the RS to establish a security context in the first place, mutual 1460 authentication may not be possible at this point. 1462 The RS MUST be prepared to store more than one token for each client, 1463 and MUST apply the combined permissions granted by all applicable, 1464 valid tokens to client requests. 1466 5.7.2. Token Expiration 1468 Depending on the capabilities of the RS, there are various ways in 1469 which it can verify the validity of a received access token. We list 1470 the possibilities here including what functionality they require of 1471 the RS. 1473 o The token is a CWT/JWT and includes a 'exp' claim and possibly the 1474 'nbf' claim. The RS verifies these by comparing them to values 1475 from its internal clock as defined in [RFC7519]. In this case the 1476 RS's internal clock must reflect the current date and time, or at 1477 least be synchronized with the AS's clock. How this clock 1478 synchronization would be performed is out of scope for this memo. 1479 o The RS verifies the validity of the token by performing an 1480 introspection request as specified in Section 5.6. This requires 1481 the RS to have a reliable network connection to the AS and to be 1482 able to handle two secure sessions in parallel (C to RS and AS to 1483 RS). 1484 o The RS and the AS both store a sequence number linked to their 1485 common security association. The AS increments this number for 1486 each access token it issues and includes it in the access token, 1487 which is a CWT. The RS keeps track of the most recently received 1488 sequence number, and only accepts tokens as valid, that are in a 1489 certain range around this number. This method does only require 1490 the RS to keep track of the sequence number. The method does not 1491 provide timely expiration, but it makes sure that older tokens 1492 cease to be valid after a certain number of newer ones got issued. 1493 For a constrained RS with no network connectivity and no means of 1494 reliably measuring time, this is the best that can be achieved. 1496 If a token, that authorizes a long running request such as e.g. a 1497 CoAP Observe [RFC7641], expires, the RS MUST send an error response 1498 with the response code 4.01 Unauthorized to the client and then 1499 terminate processing the long running request. 1501 6. Security Considerations 1503 Security considerations applicable to authentication and 1504 authorization in RESTful environments provided in OAuth 2.0 [RFC6749] 1505 apply to this work, as well as the security considerations from 1506 [I-D.ietf-ace-actors]. Furthermore [RFC6819] provides additional 1507 security considerations for OAuth which apply to IoT deployments as 1508 well. 1510 A large range of threats can be mitigated by protecting the contents 1511 of the access token by using a digital signature or a keyed message 1512 digest (MAC) or an AEAD algorithm. Consequently, the token integrity 1513 protection MUST be applied to prevent the token from being modified, 1514 particularly since it contains a reference to the symmetric key or 1515 the asymmetric key. If the access token contains the symmetric key, 1516 this symmetric key MUST be encrypted by the authorization server so 1517 that only the resource server can decrypt it. Note that using an 1518 AEAD algorithm is preferrable over using a MAC unless the message 1519 needs to be publicly readable. 1521 It is important for the authorization server to include the identity 1522 of the intended recipient (the audience), typically a single resource 1523 server (or a list of resource servers), in the token. Using a single 1524 shared secret with multiple resource servers to simplify key 1525 management is NOT RECOMMENDED since the benefit from using the proof- 1526 of-possession concept is significantly reduced. 1528 The authorization server MUST offer confidentiality protection for 1529 any interactions with the client. This step is extremely important 1530 since the client may obtion the proof-of-possession key from the 1531 authorization server for use with a specific access token. Not using 1532 confidentiality protection exposes this secret (and the access token) 1533 to an eavesdropper thereby completely negating proof-of-possession 1534 security. Profiles MUST specify how confidentiality protection is 1535 provided, and additional protection can be applied by encrypting the 1536 token, for example encryption of CWTs is specified in section 5.1 of 1537 [I-D.ietf-ace-cbor-web-token]. 1539 Developers MUST ensure that the ephemeral credentials (i.e., the 1540 private key or the session key) are not leaked to third parties. An 1541 adversary in possession of the ephemeral credentials bound to the 1542 access token will be able to impersonate the client. Be aware that 1543 this is a real risk with many constrained environments, since 1544 adversaries can often easily get physical access to the devices. 1546 Clients can at any time request a new proof-of-possession capable 1547 access token. If clients have that capability, the AS can keep the 1548 lifetime of the access token and the associated proof-of-possesion 1549 key short and therefore use shorter proof-of-possession key sizes, 1550 which translate to a performance benefit for the client and for the 1551 resource server. Shorter keys also lead to shorter messages 1552 (particularly with asymmetric keying material). 1554 When authorization servers bind symmetric keys to access tokens, they 1555 SHOULD scope these access tokens to a specific permissions. 1556 Furthermore access tokens using symmetric keys for proof-of- 1557 possession SHOULD NOT be targeted at an audience that contains more 1558 than one RS, since otherwise any RS in the audience that receives 1559 that access token can impersonate the client towards the other 1560 members of the audience. 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 this can be 1571 prevented by the Resource Owner. To do so the resource owner needs 1572 to bind the grants it issues to anonymous, ephemeral credentials, 1573 that do not allow the AS to link different grants and thus different 1574 access token requests by the same client. 1576 If access tokens are only integrity protected and not encrypted, they 1577 may reveal information to attackers listening on the wire, or able to 1578 acquire the access tokens in some other way. In the case of CWTs or 1579 JWTs the token may e.g. reveal the audience, the scope and the 1580 confirmation method used by the client. The latter may reveal the 1581 client's identity. 1583 Clients using asymmetric keys for proof-of-possession should be aware 1584 of the consequences of using the same key pair for proof-of- 1585 possession towards different RS. A set of colluding RS or an 1586 attacker able to obtain the access tokens will be able to link the 1587 requests, or even to determine the client's identity. 1589 8. IANA Considerations 1591 This specification registers new parameters for OAuth and establishes 1592 registries for mappings to CBOR. 1594 8.1. OAuth Introspection Response Parameter Registration 1596 This specification registers the following parameters in the OAuth 1597 introspection response parameters 1599 o Name: "cnf" 1600 o Description: Key to prove the right to use an access token, as 1601 defined in [RFC7800]. 1602 o Change Controller: IESG 1603 o Specification Document(s): this document 1605 o Name: "aud" 1606 o Description: Reference to intended receiving RS, as defined in PoP 1607 token specification. 1608 o Change Controller: IESG 1609 o Specification Document(s): this document 1610 o Name: "profile" 1611 o Description: The communication and communication security profile 1612 used between client and RS, as defined in ACE profiles. 1613 o Change Controller: IESG 1614 o Specification Document(s): this document 1616 o Name: "client_token" 1617 o Description: Information that the RS MUST pass to the client e.g. 1618 about the proof-of-possession keys. 1619 o Change Controller: IESG 1620 o Specification Document(s): this document 1622 o Name: "rs_cnf" 1623 o Description: Describes the public key the RS uses to authenticate. 1624 o Change Controller: IESG 1625 o Specification Document(s): this document 1627 8.2. OAuth Parameter Registration 1629 This specification registers the following parameters in the OAuth 1630 Parameters Registry 1632 o Parameter name: "profile" 1633 o Parameter usage location: token request, and token response 1634 o Change Controller: IESG 1635 o Specification Document(s): this document 1637 o Name: "cnf" 1638 o Description: Key to prove the right to use an access token, as 1639 defined in [RFC7800]. 1640 o Change Controller: IESG 1641 o Specification Document(s): this document 1643 8.3. OAuth Access Token Types 1645 This specification registers the following new token type in the 1646 OAuth Access Token Types Registry 1648 o Name: "PoP" 1649 o Description: A proof-of-possession token. 1650 o Change Controller: IESG 1651 o Specification Document(s): this document 1653 8.4. Token Type Mappings 1655 A new registry will be requested from IANA, entitled "Token Type 1656 Mappings". The registry is to be created as Expert Review Required. 1658 8.4.1. Registration Template 1660 Token Type: 1661 Name of token type as registered in the OAuth token type registry 1662 e.g. "Bearer". 1663 Mapped value: 1664 Integer representation for the token type value. The key value 1665 MUST be an integer in the range of 1 to 65536. 1666 Change Controller: 1667 For Standards Track RFCs, list the "IESG". For others, give the 1668 name of the responsible party. Other details (e.g., postal 1669 address, email address, home page URI) may also be included. 1670 Specification Document(s): 1671 Reference to the document or documents that specify the 1672 parameter,preferably including URIs that can be used to retrieve 1673 copies of the documents. An indication of the relevant sections 1674 may also be included but is not required. 1676 8.4.2. Initial Registry Contents 1678 o Parameter name: "Bearer" 1679 o Mapped value: 1 1680 o Change Controller: IESG 1681 o Specification Document(s): this document 1683 o Parameter name: "pop" 1684 o Mapped value: 2 1685 o Change Controller: IESG 1686 o Specification Document(s): this document 1688 8.5. CBOR Web Token Claims 1690 This specification registers the following new claims in the CBOR Web 1691 Token (CWT) registry: 1693 o Claim Name: "scope" 1694 o Claim Description: The scope of an access token as defined in 1695 [RFC6749]. 1696 o Change Controller: IESG 1697 o Specification Document(s): this document 1699 o Claim Name: "cnf" 1700 o Claim Description: The proof-of-possession key of an access token 1701 as defined in [RFC7800]. 1702 o Change Controller: IESG 1703 o Specification Document(s): this document 1705 8.6. ACE Profile Registry 1707 A new registry will be requested from IANA, entitled "ACE Profile 1708 Registry". The registry is to be created as Expert Review Required. 1710 8.6.1. Registration Template 1712 Profile name: 1713 Name of the profile to be included in the profile attribute. 1714 Profile description: 1715 Text giving an overview of the profile and the context it is 1716 developed for. 1717 Profile ID: 1718 Integer value to identify the profile. The value MUST be an 1719 integer in the range of 1 to 65536. 1720 Change Controller: 1721 For Standards Track RFCs, list the "IESG". For others, give the 1722 name of the responsible party. Other details (e.g., postal 1723 address, email address, home page URI) may also be included. 1724 Specification Document(s): 1725 Reference to the document or documents that specify the 1726 parameter,preferably including URIs that can be used to retrieve 1727 copies of the documents. An indication of the relevant sections 1728 may also be included but is not required. 1730 8.7. OAuth Parameter Mappings Registry 1732 A new registry will be requested from IANA, entitled "Token Endpoint 1733 CBOR Mappings Registry". The registry is to be created as Expert 1734 Review Required. 1736 8.7.1. Registration Template 1738 Parameter name: 1739 OAuth Parameter name, refers to the name in the OAuth parameter 1740 registry e.g. "client_id". 1741 CBOR key value: 1742 Key value for the claim. The key value MUST be an integer in the 1743 range of 1 to 65536. 1744 Change Controller: 1745 For Standards Track RFCs, list the "IESG". For others, give the 1746 name of the responsible party. Other details (e.g., postal 1747 address, email address, home page URI) may also be included. 1748 Specification Document(s): 1749 Reference to the document or documents that specify the 1750 parameter,preferably including URIs that can be used to retrieve 1751 copies of the documents. An indication of the relevant sections 1752 may also be included but is not required. 1754 8.7.2. Initial Registry Contents 1756 o Parameter name: "aud" 1757 o CBOR key value: 3 1758 o Change Controller: IESG 1759 o Specification Document(s): this document 1761 o Parameter name: "client_id" 1762 o CBOR key value: 8 1763 o Change Controller: IESG 1764 o Specification Document(s): this document 1766 o Parameter name: "client_secret" 1767 o CBOR key value: 9 1768 o Change Controller: IESG 1769 o Specification Document(s): this document 1771 o Parameter name: "response_type" 1772 o CBOR key value: 10 1773 o Change Controller: IESG 1774 o Specification Document(s): this document 1776 o Parameter name: "redirect_uri" 1777 o CBOR key value: 11 1778 o Change Controller: IESG 1779 o Specification Document(s): this document 1781 o Parameter name: "scope" 1782 o CBOR key value: 12 1783 o Change Controller: IESG 1784 o Specification Document(s): this document 1786 o Parameter name: "state" 1787 o CBOR key value: 13 1788 o Change Controller: IESG 1789 o Specification Document(s): this document 1791 o Parameter name: "code" 1792 o CBOR key value: 14 1793 o Change Controller: IESG 1794 o Specification Document(s): this document 1796 o Parameter name: "error" 1797 o CBOR key value: 15 1798 o Change Controller: IESG 1799 o Specification Document(s): this document 1801 o Parameter name: "error_description" 1802 o CBOR key value: 16 1803 o Change Controller: IESG 1804 o Specification Document(s): this document 1806 o Parameter name: "error_uri" 1807 o CBOR key value: 17 1808 o Change Controller: IESG 1809 o Specification Document(s): this document 1811 o Parameter name: "grant_type" 1812 o CBOR key value: 18 1813 o Change Controller: IESG 1814 o Specification Document(s): this document 1816 o Parameter name: "access_token" 1817 o CBOR key value: 19 1818 o Change Controller: IESG 1819 o Specification Document(s): this document 1821 o Parameter name: "token_type" 1822 o CBOR key value: 20 1823 o Change Controller: IESG 1824 o Specification Document(s): this document 1826 o Parameter name: "expires_in" 1827 o CBOR key value: 21 1828 o Change Controller: IESG 1829 o Specification Document(s): this document 1831 o Parameter name: "username" 1832 o CBOR key value: 22 1833 o Change Controller: IESG 1834 o Specification Document(s): this document 1836 o Parameter name: "password" 1837 o CBOR key value: 23 1838 o Change Controller: IESG 1839 o Specification Document(s): this document 1841 o Parameter name: "refresh_token" 1842 o CBOR key value: 24 1843 o Change Controller: IESG 1844 o Specification Document(s): this document 1846 o Parameter name: "cnf" 1847 o CBOR key value: 25 1848 o Change Controller: IESG 1849 o Specification Document(s): this document 1850 o Parameter name: "profile" 1851 o CBOR key value: 26 1852 o Change Controller: IESG 1853 o Specification Document(s): this document 1855 8.8. Introspection Endpoint CBOR Mappings Registry 1857 A new registry will be requested from IANA, entitled "Introspection 1858 Endpoint CBOR Mappings Registry". The registry is to be created as 1859 Expert Review Required. 1861 8.8.1. Registration Template 1863 Response parameter name: 1864 Name of the response parameter as defined in the "OAuth Token 1865 Introspection Response" registry e.g. "active". 1866 CBOR key value: 1867 Key value for the claim. The key value MUST be an integer in the 1868 range of 1 to 65536. 1869 Change Controller: 1870 For Standards Track RFCs, list the "IESG". For others, give the 1871 name of the responsible party. Other details (e.g., postal 1872 address, email address, home page URI) may also be included. 1873 Specification Document(s): 1874 Reference to the document or documents that specify the 1875 parameter,preferably including URIs that can be used to retrieve 1876 copies of the documents. An indication of the relevant sections 1877 may also be included but is not required. 1879 8.8.2. Initial Registry Contents 1881 o Response parameter name: "iss" 1882 o CBOR key value: 1 1883 o Change Controller: IESG 1884 o Specification Document(s): this document 1886 o Response parameter name: "sub" 1887 o CBOR key value: 2 1888 o Change Controller: IESG 1889 o Specification Document(s): this document 1891 o Response parameter name: "aud" 1892 o CBOR key value: 3 1893 o Change Controller: IESG 1894 o Specification Document(s): this document 1896 o Response parameter name: "exp" 1897 o CBOR key value: 4 1898 o Change Controller: IESG 1899 o Specification Document(s): this document 1901 o Response parameter name: "nbf" 1902 o CBOR key value: 5 1903 o Change Controller: IESG 1904 o Specification Document(s): this document 1906 o Response parameter name: "iat" 1907 o CBOR key value: 6 1908 o Change Controller: IESG 1909 o Specification Document(s): this document 1911 o Response parameter name: "cti" 1912 o CBOR key value: 7 1913 o Change Controller: IESG 1914 o Specification Document(s): this document 1916 o Response parameter name: "client_id" 1917 o CBOR key value: 8 1918 o Change Controller: IESG 1919 o Specification Document(s): this document 1921 o Response parameter name: "scope" 1922 o CBOR key value: 12 1923 o Change Controller: IESG 1924 o Specification Document(s): this document 1926 o Response parameter name: "token_type" 1927 o CBOR key value: 20 1928 o Change Controller: IESG 1929 o Specification Document(s): this document 1931 o Response parameter name: "username" 1932 o CBOR key value: 22 1933 o Change Controller: IESG 1934 o Specification Document(s): this document 1936 o Parameter name: "cnf" 1937 o CBOR key value: 25 1938 o Change Controller: IESG 1939 o Specification Document(s): this document 1941 o Parameter name: "profile" 1942 o CBOR key value: 26 1943 o Change Controller: IESG 1944 o Specification Document(s): this document 1945 o Response parameter name: "token" 1946 o CBOR key value: 27 1947 o Change Controller: IESG 1948 o Specification Document(s): this document 1950 o Response parameter name: "token_type_hint" 1951 o CBOR key value: 28 1952 o Change Controller: IESG 1953 o Specification Document(s): this document 1955 o Response parameter name: "active" 1956 o CBOR key value: 29 1957 o Change Controller: IESG 1958 o Specification Document(s): this document 1960 o Response parameter name: "client_token" 1961 o CBOR key value: 30 1962 o Change Controller: IESG 1963 o Specification Document(s): this document 1965 o Response parameter name: "rs_cnf" 1966 o CBOR key value: 31 1967 o Change Controller: IESG 1968 o Specification Document(s): this document 1970 8.9. CoAP Option Number Registration 1972 This section registers the "Access-Token" CoAP Option Number in the 1973 "CoRE Parameters" sub-registry "CoAP Option Numbers" in the manner 1974 described in [RFC7252]. 1976 Name 1978 Access-Token 1979 Number 1981 TBD 1982 Reference 1984 [This document]. 1985 Meaning in Request 1987 Contains an Access Token according to [This document] containing 1988 access permissions of the client. 1989 Meaning in Response 1991 Not used in response 1992 Safe-to-Forward 1993 Yes 1994 Format 1996 Based on the observer the format is perceived differently. Opaque 1997 data to the client and CWT or reference token to the RS. 1998 Length 2000 Less then 255 bytes 2002 8.10. CWT Confirmation Methods Registry 2004 This specification establishes the IANA "CWT Confirmation Methods" 2005 registry for CWT "cnf" member values. The registry records the 2006 confirmation method member and a reference to the specification that 2007 defines it. 2009 8.10.1. Registration Template 2011 Confirmation Method Name: 2012 The name requested (e.g., "kid"). This name is intended to be 2013 human readable and be used for debugging purposes. It is case 2014 sensitive. Names may not match other registered names in a case- 2015 insensitive manner unless the Designated Experts state that there 2016 is a compelling reason to allow an exception. 2018 Confirmation Method Value: 2019 Integer representation for the confirmation method value. 2020 Intended for use to uniquely identify the confirmation method. 2021 The value MUST be an integer in the range of 1 to 65536. 2023 Confirmation Method Description: 2024 Brief description of the confirmation method (e.g. "Key 2025 Identifier"). 2027 Change Controller: 2028 For Standards Track RFCs, list the "IESG". For others, give the 2029 name of the responsible party. Other details (e.g., postal 2030 address, email address, home page URI) may also be included. 2032 Specification Document(s): 2033 Reference to the document or documents that specify the parameter, 2034 preferably including URIs that can be used to retrieve copies of 2035 the documents. An indication of the relevant sections may also be 2036 included but is not required. 2038 8.10.2. Initial Registry Contents 2040 o Confirmation Method Name: "COSE_Key" 2041 o Confirmation Method Value: 1 2042 o Confirmation Method Description: A COSE_Key that is either a 2043 public key or a symmetric key. 2044 o Change Controller: IESG 2045 o Specification Document(s): this document 2047 o Confirmation Method Name: "COSE_Encrypted" 2048 o Confirmation Method Value: 2 2049 o Confirmation Method Description: A COSE_Encrypted structure that 2050 wraps a COSE_Key containing a symmetric key. 2051 o Change Controller: IESG 2052 o Specification Document(s): this document 2054 o Confirmation Method Name: "Key Identifier" 2055 o Confirmation Method Value: 3 2056 o Confirmation Method Description: A key identifier. 2057 o Change Controller: IESG 2058 o Specification Document(s): this document 2060 9. Acknowledgments 2062 We would like to thank Eve Maler for her contributions to the use of 2063 OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion 2064 input, and Malisa Vucinic for his input on the predecessors of this 2065 proposal. Finally, we would like to thank the ACE working group in 2066 general for their feedback. 2068 We would like to thank the authors of draft-ietf-oauth-pop-key- 2069 distribution, from where we copied large parts of our security 2070 considerations. 2072 Ludwig Seitz and Goeran Selander worked on this document as part of 2073 the CelticPlus project CyberWI, with funding from Vinnova. 2075 10. References 2077 10.1. Normative References 2079 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2080 Requirement Levels", BCP 14, RFC 2119, 2081 DOI 10.17487/RFC2119, March 1997, 2082 . 2084 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2085 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2086 January 2012, . 2088 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2089 Application Protocol (CoAP)", RFC 7252, 2090 DOI 10.17487/RFC7252, June 2014, 2091 . 2093 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 2094 RFC 7662, DOI 10.17487/RFC7662, October 2015, 2095 . 2097 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 2098 Possession Key Semantics for JSON Web Tokens (JWTs)", 2099 RFC 7800, DOI 10.17487/RFC7800, April 2016, 2100 . 2102 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2103 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2104 . 2106 10.2. Informative References 2108 [I-D.ietf-ace-actors] 2109 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 2110 architecture for authorization in constrained 2111 environments", draft-ietf-ace-actors-05 (work in 2112 progress), March 2017. 2114 [I-D.ietf-ace-cbor-web-token] 2115 Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 2116 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-07 2117 (work in progress), July 2017. 2119 [I-D.ietf-core-object-security] 2120 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2121 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 2122 object-security-04 (work in progress), July 2017. 2124 [I-D.ietf-oauth-device-flow] 2125 Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2126 "OAuth 2.0 Device Flow for Browserless and Input 2127 Constrained Devices", draft-ietf-oauth-device-flow-06 2128 (work in progress), May 2017. 2130 [I-D.ietf-oauth-native-apps] 2131 Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2132 draft-ietf-oauth-native-apps-12 (work in progress), June 2133 2017. 2135 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2136 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2137 . 2139 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2140 (TLS) Protocol Version 1.2", RFC 5246, 2141 DOI 10.17487/RFC5246, August 2008, 2142 . 2144 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 2145 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 2146 . 2148 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2149 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2150 . 2152 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 2153 Threat Model and Security Considerations", RFC 6819, 2154 DOI 10.17487/RFC6819, January 2013, 2155 . 2157 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2158 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2159 October 2013, . 2161 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2162 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2163 2014, . 2165 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 2166 Constrained-Node Networks", RFC 7228, 2167 DOI 10.17487/RFC7228, May 2014, 2168 . 2170 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2171 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2172 DOI 10.17487/RFC7231, June 2014, 2173 . 2175 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2176 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2177 . 2179 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 2180 "Assertion Framework for OAuth 2.0 Client Authentication 2181 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 2182 May 2015, . 2184 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 2185 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 2186 RFC 7591, DOI 10.17487/RFC7591, July 2015, 2187 . 2189 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2190 Application Protocol (CoAP)", RFC 7641, 2191 DOI 10.17487/RFC7641, September 2015, 2192 . 2194 [RFC7744] Seitz, L., Ed., Gerdes, S., Ed., Selander, G., Mani, M., 2195 and S. Kumar, "Use Cases for Authentication and 2196 Authorization in Constrained Environments", RFC 7744, 2197 DOI 10.17487/RFC7744, January 2016, 2198 . 2200 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 2201 the Constrained Application Protocol (CoAP)", RFC 7959, 2202 DOI 10.17487/RFC7959, August 2016, 2203 . 2205 Appendix A. Design Justification 2207 This section provides further insight into the design decisions of 2208 the solution documented in this document. Section 3 lists several 2209 building blocks and briefly summarizes their importance. The 2210 justification for offering some of those building blocks, as opposed 2211 to using OAuth 2.0 as is, is given below. 2213 Common IoT constraints are: 2215 Low Power Radio: 2217 Many IoT devices are equipped with a small battery which needs to 2218 last for a long time. For many constrained wireless devices the 2219 highest energy cost is associated to transmitting or receiving 2220 messages. It is therefore important to keep the total 2221 communication overhead low, including minimizing the number and 2222 size of messages sent and received, which has an impact of choice 2223 on the message format and protocol. By using CoAP over UDP, and 2224 CBOR encoded messages some of these aspects are addressed. 2225 Security protocols contribute to the communication overhead and 2226 can in some cases be optimized. For example authentication and 2227 key establishment may in certain cases where security requirements 2228 so allows be replaced by provisioning of security context by a 2229 trusted third party, using transport or application layer 2230 security. 2232 Low CPU Speed: 2234 Some IoT devices are equipped with processors that are 2235 significantly slower than those found in most current devices on 2236 the Internet. This typically has implications on what timely 2237 cryptographic operations a device is capable to perform, which in 2238 turn impacts e.g. protocol latency. Symmetric key cryptography 2239 may be used instead of the computationally more expensive public 2240 key cryptography where the security requirements so allows, but 2241 this may also require support for trusted third party assisted 2242 secret key establishment using transport or application layer 2243 security. 2245 Small Amount of Memory: 2247 Microcontrollers embedded in IoT devices are often equipped with 2248 small amount of RAM and flash memory, which places limitations 2249 what kind of processing can be performed and how much code can be 2250 put on those devices. To reduce code size fewer and smaller 2251 protocol implementations can be put on the firmware of such a 2252 device. In this case, CoAP may be used instead of HTTP, symmetric 2253 key cryptography instead of public key cryptography, and CBOR 2254 instead of JSON. Authentication and key establishment protocol, 2255 e.g. the DTLS handshake, in comparison with assisted key 2256 establishment also has an impact on memory and code. 2258 User Interface Limitations: 2260 Protecting access to resources is both an important security as 2261 well as privacy feature. End users and enterprise customers do 2262 not want to give access to the data collected by their IoT device 2263 or to functions it may offer to third parties. Since the 2264 classical approach of requesting permissions from end users via a 2265 rich user interface does not work in many IoT deployment scenarios 2266 these functions need to be delegated to user controlled devices 2267 that are better suitable for such tasks, such as smart phones and 2268 tablets. 2269 Communication Constraints: 2271 In certain constrained settings an IoT device may not be able to 2272 communicate with a given device at all times. Devices may be 2273 sleeping, or just disconnected from the Internet because of 2274 general lack of connectivity in the area, for cost reasons, or for 2275 security reasons, e.g. to avoid an entry point for Denial-of- 2276 Service attacks. 2278 The communication interactions this framework builds upon (as 2279 shown graphically in Figure 1) may be accomplished using a variety 2280 of different protocols, and not all parts of the message flow are 2281 used in all applications due to the communication constraints. 2282 While we envision deployments to make use of CoAP we explicitly 2283 want to support HTTP, HTTP/2 or specific protocols, such as 2284 Bluetooth Smart communication, which does not necessarily use IP. 2285 The latter raises the need for application layer security over the 2286 various interfaces. 2288 Appendix B. Roles and Responsibilities 2290 Resource Owner 2292 * Make sure that the RS is registered at the AS. This includes 2293 making known to the AS which profiles, token_types, scopes, and 2294 key types (symmetric/asymmetric) the RS supports. Also making 2295 it known to the AS which audience(s) the RS identifies itself 2296 with. 2297 * Make sure that clients can discover the AS which is in charge 2298 of the RS. 2299 * If the client-credentials grant is used, make sure that the AS 2300 has the necessary, up-to-date, access control policies for the 2301 RS. 2303 Requesting Party 2305 * Make sure that the client is provisioned the necessary 2306 credentials to authenticate to the AS. 2307 * Make sure that the client is configured to follow the security 2308 requirements of the Requesting Party, when issuing requests 2309 (e.g. minimum communication security requirements, trust 2310 anchors). 2311 * Register the client at the AS. This includes making known to 2312 the AS which profiles, token_types, and key types (symmetric/ 2313 asymmetric) the client. 2315 Authorization Server 2317 * Register RS and manage corresponding security contexts. 2318 * Register clients and including authentication credentials. 2319 * Allow Resource Owners to configure and update access control 2320 policies related to their registered RS' 2321 * Expose the /token endpoint to allow clients to request tokens. 2322 * Authenticate clients that wish to request a token. 2324 * Process a token request against the authorization policies 2325 configured for the RS. 2326 * Optionally: Expose the /introspection endpoint that allows RS's 2327 to submit token introspection requests. 2328 * If providing an introspection endpoint: Authenticate RS's that 2329 wish to get an introspection response. 2330 * If providing an introspection endpoint: Process token 2331 introspection requests. 2332 * Optionally: Handle token revocation. 2334 Client 2336 * Discover the AS in charge of the RS that is to be targeted with 2337 a request. 2338 * Submit the token request (A). 2340 + Authenticate towards the AS. 2341 + Optionally (if not pre-configured): Specify which RS, which 2342 resource(s), and which action(s) the request(s) will target. 2343 + If raw public key (rpk) or certificate is used, make sure 2344 the AS has the right rpk or certificate for this client. 2345 * Process the access token and RS Information (B) 2347 + Check that the RS Information provides the necessary 2348 security parameters (e.g. PoP key, information on 2349 communication security protocols supported by the RS). 2350 * Send the token and request to the RS (C) 2352 + Authenticate towards the RS (this could coincide with the 2353 proof of possession process). 2354 + Transmit the token as specified by the AS (default is to the 2355 /authz-info endpoint, alternative options are specified by 2356 profiles). 2357 + Perform the proof-of-possession procedure as specified by 2358 the profile in use (this may already have been taken care of 2359 through the authentication procedure). 2360 * Process the RS response (F) requirements of the Requesting 2361 Party, when issuing requests (e.g. minimum communication 2362 security requirements, trust anchors). 2363 * Register the client at the AS. 2365 Resource Server 2367 * Expose a way to submit access tokens. By default this is the 2368 /authz-info endpoint. 2369 * Process an access token. 2371 + Verify the token is from the right AS. 2373 + Verify that the token applies to this RS. 2374 + Check that the token has not expired (if the token provides 2375 expiration information). 2376 + Check the token's integrity. 2377 + Store the token so that it can be retrieved in the context 2378 of a matching request. 2379 * Process a request. 2381 + Set up communication security with the client. 2382 + Authenticate the client. 2383 + Match the client against existing tokens. 2384 + Check that tokens belonging to the client actually authorize 2385 the requested action. 2386 + Optionally: Check that the matching tokens are still valid, 2387 using introspection (if this is possible.) 2388 * Send a response following the agreed upon communication 2389 security. 2391 Appendix C. Requirements on Profiles 2393 This section lists the requirements on profiles of this framework, 2394 for the convenience of a profile designer. 2396 o Optionally Specify the discovery process of how the client finds 2397 the right AS for an RS it wants to send a request to. Section 4 2398 o Specify the communication protocol the client and RS the must use 2399 (e.g. CoAP). Section 5 and Section 5.5.4.4 2400 o Specify the security protocol the client and RS must use to 2401 protect their communication (e.g. OSCOAP or DTLS over CoAP). 2402 This must provide encryption and integrity protection. 2403 Section 5.5.4.4 2404 o Specify how the client and the RS mutually authenticate. 2405 Section 4 2406 o Specify the Content-format of the protocol messages (e.g. 2407 "application/cbor" or "application/cose+cbor"). Section 4 2408 o Specify the proof-of-possession protocol(s) and how to select one, 2409 if several are available. Also specify which key types (e.g. 2410 symmetric/asymmetric) are supported by a specific proof-of- 2411 possession protocol. Section 5.5.4.3 2412 o Specify a unique profile identifier. Section 5.5.4.4 2413 o Optionally specify how the RS talks to the AS for 2414 introspection.Section 5.6 2415 o Optionally specify how the client talks to the AS for requesting a 2416 token. Section 5.5 2417 o Specify how/if the /authz-info endpoint is protected. 2418 Section 5.7.1 2419 o Optionally define other methods of token transport than the 2420 /authz-info endpoint. Section 5.7.1 2422 Appendix D. Assumptions on AS knowledge about C and RS 2424 This section lists the assumptions on what an AS should know about a 2425 client and a RS in order to be able to respond to requests to the 2426 /token and /introspect endpoints. How this information is 2427 established is out of scope for this document. 2429 o The identifier of the client or RS. 2430 o The profiles that the client or RS supports. 2431 o The scopes that the RS supports. 2432 o The audiences that the RS identifies with. 2433 o The key types (e.g. pre-shared symmetric key, raw public key, key 2434 length, other key parameters) that the client or RS supports. 2435 o The types of access tokens the RS supports (e.g. CWT). 2436 o If the RS supports CWTs, the COSE parameters for the crypto 2437 wrapper (e.g. algorithm, key-wrap algorithm, key-length). 2438 o The expiration time for access tokens issued to this RS (unless 2439 the RS accepts a default time chosen by the AS). 2440 o The symmetric key shared between client or RS and AS (if any). 2441 o The raw public key of the client or RS (if any). 2443 Appendix E. Deployment Examples 2445 There is a large variety of IoT deployments, as is indicated in 2446 Appendix A, and this section highlights a few common variants. This 2447 section is not normative but illustrates how the framework can be 2448 applied. 2450 For each of the deployment variants there are a number of possible 2451 security setups between clients, resource servers and authorization 2452 servers. The main focus in the following subsections is on how 2453 authorization of a client request for a resource hosted by a RS is 2454 performed. This requires the the security of the requests and 2455 responses between the clients and the RS to consider. 2457 Note: CBOR diagnostic notation is used for examples of requests and 2458 responses. 2460 E.1. Local Token Validation 2462 In this scenario we consider the case where the resource server is 2463 offline, i.e. it is not connected to the AS at the time of the access 2464 request. This access procedure involves steps A, B, C, and F of 2465 Figure 1. 2467 Since the resource server must be able to verify the access token 2468 locally, self-contained access tokens must be used. 2470 This example shows the interactions between a client, the 2471 authorization server and a temperature sensor acting as a resource 2472 server. Message exchanges A and B are shown in Figure 18. 2474 A: The client first generates a public-private key pair used for 2475 communication security with the RS. 2476 The client sends the POST request to /token at the AS. The 2477 security of this request can be transport or application layer, it 2478 is up the the communication security profile to define. In the 2479 example transport layer identification of the AS is done and the 2480 client identifies with client_id and client_secret as in classic 2481 OAuth. The request contains the public key of the client and the 2482 Audience parameter set to "tempSensorInLivingRoom", a value that 2483 the temperature sensor identifies itself with. The AS evaluates 2484 the request and authorizes the client to access the resource. 2485 B: The AS responds with a PoP token and RS Information. The PoP 2486 token contains the public key of the client, and the RS 2487 Information contains the public key of the RS. For communication 2488 security this example uses DTLS RawPublicKey between the client 2489 and the RS. The issued token will have a short validity time, 2490 i.e. 'exp' close to 'iat', to protect the RS from replay attacks. 2491 The token includes the claim such as "scope" with the authorized 2492 access that an owner of the temperature device can enjoy. In this 2493 example, the 'scope' claim, issued by the AS, informs the RS that 2494 the owner of the token, that can prove the possession of a key is 2495 authorized to make a GET request against the /temperature resource 2496 and a POST request on the /firmware resource. Note that the 2497 syntax and semantics of the scope claim are application specific. 2498 Note: In this example we assume that the client knows what 2499 resource it wants to access, and is therefore able to request 2500 specific audience and scope claims for the access token. 2502 Authorization 2503 Client Server 2504 | | 2505 |<=======>| DTLS Connection Establishment 2506 | | to identify the AS 2507 | | 2508 A: +-------->| Header: POST (Code=0.02) 2509 | POST | Uri-Path:"token" 2510 | | Content-Type: application/cbor 2511 | | Payload: 2512 | | 2513 B: |<--------+ Header: 2.05 Content 2514 | 2.05 | Content-Type: application/cbor 2515 | | Payload: 2516 | | 2518 Figure 18: Token Request and Response Using Client Credentials. 2520 The information contained in the Request-Payload and the Response- 2521 Payload is shown in Figure 19. Note that we assume a DTLS-based 2522 communication security profile for this example, therefore the 2523 Content-Type is "application/cbor". 2525 Request-Payload : 2526 { 2527 "grant_type" : "client_credentials", 2528 "aud" : "tempSensorInLivingRoom", 2529 "client_id" : "myclient", 2530 "client_secret" : "qwerty" 2531 } 2533 Response-Payload : 2534 { 2535 "access_token" : b64'SlAV32hkKG ...', 2536 "token_type" : "pop", 2537 "csp" : "DTLS", 2538 "cnf" : { 2539 "COSE_Key" : { 2540 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2541 "kty" : "EC", 2542 "crv" : "P-256", 2543 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 2544 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 2545 } 2546 } 2547 } 2549 Figure 19: Request and Response Payload Details. 2551 The content of the access token is shown in Figure 20. 2553 { 2554 "aud" : "tempSensorInLivingRoom", 2555 "iat" : "1360189224", 2556 "exp" : "1360289224", 2557 "scope" : "temperature_g firmware_p", 2558 "cnf" : { 2559 "jwk" : { 2560 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 2561 "kty" : "EC", 2562 "crv" : "P-256", 2563 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 2564 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 2565 } 2566 } 2567 } 2569 Figure 20: Access Token including Public Key of the Client. 2571 Messages C and F are shown in Figure 21 - Figure 22. 2573 C: The client then sends the PoP token to the /authz-info endpoint 2574 at the RS. This is a plain CoAP request, i.e. no transport or 2575 application layer security between client and RS, since the token 2576 is integrity protected between AS and RS. The RS verifies that 2577 the PoP token was created by a known and trusted AS, is valid, and 2578 responds to the client. The RS caches the security context 2579 together with authorization information about this client 2580 contained in the PoP token. 2582 Resource 2583 Client Server 2584 | | 2585 C: +-------->| Header: POST (Code=0.02) 2586 | POST | Uri-Path:"authz-info" 2587 | | Payload: SlAV32hkKG ... 2588 | | 2589 |<--------+ Header: 2.04 Changed 2590 | 2.04 | 2591 | | 2593 Figure 21: Access Token provisioning to RS 2594 The client and the RS runs the DTLS handshake using the raw public 2595 keys established in step B and C. 2597 The client sends the CoAP request GET to /temperature on RS over 2598 DTLS. The RS verifies that the request is authorized, based on 2599 previously established security context. 2600 F: The RS responds with a resource representation over DTLS. 2602 Resource 2603 Client Server 2604 | | 2605 |<=======>| DTLS Connection Establishment 2606 | | using Raw Public Keys 2607 | | 2608 +-------->| Header: GET (Code=0.01) 2609 | GET | Uri-Path: "temperature" 2610 | | 2611 | | 2612 | | 2613 F: |<--------+ Header: 2.05 Content 2614 | 2.05 | Payload: 2615 | | 2617 Figure 22: Resource Request and Response protected by DTLS. 2619 E.2. Introspection Aided Token Validation 2621 In this deployment scenario we assume that a client is not able to 2622 access the AS at the time of the access request. Since the RS is, 2623 however, connected to the back-end infrastructure it can make use of 2624 token introspection. This access procedure involves steps A-F of 2625 Figure 1, but assumes steps A and B have been carried out during a 2626 phase when the client had connectivity to AS. 2628 Since the client is assumed to be offline, at least for a certain 2629 period of time, a pre-provisioned access token has to be long-lived. 2630 The resource server may use its online connectivity to validate the 2631 access token with the authorization server, which is shown in the 2632 example below. 2634 In the example interactions between an offline client (key fob), a RS 2635 (online lock), and an AS is shown. We assume that there is a 2636 provisioning step where the client has access to the AS. This 2637 corresponds to message exchanges A and B which are shown in 2638 Figure 23. 2640 Authorization consent from the resource owner can be pre-configured, 2641 but it can also be provided via an interactive flow with the resource 2642 owner. An example of this for the key fob case could be that the 2643 resource owner has a connected car, he buys a generic key that he 2644 wants to use with the car. To authorize the key fob he connects it 2645 to his computer that then provides the UI for the device. After that 2646 OAuth 2.0 implicit flow can used to authorize the key for his car at 2647 the the car manufacturers AS. 2649 Note: In this example the client does not know the exact door it will 2650 be used to access since the token request is not send at the time of 2651 access. So the scope and audience parameters is set quite wide to 2652 start with and new values different form the original once can be 2653 returned from introspection later on. 2655 A: The client sends the request using POST to /token at AS. The 2656 request contains the Audience parameter set to "PACS1337" (PACS, 2657 Physical Access System), a value the that the online door in 2658 question identifies itself with. The AS generates an access token 2659 as on opaque string, which it can match to the specific client, a 2660 targeted audience and a symmetric key. The security is provided 2661 by identifying the AS on transport layer using a pre shared 2662 security context (psk, rpk or certificate) and then the client is 2663 identified using client_id and client_secret as in classic OAuth 2664 B: The AS responds with the an access token and RS Information, 2665 the latter containing a symmetric key. Communication security 2666 between C and RS will be DTLS and PreSharedKey. The PoP key being 2667 used as the PreSharedKey. 2669 Authorization 2670 Client Server 2671 | | 2672 | | 2673 A: +-------->| Header: POST (Code=0.02) 2674 | POST | Uri-Path:"token" 2675 | | Content-Type: application/cbor 2676 | | Payload: 2677 | | 2678 B: |<--------+ Header: 2.05 Content 2679 | | Content-Type: application/cbor 2680 | 2.05 | Payload: 2681 | | 2683 Figure 23: Token Request and Response using Client Credentials. 2685 The information contained in the Request-Payload and the Response- 2686 Payload is shown in Figure 24. 2688 Request-Payload: 2689 { 2690 "grant_type" : "client_credentials", 2691 "aud" : "lockOfDoor4711", 2692 "client_id" : "keyfob", 2693 "client_secret" : "qwerty" 2694 } 2696 Response-Payload: 2697 { 2698 "access_token" : b64'SlAV32hkKG ...' 2699 "token_type" : "pop", 2700 "csp" : "DTLS", 2701 "cnf" : { 2702 "COSE_Key" : { 2703 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2704 "kty" : "oct", 2705 "alg" : "HS256", 2706 "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' 2707 } 2708 } 2709 } 2711 Figure 24: Request and Response Payload for C offline 2713 The access token in this case is just an opaque string referencing 2714 the authorization information at the AS. 2716 C: Next, the client POSTs the access token to the /authz-info 2717 endpoint in the RS. This is a plain CoAP request, i.e. no DTLS 2718 between client and RS. Since the token is an opaque string, the 2719 RS cannot verify it on its own, and thus defers to respond the 2720 client with a status code until after step E. 2721 D: The RS forwards the token to the /introspect endpoint on the 2722 AS. Introspection assumes a secure connection between the AS and 2723 the RS, e.g. using transport of application layer security. In 2724 the example AS is identified using pre shared security context 2725 (psk, rpk or certificate) while RS is acting as client and is 2726 identified with client_id and client_secret. 2727 E: The AS provides the introspection response containing 2728 parameters about the token. This includes the confirmation key 2729 (cnf) parameter that allows the RS to verify the client's proof of 2730 possession in step F. 2731 After receiving message E, the RS responds to the client's POST in 2732 step C with the CoAP response code 2.01 (Created). 2734 Resource 2735 Client Server 2736 | | 2737 C: +-------->| Header: POST (T=CON, Code=0.02) 2738 | POST | Uri-Path:"authz-info" 2739 | | Content-Type: "application/cbor" 2740 | | Payload: b64'SlAV32hkKG ...'' 2741 | | 2742 | | Authorization 2743 | | Server 2744 | | | 2745 | D: +--------->| Header: POST (Code=0.02) 2746 | | POST | Uri-Path: "introspect" 2747 | | | Content-Type: "application/cbor" 2748 | | | Payload: 2749 | | | 2750 | E: |<---------+ Header: 2.05 Content 2751 | | 2.05 | Content-Type: "application/cbor" 2752 | | | Payload: 2753 | | | 2754 | | 2755 |<--------+ Header: 2.01 Created 2756 | 2.01 | 2757 | | 2759 Figure 25: Token Introspection for C offline 2760 The information contained in the Request-Payload and the Response- 2761 Payload is shown in Figure 26. 2763 Request-Payload: 2764 { 2765 "token" : b64'SlAV32hkKG...', 2766 "client_id" : "FrontDoor", 2767 "client_secret" : "ytrewq" 2768 } 2770 Response-Payload: 2771 { 2772 "active" : true, 2773 "aud" : "lockOfDoor4711", 2774 "scope" : "open, close", 2775 "iat" : 1311280970, 2776 "cnf" : { 2777 "kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 2778 } 2779 } 2781 Figure 26: Request and Response Payload for Introspection 2783 The client uses the symmetric PoP key to establish a DTLS 2784 PreSharedKey secure connection to the RS. The CoAP request PUT is 2785 sent to the uri-path /state on RS changing state of the door to 2786 locked. 2787 F: The RS responds with a appropriate over the secure DTLS 2788 channel. 2790 Resource 2791 Client Server 2792 | | 2793 |<=======>| DTLS Connection Establishment 2794 | | using Pre Shared Key 2795 | | 2796 +-------->| Header: PUT (Code=0.03) 2797 | PUT | Uri-Path: "state" 2798 | | Payload: 2799 | | 2800 F: |<--------+ Header: 2.04 Changed 2801 | 2.04 | Payload: 2802 | | 2804 Figure 27: Resource request and response protected by OSCOAP 2806 Appendix F. Document Updates 2808 F.1. Version -06 to -07 2810 o Various clarifications added. 2811 o Fixed erroneous author email. 2813 F.2. Version -05 to -06 2815 o Moved sections that define the ACE framework into a subsection of 2816 the framework Section 5. 2817 o Split section on client credentials and grant into two separate 2818 sections, Section 5.1, and Section 5.2. 2819 o Added Section 5.3 on AS authentication. 2820 o Added Section 5.4 on the Authorize endpoint. 2822 F.3. Version -04 to -05 2824 o Added RFC 2119 language to the specification of the required 2825 behavior of profile specifications. 2826 o Added Section 5.2 on the relation to the OAuth2 grant types. 2827 o Added CBOR abbreviations for error and the error codes defined in 2828 OAuth2. 2829 o Added clarification about token expiration and long-running 2830 requests in Section 5.7.2 2832 o Added security considerations about tokens with symmetric pop keys 2833 valid for more than one RS. 2834 o Added privacy considerations section. 2835 o Added IANA registry mapping the confirmation types from RFC 7800 2836 to equivalent COSE types. 2837 o Added appendix D, describing assumptions about what the AS knows 2838 about the client and the RS. 2840 F.4. Version -03 to -04 2842 o Added a description of the terms "framework" and "profiles" as 2843 used in this document. 2844 o Clarified protection of access tokens in section 3.1. 2845 o Clarified uses of the 'cnf' parameter in section 6.4.5. 2846 o Clarified intended use of Client Token in section 7.4. 2848 F.5. Version -02 to -03 2850 o Removed references to draft-ietf-oauth-pop-key-distribution since 2851 the status of this draft is unclear. 2852 o Copied and adapted security considerations from draft-ietf-oauth- 2853 pop-key-distribution. 2854 o Renamed "client information" to "RS information" since it is 2855 information about the RS. 2856 o Clarified the requirements on profiles of this framework. 2857 o Clarified the token endpoint protocol and removed negotiation of 2858 'profile' and 'alg' (section 6). 2859 o Renumbered the abbreviations for claims and parameters to get a 2860 consistent numbering across different endpoints. 2861 o Clarified the introspection endpoint. 2862 o Renamed token, introspection and authz-info to 'endpoint' instead 2863 of 'resource' to mirror the OAuth 2.0 terminology. 2864 o Updated the examples in the appendices. 2866 F.6. Version -01 to -02 2868 o Restructured to remove communication security parts. These shall 2869 now be defined in profiles. 2870 o Restructured section 5 to create new sections on the OAuth 2871 endpoints /token, /introspect and /authz-info. 2872 o Pulled in material from draft-ietf-oauth-pop-key-distribution in 2873 order to define proof-of-possession key distribution. 2874 o Introduced the 'cnf' parameter as defined in RFC7800 to reference 2875 or transport keys used for proof of possession. 2876 o Introduced the 'client-token' to transport client information from 2877 the AS to the client via the RS in conjunction with introspection. 2878 o Expanded the IANA section to define parameters for token request, 2879 introspection and CWT claims. 2881 o Moved deployment scenarios to the appendix as examples. 2883 F.7. Version -00 to -01 2885 o Changed 5.1. from "Communication Security Protocol" to "Client 2886 Information". 2887 o Major rewrite of 5.1 to clarify the information exchanged between 2888 C and AS in the PoP token request profile for IoT. 2890 * Allow the client to indicate preferences for the communication 2891 security protocol. 2892 * Defined the term "Client Information" for the additional 2893 information returned to the client in addition to the access 2894 token. 2895 * Require that the messages between AS and client are secured, 2896 either with (D)TLS or with COSE_Encrypted wrappers. 2897 * Removed dependency on OSCOAP and added generic text about 2898 object security instead. 2899 * Defined the "rpk" parameter in the client information to 2900 transmit the raw public key of the RS from AS to client. 2901 * (D)TLS MUST use the PoP key in the handshake (either as PSK or 2902 as client RPK with client authentication). 2903 * Defined the use of x5c, x5t and x5tS256 parameters when a 2904 client certificate is used for proof of possession. 2905 * Defined "tktn" parameter for signaling for how to transfer the 2906 access token. 2907 o Added 5.2. the CoAP Access-Token option for transferring access 2908 tokens in messages that do not have payload. 2909 o 5.3.2. Defined success and error responses from the RS when 2910 receiving an access token. 2911 o 5.6.:Added section giving guidance on how to handle token 2912 expiration in the absence of reliable time. 2913 o Appendix B Added list of roles and responsibilities for C, AS and 2914 RS. 2916 Authors' Addresses 2918 Ludwig Seitz 2919 RISE SICS 2920 Scheelevaegen 17 2921 Lund 223 70 2922 SWEDEN 2924 Email: ludwig.seitz@ri.se 2925 Goeran Selander 2926 Ericsson 2927 Faroegatan 6 2928 Kista 164 80 2929 SWEDEN 2931 Email: goran.selander@ericsson.com 2933 Erik Wahlstroem 2934 (no affiliation) 2935 Sweden 2937 Email: erik@wahlstromtekniska.se 2939 Samuel Erdtman 2940 Spotify AB 2941 Birger Jarlsgatan 61, 4tr 2942 Stockholm 113 56 2943 Sweden 2945 Email: erdtman@spotify.com 2947 Hannes Tschofenig 2948 ARM Ltd. 2949 Hall in Tirol 6060 2950 Austria 2952 Email: Hannes.Tschofenig@arm.com