idnits 2.17.1 draft-sakimura-oauth-meta-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 (December 12, 2012) is 4150 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) == Unused Reference: 'RFC6750' is defined on line 352, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group N. Sakimura, Ed. 3 Internet-Draft Nomura Research Institute 4 Intended status: Standards Track December 12, 2012 5 Expires: June 15, 2013 7 JSON Metadata for OAuth Responses 8 draft-sakimura-oauth-meta-00 10 Abstract 12 This specification defines an extensible metadata member that may be 13 inserted into the OAuth 2.0 responses to assist the clients to 14 process those responses. It is expressed as a member called "_links" 15 that is inserted as the top level member in the responses. It will 16 allow the client to learn where the members in the response could be 17 used and how, etc. Since it is just a member, any client that does 18 not understand this extension should not break and work normally 19 while supporting clients can utilize the metadata to its advantage. 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 June 15, 2013. 38 Copyright Notice 40 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. JSON Meta Object . . . . . . . . . . . . . . . . . . . . . . . 3 58 3.1. _links Member . . . . . . . . . . . . . . . . . . . . . . . 4 59 3.1.1. href . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.1.2. method . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3.1.3. params . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.1.4. content-type . . . . . . . . . . . . . . . . . . . . . 5 63 3.1.5. Authorize . . . . . . . . . . . . . . . . . . . . . . . 5 64 4. Application to the OAuth 2.0 Token Endpoint References . . . . 5 65 4.1. Successful Responses . . . . . . . . . . . . . . . . . . . 5 66 4.1.1. self . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 4.1.2. describedby . . . . . . . . . . . . . . . . . . . . . . 6 68 4.1.3. Protected Resources . . . . . . . . . . . . . . . . . . 6 69 4.2. Error Responses . . . . . . . . . . . . . . . . . . . . . . 7 70 4.2.1. self . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 4.2.2. describedby . . . . . . . . . . . . . . . . . . . . . . 7 72 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 73 5.1. Link Type Registration . . . . . . . . . . . . . . . . . . 7 74 5.1.1. OAuth 2 Registrations . . . . . . . . . . . . . . . . . 7 75 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 76 6.1. href tampering . . . . . . . . . . . . . . . . . . . . . . 8 77 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 8 78 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 79 8.1. Normative References . . . . . . . . . . . . . . . . . . . 8 80 8.2. Informational References . . . . . . . . . . . . . . . . . 9 81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 83 1. Introduction 85 Although OAuth 2.0 [RFC6749] has been known for its REST 86 friendliness, OAuth itself is not RESTful, as it heavily relies on 87 out-of-band information to drive the interactions. This situation 88 can be eased by hypertext-enabling the JSON responses through the 89 introduction of a member that represents such hypertext and other 90 metadata. To achieve this, this specification introduces a top level 91 member ""_links"" that represents various link relationships and 92 other metadata. 94 2. Requirements 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 98 document are to be interpreted as described in RFC 2119 [RFC2119]. 100 3. JSON Meta Object 102 A JSON Meta Object uses the format described in [RFC4627] and is 103 intended to be inserted into a JSON document to express some of the 104 metadata associated with it as "_links" member. 106 The value of the "_links" member is a JSON object that expresses link 107 relationships ("rel"), which in turn holds an object with "href" and 108 other members or an array of such objects. 110 Following non-normative schematic example should help envisage what 111 it would look like the following. (Note: line-wraps are for display 112 purpose only.) 113 { 114 "_links":{ 115 "self":{"href":"https://example.com/token?code=123"}, 116 "http://openid.net/specs/connect/1.0/#userinfo_ep":[ 117 { 118 "href":"https://example.com/user/{user_id}", 119 "method":"GET", 120 "Authorize":"{token_type} {access_token}" 121 }, 122 { 123 "href":"https://example.com/user/{user_id}", 124 "method":"POST", 125 "Authorize":"{token_type} {access_token}", 126 "params":[ 127 "name","birthday" 128 ] 129 } 130 }, 131 "token_type":"Bearer", 132 "access_token":"aCeSsToKen" 133 } 135 Here, we have "_links" member that expresses various "relations" such 136 as "self" and "http://openid.net/specs/connect/1.0/#userinfo_ep". 137 Each relationships has either a link relations object or an array of 138 link relations objects as its value. The link relations objects 139 holds various members such as "href". They are explained in the next 140 section. 142 3.1. _links Member 144 "_links" member holds exactly one object that contains the following 145 members with relation as the "string" defined in [RFC4627]. The 146 "string" SHOULD be a link relation type that is either defined in the 147 IANA registry defined in Web Linking [RFC5988] or a URI that 148 describes the relation. 150 Each relation member holds exactly one object or one array, whose 151 items are objects. Each object has following members, which are all 152 optional. 154 3.1.1. href 156 The value of the "href" member is a URI Template [RFC6570] that the 157 relation points to. The values for template parameters SHOULD be 158 taken from the value of the top-level members in the including JSON 159 object whose "string" matches the template variable name. 161 3.1.2. method 163 The value of the "method" member is the HTTP method defined in 164 Hypertext Transfer Protocol -- HTTP/1.1 [RFC2616][RFC2616] that can 165 be used to the URL described in the "href". e.g., GET, POST, PUT, 166 DELETE. 168 3.1.3. params 170 The "params" member describes the parameters to be sent to the URL 171 expressed in "href". The "value" is an array of "pairs" whose string 172 corresponds to the parameter names of the parameters that are to be 173 sent to the URL. The "value" of the "pair" is an "object" with 174 following "members" . All "members" are optional. 176 required Boolean. true of false. Indicates whether this parameter 177 is required to be sent with the request. 179 description Human readable description of the variable. 181 3.1.4. content-type 183 The content-type to be used when the parameters are sent to the URL. 185 e.g., "application/x-www-form-urlencoded", "multipart/form-data", 186 "application/json". 188 3.1.5. Authorize 190 The HTTP Authorize header defined in Hypertext Transfer Protocol -- 191 HTTP/1.1 [RFC2616] to be used when accessing the resource identified 192 by href. It is templated in exactly the same syntax as in URI 193 Template [RFC6570] except that it is applied to the Authorization 194 request header than the URI. 196 4. Application to the OAuth 2.0 Token Endpoint References 198 To create the Section 3 should be used in the token endpoint 199 responses of the OAuth 2.0 Authorization Framework [RFC6749], 200 following relations SHOULD be included. 202 4.1. Successful Responses 204 In the case of the Successful Response described in section 5.1. of 205 [RFC6749], the following member SHOULD be present in the value of the 206 Section 3.1. 208 4.1.1. self 210 An object with the following members. 212 href REQUIRED. The URI that resulted in this response. 214 4.1.2. describedby 216 An object with the following members. 218 href REQUIRED. The value is one of the following URIs: 219 "http://tools.ietf.org/html/rfc6749#section-4.1.4", 220 "http://tools.ietf.org/html/rfc6749#section-4.3.3", 221 "http://tools.ietf.org/html/rfc6749#section-4.4.3". 223 4.1.3. Protected Resources 225 Each protected resources MUST provide a unique Relation Name by 226 either registering to the Link Relation Type Registry defined in 227 section 6.2 of [RFC5988] or providing an absolute URI that provides a 228 collision registant name. The value is an array of objects that has 229 the following members. 231 href REQUIRED. The URI template that describes the request to the 232 resource as described in section 3.1.1. (Section 3.1.1). 234 method OPTIONAL. HTTP request method to be used as described in 235 section 3.1.2. (Section 3.1.2). Defaults to "GET". Semantics of 236 the HTTP methods in this case SHOULD map as follows: "GET" means 237 reading the resource. "POST" means creating or updating the 238 resource with supplied parameters in "params" member below. 239 "DELETE" means deleting the corresponding resource. "PUT" means 240 the complete replacement of the resource by the body of the 241 request. The resource MUST support "GET" method. The support of 242 other methods are OPTIONAL. 244 params OPTIONAL. Parameters to be sent as described in section 245 3.1.3. (Section 3.1.3). 247 content-type OPTIONAL. As described in section 3.1.4. 248 (Section 3.1.4). 250 Authorize OPTIONAL. HTTP Authorization header to be sent when 251 accessing the resource. This is described in section 3.1.5. 252 (Section 3.1.5). If this member is not available, then the client 253 SHOULD access the expanded "href" value to obtain the 254 Authorization header response to learn what authorization scheme 255 it should use. 257 4.2. Error Responses 259 In the case of the Error Response described in section 5.2. of 260 [RFC6749], the folloing member SHOULD be present. 262 4.2.1. self 264 An object with the following members. 266 href REQUIRED. The URI that resulted in this response. 268 4.2.2. describedby 270 An object with the following members. 272 href REQUIRED. The value is 273 "http://tools.ietf.org/html/rfc6749#section-5.2". 275 5. IANA Considerations 277 This document makes no request of IANA. 279 Note to RFC Editor: this section may be removed on publication as an 280 RFC. 282 5.1. Link Type Registration 284 Pursuant to [RFC5988], the following link type registrations [[will 285 be]] registered by mail to link-relations@ietf.org. 287 5.1.1. OAuth 2 Registrations 289 The secition 3 of the OAuth 2.0 Authorization Framework [RFC6749] 290 defines two endpoints that may be discovered through this 291 specification. These are the user Authorization Endpoint and the 292 Token Endpoint. 294 5.1.1.1. Authorization Endpoint 296 o Relation Name: oauth2-authorize 298 o Descritpion: An OAuth 2.0 Authorization Endpoint specified in 299 section 3.1 of [RFC6749] 301 o Reference: [RFC6749] 303 5.1.1.2. Token Endpoint 305 o Relation Name: oauth2-token 307 o Description: An OAuth 2.0 Token Endpoint specified in section 3.2 308 of [RFC6749]. 310 o Refeence: [RFC6749] 312 6. Security Considerations 314 6.1. href tampering 316 Unless integrity protected channel is used, an attacker may be able 317 to tamper the value of the href thereby causing the receiver of the 318 JSON response to send a request to the URL under the attacker's 319 control with potentially confidential information contained in the 320 parameters. To mitigate this risk, an integrity protected channel 321 such as TLS protected channel should be used. 323 7. Acknowledgements 325 This specification borrows heavily from [HAL]. The Link type 326 registration is taken from [oauth-lrdd]. 328 [todo] 330 8. References 332 8.1. Normative References 334 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 335 Requirement Levels", BCP 14, RFC 2119, March 1997. 337 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 338 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 339 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 341 [RFC4627] Crockford, D., "The application/json Media Type for 342 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 344 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 346 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 347 and D. Orchard, "URI Template", RFC 6570, March 2012. 349 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 350 RFC 6749, October 2012. 352 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 353 Framework: Bearer Token Usage", RFC 6750, October 2012. 355 8.2. Informational References 357 [HAL] Kelly, M., "JSON Hypermedia API Language", 07 2012. 359 [oauth-lrdd] 360 Mills, W., "Link Type Registrations for OAuth 2", 361 October 2012. 363 Author's Address 365 Nat Sakimura (editor) 366 Nomura Research Institute 368 Email: sakimura@gmail.com