idnits 2.17.1 draft-tschofenig-ace-oauth-bt-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 date (July 4, 2014) is 3584 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 6347 (ref. '1') (Obsoleted by RFC 9147) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group H. Tschofenig 3 Internet-Draft ARM Limited 4 Intended status: Informational July 4, 2014 5 Expires: January 5, 2015 7 The OAuth 2.0 Bearer Token Usage over the Constrained Application 8 Protocol (CoAP) 9 draft-tschofenig-ace-oauth-bt-00.txt 11 Abstract 13 This specification describes how to use OAuth 2.0 bearer tokens to 14 access protected resources using the Constrained Application Protocol 15 (CoAP). Any party in possession of a bearer token (a "bearer") can 16 use it to get access to the associated resources (without 17 demonstrating possession of a cryptographic key). To prevent misuse, 18 bearer tokens need to be protected from disclosure in storage and in 19 transport. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 5, 2015. 38 Copyright Notice 40 Copyright (c) 2014 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 57 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 4. Requests . . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 5. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 61 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 62 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 63 9. Normative References . . . . . . . . . . . . . . . . . . . . 7 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 66 1. Introduction 68 OAuth enables clients to access protected resources by obtaining an 69 access token, which is defined in "The OAuth 2.0 Authorization 70 Framework" [4] as "a string representing an access authorization 71 issued to the client", rather than using the resource owner's 72 credentials directly. 74 Tokens are issued to clients by an authorization server and the 75 client uses the access token to access the protected resources hosted 76 by the resource server. This specification describes how to make 77 protected resource requests when the access token is a bearer token 78 and conveyed from the client to the resource server using the 79 Constrained Application Protocol (CoAP) [3]. To secure the 80 communication exchange the Datagram Transport Layer Security Version 81 1.2 [1] is mandatory to use. 83 2. Terminology 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 87 document are to be interpreted as described in "Key words for use in 88 RFCs to Indicate Requirement Levels" [5]. 90 This document also re-uses terminology from RFC 6749 [4] and RFC 6750 91 [2]. 93 3. Introduction 95 The abstract OAuth 2.0 flow illustrated in Figure 1 describes the 96 interaction between the client, resource owner, authorization server, 97 and resource server (described in [[4]). The following two steps are 98 specified within this document: 100 (E) The client requests the protected resource from the resource 101 server and authenticates by presenting the access token. 103 (F) The resource server validates the access token, and if valid, 104 serves the request. 106 This document also imposes semantic requirements upon the access 107 token returned in step (D). 109 +--------+ +---------------+ 110 | |--(A)- Authorization Request ->| Resource | 111 | | | Owner | 112 | |<-(B)-- Authorization Grant ---| | 113 | | +---------------+ 114 | | 115 | | +---------------+ 116 | |--(C)-- Authorization Grant -->| Authorization | 117 | Client | | Server | 118 | |<-(D)----- Access Token -------| | 119 | | +---------------+ 120 | | 121 | | +---------------+ 122 | |--(E)----- Access Token ------>| Resource | 123 | | | Server | 124 | |<-(F)--- Protected Resource ---| | 125 +--------+ +---------------+ 127 Figure 1: Abstract OAuth 2.0 Protocol Flow. 129 4. Requests 131 Access tokens are embedded in a CoAP message by the use of the 132 "Bearer" option. The definition is shown in Figure 2. 134 +-----+----+---+---+---+----------------+--------+--------+---------+ 135 | No. | C | U | N | R | Name | Format | Length | Default | 136 +-----+----+---+---+---+----------------+--------+--------+---------+ 137 | TBD | x | | | | Bearer | opaque | var | (none) | 138 +-----+----+---+---+---+----------------+--------+--------+---------+ 140 Legend: 141 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 143 Figure 2: Bearer Option Definition. 145 Figure 3 shows an example request from the client to the resource 146 server. 148 Header: GET (T=CON, Code=0.01, MID=0x7d34, 149 Uri-Path:"resource", Bearer: "mF_9.B5f-4.1JqM") 151 Figure 3: Example CoAP Request with Bearer Token. 153 5. Responses 155 If the request does not contain an access token that enables access 156 to the protected resource, the resource server MUST respond with a 157 4.01 "Unauthorized" error message. 159 QUESTION: Should the response also provide information about the 160 scheme (e.g., 'Bearer Tokens' vs. 'Proof-of-Possession Tokens')? 161 Should it contain a "realm" attribute as well? Should a scope value 162 be returned to provide some guidance about the available scopes at 163 that resource server? 165 For example, in response to a protected resource request without a 166 needed bearer token the error response shown in Figure 4 is sent. 168 Header: ACK (T=ACK, Code=4.01, MID=0x7d34) 170 Figure 4: Failed Request due to Missing Access Token. 172 To provide information back to the client about the failure of the 173 request the following error codes are defined. These error codes are 174 conveyed within the 'Error' option, which is defined in Figure 5. 176 +-----+----+---+---+---+----------------+--------+--------+---------+ 177 | No. | C | U | N | R | Name | Format | Length | Default | 178 +-----+----+---+---+---+----------------+--------+--------+---------+ 179 | TBD | | | | | Error | uint | 0-2 | (none) | 180 +-----+----+---+---+---+----------------+--------+--------+---------+ 182 Legend: 183 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 185 Figure 5: Error Option Definition. 187 This specification defines the following error codes that are used 188 with the 'Error' option: 190 invalid_request (0) 192 The request is missing a required parameter, includes an 193 unsupported parameter or parameter value, repeats the same 194 parameter, uses more than one method for including an access 195 token, or is otherwise malformed. The resource server MUST 196 respond with the 4.00 (Bad Request) status code. 198 invalid_token (1) 200 The access token provided is expired, revoked, malformed, or 201 invalid for other reasons. The resource MUST respond with the 202 4.01 (Unauthorized) status code. The client MAY request a new 203 access token and retry the protected resource request. 205 insufficient_scope (2) 207 The request requires higher privileges than provided by the access 208 token. The resource server MUST respond with the 4.03 (Forbidden) 209 status code. 211 QUESTION: Is the granularity of the error messages useful enough for 212 client implementations to take actions? 214 As an example, in response to a request using an expired access token 215 the following error is returned. 217 Header: ACK (T=ACK, Code=4.01, MID=0x7d34, 218 Error="1") 220 Figure 6: Failed Request due Expired Access Token. 222 6. Security Considerations 224 The security threats of this specification are identical to those 225 discussed in RFC 6750 since the encoding of the request does not 226 change the security threats. 228 It is nevertheless worthwhile to replicate the security 229 recommendation here for readers who do not want to consult another 230 document. 232 Safeguard bearer tokens: Client implementations MUST ensure that 233 bearer tokens are not leaked to unintended parties, as they will 234 be able to use them to gain access to protected resources. This 235 is the primary security consideration when using bearer tokens and 236 underlies all the more specific recommendations that follow. 238 Validate TLS certificate chains: The client MUST validate the 239 certificate chain, if the resource server is authenticated using a 240 certificate-based ciphersuite in DTLS, when making requests to 241 protected resources. Failing to do so may enable man-in-the- 242 middle attacks. 244 Always use DTLS (coaps): Clients MUST always use DTLS [1] when 245 making requests with bearer tokens. Failing to do so exposes the 246 token to third parties and could consequently give attackers 247 unintended access. 249 Issue short-lived bearer tokens: Authorization servers SHOULD issue 250 short-lived bearer tokens. Using short-lived bearer tokens 251 reduces the impact of them being leaked. 253 Issue scoped bearer tokens: Authorization servers MUST issue bearer 254 tokens that contain an audience restriction, scoping their use to 255 the intended relying party or set of relying parties. 257 7. IANA Considerations 259 This specification requests IANA to allocate two values, as shown 260 below, in the 0..255 range of the CoAP option number registry 261 established with RFC 7252. 263 +--------+-----------+------------+ 264 | Number | Name | Reference | 265 +--------+-----------+------------+ 266 | TBD-61 | Bearer | [this RFC] | 267 | TBD-62 | Error | [this RFC] | 268 +--------+-----------+------------+ 270 TBD: Add a registry for error codes. 272 8. Acknowledgements 274 The author would like to thank Mike Jones and Dick Hardt for their 275 work on RFC 6750. This document is heavily inspired by their work. 277 9. Normative References 279 [1] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 280 Security Version 1.2", RFC 6347, January 2012. 282 [2] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 283 Framework: Bearer Token Usage", RFC 6750, October 2012. 285 [3] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 286 Application Protocol (CoAP)", RFC 7252, June 2014. 288 [4] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 289 6749, October 2012. 291 [5] Bradner, S., "Key words for use in RFCs to Indicate 292 Requirement Levels", BCP 14, RFC 2119, March 1997. 294 Author's Address 296 Hannes Tschofenig 297 ARM Limited 298 Austria 300 Email: Hannes.Tschofenig@gmx.net 301 URI: http://www.tschofenig.priv.at