idnits 2.17.1 draft-richer-oauth-xml-01.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 == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: This extension does not define a required namespace for the OAuth XML encoding, and a supporting server SHOULD not use a namespace. -- The document date (April 23, 2012) is 4385 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'REF' is mentioned on line 147, but not defined == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-23 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Richer, Ed. 3 Internet-Draft The MITRE Corporation 4 Intended status: Experimental April 23, 2012 5 Expires: October 25, 2012 7 Alternate Encoding for OAuth 2 Token Responses 8 draft-richer-oauth-xml-01 10 Abstract 12 This document describes a method of representing the JSON structured 13 responses from the OAuth 2 Token Endpoint into XML and form encoded 14 responses. 16 Requirements Language 18 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 19 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 20 document are to be interpreted as described in RFC 2119 [RFC2119]. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on October 25, 2012. 39 Copyright Notice 41 Copyright (c) 2012 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 3 58 2.1. Form Parameter . . . . . . . . . . . . . . . . . . . . . . 3 59 2.2. Accept Header . . . . . . . . . . . . . . . . . . . . . . 4 60 3. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3.1. XML . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 3.2. Form Encoding . . . . . . . . . . . . . . . . . . . . . . 5 63 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 4.1. Standard OAuth Token . . . . . . . . . . . . . . . . . . . 5 65 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 66 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 67 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6 68 8. Normative References . . . . . . . . . . . . . . . . . . . . . 6 69 Appendix A. General XML Encoding Rules . . . . . . . . . . . . . 7 70 A.1. Objects and Members . . . . . . . . . . . . . . . . . . . 7 71 A.2. Type Identifiers . . . . . . . . . . . . . . . . . . . . . 7 72 A.3. Strings and Numbers . . . . . . . . . . . . . . . . . . . 7 73 A.4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 A.5. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 8 75 A.6. Information Loss . . . . . . . . . . . . . . . . . . . . . 8 76 A.7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8 77 Appendix B. General Form Encoding Rules . . . . . . . . . . . . . 10 78 B.1. Objects and Members . . . . . . . . . . . . . . . . . . . 10 79 B.2. Strings and Numbers . . . . . . . . . . . . . . . . . . . 11 80 B.3. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . 11 81 B.4. Information Loss . . . . . . . . . . . . . . . . . . . . . 11 82 B.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 12 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 85 1. Introduction 87 The OAuth 2 Protocol [I-D.ietf-oauth-v2] defines a standard JSON 88 [RFC4627] encoding for structured return values from the Token 89 Endpoint in section 5.1 of the specification when used with most 90 flows. Additionally, the OAuth 2 specification defines a URI 91 fragment encoding for tokens issued from the Authorization Endpoint 92 in the Implicit Grant flow using "application/x-www-form-url-encoded" 93 encoding in section 4.2.2. 95 When OAuth is being used as part of an API that is built around 96 different encoding technologies, such as XML [W3C.CR-xml11-20021015], 97 it is not desirable for application developers to have to parse JSON 98 encoded objects just to handle authorization step. This extension 99 describes a means for the client to request an alternative format for 100 respones from the Token Endpoint and methods for the Token Endpoint 101 to encode its responses as XML documents and form-encoded parameters. 102 This extension makes no claim on responses from the Authorization 103 Endpoint or other endpoints defined in OAuth2, its extensions, or 104 profiles. 106 2. Content Negotiation 108 To request an alternate encoding from the OAuth 2 Token Endpoint, the 109 client indicates the desired encoding through one of the following 110 methods. Authorization Servers SHOULD support all methods but MUST 111 support at least one so that supporting clients can be configured to 112 request the right format. Particular formats available from a given 113 Authorization Server MUST be documented and MAY be discoverable 114 through some other means. 116 2.1. Form Parameter 118 In this method, the client sends the following OPTIONAL form 119 parameter in any request to the Token Endpoint to indicate its 120 encoding preference. 122 format 123 OPTIONAL. The format parameter specifies the client's desired 124 format for responses from the token endpoint. Valid values are 125 "json", "xml", and "form", though other extensions MAY define 126 other valid values. 128 If the value of the parameter is set to "xml" and the authorization 129 server supports XML encoding, the authorization server MUST respond 130 to a valid token request with an HTTP 200 response, a content type of 131 "application/xml", and HTTP body content as described in Section 3.1. 133 If the value of the parameter is set to "form" and the authorization 134 server supports form encoding, the authorization server MUST respond 135 to a valid token request with an HTTP 200 response, a content type of 136 "application/x-www-form-encoded", and an HTTP body content as 137 described in Section 3.2. 139 If the value of this parameter is "json" or the parameter is omitted 140 entirely, the authorization server MUST respond to a valid token 141 reqeust as defined in OAuth 2 [I-D.ietf-oauth-v2]. 143 2.2. Accept Header 145 In this method, the client sends an HTTP "Accept" header to indicate 146 to the Authorization Server what encodings it prefers as described in 147 the HTTP specification [REF]. 149 If the value of the header includes "application/xml" and the 150 authorization server supports XML encoding, the authorization server 151 MUST respond to a valid token request with an HTTP 200 response, a 152 content type of "application/xml", and HTTP body content as described 153 in Section 3.1. 155 If the value of the header includes "application/x-www-form-encoded" 156 and the authorization server supports form encoding, the 157 authorization server MUST respond to a valid token request with an 158 HTTP 200 response, a content type of 159 "application/x-www-form-url-encoded", and an HTTP body content as 160 described in Section 3.2. 162 If the value of the header is "application/json" or no accept 163 preference is otherwise given, the authorization server MUST respond 164 to a valid token reqeust as defined in OAuth 2 [I-D.ietf-oauth-v2]. 166 3. Encoding 168 All alternate forms of encoding MUST account for all elements of a 169 token as specified in OAuth2. 171 3.1. XML 173 For a full description of the transformation rules, see Appendix A 174 (Appendix A). 176 The response MUST use a single XML root element with a node name of 177 "oauth" to represent the anonymous root JSON object specified in the 178 OAuth JSON response. 180 The response SHOULD NOT include a default namespace. 182 All elements of the JSON object MUST be encoded as XML elements, with 183 values encoded as CDATA within each element. 185 3.2. Form Encoding 187 For a full description of the transformation rules, see Appendix B 188 (Appendix B). 190 The form encoding MUST follow the same encoding rules as defined in 191 Section 4.2.2 of OAuth2. 193 All values of the JSON response MUST be encoded as key-value pairs. 195 4. Examples 197 Below are examples of encoding different OAuth JSON objects with XML. 198 All line breaks are for display purposes only. 200 4.1. Standard OAuth Token 202 A standard OAuth JSON-encoded token response (example from OAuth2 203 Core): 205 HTTP/1.1 200 OK 206 Content-Type: application/json;charset=UTF-8 207 Cache-Control: no-store 208 Pragma: no-cache 210 { 211 "access_token":"2YotnFZFEjr1zCsicMWpAA", 212 "token_type":"example", 213 "expires_in":3600, 214 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 215 "example_parameter":"example_value" 216 } 218 Can be encoded in as the following XML response document: 220 HTTP/1.1 200 OK 221 Content-Type: application/xml 222 Cache-Control: no-store 224 225 2YotnFZFEjr1zCsicMWpAA 226 example 227 3600 228 tGzv3JOkF0XG5Qx2TlKWIA 229 example_value 230 232 The same response can be encoded in form encoding a follows: 234 HTTP/1.2 200 OK 235 Content-Type: application/x-www-form-encoded 236 Cache-Control: no-store 238 access_token=2YotnFZFEjr1zCsicMWpAA&token_type=example& 239 expires_in=3600&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA& 240 example_parameter=example_value 242 5. IANA Considerations 244 This document makes no request of IANA. 246 6. Security Considerations 248 There are no additional security considerations. 250 7. Acknowledgements 252 Thanks to Eve Maler, Joseph Holsten, Tim Brody, and the OAuth Working 253 Group for feedback. 255 8. Normative References 257 [I-D.ietf-oauth-v2] 258 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 259 2.0 Authorization Protocol", draft-ietf-oauth-v2-23 (work 260 in progress), January 2012. 262 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 263 Requirement Levels", BCP 14, RFC 2119, March 1997. 265 [RFC4627] Crockford, D., "The application/json Media Type for 266 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 268 [W3C.CR-xml11-20021015] 269 Cowan, J., "Extensible Markup Language (XML) 1.1", W3C 270 CR CR-xml11-20021015, October 2002. 272 Appendix A. General XML Encoding Rules 274 This Appendix defines encodings for different parts of the JSON data 275 model in XML equivalents to facilitate structured extensions to the 276 OAuth2 JSON token response. Since this JSON response MAY include 277 elements such as JSON objects or arrays, a server wishing to support 278 such extended responses and XML encoding MUST use these encoding 279 rules to translate them. 281 A.1. Objects and Members 283 JSON objects SHALL be encoded by using XML Elements. The object 284 itself SHALL be represented by the root elment of an XML subtree. 285 All members of the object SHALL be represented by sub-elements of the 286 root element. The key of the member pair SHALL be the node name of 287 the XML Element, and the value of the member pair SHALL be encoded as 288 the content of the XML Element. 290 A.2. Type Identifiers 292 All elements MAY have an OPTIONAL "type" attribute, which has a valid 293 value of "object", "string", "number", or "array". These attributes 294 can be used to differentiate between otherwise potentially ambiguous 295 encodings (Appendix A.6), though the most common cases will not need 296 them. 298 A.3. Strings and Numbers 300 Strings and numbers SHALL be encoded as CDATA within their enclosing 301 element. These values MUST be properly escaped XML CDATA, and MAY be 302 represented using <[CDATA[ ... ]]> encoding. 304 A.4. Arrays 306 Arrays SHALL be represented using repeated, sibling XML Element nodes 307 (nodes with the same node name). The order of the array is encoded 308 using document order of the array elements. 310 A.5. Namespace 312 This extension does not define a required namespace for the OAuth XML 313 encoding, and a supporting server SHOULD not use a namespace. 315 A.6. Information Loss 317 This encoding scheme is intended to give a clear an intuitive mapping 318 between JSON and XML data structures. However, the mapping between 319 the two formats is not exact and some information loss may occur, and 320 round-trip translation between the two formats MUST NOT be depended 321 upon. 323 1. Both strings and numbers (Appendix A.3) in JSON are represented 324 as CDATA in XML. Without type identifiers (Appendix A.2) there 325 is no clear way to differentiate between the two in the XML 326 encoding. 328 2. Arrays (Appendix A.4) in JSON are represented by repeated 329 elements in XML. There is therefore no reliable way to 330 distinguish between a single-element array and a standalone 331 string or number value in the XML encoding, as both would be 332 encoded the same way. 334 A.7. Examples 336 Line breaks are for display purposes only. 338 The example above, with type attributes (Appendix A.2) in place: 340 HTTP/1.1 200 OK 341 Content-Type: application/xml 342 Cache-Control: no-store 344 345 2YotnFZFEjr1zCsicMWpAA 346 example 347 3600 348 tGzv3JOkF0XG5Qx2TlKWIA 349 example_value 350 351 This example uses both objects and arrays to support a complicated, 352 fictional example extension to the OAuth protocol: 354 HTTP/1.1 200 OK 355 Content-Type: application/json 356 Cache-Control: no-store 358 { 359 "access_token":"2YotnFZFEjr1zCsicMWpAA", 360 "token_type":"example", 361 "expires_in":3600, 362 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 363 "ext_value": "extension", 364 "ext_list": [ 1, 2, "three" ], 365 "ext_object": { 366 "member1": "value1", 367 "memberlist": [ "A", "B", "C"], 368 "member3": 3, 369 "memberobj": { 370 "a": "first", 371 "b": "second", 372 "c": "third" 373 } 374 } 375 } 377 The above is encoded into XML as follows (without using type 378 attributes): 380 HTTP/1.1 200 OK 381 Content-Type: application/xml 382 Cache-Control: no-store 384 385 2YotnFZFEjr1zCsicMWpAA 386 example 387 3600 388 tGzv3JOkF0XG5Qx2TlKWIA 389 extension 390 1 391 2 392 three 393 394 value1 395 A 396 B 397 C 398 3 399 400 first 401 second 402 third 403 404 405 407 Appendix B. General Form Encoding Rules 409 This Appendix defines encodings for different parts of the JSON data 410 model in form encoded equivalents to facilitate structured extensions 411 to the OAuth2 JSON token response. Since this JSON response MAY 412 include elements such as JSON objects or arrays, a server wishing to 413 support such extended responses and form encoding MUST use these 414 encoding rules to translate them. These encoding rules MAY be used 415 to extend the response of the Authorization Endpoint in the Implicit 416 flow. 418 B.1. Objects and Members 420 JSON objects SHALL be represented by encoding all members as separate 421 form parameters. Sub-objects SHALL be encoded by a dot-notation 422 syntax, with the member name of a sub-object being appended to the 423 name of its containing object member, separated by a single period. 425 B.2. Strings and Numbers 427 All String and Number values SHALL be encoded as simple string 428 values. 430 B.3. Arrays 432 Arrays SHALL be encoded by repeating the member name for each value 433 in the array. The order of the array is encoded by the presentation 434 order of the values in the response. 436 B.4. Information Loss 438 This encoding scheme is intended to give a clear an intuitive mapping 439 between JSON and form encoded data structures. However, the mapping 440 between the two formats is not exact and some information loss may 441 occur, and round-trip translation between the two formats MUST NOT be 442 depended upon. 444 1. Both strings and numbers (Appendix B.2) in JSON are represented 445 as strings in the form encoding, and there is no clear way to 446 differentiate between the two in the form encoding. 448 2. Arrays (Appendix B.3) in JSON are represented by repeated 449 elements in the form encoding. There is therefore no reliable 450 way to distinguish between a single-element array and a 451 standalone string or number value in the form encoding, as both 452 would be encoded the same way. 454 B.5. Examples 456 This example encodes the fictionally extended OAuth token response 457 above. Line breaks are for display purposes only. 459 HTTP/1.1 200 OK 460 Content-Type: application/x-www-form-encoded 461 Cache-Control: no-store 463 access_token=2YotnFZFEjr1zCsicMWpAA&token_type=example& 464 expires_in=3600&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA& 465 ext_value=extension&ext_list=1&ext_list=2&ext_list=three& 466 ext_object.member1=value1&ext_object.memberlist=A& 467 ext_object.memberlist=B&ext_object.memberlist=C& 468 ext_object.member3=3&ext_object.memberobj.a=first& 469 ext_object.memberobj.b=second&ext_object.memberobj.c=third 471 Author's Address 473 Justin Richer (editor) 474 The MITRE Corporation 476 Email: jricher@mitre.org