idnits 2.17.1 draft-tschofenig-ace-oauth-iot-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 4, 2014) is 3584 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-17) exists of draft-ietf-dice-profile-01 ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-09) exists of draft-bormann-core-ace-aif-00 == Outdated reference: A later version (-23) exists of draft-ietf-kitten-sasl-oauth-14 == Outdated reference: A later version (-32) exists of draft-ietf-oauth-json-web-token-24 == Outdated reference: A later version (-06) exists of draft-richer-oauth-introspection-04 == Outdated reference: A later version (-02) exists of draft-seitz-ace-usecases-00 Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE H. Tschofenig 3 Internet-Draft ARM Limited 4 Intended status: Informational July 4, 2014 5 Expires: January 5, 2015 7 The OAuth 2.0 Internet of Things (IoT) Client Credentials Grant 8 draft-tschofenig-ace-oauth-iot-00.txt 10 Abstract 12 As Internet of Things (IoT) deployments increase steadily the need 13 for a better user experience for handling the authentication and 14 authorization tasks in constrained environments increases. 16 While several technologies have been developed already that allow 17 federated access to protected resource the nature of IoT deployments 18 requires care with the limited resources available on many of these 19 devices. 21 This document defines a new OAuth 2.0 authorization grant for the 22 interaction between constrained clients and resource servers to 23 obtain access tokens for access to protected resources. It does so 24 by leveraging prior work on OAuth 2.0, CoAP, and DTLS. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 5, 2015. 43 Copyright Notice 45 Copyright (c) 2014 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3. Applicability Statement . . . . . . . . . . . . . . . . . . . 5 63 4. IoT Client Credentials Grant . . . . . . . . . . . . . . . . 5 64 4.1. Authorization Request and Response . . . . . . . . . . . 6 65 4.2. Access Token Request . . . . . . . . . . . . . . . . . . 6 66 4.3. Access Token Response . . . . . . . . . . . . . . . . . . 6 67 5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 69 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 70 7.1. Sub-Namespace Registration of urn:ietf:params:oauth 71 :grant-type:iot . . . . . . . . . . . . . . . . . . . . . 8 72 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 8.1. Normative References . . . . . . . . . . . . . . . . . . 8 74 8.2. Informative References . . . . . . . . . . . . . . . . . 9 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 77 1. Introduction 79 Early Internet of Things deployments used Internet connectivity to 80 push data to a cloud service or to an application on a smart phone. 81 While these IoT deployments offer great benefits for their users they 82 also suffer from a usability problem that can best be demonstrated 83 with a door lock example. 85 Consider an enterprise environment where access to different parts of 86 the campus is granted to employees dynamically and on a need-by-need 87 basis. New employees receive access rights and those who decide to 88 leave the company get their access rights revoked. 90 When an employee approaches a door the door lock is supposed to check 91 the authorization rights of that employee in a fraction of a second 92 and to grant (or deny) access appropriately. The building managers 93 expect a centralized management of employees and their access rights 94 and no prior interaction of employees with any object, such as a 95 door, upfront (such as it would be needed with pairing mechanisms 96 utilized by some IoT technologies). 98 To accomplish such a seamless user experience and offering security 99 at the same time it is necessary to make use of an authentication and 100 authorization server that manages policies for access to protected 101 resources (such as door locks in the previous example). As outlined 102 in [I-D.seitz-ace-usecases], it is assumed that resource servers do 103 not necessarily need to contact the authorization server every time 104 they receive an access request. 106 OAuth 2.0 [RFC6749] is a technology that offers such a design pattern 107 via the use of access tokens, which are requested by clients, and 108 subsequently presented to resource servers when demanding access to 109 protected resources managed by those resource servers. 111 OAuth 2.0 was, however, design primarily for use with the HTTP-based 112 web infrastructure and has only recently been extended for use with 113 SASL [I-D.ietf-kitten-sasl-oauth]. This document extends the OAuth 114 2.0 idea one step further and defines a Constrained Application 115 Protocol (CoAP)- based transport profile for OAuth 2.0. CoAP is 116 specified in RFC 7252 [RFC7252]. 118 The benefits are as follows: 120 o The use of the Constrained Application Protocol (CoAP) [RFC6749] 121 (instead of HTTP) for encoding of requests and responses leads to 122 smaller and fewer message exchanges since CoAP uses a binary 123 format and relies on UDP rather than TCP. 125 o The of Datagram Transport Layer Security (DTLS) [RFC6347] (instead 126 of Transport Layer Security (TLS) for authentication) of the 127 authorization server to the client and for establishment of an 128 integrity protected and confidential communication channel follows 129 the spirit of TLS but is tailored to the unreliable transport 130 protocol used by CoAP. 132 o The use of DTLS allows to re-use well-analyzed security 133 functionality and does not require re-designing the same features 134 at the application layer. Note that the use of DTLS also allows 135 different credential-types to be re-used, as explained in 136 [I-D.ietf-dice-profile]. 138 o The use of DTLS client-side authentication instead of the 139 previously defined application layer client authentication 140 mechanisms (as, for example defined in Section 2.3 of RFC 6749) 141 offers security properties that have not been exploited in the TLS 142 usage in the Web. 144 o Allows to re-use the standardized access token format, namely JSON 145 Web Token (JWT) [I-D.ietf-oauth-json-web-token], as well as proof- 146 of-possession tokens [I-D.hunt-oauth-pop-architecture]. 148 Intentionally left outside the scope of this document are the 149 following items: 151 o Registration of the client with the authorization server. This 152 includes the provisioning of security credentials at the client 153 for subsequent use in case of client authentication. 155 o The interaction between the client and the resource server when 156 presenting the access token since a variety of different 157 deployment models may be envisioned. In some deployment scenarios 158 the use of bearer tokens may be appropriate whereas in others 159 proof-of-possession techniques may provide the desired level of 160 security. Also the desire to use application layer security (in 161 comparison to re-using DTLS) leads to different security designs. 163 o The interaction between the resource server and the authorization 164 server for provisioning of access control policies as well as the 165 ability to ask the authorization in real-time for access control 166 decisions (using the token introspection endpoint 167 [I-D.richer-oauth-introspection]). This is an optional part of 168 the OAuth 2.0 architecture that may be used in deployments where a 169 tied coupling between the authorization server and the resource 170 servers exists and the real-time interaction is desired. 172 o Cross realm use where authorization servers from different 173 administrative domains are involved. The use of this protocol 174 needs to be beneficial in a single domain concept to subsequently 175 see demand in a cross realm situation. Experience from other 176 federated authentication and authorization protocols shows that 177 adding the cross realm support is technically but complex from a 178 business point of view. 180 o The authorization server may place authorization information 181 inside the access token so that the resource server can enforce 182 these access control decisions autonomously. This information may 183 come in various flavors, such as basic JWT claims (such 184 'audience', 'expiration time', 'not before') or more sophisticated 185 access control information like [I-D.bormann-core-ace-aif]. These 186 policy languages are largely independent of the OAuth 2.0 187 framework. 189 2. Terminology 191 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 192 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 193 specification are to be interpreted as described in [RFC2119]. 195 All terms are as defined in The OAuth 2.0 Authorization Framework 196 [RFC6749]. 198 3. Applicability Statement 200 The OAuth 2.0 IoT grant defined in this document is only applicable 201 for OAuth 2.0 clients that are resource constrained. For all other 202 clients regular OAuth 2.0 can be re-used since those clients will be 203 able to execute the RFC 6749-defined client credential grant, which 204 uses HTTPS as a transport. 206 The communication between the client and a resource constrained 207 resource server is not described in this document and orthogonal to 208 this document. 210 4. IoT Client Credentials Grant 212 This IoT credential grant is a variation of the client credential 213 grant defined in RFC 6749. 215 The client can request an access token using only its client 216 credentials when the client is requesting access to the protected 217 resources under its control, or those of another resource owner that 218 have been previously arranged with the authorization server (the 219 method of which is beyond the scope of this specification). 221 The IoT client credentials grant type MUST only be used by 222 confidential clients. 224 +---------+ +---------------+ 225 | | | | 226 | |>--(A)- Access Token Request --->| Authorization | 227 | Client | (protected by DTLS) | Server | 228 | |<--(B)- Access Token Response ---<| | 229 | | (protected by DTLS) | | 230 +---------+ +---------------+ 232 Figure 1: IoT Client Credentials Flow. 234 The exchange illustrated in Figure 1 includes the following steps: 236 (A) The client authenticates with the authorization server and 237 requests an access token from the token endpoint. Mutual 238 authentication between the client and then authorization server 239 authentication takes place as part of the DTLS exchange. 241 (B) The authorization server authenticates the client, and if the 242 request is valid and authorized, issues an access token. 244 4.1. Authorization Request and Response 246 Since the client authentication is used as the authorization grant, 247 no additional authorization request is needed. 249 4.2. Access Token Request 251 The client makes a request to the token endpoint by adding the 252 following parameters using the "application/x-www-form-urlencoded" 253 format with a character encoding of UTF-8 in the CoAP request entity- 254 body: 256 grant_type: OPTIONAL. Value MUST be set to 257 "urn:ietf:params:oauth:grant-type:iot" for this grant type. The 258 value is optional since the client may have been pre-provisioned 259 by the authorization server with information about the grant type. 261 scope: OPTIONAL. The scope of the access request as described by 262 Section 3.3 of RFC 6749. 264 audience: OPTIONAL. Value is used by the client to indicate what 265 resource server, as the intended recipient, it wants to access. 266 This field is defined in [I-D.tschofenig-oauth-audience] 268 (QUESTION: Would it be useful to also use a JSON encoding here?) 270 In order to prevent man-in-the-middle attacks, the client MUST 271 require the use of DTLS with server authentication for any request 272 sent to the authorization and token endpoints. If certificate-based 273 server authentication is used then the client MUST validate the TLS 274 certificate of the authorization server, as defined by [RFC6125]. 276 4.3. Access Token Response 278 If the access token request is valid and authorized, the 279 authorization server issues an access token as described in 280 Section 5.1 of RFC 6749 but encoded in a CoAP message using the 281 Content response code with the response encoded as a JSON structure 282 in the payload of the message. A refresh token MUST NOT be included. 283 If the request failed client authentication or is invalid, the 284 authorization server returns an error response using the CoAP 4.00 285 'Bad Request' response code with the error messages defined in 286 Section 5.2 of RFC 6749. 288 Note that the HTTP "Cache-Control" parameters are not used in the 289 CoAP response message. 291 QUESTION: Would it be useful to use the CBOR encoding for the 292 response? This could reduce the response size by a few %. 294 5. Example 296 For example, the client makes a CoAP carrying the Access Token 297 Request protected with DTLS to the authorization server. It then 298 receives a successful Access Token Response containing the access 299 token. 301 In the example below content-type 51 corresponds to the 'application/ 302 x-www-form-urlencoded'. 304 Authorization 305 Client Server 306 | | 307 |<=======>| DTLS Connection Establishment 308 | | 309 +-------->| Header: POST (T=CON, Code=0.02, MID=0x7d34, 310 | POST | ct=51, Uri-Path:"token" 311 | | Payload: grant_type=client_credentials 312 | | 313 |<--------+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34, 314 | 2.05 | ct=50) 315 | | Payload: 316 | | 318 := 319 { 320 "access_token":"2YotnFZFE...jr1zCsicMWpAA", 321 "token_type":"bearer", 322 "expires_in":28800 323 } 325 Figure 2: Example CoAP POST Message Exchange. 327 6. Security Considerations 329 This document re-uses a sub-set of the OAuth 2.0 functionality 330 specified in RFC 6749 and intentionally inherits the security 331 properties of OAuth 2.0, and DTLS. The discussion in Section 10 of 332 RFC 6749 and Section 4 of RFC 6819 are relevant for this document. 334 7. IANA Considerations 336 7.1. Sub-Namespace Registration of urn:ietf:params:oauth:grant-type:iot 338 This specification registers the value "grant-type:iot" in the IANA 339 urn:ietf:params:oauth registry established in An IETF URN Sub- 340 Namespace for OAuth [RFC6755]. 342 o URN: urn:ietf:params:oauth:grant-type:iot 344 o Common Name: Internet of Things (IoT) Client Credentails Grant 345 Type Profile for OAuth 2.0 347 o Change controller: IETF 349 o Specification Document: [[this document]] 351 8. References 353 8.1. Normative References 355 [I-D.ietf-dice-profile] 356 Hartke, K. and H. Tschofenig, "A DTLS 1.2 Profile for the 357 Internet of Things", draft-ietf-dice-profile-01 (work in 358 progress), May 2014. 360 [I-D.tschofenig-oauth-audience] 361 Tschofenig, H., "OAuth 2.0: Audience Information", draft- 362 tschofenig-oauth-audience-00 (work in progress), February 363 2013. 365 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 366 Requirement Levels", BCP 14, RFC 2119, March 1997. 368 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 369 Verification of Domain-Based Application Service Identity 370 within Internet Public Key Infrastructure Using X.509 371 (PKIX) Certificates in the Context of Transport Layer 372 Security (TLS)", RFC 6125, March 2011. 374 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 375 Security Version 1.2", RFC 6347, January 2012. 377 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 378 6749, October 2012. 380 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 381 for OAuth", RFC 6755, October 2012. 383 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 384 Application Protocol (CoAP)", RFC 7252, June 2014. 386 8.2. Informative References 388 [I-D.bormann-core-ace-aif] 389 Bormann, C., "An Authorization Information Format (AIF) 390 for ACE", draft-bormann-core-ace-aif-00 (work in 391 progress), January 2014. 393 [I-D.hunt-oauth-pop-architecture] 394 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 395 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 396 Architecture", draft-hunt-oauth-pop-architecture-02 (work 397 in progress), June 2014. 399 [I-D.ietf-kitten-sasl-oauth] 400 Mills, W., Showalter, T., and H. Tschofenig, "A set of 401 SASL Mechanisms for OAuth", draft-ietf-kitten-sasl- 402 oauth-14 (work in progress), March 2014. 404 [I-D.ietf-oauth-json-web-token] 405 Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 406 (JWT)", draft-ietf-oauth-json-web-token-24 (work in 407 progress), July 2014. 409 [I-D.richer-oauth-introspection] 410 Richer, J., "OAuth Token Introspection", draft-richer- 411 oauth-introspection-04 (work in progress), May 2013. 413 [I-D.seitz-ace-usecases] 414 Seitz, L., Gerdes, S., and G. Selander, "ACE use cases", 415 draft-seitz-ace-usecases-00 (work in progress), February 416 2014. 418 Author's Address 420 Hannes Tschofenig 421 ARM Limited 422 Austria 424 Email: Hannes.Tschofenig@gmx.net 425 URI: http://www.tschofenig.priv.at