idnits 2.17.1 draft-ietf-ace-oauth-authz-02.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 (June 10, 2016) is 2877 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-15) exists of draft-ietf-ace-cbor-web-token-00 == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-12 == Outdated reference: A later version (-06) exists of draft-selander-ace-object-security-04 ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-07) exists of draft-ietf-ace-actors-03 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-20 == Outdated reference: A later version (-08) exists of draft-ietf-oauth-pop-architecture-07 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group L. Seitz 3 Internet-Draft SICS 4 Intended status: Standards Track G. Selander 5 Expires: December 12, 2016 Ericsson 6 E. Wahlstroem 7 Nexus Technology 8 S. Erdtman 9 Spotify AB 10 H. Tschofenig 11 ARM Ltd. 12 June 10, 2016 14 Authentication and Authorization for Constrained Environments (ACE) 15 draft-ietf-ace-oauth-authz-02 17 Abstract 19 This specification defines the ACE framework for authentication and 20 authorization in Internet of Things (IoT) deployments. The ACE 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 limitations of IoT devices require it, 25 profiles and extensions are provided. 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 December 12, 2016. 44 Copyright Notice 46 Copyright (c) 2016 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 65 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 9 67 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 6. The 'Token' Resource . . . . . . . . . . . . . . . . . . . . 14 69 6.1. Client-to-AS Request . . . . . . . . . . . . . . . . . . 14 70 6.2. AS-to-Client Response . . . . . . . . . . . . . . . . . . 17 71 6.3. Error Response . . . . . . . . . . . . . . . . . . . . . 18 72 6.4. New Request and Response Parameters . . . . . . . . . . . 18 73 6.4.1. Grant Type . . . . . . . . . . . . . . . . . . . . . 19 74 6.4.2. Token Type and Algorithms . . . . . . . . . . . . . . 19 75 6.4.3. Profile . . . . . . . . . . . . . . . . . . . . . . . 20 76 6.4.4. Confirmation . . . . . . . . . . . . . . . . . . . . 20 77 6.5. Mapping parameters to CBOR . . . . . . . . . . . . . . . 22 78 7. The 'Introspect' Resource . . . . . . . . . . . . . . . . . . 22 79 7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . . . 23 80 7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . . . 23 81 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 24 82 7.4. Client Token . . . . . . . . . . . . . . . . . . . . . . 25 83 7.5. Mapping Introspection parameters to CBOR . . . . . . . . 26 84 8. The Access Token . . . . . . . . . . . . . . . . . . . . . . 27 85 8.1. The 'Authorization Information' Resource . . . . . . . . 27 86 8.2. Token Expiration . . . . . . . . . . . . . . . . . . . . 28 87 9. Security Considerations . . . . . . . . . . . . . . . . . . . 28 88 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 89 10.1. OAuth Introspection Response Parameter Registration . . 29 90 10.2. OAuth Parameter Registration . . . . . . . . . . . . . . 30 91 10.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 30 92 10.4. Token Type Mappings . . . . . . . . . . . . . . . . . . 30 93 10.4.1. Registration Template . . . . . . . . . . . . . . . 30 94 10.4.2. Initial Registry Contents . . . . . . . . . . . . . 31 95 10.5. JSON Web Token Claims . . . . . . . . . . . . . . . . . 31 96 10.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 31 97 10.6.1. Registration Template . . . . . . . . . . . . . . . 31 98 10.7. OAuth Parameter Mappings Registry . . . . . . . . . . . 32 99 10.7.1. Registration Template . . . . . . . . . . . . . . . 32 100 10.7.2. Initial Registry Contents . . . . . . . . . . . . . 32 101 10.8. Introspection Resource CBOR Mappings Registry . . . . . 34 102 10.8.1. Registration Template . . . . . . . . . . . . . . . 35 103 10.8.2. Initial Registry Contents . . . . . . . . . . . . . 35 104 10.9. CoAP Option Number Registration . . . . . . . . . . . . 37 105 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 37 106 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 107 12.1. Normative References . . . . . . . . . . . . . . . . . . 38 108 12.2. Informative References . . . . . . . . . . . . . . . . . 38 109 Appendix A. Design Justification . . . . . . . . . . . . . . . . 40 110 Appendix B. Roles and Responsibilites . . . . . . . . . . . . . 42 111 Appendix C. Deployment Examples . . . . . . . . . . . . . . . . 44 112 C.1. Local Token Validation . . . . . . . . . . . . . . . . . 44 113 C.2. Introspection Aided Token Validation . . . . . . . . . . 48 114 Appendix D. Document Updates . . . . . . . . . . . . . . . . . . 51 115 D.1. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 52 116 D.2. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 52 117 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 53 119 1. Introduction 121 Authorization is the process for granting approval to an entity to 122 access a resource [RFC4949]. The authorization task itself can best 123 be described as granting access to a requesting client, for a 124 resource hosted on a device, the resource server (RS). This exchange 125 is mediated by one or multiple authorization servers (AS). Managing 126 authorization for a large number of devices and users is a complex 127 task. 129 We envision that end consumers and enterprises will manage access to 130 resources on, or produced by, Internet of Things (IoT) devices in the 131 same style as they do today with data, services and applications on 132 the Web or with their mobile devices. This desire will increase with 133 the number of exposed services and capabilities provided by 134 applications hosted on the IoT devices. 136 While prior work on authorization solutions for the Web and for the 137 mobile environment also applies to the IoT environment many IoT 138 devices are constrained, for example in terms of processing 139 capabilities, available memory, etc. For web applications on 140 constrained nodes this specification makes use of CoAP [RFC7252]. 142 A detailed treatment of constraints can be found in [RFC7228], and 143 the different IoT deployments present a continuous range of device 144 and network capabilities. Taking energy consumption as an example: 146 At one end there are energy-harvesting or battery powered devices 147 which have a tight power budget, on the other end there are mains- 148 powered devices, and all levels in between. 150 Hence, IoT devices may be very different in terms of available 151 processing and message exchange capabilities and there is a need to 152 support many different authorization use cases [RFC7744]. 154 This specification describes a framework for authentication and 155 authorization in constrained environments (ACE) built on re-use of 156 OAuth 2.0 [RFC6749], thereby extending authorization to Internet of 157 Things devices. This specification contains the necessary building 158 blocks for adjusting OAuth 2.0 to IoT environments. 160 More detailed, interoperable specifications can be found in profiles. 161 Implementations may claim conformance with a specific profile, 162 whereby implementations utilizing the same profile interoperate while 163 implementations of different profiles are not expected to be 164 interoperable. Some devices, such as mobile phones and tablets, may 165 implement multiple profiles and will therefore be able to interact 166 with a wider range of low end devices. 168 2. Terminology 170 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 171 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 172 document are to be interpreted as described in [RFC2119]. 174 Certain security-related terms such as "authentication", 175 "authorization", "confidentiality", "(data) integrity", "message 176 authentication code", and "verify" are taken from [RFC4949]. 178 Since we describe exchanges as RESTful protocol interactions HTTP 179 [RFC7231] offers useful terminology. 181 Terminology for entities in the architecture is defined in OAuth 2.0 182 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 183 server (RS), and authorization server (AS). 185 Note that the term "endpoint" is used here following its OAuth 186 definition, which is to denote resources such as /token and 187 /introspect at the AS and /authz-info at the RS. The CoAP [RFC7252] 188 definition, which is "An entity participating in the CoAP protocol" 189 is not used in this memo. 191 Since this specification focuses on the problem of access control to 192 resources, we simplify the actors by assuming that the client 193 authorization server (CAS) functionality is not stand-alone but 194 subsumed by either the authorization server or the client (see 195 section 2.2 in [I-D.ietf-ace-actors]). 197 3. Overview 199 This specification describes the ACE framework for authorization in 200 the Internet of Things consisting of a set of building blocks. 202 The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys 203 widespread deployment. Many IoT devices can support OAuth 2.0 204 without any additional extensions, but for certain constrained 205 settings additional profiling is needed. 207 Another building block is the lightweight web transfer protocol CoAP 208 [RFC7252] for those communication environments where HTTP is not 209 appropriate. CoAP typically runs on top of UDP which further reduces 210 overhead and message exchanges. While this specification defines 211 extensions for the use of OAuth over CoAP, we do envision further 212 underlying protocols to be supported in the future, such as MQTT or 213 QUIC. 215 A third building block is CBOR [RFC7049] for encodings where JSON 216 [RFC7159] is not sufficiently compact. CBOR is a binary encoding 217 designed for small code and message size, which may be used for 218 encoding of self contained tokens, and also for encoding CoAP POST 219 parameters and CoAP responses. 221 A fourth building block is the compact CBOR-based secure message 222 format COSE [I-D.ietf-cose-msg], which enables application layer 223 security as an alternative or complement to transport layer security 224 (DTLS [RFC6347] or TLS [RFC5246]). COSE is used to secure self 225 contained tokens such as proof-of-possession (PoP) tokens 226 [I-D.ietf-oauth-pop-architecture], which is an extension to the OAuth 227 access tokens, and "client tokens" which are defined in this 228 framework (see Section 7.4). The default access token format is 229 defined in CBOR web token (CWT) [I-D.ietf-ace-cbor-web-token]. 230 Application layer security for CoAP using COSE can be provided with 231 OSCOAP [I-D.selander-ace-object-security]. 233 With the building blocks listed above, solutions satisfying various 234 IoT device and network constraints are possible. A list of 235 constraints is described in detail in RFC 7228 [RFC7228] and a 236 description of how the building blocks mentioned above relate to the 237 various constraints can be found in Appendix A. 239 Luckily, not every IoT device suffers from all constraints. The ACE 240 framework nevertheless takes all these aspects into account and 241 allows several different deployment variants to co-exist rather than 242 mandating a one-size-fits-all solution. We believe this is important 243 to cover the wide range of possible interworking use cases and the 244 different requirements from a security point of view. Once IoT 245 deployments mature, popular deployment variants will be documented in 246 form of ACE profiles. 248 In the subsections below we provide further details about the 249 different building blocks. 251 3.1. OAuth 2.0 253 The OAuth 2.0 authorization framework enables a client to obtain 254 limited access to a resource with the permission of a resource owner. 255 Authorization information, or references to it, is passed between the 256 nodes using access tokens. These access tokens are issued to clients 257 by an authorization server with the approval of the resource owner. 258 The client uses the access token to access the protected resources 259 hosted by the resource server. 261 A number of OAuth 2.0 terms are used within this specification: 263 The token and introspect Endpoints: 265 The AS hosts the /token endpoint that allows a client to request 266 access tokens. The client makes a POST request to the /token 267 endpoint on the AS and receives the access token in the response 268 (if the request was successful). 270 The token introspection endpoint, /introspect, is used by the RS 271 when requesting additional information regarding a received access 272 token. The RS makes a POST request to /introspect on the AS and 273 receives information about the access token contain in the 274 response. (See "Introspection" below.) 276 Access Tokens: 278 Access tokens are credentials needed to access protected 279 resources. An access token is a data structure representing 280 authorization permissions issued by the AS to the client. Access 281 tokens are generated by the authorization server and consumed by 282 the resource server. The access token content is opaque to the 283 client. 285 Access tokens can have different formats, and various methods of 286 utilization (e.g., cryptographic properties) based on the security 287 requirements of the given deployment. 289 Proof of Possession Tokens: 291 An access token may be bound to a cryptographic key, which is then 292 used by an RS to authenticate requests from a client. Such tokens 293 are called proof-of-possession tokens (or PoP tokens) 294 [I-D.ietf-oauth-pop-architecture]. 296 The proof-of-possession (PoP) security concept assumes that the AS 297 acts as a trusted third party that binds keys to access tokens. 298 These so called PoP keys are then used by the client to 299 demonstrate the possession of the secret to the RS when accessing 300 the resource. The RS, when receiving an access token, needs to 301 verify that the key used by the client matches the one included in 302 the access token. When this specification uses the term "access 303 token" it is assumed to be a PoP token unless specifically stated 304 otherwise. 306 The key bound to the access token (aka PoP key) may be based on 307 symmetric as well as on asymmetric cryptography. The appropriate 308 choice of security depends on the constraints of the IoT devices 309 as well as on the security requirements of the use case. 311 Symmetric PoP key: The AS generates a random symmetric PoP key, 312 encrypts it for the RS and includes it inside an access token. 313 The PoP key is also encrypted for the client and sent together 314 with the access token to the client.> 316 Asymmetric PoP key: An asymmetric key pair is generated on the 317 client and the public key is sent to the AS (if it does not 318 already have knowledge of the client's public key). 319 Information about the public key, which is the PoP key in this 320 case, is then included inside the access token and sent back to 321 the requesting client. The RS can identify the client's public 322 key from the information in the token, which allows the client 323 to use the corresponding private key for the proof of 324 possession. 326 The access token is protected against modifications using a MAC or 327 a digital signature, which is added by the AS. The choice of PoP 328 key does not necessarily imply a specific credential type for the 329 integrity protection of the token. More information about PoP 330 tokens can be found in [I-D.ietf-oauth-pop-architecture]. 332 Scopes and Permissions: 334 In OAuth 2.0, the client specifies the type of permissions it is 335 seeking to obtain (via the scope parameter) in the access request. 336 In turn, the AS may use the scope response parameter to inform the 337 client of the scope of the access token issued. As the client 338 could be a constrained device as well, this specification uses 339 CBOR encoded messages for CoAP, defined in Section 5, to request 340 scopes and to be informed what scopes the access token was 341 actually authorized for by the AS. 343 The values of the scope parameter are expressed as a list of 344 space- delimited, case-sensitive strings, with a semantic that is 345 well-known to the AS and the RS. More details about the concept 346 of scopes is found under Section 3.3 in [RFC6749]. 348 Claims: 350 Information carried in the access token, called claims, is in the 351 form of type-value pairs. An access token may, for example, 352 include a claim identifying the AS that issued the token (via the 353 "iss" claim) and what audience the access token is intended for 354 (via the "aud" claim). The audience of an access token can be a 355 specific resource or one or many resource servers. The resource 356 owner policies influence what claims are put into the access token 357 by the authorization server. 359 While the structure and encoding of the access token varies 360 throughout deployments, a standardized format has been defined 361 with the JSON Web Token (JWT) [RFC7519] where claims are encoded 362 as a JSON object. In [I-D.ietf-ace-cbor-web-token] an equivalent 363 format using CBOR encoding (CWT) has been defined. 365 Introspection: 367 Introspection is a method for a resource server to query the 368 authorization server for the active state and content of a 369 received access token. This is particularly useful in those cases 370 where the authorization decisions are very dynamic and/or where 371 the received access token itself is a reference rather than a 372 self-contained token. More information about introspection in 373 OAuth 2.0 can be found in [RFC7662]. 375 3.2. CoAP 377 CoAP is an application layer protocol similar to HTTP, but 378 specifically designed for constrained environments. CoAP typically 379 uses datagram-oriented transport, such as UDP, where reordering and 380 loss of packets can occur. A security solution need to take the 381 latter aspects into account. 383 While HTTP uses headers and query-strings to convey additional 384 information about a request, CoAP encodes such information in so- 385 called 'options'. 387 CoAP supports application-layer fragmentation of the CoAP payloads 388 through blockwise transfers [I-D.ietf-core-block]. However, block- 389 wise transfer does not increase the size limits of CoAP options, 390 therefore data encoded in options has to be kept small. 392 Transport layer security for CoAP can be provided by DTLS 1.2 393 [RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy 394 operations which requires transport layer security to be terminated 395 at the proxy. One approach for protecting CoAP communication end-to- 396 end through proxies, and also to support security for CoAP over 397 different transport in a uniform way, is to provide security on 398 application layer using an object-based security mechanism such as 399 CBOR Encoded Message Syntax [I-D.ietf-cose-msg]. 401 One application of COSE is OSCOAP [I-D.selander-ace-object-security], 402 which provides end-to-end confidentiality, integrity and replay 403 protection, and a secure binding between CoAP request and response 404 messages. In OSCOAP, the CoAP messages are wrapped in COSE objects 405 and sent using CoAP. 407 4. Protocol Interactions 409 The ACE framework is based on the OAuth 2.0 protocol interactions 410 using the /token and /introspect endpoints. A client obtains an 411 access token from an AS using the /token endpoint and subsequently 412 presents the access token to a RS to gain access to a protected 413 resource. The RS, after receiving an access token, may present it to 414 the AS via the /introspect endpoint to get information about the 415 access token. In other deployments the RS may process the access 416 token locally without the need to contact an AS. These interactions 417 are shown in Figure 1. An overview of various OAuth concepts is 418 provided in Section 3.1. 420 The consent of the resource owner, for giving a client access to a 421 protected resource, can be pre-configured authorization policies or 422 dynamically at the time when the request is sent. The resource owner 423 and the requesting party (i.e. client owner) are not shown in 424 Figure 1. 426 This framework supports a wide variety of communication security 427 mechanisms between the ACE entities, such as client, AS, and RS. We 428 assume that the client has been registered (also called enrolled or 429 onboarded) to an AS using a mechanism defined outside the scope of 430 this document. In practice, various techniques for onboarding have 431 been used, such as factory-based provisioning or the use of 432 commissioning tools. Regardless of the onboarding technique, this 433 registration procedure implies that the client and the AS share 434 credentials, and configuration parameters. These credentials are 435 used to mutually authenticate each other and to protect messages 436 exchanged between the client and the AS. 438 It is also assumed that the RS has been registered with the AS, 439 potentially in a similar way as the client has been registered with 440 the AS. Established keying material between the AS and the RS allows 441 the AS to apply cryptographic protection to the access token to 442 ensure that its content cannot be modified, and if needed, that the 443 content is confidentiality protected. 445 The keying material necessary for establishing communication security 446 between C and RS is dynamically established as part of the protocol 447 described in this document. 449 At the start of the protocol there is an optional discovery step 450 where the client discovers the resource server and the resources this 451 server hosts. In this step the client might also determine what 452 permissions are needed to access the protected resource. The 453 detailed procedures for this discovery process may be defined in an 454 ACE profile and depend on the protocols being used and the specific 455 deployment environment. 457 In Bluetooth Low Energy, for example, advertisements are broadcasted 458 by a peripheral, including information about the primary services. 459 In CoAP, as a second example, a client can makes a request to 460 "/.well-known/core" to obtain information about available resources, 461 which are returned in a standardized format as described in 462 [RFC6690]. 464 +--------+ +---------------+ 465 | |---(A)-- Token Request ------->| | 466 | | | Authorization | 467 | |<--(B)-- Access Token ---------| Server | 468 | | + Client Information | | 469 | | +---------------+ 470 | | ^ | 471 | | Introspection Request (D)| | 472 | Client | | | 473 | | Response + Client Token | |(E) 474 | | | v 475 | | +--------------+ 476 | |---(C)-- Token + Request ----->| | 477 | | | Resource | 478 | |<--(F)-- Protected Resource ---| Server | 479 | | | | 480 +--------+ +--------------+ 482 Figure 1: Basic Protocol Flow. 484 Requesting an Access Token (A): 486 The client makes an access token request to the /token endpoint at 487 the AS. This framework assumes the use of PoP tokens (see 488 Section 3.1 for a short description) wherein the AS binds a key to 489 an access token. The client may include permissions it seeks to 490 obtain, and information about the credentials it wants to use 491 (e.g., symmetric/asymmetric cryptography or a reference to a 492 specific credential). 494 Access Token Response (B): 496 If the AS successfully processes the request from the client, it 497 returns an access token. It also returns various parameters, 498 referred as "Client Information". In addition to the response 499 parameters defined by OAuth 2.0 and the PoP token extension, 500 further response parameters, such as information on which profile 501 the client should use with the resource server(s). More 502 information about these parameters can be found in in Section 6.4. 504 Resource Request (C): 506 The client interacts with the RS to request access to the 507 protected resource and provides the access token. The protocol to 508 use between the client and the RS is not restricted to CoAP. 509 HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also 510 viable candidates. 512 Depending on the device limitations and the selected protocol this 513 exchange may be split up into two parts: 515 (1) the client sends the access token containing, or 516 referencing, the authorization information to the RS, that may 517 be used for subsequent resource requests by the client, and 518 (2) the client makes the resource access request, using the 519 communication security protocol and other client information 520 obtained from the AS. 522 The Client and the RS mutually authenticate using the security 523 protocol specified in the profile (see step B) and the keys 524 obtained in the access token or the client information or the 525 client token. The RS verifies that the token is integrity 526 protected by the AS and compares the claims contained in the 527 access token with the resource request. If the RS is online, 528 validation can be handed over to the AS using token introspection 529 (see messages D and E) over HTTP or CoAP, in which case the 530 different parts of step C may be interleaved with introspection. 532 Token Introspection Request (D): 534 A resource server may be configured to introspect the access token 535 by including it in a request to the /introspect endpoint at that 536 AS. Token introspection over CoAP is defined in Section 7 and for 537 HTTP in [RFC7662]. 539 Note that token introspection is an optional step and can be 540 omitted if the token is self-contained and the resource server is 541 prepared to perform the token validation on its own. 543 Token Introspection Response (E): 545 The AS validates the token and returns the most recent parameters, 546 such as scope, audience, validity etc. associated with it back to 547 the RS. The RS then uses the received parameters to process the 548 request to either accept or to deny it. The AS can additionally 549 return information that the RS needs to pass on to the client in 550 the form of a client token. The latter is used to establish keys 551 for mutual authentication between client and RS, when the client 552 has no direct connectivity to the AS. 554 Protected Resource (F): 556 If the request from the client is authorized, the RS fulfills the 557 request and returns a response with the appropriate response code. 558 The RS uses the dynamically established keys to protect the 559 response, according to used communication security protocol. 561 5. Framework 563 The following sections detail the profiling and extensions of OAuth 564 2.0 for constrained environments which constitutes the ACE framework. 566 Credential Provisioning 568 For IoT we cannot generally assume that the client and RS are part 569 of a common key infrastructure, so the AS provisions credentials 570 or associated information to allow mutual authentication. These 571 credentials need to be provided to the parties before or during 572 the authentication protocol is executed, and may be re-used for 573 subsequent token requests. 575 Proof-of-Possession 577 The ACE framework by default implements proof-of-possession for 578 access tokens, i.e. that the authenticated token holder is bound 579 to the token. The binding is provided by the "cnf" claim 580 indicating what key is used for mutual authentication. If clients 581 need to update a token, e.g. to get additional rights, they can 582 request that the AS binds the new access token to the same 583 credential as the previous token. 585 ACE Profile Negotiation 587 The client or RS may be limited in the encodings or protocols it 588 supports. To support a variety of different deployment settings, 589 specific interactions between client and RS are defined in an ACE 590 profile. The ACE framework supports the negotiation of different 591 ACE profiles between client and AS using the "profile" parameter 592 in the token request and token response. 594 OAuth 2.0 requires the use of TLS both to protect the communication 595 between AS and client when requesting an access token and between AS 596 and RS for introspection. In constrained settings TLS is not always 597 feasible, or desirable. Nevertheless it is REQUIRED that the data 598 exchanged with the AS is encrypted and integrity protected. It is 599 furthermore REQUIRED that the AS and the endpoint communicating with 600 it (client or RS) perform mutual authentication. 602 Profiles are expected to specify the details of how this is done, 603 depending e.g. on the communication protocol and the credentials used 604 by the client or the RS. 606 In OAuth 2.0 the communication with the Token and the Introspection 607 resources at the AS is assumed to be via HTTP and may use Uri-query 608 parameters. This framework RECOMMENDS to use CoAP instead and 609 RECOMMENDS the use of the following alternative instead of Uri-query 610 parameters: The sender (client or RS) encodes the parameters of its 611 request as a CBOR map and submits that map as the payload of the POST 612 request. The Content-format MUST be "application/cbor" in that case. 614 The OAuth 2.0 AS uses a JSON structure in the payload of its 615 responses both to client and RS. This framework RECOMMENDS the use 616 of CBOR [RFC7049] instead. The requesting device can explicitly 617 request this encoding by setting the CoAP Accept option in the 618 request to "application/cbor". 620 6. The 'Token' Resource 622 In plain OAuth 2.0 the AS provides the /token resource for submitting 623 access token requests. This framework extends the functionality of 624 the /token resource, giving the AS the possibility to help client and 625 RS to establish shared keys or to exchange their public keys. 627 Communication between the client and the token resource at the AS 628 MUST be integrity protected and encrypted. Furthermore AS and client 629 MUST perform mutual authentication. Profiles of this framework are 630 expected to specify how authentication and communication security is 631 implemented. 633 The figures of this section uses CBOR diagnostic notation without the 634 integer abbreviations for the parameters or their values for better 635 readability. 637 6.1. Client-to-AS Request 639 When requesting an access token from the AS, the client MAY include 640 the following parameters in the request in addition to the ones 641 required or optional according to the OAuth 2.0 specification 642 [RFC6749]: 644 token_type 645 OPTIONAL. See Section 6.4 for more details. 647 alg 648 OPTIONAL. See Section 6.4 for more details. 650 profile 651 OPTIONAL. This indicates the profile that the client would like 652 to use with the RS. See Section 6.4 for more details on the 653 formatting of this parameter. If the RS cannot support the 654 requested profile, the AS MUST reply with an error message. 656 cnf 657 OPTIONAL. This field contains information about a public key the 658 client would like to bind to the access token. If the client 659 requests an asymmetric proof-of-possession algorithm, but does not 660 provide a public key, the AS MUST respond with an error message. 661 See Section 6.4 for more details on the formatting of the 'cnf' 662 parameter. 664 These new parameters are optional in the case where the AS has prior 665 knowledge of the capabilities of the client, otherwise these 666 parameters are required. This prior knowledge may, for example, be 667 set by the use of a dynamic client registration protocol exchange 668 [RFC7591]. 670 The following examples illustrate different types of requests for 671 proof-of-possession tokens. 673 Figure 2 shows a request for a token with a symmetric proof-of- 674 possession key. 676 Header: POST (Code=0.02) 677 Uri-Host: "server.example.com" 678 Uri-Path: "token" 679 Content-Type: "application/cbor" 680 Payload: 681 { 682 "grant_type" : "client_credentials", 683 "aud" : "tempSensor4711", 684 "client_id" : "myclient", 685 "client_secret" : b64'FWRUVGZUZmZFRkWSRlVGhA', 686 "token_type" : "pop", 687 "alg" : "HS256", 688 "profile" : "coap_dtls" 689 } 691 Figure 2: Example request for an access token bound to a symmetric 692 key. 694 Figure 3 shows a request for a token with an asymmetric proof-of- 695 possession key. 697 Header: POST (Code=0.02) 698 Uri-Host: "server.example.com" 699 Uri-Path: "token" 700 Content-Type: "application/cbor" 701 Payload: 702 { 703 "grant_type" : "token", 704 "aud" : "lockOfDoor0815", 705 "client_id" : "myclient", 706 "token_type" : "pop", 707 "alg" : "ES256", 708 "profile" : "coap_oscoap" 709 "cnf" : { 710 "COSE_Key" : { 711 "kty" : "EC", 712 "kid" : h'11', 713 "crv" : "P-256", 714 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 715 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 716 } 717 } 718 } 720 Figure 3: Example request for an access token bound to an asymmetric 721 key. 723 Figure 4 shows a request for a token where a previously communicated 724 proof-of-possession key is only referenced. 726 Header: POST (Code=0.02) 727 Uri-Host: "server.example.com" 728 Uri-Path: "token" 729 Content-Type: "application/cbor" 730 Payload: 731 { 732 "grant_type" : "client_credentials", 733 "aud" : "valve424", 734 "scope" : "read", 735 "client_id" : "myclient", 736 "token_type" : "pop", 737 "alg" : "ES256", 738 "profile" : "coap_oscoap" 739 "cnf" : { 740 "kid" : b64'6kg0dXJM13U' 741 } 742 } 744 Figure 4: Example request for an access token bound to a key 745 reference. 747 6.2. AS-to-Client Response 749 If the access token request has been successfully verified by the AS 750 and the client is authorized to obtain a PoP token for the indicated 751 audience and scopes (if any), the AS issues an access token. If 752 client authentication failed or is invalid, the authorization server 753 returns an error response as described in Section 6.3. 755 The following parameters may also be part of a successful response in 756 addition to those defined in section 5.1 of [RFC6749]: 758 profile 759 REQUIRED. This indicates the profile that the client MUST use 760 towards the RS. See Section 6.4 for the formatting of this 761 parameter. 763 cnf 764 REQUIRED. This field contains information about the proof-of 765 possession key for this access token. See Section 6.4 for the 766 formatting of this parameter. 768 Note that the access token can also contains a 'cnf' claim, however, 769 these two values are consumed by different parties. The access token 770 is created by the AS and processed by the RS (and opaque to the 771 client) whereas the Client Information is created by the AS and 772 processed by the client; it is never forwarded to the resource 773 server. 775 The following examples illustrate different types of responses for 776 proof-of-possession tokens. 778 Figure 5 shows a response containing a token and a 'cnf' parameter 779 with a symmetric proof-of-possession key. 781 Header: Created (Code=2.01) 782 Content-Type: "application/cbor" 783 Payload: 784 { 785 "access_token" : b64'SlAV32hkKG ... 786 (remainder of CWT omitted for brevity; 787 CWT contains COSE_Key in the 'cnf' claim)', 788 "token_type" : "pop", 789 "alg" : "HS256", 790 "expires_in" : "3600", 791 "profile" : "coap_dtls" 792 "cnf" : { 793 "COSE_Key" : { 794 "kty" : "Symmetric", 795 "kid" : b64'39Gqlw', 796 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 797 } 798 } 799 } 801 Figure 5: Example AS response with an access token bound to a 802 symmetric key. 804 6.3. Error Response 806 The error responses for CoAP-based interactions with the AS are 807 equivalent to the ones for HTTP-based interactions as defined in 808 section 5.2 of [RFC6749], with the following differences: The 809 Content-Type MUST be set to "application/cbor", the payload MUST be 810 encoded in a CBOR map and the CoAP response code 4.00 Bad Request 811 MUST be used unless specified otherwise. 813 6.4. New Request and Response Parameters 815 This section defines parameters that can be used in access token 816 requests and responses, as well as abbreviations for more compact 817 encoding of existing parameters and common values. 819 6.4.1. Grant Type 821 The abbreviations in Figure 6 MAY be used in CBOR encodings instead 822 of the string values defined in [RFC6749]. 824 /--------------------+----------+--------------\ 825 | grant_type | CBOR Key | Major Type | 826 |--------------------+----------+--------------| 827 | password | 0 | 0 (uint) | 828 | authorization_code | 1 | 0 | 829 | client_credentials | 2 | 0 | 830 | refresh_token | 3 | 0 | 831 \--------------------+----------+--------------/ 833 Figure 6: CBOR abbreviations for common grant types 835 6.4.2. Token Type and Algorithms 837 To allow clients to indicate support for specific token types and 838 respective algorithms they need to interact with the AS. They can 839 either provide this information out-of-band or via the 'token_type' 840 and 'alg' parameter in the client request. 842 The value in the 'alg' parameter together with value from the 843 'token_type' parameter allow the client to indicate the supported 844 algorithms for a given token type. The token type refers to the 845 specification used by the client to interact with the resource server 846 to demonstrate possession of the key. The 'alg' parameter provides 847 further information about the algorithm, such as whether a symmetric 848 or an asymmetric crypto-system is used. Hence, a client supporting a 849 specific token type also knows how to populate the values to the 850 'alg' parameter. 852 This document registers the new value "pop" for the OAuth Access 853 Token Types registry, specifying a Proof-of-Possession token. How 854 the proof-of-possession is performed is specified by the 'alg' 855 parameter. Profiles of this framework are responsible for defining 856 values for the 'alg' parameter together with the corresponding proof- 857 of-possession mechanisms. 859 The values in the 'alg' parameter are case-sensitive. If the client 860 supports more than one algorithm then each individual value MUST be 861 separated by a space. 863 6.4.3. Profile 865 The "profile" parameter identifies the communication protocol and the 866 communication security protocol between the client and the RS. 868 An initial set of profile identifiers and their CBOR encodings are 869 specified in Figure 7. Profiles using other combinations of 870 protocols are expected to define their own profile identifiers. 872 /--------------------+----------+--------------\ 873 | Profile identifier | CBOR Key | Major Type | 874 |--------------------+----------+--------------| 875 | http_tls | 0 | 0 (uint) | 876 | coap_dtls | 1 | 0 | 877 | coap_oscoap | 2 | 0 | 878 \--------------------+----------+--------------/ 880 Figure 7: Profile identifiers and their CBOR mappings 882 Profiles MAY define additional parameters for both the token request 883 and the client information in the access token response in order to 884 support negotioation or signalling of profile specific parameters. 886 6.4.4. Confirmation 888 The "cnf" parameter identifies or provides the key used for proof-of- 889 possession. This framework extends the definition of 'cnf' from 890 [RFC7800] by defining CBOR/COSE encodings and the use of 'cnf' for 891 transporting keys in the client information. 893 A CBOR encoded payload MAY contain the 'cnf' parameter with the 894 following contents: 896 COSE_Key In this case the 'cnf' parameter contains the proof-of- 897 possession key to be used by the client. An example is shown in 898 Figure 8. 900 "cnf" : { 901 "COSE_Key" : { 902 "kty" : "EC", 903 "kid" : h'11', 904 "crv" : "P-256", 905 "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', 906 "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' 907 } 908 } 910 Figure 8: Confirmation parameter containing a public key 912 COSE_Encrypted In this case the 'cnf' parameter contains an 913 encrypted symmetriic key destined for the client. The client is 914 assumed to be able to decrypt the cihpertext of this parameter. 915 The parameter is encoded as COSE_Encrypted object wrapping a 916 COSE_Key object. Figure 9 shows an example of this type of 917 encoding. 919 "cnf" : { 920 "COSE_Encrypted" : { 921 993( 922 [ h'a1010a' # protected header : {"alg" : "AES-CCM-16-64-128"} 923 "iv" : b64'ifUvZaHFgJM7UmGnjA', # unprotected header 924 b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext 925 ] 926 ) 927 } 928 } 930 Figure 9: Confirmation paramter containing an encrypted symmetric key 932 The ciphertext here could e.g. contain a symmetric key as in 933 Figure 10. 935 { 936 "kty" : "Symmetric", 937 "kid" : b64'39Gqlw', 938 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 939 } 941 Figure 10: Example plaintext of an encrypted cnf parameter 943 Key Identifier In this case the 'cnf' parameter references a key 944 that is assumed to be previously known by the recipient. This 945 allows clients that perform repeated requests for an access token 946 for the same audience but e.g. with different scopes to omit key 947 transport in the access token, token request and token response. 948 Figure 11 shows such an example. 950 "cnf" : { 951 "kid" : b64'39Gqlw' 952 } 954 Figure 11: A Confirmation parameter with just a key identifier 956 6.5. Mapping parameters to CBOR 958 All OAuth parameters in access token requests and responses are 959 mapped to CBOR types as follows and are given an integer key value to 960 save space. 962 /-------------------+----------+-----------------\ 963 | Parameter name | CBOR Key | Major Type | 964 |-------------------+----------+-----------------| 965 | client_id | 1 | 3 (text string) | 966 | client_secret | 2 | 2 (byte string) | 967 | response_type | 3 | 3 | 968 | redirect_uri | 4 | 3 | 969 | scope | 5 | 3 | 970 | state | 6 | 3 | 971 | code | 7 | 2 | 972 | error_description | 8 | 3 | 973 | error_uri | 9 | 3 | 974 | grant_type | 10 | 0 (unit) | 975 | access_token | 11 | 3 | 976 | token_type | 12 | 0 | 977 | expires_in | 13 | 0 | 978 | username | 14 | 3 | 979 | password | 15 | 3 | 980 | refresh_token | 16 | 3 | 981 | alg | 17 | 3 | 982 | cnf | 18 | 5 (map) | 983 | aud | 19 | 3 | 984 | profile | 20 | 0 | 985 \---------------+--------------+-----------------/ 987 Figure 12: CBOR mappings used in token requests 989 7. The 'Introspect' Resource 991 Token introspection [RFC7662] is used by the RS and potentially the 992 client to query the AS for metadata about a given token e.g. validity 993 or scope. Analogous to the protocol defined in RFC 7662 [RFC7662] 994 for HTTP and JSON, this section defines adaptations to more 995 constrained environments using CoAP and CBOR. 997 Communication between the RS and the introspection resource at the AS 998 MUST be integrity protected and encrypted. Furthermore AS and RS 999 MUST perform mutual authentication. Finally the AS SHOULD to verify 1000 that the RS has the right to access introspection information about 1001 the provided token. Profiles of this framework are expected to 1002 specify how authentication and communication security is implemented. 1004 The figures of this section uses CBOR diagnostic notation without the 1005 integer abbreviations for the parameters or their values for better 1006 readability. 1008 7.1. RS-to-AS Request 1010 The RS sends a CoAP POST request to the introspection resource at the 1011 AS, with payload sent as "application/cbor" data. The payload is a 1012 CBOR map with a 'token' parameter containing the access token along 1013 with optional parameters representing additional context that is 1014 known by the RS to aid the AS in its response. 1016 The same parameters are required and optional as in section 2.1 of 1017 RFC 7662 [RFC7662]. 1019 For example, Figure 13 shows a RS calling the token introspection 1020 resource at the AS to query about an OAuth 2.0 proof-of-possession 1021 token. 1023 Header: POST (Code=0.02) 1024 Uri-Host: "server.example.com" 1025 Uri-Path: "introspect" 1026 Content-Type: "application/cbor" 1027 Payload: 1028 { 1029 "token" : b64'7gj0dXJQ43U', 1030 "token_type_hint" : "pop" 1031 } 1033 Figure 13: Example introspection request. 1035 7.2. AS-to-RS Response 1037 The AS responds with a CBOR object in "application/cbor" format with 1038 the same required and optional parameters as in section 2.2. of RFC 1039 7662 [RFC7662] with the following additions: 1041 alg 1042 OPTIONAL. See Section 6.4 for more details. 1044 cnf 1045 OPTIONAL. This field contains information about the proof-of- 1046 possession key that binds the client to the access token. See 1047 Section 6.4 for more details on the formatting of the 'cnf' 1048 parameter. 1050 profile 1051 OPTIONAL. This indicates the profile that the RS MUST use with 1052 the client. See Section 6.4 for more details on the formatting of 1053 this parameter. 1055 client_token 1056 OPTIONAL. This parameter contains information that the RS MUST 1057 pass on to the client. See Section 7.4 for more details. 1059 For example, Figure 14 shows an AS response to the introspection 1060 request in Figure 13. 1062 Header: Created Code=2.01) 1063 Content-Type: "application/cbor" 1064 Payload: 1065 { 1066 "active" : true, 1067 "scope" : "read", 1068 "token_type" : "pop", 1069 "alg" : "HS256", 1070 "profile" : "coap_dtls", 1071 "client_token" : b64'2QPhg0OhAQo ... 1072 (remainder of client token omitted for brevity)', 1073 "cnf" : { 1074 "COSE_Key" : { 1075 "kty" : "Symmetric", 1076 "kid" : b64'39Gqlw', 1077 "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' 1078 } 1079 } 1080 } 1082 Figure 14: Example introspection response. 1084 7.3. Error Response 1086 The error responses for CoAP-based interactions with the AS are 1087 equivalent to the ones for HTTP-based interactions as defined in 1088 section 2.3 of [RFC7662], with the following differences: 1090 o If content is sent, the Content-Type MUST be set to "application/ 1091 cbor", and the payload MUST be encoded in a CBOR map. 1092 o If the credentials used by the RS are invalid the AS MUST respond 1093 with the CoAP response code code 4.01 (Unauthorized) and use the 1094 required and optional parameters from section 5.2 in RFC 6749 1095 [RFC6749]. 1096 o If the RS does not have the right to perform this introspection 1097 request, the AS MUST respond with the CoAP response code 4.03 1098 (Forbidden). In this case no payload is returned. 1100 Note that a properly formed and authorized query for an inactive or 1101 otherwise invalid token does not warrant an error response by this 1102 specification. In these cases, the authorization server MUST instead 1103 respond with an introspection response with the "active" field set to 1104 "false". 1106 7.4. Client Token 1108 EDITORIAL NOTE: We have tentatively introduced this concept and would 1109 specifically like feedback if this is viewed as a useful addition to 1110 the framework. 1112 In cases where the client has limited connectivity and is requesting 1113 access to a previously unknown resource servers, using a long term 1114 token, there are situations where it would be beneficial to relay the 1115 proof-of-possession key and other relevant information from the AS to 1116 the client through the RS. The client_token parameter is designed to 1117 carry such information, and is intended to be used as described in 1118 Figure 15. 1120 Resource Authorization 1121 Client Server Server 1122 | | | 1123 | | | 1124 A: +--------------->| | 1125 | POST | | 1126 | Access Token | | 1127 | B: +--------------->| 1128 | | Introspection | 1129 | | Request | 1130 | | | 1131 | C: +<---------------+ 1132 | | Introspection | 1133 | | Response | 1134 | | + Client Token | 1135 D: |<---------------+ | 1136 | 2.01 Created | | 1137 | + Client Token | 1139 Figure 15: Use of the client_token parameter. 1141 The client token is a COSE_Encrytped object, containing as payload a 1142 CBOR map with the following claims: 1144 cnf 1145 REQUIRED. Contains information about the proof-of-possession key 1146 the client is to use with its access token. See Section 6.4.4. 1148 token_type 1149 OPTIONAL. See Section 6.4.2. 1151 alg 1152 OPTIONAL. See Section 6.4.2. 1154 profile 1155 REQUIRED. See Section 6.4.3. 1157 rs_cnf 1158 OPTIONAL. Contains information about the key that the RS uses to 1159 authenticate towards the client. If the key is symmetric then 1160 this claim MUST NOT be part of the Client Token, since this is the 1161 same key as the one specified through the 'cnf' claim. This claim 1162 uses the same encoding as the 'cnf' parameter. See Section 6.4.3. 1164 The AS encrypts this token using a key shared between the AS and the 1165 client, so that only the client can decrypt it and access its 1166 payload. How this key is established is out of scope of this 1167 framework. 1169 7.5. Mapping Introspection parameters to CBOR 1171 The introspection request and response parameters are mapped to CBOR 1172 types as follows and are given an integer key value to save space. 1174 /----------------+----------+-----------------\ 1175 | Parameter name | CBOR Key | Major Type | 1176 |----------------+----------+-----------------| 1177 | active | 1 | 0 (uint) | 1178 | username | 2 | 3 (text string) | 1179 | client_id | 3 | 3 | 1180 | scope | 4 | 3 | 1181 | token_type | 5 | 3 | 1182 | exp | 6 | 6 tag value 1 | 1183 | iat | 7 | 6 tag value 1 | 1184 | nbf | 8 | 6 tag value 1 | 1185 | sub | 9 | 3 | 1186 | aud | 10 | 3 | 1187 | iss | 11 | 3 | 1188 | jti | 12 | 3 | 1189 | alg | 13 | 3 | 1190 | cnf | 14 | 5 (map) | 1191 | aud | 15 | 3 | 1192 | client_token | 16 | 3 | 1193 | rs_cnf | 17 | 5 | 1194 \----------------+----------+-----------------/ 1196 Figure 16: CBOR Mappings to Token Introspection Parameters. 1198 8. The Access Token 1200 This framework RECOMMENDS the use of CBOR web token (CWT) as 1201 specified in [I-D.ietf-ace-cbor-web-token]. 1203 In order to facilitate offline processing of access tokens, this 1204 draft specfifies the "scope" claim for access tokens that explicitly 1205 encodes the scope of a given access token. This claim follows the 1206 same encoding rules as defined in section 3.3 of [RFC6749]. The 1207 meaning of a specific scope value is application specific and 1208 expected to be known to the RS running that application. 1210 8.1. The 'Authorization Information' Resource 1212 The access token, containing authorization information and 1213 information of the key used by the client, is transported to the RS 1214 so that the RS can authenticate and authorize the client request. 1215 This section defines a method for transporting the access token to 1216 the RS using CoAP that MAY be used. An ACE profile MAY define other 1217 methods for token transport. 1219 This method REQUIRES the RS to implement an /authz-info resource. A 1220 client using this method MUST make a POST request to /authz-info on 1221 the RS with the access token in the payload. The RS receiving the 1222 token MUST verify the validity of the token. If the token is valid, 1223 the RS MUST respond to the POST request with 2.04 (Changed). 1225 If the token is not valid, the RS MUST respond with error code 4.01 1226 (Unauthorized). If the token is valid but the audience of the token 1227 does not match the RS, the RS MUST respond with error code 4.03 1228 (Forbidden). 1230 The RS MAY make an introspection request to validate the token before 1231 responding to the POST /authz-info request. If the introspection 1232 response contains a client token (Section 7.4) then this token SHALL 1233 be included in the payload of the 2.04 (Changed) response. 1235 8.2. Token Expiration 1237 Depending on the capabilities of the RS, there are various ways in 1238 which it can verify the validity of a received access token. We list 1239 the possibilities here including what functionality they require of 1240 the RS. 1242 o The token is a CWT/JWT and includes a 'exp' claim and possibly the 1243 'nbf' claim. The RS verifies these by comparing them to values 1244 from its internal clock as defined in [RFC7519]. In this case the 1245 RS must have a real time chip (RTC) or some other way of reliably 1246 measuring time. 1247 o The RS verifies the validity of the token by performing an 1248 introspection request as specified in Section 7. This requires 1249 the RS to have a reliable network connection to the AS and to be 1250 able to handle two secure sessions in parallel (C to RS and AS to 1251 RS). 1252 o The RS and the AS both store a sequence number linked to their 1253 common security association. The AS increments this number for 1254 each access token it issues and includes it in the access token, 1255 which is a CWT/JWT. The RS keeps track of the most recently 1256 received sequence number, and only accepts tokens as valid, that 1257 are in a certain range around this number. This method does only 1258 require the RS to keep track of the sequence number. The method 1259 does not provide timely expiration, but it makes sure that older 1260 tokens cease to be valid after a certain number of newer ones got 1261 issued. For a constrained RS with no network connectivity and no 1262 means of reliably measuring time, this is the best that can be 1263 achieved. 1265 9. Security Considerations 1267 The entire document is about security. Security considerations 1268 applicable to authentication and authorization in RESTful 1269 environments provided in OAuth 2.0 [RFC6749] apply to this work, as 1270 well as the security considerations from [I-D.ietf-ace-actors]. 1271 Furthermore [RFC6819] provides additional security considerations for 1272 OAuth which apply to IoT deployments as well. Finally 1273 [I-D.ietf-oauth-pop-architecture] discusses security and privacy 1274 threats as well as mitigation measures for Proof-of-Possession 1275 tokens. 1277 10. IANA Considerations 1279 This specification registers new parameters for OAuth and establishes 1280 registries for mappings to CBOR. 1282 10.1. OAuth Introspection Response Parameter Registration 1284 This specification registers the following parameters in the OAuth 1285 introspection response parameters 1287 o Name: "alg" 1288 o Description: Algorithm to use with PoP key, as defined in PoP 1289 token specification, 1290 o Change Controller: IESG 1291 o Specification Document(s): this document 1293 o Name: "cnf" 1294 o Description: Key to use to prove the right to use an access token, 1295 as defined in [RFC7800]. 1296 o Change Controller: IESG 1297 o Specification Document(s): this document 1299 o Name: "aud" 1300 o Description: reference to intended receiving RS, as defined in PoP 1301 token specification. 1302 o Change Controller: IESG 1303 o Specification Document(s): this document 1305 o Name: "profile" 1306 o Description: The communication and communication security profile 1307 used between client and RS, as defined in ACE profiles. 1308 o Change Controller: IESG 1309 o Specification Document(s): this document 1311 o Name: "client_token" 1312 o Description: Information that the RS MUST pass to the client e.g. 1313 about the proof-of-possession keys. 1314 o Change Controller: IESG 1315 o Specification Document(s): this document 1317 10.2. OAuth Parameter Registration 1319 This specification registers the following parameters in the OAuth 1320 Parameters Registry 1322 o Name: "alg" 1323 o Description: Algorithm to use with PoP key, as defined in PoP 1324 token specification, 1325 o Change Controller: IESG 1326 o Specification Document(s): this document 1328 o Parameter name: "profile" 1329 o Parameter usage location: token request, and token response 1330 o Change Controller: IESG 1331 o Specification Document(s): this document 1333 o Name: "cnf" 1334 o Description: Key to use to prove the right to use an access token, 1335 as defined in [RFC7800]. 1336 o Change Controller: IESG 1337 o Specification Document(s): this document 1339 10.3. OAuth Access Token Types 1341 This specification registers the following new token type in the 1342 OAuth Access Token Types Registry 1344 o Name: "PoP" 1345 o Description: A proof-of-possession token. 1346 o Change Controller: IESG 1347 o Specification Document(s): this document 1349 10.4. Token Type Mappings 1351 A new registry will be requested from IANA, entitled "Token Type 1352 Mappings". The registry is to be created as Expert Review Required. 1354 10.4.1. Registration Template 1356 Token Type: 1357 Name of token type as registered in the OAuth token type registry 1358 e.g. "Bearer". 1359 Mapped value: 1360 Integer representation for the token type value. The key value 1361 MUST be an integer in the range of 1 to 65536. 1362 Change Controller: 1364 For Standards Track RFCs, list the "IESG". For others, give the 1365 name of the responsible party. Other details (e.g., postal 1366 address, email address, home page URI) may also be included. 1367 Specification Document(s): 1368 Reference to the document or documents that specify the 1369 parameter,preferably including URIs that can be used to retrieve 1370 copies of the documents. An indication of the relevant sections 1371 may also be included but is not required. 1373 10.4.2. Initial Registry Contents 1375 o Parameter name: "Bearer" 1376 o Mapped value: 1 1377 o Change Controller: IESG 1378 o Specification Document(s): this document 1380 o Parameter name: "pop" 1381 o Mapped value: 2 1382 o Change Controller: IESG 1383 o Specification Document(s): this document 1385 10.5. JSON Web Token Claims 1387 This specification registers the following new claim in the JSON Web 1388 Token (JWT) registry. 1390 o Claim Name: "scope" 1391 o Claim Description: The scope of an access token as defined in 1392 [RFC6749]. 1393 o Change Controller: IESG 1394 o Specification Document(s): this document 1396 10.6. ACE Profile Registry 1398 A new registry will be requested from IANA, entitled "ACE Profile 1399 Registry". The registry is to be created as Expert Review Required. 1401 10.6.1. Registration Template 1403 Profile name: 1404 Name of the profile to be included in the profile attribute. 1405 Profile description: 1406 Text giving an over view of the profile and the context it is 1407 developed for. 1408 Profile ID: 1409 Integer value to identify the profile. The value MUST be an 1410 integer in the range of 1 to 65536. 1411 Change Controller: 1413 For Standards Track RFCs, list the "IESG". For others, give the 1414 name of the responsible party. Other details (e.g., postal 1415 address, email address, home page URI) may also be included. 1416 Specification Document(s): 1417 Reference to the document or documents that specify the 1418 parameter,preferably including URIs that can be used to retrieve 1419 copies of the documents. An indication of the relevant sections 1420 may also be included but is not required. 1422 10.7. OAuth Parameter Mappings Registry 1424 A new registry will be requested from IANA, entitled "Token Resource 1425 CBOR Mappings Registry". The registry is to be created as Expert 1426 Review Required. 1428 10.7.1. Registration Template 1430 Parameter name: 1431 OAuth Parameter name, refers to the name in the OAuth parameter 1432 registry e.g. "client_id". 1433 CBOR key value: 1434 Key value for the claim. The key value MUST be an integer in the 1435 range of 1 to 65536. 1436 Change Controller: 1437 For Standards Track RFCs, list the "IESG". For others, give the 1438 name of the responsible party. Other details (e.g., postal 1439 address, email address, home page URI) may also be included. 1440 Specification Document(s): 1441 Reference to the document or documents that specify the 1442 parameter,preferably including URIs that can be used to retrieve 1443 copies of the documents. An indication of the relevant sections 1444 may also be included but is not required. 1446 10.7.2. Initial Registry Contents 1448 o Parameter name: "client_id" 1449 o CBOR key value: 1 1450 o Change Controller: IESG 1451 o Specification Document(s): this document 1453 o Parameter name: "client_secret" 1454 o CBOR key value: 2 1455 o Change Controller: IESG 1456 o Specification Document(s): this document 1458 o Parameter name: "response_type" 1459 o CBOR key value: 3 1460 o Change Controller: IESG 1461 o Specification Document(s): this document 1463 o Parameter name: "redirect_uri" 1464 o CBOR key value: 4 1465 o Change Controller: IESG 1466 o Specification Document(s): this document 1468 o Parameter name: "scope" 1469 o CBOR key value: 5 1470 o Change Controller: IESG 1471 o Specification Document(s): this document 1473 o Parameter name: "state" 1474 o CBOR key value: 6 1475 o Change Controller: IESG 1476 o Specification Document(s): this document 1478 o Parameter name: "code" 1479 o CBOR key value: 7 1480 o Change Controller: IESG 1481 o Specification Document(s): this document 1483 o Parameter name: "error_description" 1484 o CBOR key value: 8 1485 o Change Controller: IESG 1486 o Specification Document(s): this document 1488 o Parameter name: "error_uri" 1489 o CBOR key value: 9 1490 o Change Controller: IESG 1491 o Specification Document(s): this document 1493 o Parameter name: "grant_type" 1494 o CBOR key value: 10 1495 o Change Controller: IESG 1496 o Specification Document(s): this document 1498 o Parameter name: "access_token" 1499 o CBOR key value: 11 1500 o Change Controller: IESG 1501 o Specification Document(s): this document 1503 o Parameter name: "token_type" 1504 o CBOR key value: 12 1505 o Change Controller: IESG 1506 o Specification Document(s): this document 1508 o Parameter name: "expires_in" 1509 o CBOR key value: 13 1510 o Change Controller: IESG 1511 o Specification Document(s): this document 1513 o Parameter name: "username" 1514 o CBOR key value: 14 1515 o Change Controller: IESG 1516 o Specification Document(s): this document 1518 o Parameter name: "password" 1519 o CBOR key value: 15 1520 o Change Controller: IESG 1521 o Specification Document(s): this document 1523 o Parameter name: "refresh_token" 1524 o CBOR key value: 16 1525 o Change Controller: IESG 1526 o Specification Document(s): this document 1528 o Parameter name: "alg" 1529 o CBOR key value: 17 1530 o Change Controller: IESG 1531 o Specification Document(s): this document 1533 o Parameter name: "cnf" 1534 o CBOR key value: 18 1535 o Change Controller: IESG 1536 o Specification Document(s): this document 1538 o Parameter name: "aud" 1539 o CBOR key value: 19 1540 o Change Controller: IESG 1541 o Specification Document(s): this document 1543 o Parameter name: "profile" 1544 o CBOR key value: 20 1545 o Change Controller: IESG 1546 o Specification Document(s): this document 1548 10.8. Introspection Resource CBOR Mappings Registry 1550 A new registry will be requested from IANA, entitled "Introspection 1551 Resource CBOR Mappings Registry". The registry is to be created as 1552 Expert Review Required. 1554 10.8.1. Registration Template 1556 Response parameter name: 1557 Name of the response parameter as defined in the "OAuth Token 1558 Introspection Response" registry e.g. "active". 1559 CBOR key value: 1560 Key value for the claim. The key value MUST be an integer in the 1561 range of 1 to 65536. 1562 Change Controller: 1563 For Standards Track RFCs, list the "IESG". For others, give the 1564 name of the responsible party. Other details (e.g., postal 1565 address, email address, home page URI) may also be included. 1566 Specification Document(s): 1567 Reference to the document or documents that specify the 1568 parameter,preferably including URIs that can be used to retrieve 1569 copies of the documents. An indication of the relevant sections 1570 may also be included but is not required. 1572 10.8.2. Initial Registry Contents 1574 o Response parameter name: "active" 1575 o CBOR key value: 1 1576 o Change Controller: IESG 1577 o Specification Document(s): this document 1579 o Response parameter name: "username" 1580 o CBOR key value: 2 1581 o Change Controller: IESG 1582 o Specification Document(s): this document 1584 o Response parameter name: "client_id" 1585 o CBOR key value: 3 1586 o Change Controller: IESG 1587 o Specification Document(s): this document 1589 o Response parameter name: "scope" 1590 o CBOR key value: 4 1591 o Change Controller: IESG 1592 o Specification Document(s): this document 1594 o Response parameter name: "token_type" 1595 o CBOR key value: 5 1596 o Change Controller: IESG 1597 o Specification Document(s): this document 1599 o Response parameter name: "exp" 1600 o CBOR key value: 6 1601 o Change Controller: IESG 1602 o Specification Document(s): this document 1604 o Response parameter name: "iat" 1605 o CBOR key value: 7 1606 o Change Controller: IESG 1607 o Specification Document(s): this document 1609 o Response parameter name: "nbf" 1610 o CBOR key value: 8 1611 o Change Controller: IESG 1612 o Specification Document(s): this document 1614 o Response parameter name: "sub" 1615 o CBOR key value: 9 1616 o Change Controller: IESG 1617 o Specification Document(s): this document 1619 o Response parameter name: "aud" 1620 o CBOR key value: 10 1621 o Change Controller: IESG 1622 o Specification Document(s): this document 1624 o Response parameter name: "iss" 1625 o CBOR key value: 11 1626 o Change Controller: IESG 1627 o Specification Document(s): this document 1629 o Response parameter name: "jti" 1630 o CBOR key value: 12 1631 o Change Controller: IESG 1632 o Specification Document(s): this document 1634 o Parameter name: "alg" 1635 o CBOR key value: 13 1636 o Change Controller: IESG 1637 o Specification Document(s): this document 1639 o Parameter name: "cnf" 1640 o CBOR key value: 14 1641 o Change Controller: IESG 1642 o Specification Document(s): this document 1644 o Parameter name: "aud" 1645 o CBOR key value: 15 1646 o Change Controller: IESG 1647 o Specification Document(s): this document 1649 10.9. CoAP Option Number Registration 1651 This section registers the "Access-Token" CoAP Option Number in the 1652 "CoRE Parameters" sub-registry "CoAP Option Numbers" in the manner 1653 described in [RFC7252]. 1655 Name 1657 Access-Token 1658 Number 1660 TBD 1661 Reference 1663 [This document]. 1664 Meaning in Request 1666 Contains an Access Token according to [This document] containing 1667 access permissions of the client. 1668 Meaning in Response 1670 Not used in response 1671 Safe-to-Forward 1673 TBD 1674 Format 1676 Based on the observer the format is perceived differently. Opaque 1677 data to the client and CWT or reference token to the RS. 1678 Length 1680 Less then 255 bytes 1682 11. Acknowledgments 1684 We would like to thank Eve Maler for her contributions to the use of 1685 OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion 1686 input, and Malisa Vucinic for his input on the ACRE proposal 1687 [I-D.seitz-ace-core-authz] which was one source of inspiration for 1688 this work. Finally, we would like to thank the ACE working group in 1689 general for their feedback. 1691 Ludwig Seitz and Goeran Selander worked on this document as part of 1692 the CelticPlus project CyberWI, with funding from Vinnova. 1694 12. References 1696 12.1. Normative References 1698 [I-D.ietf-ace-cbor-web-token] 1699 Wahlstroem, E., Jones, M., and H. Tschofenig, "CBOR Web 1700 Token (CWT)", draft-ietf-ace-cbor-web-token-00 (work in 1701 progress), May 2016. 1703 [I-D.ietf-cose-msg] 1704 Schaad, J., "CBOR Encoded Message Syntax", draft-ietf- 1705 cose-msg-12 (work in progress), May 2016. 1707 [I-D.selander-ace-object-security] 1708 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1709 "Object Security of CoAP (OSCOAP)", draft-selander-ace- 1710 object-security-04 (work in progress), March 2016. 1712 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1713 Requirement Levels", BCP 14, RFC 2119, 1714 DOI 10.17487/RFC2119, March 1997, 1715 . 1717 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1718 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1719 January 2012, . 1721 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1722 Application Protocol (CoAP)", RFC 7252, 1723 DOI 10.17487/RFC7252, June 2014, 1724 . 1726 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1727 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1728 . 1730 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1731 Possession Key Semantics for JSON Web Tokens (JWTs)", 1732 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1733 . 1735 12.2. Informative References 1737 [I-D.ietf-ace-actors] 1738 Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An 1739 architecture for authorization in constrained 1740 environments", draft-ietf-ace-actors-03 (work in 1741 progress), March 2016. 1743 [I-D.ietf-core-block] 1744 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 1745 draft-ietf-core-block-20 (work in progress), April 2016. 1747 [I-D.ietf-oauth-pop-architecture] 1748 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 1749 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 1750 Architecture", draft-ietf-oauth-pop-architecture-07 (work 1751 in progress), December 2015. 1753 [I-D.seitz-ace-core-authz] 1754 Seitz, L., Selander, G., and M. Vucinic, "Authorization 1755 for Constrained RESTful Environments", draft-seitz-ace- 1756 core-authz-00 (work in progress), June 2015. 1758 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1759 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1760 . 1762 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1763 (TLS) Protocol Version 1.2", RFC 5246, 1764 DOI 10.17487/RFC5246, August 2008, 1765 . 1767 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1768 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1769 . 1771 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1772 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1773 . 1775 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 1776 Threat Model and Security Considerations", RFC 6819, 1777 DOI 10.17487/RFC6819, January 2013, 1778 . 1780 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1781 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1782 October 2013, . 1784 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1785 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1786 2014, . 1788 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1789 Constrained-Node Networks", RFC 7228, 1790 DOI 10.17487/RFC7228, May 2014, 1791 . 1793 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1794 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1795 DOI 10.17487/RFC7231, June 2014, 1796 . 1798 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1799 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1800 . 1802 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 1803 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 1804 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1805 . 1807 [RFC7744] Seitz, L., Ed., Gerdes, S., Ed., Selander, G., Mani, M., 1808 and S. Kumar, "Use Cases for Authentication and 1809 Authorization in Constrained Environments", RFC 7744, 1810 DOI 10.17487/RFC7744, January 2016, 1811 . 1813 Appendix A. Design Justification 1815 This section provides further insight into the design decisions of 1816 the solution documented in this document. Section 3 lists several 1817 building blocks and briefly summarizes their importance. The 1818 justification for offering some of those building blocks, as opposed 1819 to using OAuth 2.0 as is, is given below. 1821 Common IoT constraints are: 1823 Low Power Radio: 1825 Many IoT devices are equipped with a small battery which needs to 1826 last for a long time. For many constrained wireless devices the 1827 highest energy cost is associated to transmitting or receiving 1828 messages. It is therefore important to keep the total 1829 communication overhead low, including minimizing the number and 1830 size of messages sent and received, which has an impact of choice 1831 on the message format and protocol. By using CoAP over UDP, and 1832 CBOR encoded messages some of these aspects are addressed. 1833 Security protocols contribute to the communication overhead and 1834 can in some cases be optimized. For example authentication and 1835 key establishment may in certain cases where security requirements 1836 so allows be replaced by provisioning of security context by a 1837 trusted third party, using transport or application layer 1838 security. 1840 Low CPU Speed: 1842 Some IoT devices are equipped with processors that are 1843 significantly slower than those found in most current devices on 1844 the Internet. This typically has implications on what timely 1845 cryptographic operations a device is capable to perform, which in 1846 turn impacts e.g. protocol latency. Symmetric key cryptography 1847 may be used instead of the computationally more expensive public 1848 key cryptography where the security requirements so allows, but 1849 this may also require support for trusted third party assisted 1850 secret key establishment using transport or application layer 1851 security. 1853 Small Amount of Memory: 1855 Microcontrollers embedded in IoT devices are often equipped with 1856 small amount of RAM and flash memory, which places limitations 1857 what kind of processing can be performed and how much code can be 1858 put on those devices. To reduce code size fewer and smaller 1859 protocol implementations can be put on the firmware of such a 1860 device. In this case, CoAP may be used instead of HTTP, symmetric 1861 key cryptography instead of public key cryptography, and CBOR 1862 instead of JSON. Authentication and key establishment protocol, 1863 e.g. the DTLS handshake, in comparison with assisted key 1864 establishment also has an impact on memory and code. 1866 User Interface Limitations: 1868 Protecting access to resources is both an important security as 1869 well as privacy feature. End users and enterprise customers do 1870 not want to give access to the data collected by their IoT device 1871 or to functions it may offer to third parties. Since the 1872 classical approach of requesting permissions from end users via a 1873 rich user interface does not work in many IoT deployment scenarios 1874 these functions need to be delegated to user controlled devices 1875 that are better suitable for such tasks, such as smart phones and 1876 tablets. 1877 Communication Constraints: 1879 In certain constrained settings an IoT device may not be able to 1880 communicate with a given device at all times. Devices may be 1881 sleeping, or just disconnected from the Internet because of 1882 general lack of connectivity in the area, for cost reasons, or for 1883 security reasons, e.g. to avoid an entry point for Denial-of- 1884 Service attacks. 1886 The communication interactions this framework builds upon (as 1887 shown graphically in Figure 1) may be accomplished using a variety 1888 of different protocols, and not all parts of the message flow are 1889 used in all applications due to the communication constraints. 1890 While we envision deployments to make use of CoAP we explicitly 1891 want to support HTTP, HTTP/2 or specific protocols, such as 1892 Bluetooth Smart communication, which does not necessarily use IP. 1893 The latter raises the need for application layer security over the 1894 various interfaces. 1896 Appendix B. Roles and Responsibilites 1898 Resource Owner 1900 * Make sure that the RS is registered at the AS. 1901 * Make sure that clients can discover the AS which is in charge 1902 of the RS. 1903 * Make sure that the AS has the necessary, up-to-date, access 1904 control policies for the RS. 1906 Requesting Party 1908 * Make sure that the client is provisioned the necessary 1909 credentials to authenticate to the AS. 1910 * Make sure that the client is configured to follow the security 1911 requirements of the Requesting Party, when issuing requests 1912 (e.g. minimum communication security requirements, trust 1913 anchors). 1914 * Register the client at the AS. 1916 Authorization Server 1918 * Register RS and manage corresponding security contexts. 1919 * Register clients and including authentication credentials. 1920 * Allow Resource Owners to configure and update access control 1921 policies related to their registered RS' 1922 * Expose a service that allows clients to request tokens. 1923 * Authenticate clients that wishes to request a token. 1924 * Process a token requests against the authorization policies 1925 configured for the RS. 1926 * Expose a service that allows RS's to submit token introspection 1927 requests. 1928 * Authenticate RS's that wishes to get an introspection response. 1929 * Process token introspection requests. 1930 * Optionally: Handle token revocation. 1932 Client 1934 * Discover the AS in charge of the RS that is to be targeted with 1935 a request. 1936 * Submit the token request (A). 1938 + Authenticate towards the AS. 1939 + Specify which RS, which resource(s), and which action(s) the 1940 request(s) will target. 1941 + Specify preferences for communication security 1942 + If raw public key (rpk) or certificate is used, make sure 1943 the AS has the right rpk or certificate for this client. 1944 * Process the access token and client information (B) 1946 + Check that the token has the right format (e.g. CWT). 1947 + Check that the client information provides the necessary 1948 security parameters (e.g. PoP key, information on 1949 communication security protocols supported by the RS). 1950 * Send the token and request to the RS (C) 1952 + Authenticate towards the RS (this could coincide with the 1953 proof of possession process). 1954 + Transmit the token as specified by the AS (default is to an 1955 authorization information resource, alternative options are 1956 as a CoAP option or in the DTLS handshake). 1957 + Perform the proof-of-possession procedure as specified for 1958 the type of used token (this may already have been taken 1959 care of through the authentication procedure). 1960 * Process the RS response (F) requirements of the Requesting 1961 Party, when issuing requests (e.g. minimum communication 1962 security requirements, trust anchors). 1963 * Register the client at the AS. 1965 Resource Server 1967 * Expose a way to submit access tokens. 1968 * Process an access token. 1970 + Verify the token is from the right AS. 1971 + Verify that the token applies to this RS. 1972 + Check that the token has not expired (if the token provides 1973 expiration information). 1974 + Check the token's integrity. 1975 + Store the token so that it can be retrieved in the context 1976 of a matching request. 1977 * Process a request. 1979 + Set up communication security with the client. 1981 + Authenticate the client. 1982 + Match the client against existing tokens. 1983 + Check that tokens belonging to the client actually authorize 1984 the requested action. 1985 + Optionally: Check that the matching tokens are still valid 1986 (if this is possible. 1987 * Send a response following the agreed upon communication 1988 security. 1990 Appendix C. Deployment Examples 1992 There is a large variety of IoT deployments, as is indicated in 1993 Appendix A, and this section highlights a few common variants. This 1994 section is not normative but illustrates how the framework can be 1995 applied. 1997 For each of the deployment variants there are a number of possible 1998 security setups between clients, resource servers and authorization 1999 servers. The main focus in the following subsections is on how 2000 authorization of a client request for a resource hosted by a RS is 2001 performed. This requires the the security of the requests and 2002 responses between the clients and the RS to consider. 2004 Note: CBOR diagnostic notation is used for examples of requests and 2005 responses. 2007 C.1. Local Token Validation 2009 In this scenario we consider the case where the resource server is 2010 offline, i.e. it is not connected to the AS at the time of the access 2011 request. This access procedure involves steps A, B, C, and F of 2012 Figure 1. 2014 Since the resource server must be able to verify the access token 2015 locally, self-contained access tokens must be used. 2017 This example shows the interactions between a client, the 2018 authorization server and a temperature sensor acting as a resource 2019 server. Message exchanges A and B are shown in Figure 17. 2021 A: The client first generates a public-private key pair used for 2022 communication security with the RS. 2023 The client sends the POST request to /token at the AS. The 2024 request contains the public key of the client and the Audience 2025 parameter set to "tempSensorInLivingRoom", a value that the 2026 temperature sensor identifies itself with. The AS evaluates the 2027 request and authorizes the client to access the resource. 2029 B: The AS responds with a PoP token and client information. The 2030 PoP token contains the public key of the client, and the client 2031 information contains the public key of the RS. For communication 2032 security this example uses DTLS RawPublicKey between the client 2033 and the RS. The issued token will have a short validity time, 2034 i.e. 'exp' close to 'iat', to protect the RS from replay attacks 2035 since it, that cannot do introspection to check the tokens current 2036 validity. The token includes the claim "aif" with the authorized 2037 access that an owner of the temperature device can enjoy. The 2038 'aif' claim, issued by the AS, informs the RS that the owner of 2039 the token, that can prove the possession of a key is authorized to 2040 make a GET request against the /temperature resource and a POST 2041 request on the /firmware resource. 2042 Note: In this example we assume that the client knows what 2043 resource it wants to access, and is therefore able to request 2044 specific audience and scope claims for the access token. 2046 Authorization 2047 Client Server 2048 | | 2049 | | 2050 A: +-------->| Header: POST (Code=0.02) 2051 | POST | Uri-Path:"token" 2052 | | Content-Type: application/cbor 2053 | | Payload: 2054 | | 2055 B: |<--------+ Header: 2.05 Content 2056 | 2.05 | Content-Type: application/cbor 2057 | | Payload: 2058 | | 2060 Figure 17: Token Request and Response Using Client Credentials. 2062 The information contained in the Request-Payload and the Response- 2063 Payload is shown in Figure 18. 2065 Request-Payload : 2066 { 2067 "grant_type" : "client_credentials", 2068 "aud" : "tempSensorInLivingRoom", 2069 "client_id" : "myclient", 2070 "client_secret" : "qwerty" 2071 } 2073 Response-Payload : 2074 { 2075 "access_token" : b64'SlAV32hkKG ...', 2076 "token_type" : "pop", 2077 "csp" : "DTLS", 2078 "cnf" : { 2079 "COSE_Key" : { 2080 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2081 "kty" : "EC", 2082 "crv" : "P-256", 2083 "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', 2084 "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' 2085 } 2086 } 2087 } 2089 Figure 18: Request and Response Payload Details. 2091 The content of the access token is shown in Figure 19. 2093 { 2094 "aud" : "tempSensorInLivingRoom", 2095 "iat" : "1360189224", 2096 "exp" : "1360289224", 2097 "aif" : [["/temperature", 0], ["/firmware", 2]], 2098 "cnf" : { 2099 "jwk" : { 2100 "kid" : b64'1Bg8vub9tLe1gHMzV76e8', 2101 "kty" : "EC", 2102 "crv" : "P-256", 2103 "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', 2104 "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' 2105 } 2106 } 2107 } 2109 Figure 19: Access Token including Public Key of the Client. 2111 Messages C and F are shown in Figure 20 - Figure 21. 2113 C: The client then sends the PoP token to the /authz-info resource 2114 at the RS. This is a plain CoAP request, i.e. no transport or 2115 application layer security between client and RS, since the token 2116 is integrity protected between AS and RS. The RS verifies that 2117 the PoP token was created by a known and trusted AS, is valid, and 2118 responds to the client. The RS caches the security context 2119 together with authorization information about this client 2120 contained in the PoP token. 2122 Resource 2123 Client Server 2124 | | 2125 C: +-------->| Header: POST (Code=0.02) 2126 | POST | Uri-Path:"authz-info" 2127 | | Payload: SlAV32hkKG ... 2128 | | 2129 |<--------+ Header: 2.01 Created 2130 | 2.01 | 2131 | | 2133 Figure 20: Access Token provisioning to RS 2134 The client and the RS runs the DTLS handshake using the raw public 2135 keys established in step B and C. 2136 The client sends the CoAP request GET to /temperature on RS over 2137 DTLS. The RS verifies that the request is authorized, based on 2138 previously established security context. 2139 F: The RS responds with a resource representation over DTLS. 2141 Resource 2142 Client Server 2143 | | 2144 |<=======>| DTLS Connection Establishment 2145 | | using Raw Public Keys 2146 | | 2147 +-------->| Header: GET (Code=0.01) 2148 | GET | Uri-Path: "temperature" 2149 | | 2150 | | 2151 | | 2152 F: |<--------+ Header: 2.05 Content 2153 | 2.05 | Payload: 2154 | | 2156 Figure 21: Resource Request and Response protected by DTLS. 2158 C.2. Introspection Aided Token Validation 2160 In this deployment scenario we assume that a client is not be able to 2161 access the AS at the time of the access request. Since the RS is, 2162 however, connected to the back-end infrastructure it can make use of 2163 token introspection. This access procedure involves steps A-F of 2164 Figure 1, but assumes steps A and B have been carried out during a 2165 phase when the client had connectivity to AS. 2167 Since the client is assumed to be offline, at least for a certain 2168 period of time, a pre-provisioned access token has to be long-lived. 2169 The resource server may use its online connectivity to validate the 2170 access token with the authorization server, which is shown in the 2171 example below. 2173 In the example we show the interactions between an offline client 2174 (key fob), a resource server (online lock), and an authorization 2175 server. We assume that there is a provisioning step where the client 2176 has access to the AS. This corresponds to message exchanges A and B 2177 which are shown in Figure 22. 2179 Authorization consent from the resource owner can be pre-configured, 2180 but it can also be provided via an interactive flow with the resource 2181 owner. An example of this for the key fob case could be that the 2182 resource owner has a connected car, he buys a generic key that he 2183 wants to use with the car. To authorize the key fob he connects it 2184 to his computer that then provides the UI for the device. After that 2185 OAuth 2.0 implicit flow can used to authorize the key for his car at 2186 the the car manufacturers AS. 2188 Note: In this example the client does not know the exact door it will 2189 be used to access since the token request is not send at the time of 2190 access. So the scope and audience parameters is set quite wide to 2191 start with and new values different form the original once can be 2192 returned from introspection later on. 2194 A: The client sends the request using POST to /token at AS. The 2195 request contains the Audience parameter set to "PACS1337" (PACS, 2196 Physical Access System), a value the that the online door in 2197 question identifies itself with. The AS generates an access token 2198 as on opaque string, which it can match to the specific client, a 2199 targeted audience and a symmetric key. 2200 B: The AS responds with the an access token and client 2201 information, the latter containing a symmetric key. Communication 2202 security between C and RS will be DTLS and PreSharedKey. The PoP 2203 key being used as the PreSharedKey. 2205 Authorization 2206 Client Server 2207 | | 2208 | | 2209 A: +-------->| Header: POST (Code=0.02) 2210 | POST | Uri-Path:"token" 2211 | | Content-Type: application/cbor 2212 | | Payload: 2213 | | 2214 B: |<--------+ Header: 2.05 Content 2215 | | Content-Type: application/cbor 2216 | 2.05 | Payload: 2217 | | 2219 Figure 22: Token Request and Response using Client Credentials. 2221 The information contained in the Request-Payload and the Response- 2222 Payload is shown in Figure 23. 2224 Request-Payload: 2225 { 2226 "grant_type" : "client_credentials", 2227 "aud" : "lockOfDoor4711", 2228 "client_id" : "keyfob", 2229 "client_secret" : "qwerty" 2230 } 2232 Response-Payload: 2233 { 2234 "access_token" : b64'SlAV32hkKG ...' 2235 "token_type" : "pop", 2236 "csp" : "DTLS", 2237 "cnf" : { 2238 "COSE_Key" : { 2239 "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', 2240 "kty" : "oct", 2241 "alg" : "HS256", 2242 "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' 2243 } 2244 } 2245 } 2247 Figure 23: Request and Response Payload for C offline 2249 The access token in this case is just an opaque string referencing 2250 the authorization information at the AS. 2252 C: Next, the client POSTs the access token to the /authz-info 2253 resource in the RS. This is a plain CoAP request, i.e. no DTLS 2254 between client and RS. Since the token is an opaque string, the 2255 RS cannot verify it on its own, and thus defers to respond the 2256 client with a status code until after step E. 2257 D: The RS forwards the token to the /introspect resource on the 2258 AS. Introspection assumes a secure connection between the AS and 2259 the RS, e.g. using transport of application layer security, which 2260 is not detailed in this example. 2261 E: The AS provides the introspection response containing 2262 parameters about the token. This includes the confirmation key 2263 (cnf) parameter that allows the RS to verify the client's proof of 2264 possession in step F. 2265 After receiving message E, the RS responds to the client's POST in 2266 step C with Code 2.01 Created. 2268 Resource 2269 Client Server 2270 | | 2271 C: +-------->| Header: POST (T=CON, Code=0.02) 2272 | POST | Uri-Path:"authz-info" 2273 | | Content-Type: "application/cbor" 2274 | | Payload: b64'SlAV32hkKG ...'' 2275 | | 2276 | | Authorization 2277 | | Server 2278 | | | 2279 D: | +--------->| Header: POST (Code=0.02) 2280 | | POST | Uri-Path: "introspect" 2281 | | | Content-Type: "application/cbor" 2282 | | | Payload: 2283 | | | 2284 E: | |<---------+ Header: 2.05 Content 2285 | | 2.05 | Content-Type: "application/cbor" 2286 | | | Payload: 2287 | | | 2288 | | 2289 C: |<--------+ Header: 2.01 Created 2290 | 2.01 | 2291 | | 2293 Figure 24: Token Introspection for C offline 2294 The information contained in the Request-Payload and the Response- 2295 Payload is shown in Figure 25. 2297 Request-Payload: 2298 { 2299 "token" : b64'SlAV32hkKG...', 2300 "client_id" : "FrontDoor", 2301 "client_secret" : "ytrewq" 2302 } 2304 Response-Payload: 2305 { 2306 "active" : true, 2307 "aud" : "lockOfDoor4711", 2308 "scope" : "open, close", 2309 "iat" : 1311280970, 2310 "cnf" : { 2311 "kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' 2312 } 2313 } 2315 Figure 25: Request and Response Payload for Introspection 2317 The client uses the symmetric PoP key to establish a DTLS 2318 PreSharedKey secure connection to the RS. The CoAP request PUT is 2319 sent to the uri-path /state on RS changing state of the door to 2320 locked. 2321 F: The RS responds with a appropriate over the secure DTLS 2322 channel. 2324 Resource 2325 Client Server 2326 | | 2327 |<=======>| DTLS Connection Establishment 2328 | | using Pre Shared Key 2329 | | 2330 +-------->| Header: PUT (Code=0.03) 2331 | PUT | Uri-Path: "state" 2332 | | Payload: 2333 | | 2334 F: |<--------+ Header: 2.04 Changed 2335 | 2.04 | Payload: 2336 | | 2338 Figure 26: Resource request and response protected by OSCOAP 2340 Appendix D. Document Updates 2341 D.1. Version -01 to -02 2343 o Restructured to remove communication security parts. These shall 2344 now be defined in profiles. 2345 o Restructured section 5 to create new sections on the OAuth 2346 endpoints /token, /introspect and /authz-info. 2347 o Pulled in material from draft-ietf-oauth-pop-key-distribution in 2348 order to define proof-of-possession key distribution. 2349 o Introduced the 'cnf' parameter as defined in RFC7800 to reference 2350 or transport keys used for proof of posession. 2351 o Introduced the 'client-token' to transport client information from 2352 the AS to the client via the RS in conjunction with introspection. 2353 o Expanded the IANA section to define parameters for token request, 2354 introspection and CWT claims. 2355 o Moved deployment scenarios to the appendix as examples. 2357 D.2. Version -00 to -01 2359 o Changed 5.1. from "Communication Security Protocol" to "Client 2360 Information". 2361 o Major rewrite of 5.1 to clarify the information exchanged between 2362 C and AS in the PoP token request profile for IoT. 2364 * Allow the client to indicate preferences for the communication 2365 security protocol. 2366 * Defined the term "Client Information" for the additional 2367 information returned to the client in addition to the access 2368 token. 2369 * Require that the messages between AS and client are secured, 2370 either with (D)TLS or with COSE_Encrypted wrappers. 2371 * Removed dependency on OSCoAP and added generic text about 2372 object security instead. 2373 * Defined the "rpk" parameter in the client information to 2374 transmit the raw public key of the RS from AS to client. 2375 * (D)TLS MUST use the PoP key in the handshake (either as PSK or 2376 as client RPK with client authentication). 2377 * Defined the use of x5c, x5t and x5tS256 parameters when a 2378 client certificate is used for proof of possession. 2379 * Defined "tktn" parameter for signaling for how to transfer the 2380 access token. 2381 o Added 5.2. the CoAP Access-Token option for transferring access 2382 tokens in messages that do not have payload. 2383 o 5.3.2. Defined success and error responses from the RS when 2384 receiving an access token. 2385 o 5.6.:Added section giving guidance on how to handle token 2386 expiration in the absence of reliable time. 2387 o Appendix B Added list of roles and responsibilities for C, AS and 2388 RS. 2390 Authors' Addresses 2392 Ludwig Seitz 2393 SICS 2394 Scheelevaegen 17 2395 Lund 223 70 2396 SWEDEN 2398 Email: ludwig@sics.se 2400 Goeran Selander 2401 Ericsson 2402 Faroegatan 6 2403 Kista 164 80 2404 SWEDEN 2406 Email: goran.selander@ericsson.com 2408 Erik Wahlstroem 2409 Nexus Technology 2410 Telefonvagen 26 2411 Hagersten 126 26 2412 Sweden 2414 Email: erik.wahlstrom@nexusgroup.com 2416 Samuel Erdtman 2417 Spotify AB 2418 Birger Jarlsgatan 61, 4tr 2419 Stockholm 113 56 2420 Sweden 2422 Email: erdtman@spotify.com 2424 Hannes Tschofenig 2425 ARM Ltd. 2426 Hall in Tirol 6060 2427 Austria 2429 Email: Hannes.Tschofenig@arm.com