Network Working Group J. Richer, Ed. Internet-Draft The MITRE Corporation Intended status: Experimental April 23, 2012 Expires: October 25, 2012 Alternate Encoding for OAuth 2 Token Responses draft-richer-oauth-xml-01 Abstract This document describes a method of representing the JSON structured responses from the OAuth 2 Token Endpoint into XML and form encoded responses. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on October 25, 2012. Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect Richer Expires October 25, 2012 [Page 1] Internet-Draft oauth-xml April 2012 to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 3 2.1. Form Parameter . . . . . . . . . . . . . . . . . . . . . . 3 2.2. Accept Header . . . . . . . . . . . . . . . . . . . . . . 4 3. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. XML . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Form Encoding . . . . . . . . . . . . . . . . . . . . . . 5 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.1. Standard OAuth Token . . . . . . . . . . . . . . . . . . . 5 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6 8. Normative References . . . . . . . . . . . . . . . . . . . . . 6 Appendix A. General XML Encoding Rules . . . . . . . . . . . . . 7 A.1. Objects and Members . . . . . . . . . . . . . . . . . . . 7 A.2. Type Identifiers . . . . . . . . . . . . . . . . . . . . . 7 A.3. Strings and Numbers . . . . . . . . . . . . . . . . . . . 7 A.4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . 8 A.5. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 8 A.6. Information Loss . . . . . . . . . . . . . . . . . . . . . 8 A.7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8 Appendix B. General Form Encoding Rules . . . . . . . . . . . . . 10 B.1. Objects and Members . . . . . . . . . . . . . . . . . . . 10 B.2. Strings and Numbers . . . . . . . . . . . . . . . . . . . 11 B.3. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . 11 B.4. Information Loss . . . . . . . . . . . . . . . . . . . . . 11 B.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 Richer Expires October 25, 2012 [Page 2] Internet-Draft oauth-xml April 2012 1. Introduction The OAuth 2 Protocol [I-D.ietf-oauth-v2] defines a standard JSON [RFC4627] encoding for structured return values from the Token Endpoint in section 5.1 of the specification when used with most flows. Additionally, the OAuth 2 specification defines a URI fragment encoding for tokens issued from the Authorization Endpoint in the Implicit Grant flow using "application/x-www-form-url-encoded" encoding in section 4.2.2. When OAuth is being used as part of an API that is built around different encoding technologies, such as XML [W3C.CR-xml11-20021015], it is not desirable for application developers to have to parse JSON encoded objects just to handle authorization step. This extension describes a means for the client to request an alternative format for respones from the Token Endpoint and methods for the Token Endpoint to encode its responses as XML documents and form-encoded parameters. This extension makes no claim on responses from the Authorization Endpoint or other endpoints defined in OAuth2, its extensions, or profiles. 2. Content Negotiation To request an alternate encoding from the OAuth 2 Token Endpoint, the client indicates the desired encoding through one of the following methods. Authorization Servers SHOULD support all methods but MUST support at least one so that supporting clients can be configured to request the right format. Particular formats available from a given Authorization Server MUST be documented and MAY be discoverable through some other means. 2.1. Form Parameter In this method, the client sends the following OPTIONAL form parameter in any request to the Token Endpoint to indicate its encoding preference. format OPTIONAL. The format parameter specifies the client's desired format for responses from the token endpoint. Valid values are "json", "xml", and "form", though other extensions MAY define other valid values. If the value of the parameter is set to "xml" and the authorization server supports XML encoding, the authorization server MUST respond to a valid token request with an HTTP 200 response, a content type of "application/xml", and HTTP body content as described in Section 3.1. Richer Expires October 25, 2012 [Page 3] Internet-Draft oauth-xml April 2012 If the value of the parameter is set to "form" and the authorization server supports form encoding, the authorization server MUST respond to a valid token request with an HTTP 200 response, a content type of "application/x-www-form-encoded", and an HTTP body content as described in Section 3.2. If the value of this parameter is "json" or the parameter is omitted entirely, the authorization server MUST respond to a valid token reqeust as defined in OAuth 2 [I-D.ietf-oauth-v2]. 2.2. Accept Header In this method, the client sends an HTTP "Accept" header to indicate to the Authorization Server what encodings it prefers as described in the HTTP specification [REF]. If the value of the header includes "application/xml" and the authorization server supports XML encoding, the authorization server MUST respond to a valid token request with an HTTP 200 response, a content type of "application/xml", and HTTP body content as described in Section 3.1. If the value of the header includes "application/x-www-form-encoded" and the authorization server supports form encoding, the authorization server MUST respond to a valid token request with an HTTP 200 response, a content type of "application/x-www-form-url-encoded", and an HTTP body content as described in Section 3.2. If the value of the header is "application/json" or no accept preference is otherwise given, the authorization server MUST respond to a valid token reqeust as defined in OAuth 2 [I-D.ietf-oauth-v2]. 3. Encoding All alternate forms of encoding MUST account for all elements of a token as specified in OAuth2. 3.1. XML For a full description of the transformation rules, see Appendix A (Appendix A). The response MUST use a single XML root element with a node name of "oauth" to represent the anonymous root JSON object specified in the OAuth JSON response. Richer Expires October 25, 2012 [Page 4] Internet-Draft oauth-xml April 2012 The response SHOULD NOT include a default namespace. All elements of the JSON object MUST be encoded as XML elements, with values encoded as CDATA within each element. 3.2. Form Encoding For a full description of the transformation rules, see Appendix B (Appendix B). The form encoding MUST follow the same encoding rules as defined in Section 4.2.2 of OAuth2. All values of the JSON response MUST be encoded as key-value pairs. 4. Examples Below are examples of encoding different OAuth JSON objects with XML. All line breaks are for display purposes only. 4.1. Standard OAuth Token A standard OAuth JSON-encoded token response (example from OAuth2 Core): HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"example", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "example_parameter":"example_value" } Richer Expires October 25, 2012 [Page 5] Internet-Draft oauth-xml April 2012 Can be encoded in as the following XML response document: HTTP/1.1 200 OK Content-Type: application/xml Cache-Control: no-store 2YotnFZFEjr1zCsicMWpAA example 3600 tGzv3JOkF0XG5Qx2TlKWIA example_value The same response can be encoded in form encoding a follows: HTTP/1.2 200 OK Content-Type: application/x-www-form-encoded Cache-Control: no-store access_token=2YotnFZFEjr1zCsicMWpAA&token_type=example& expires_in=3600&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA& example_parameter=example_value 5. IANA Considerations This document makes no request of IANA. 6. Security Considerations There are no additional security considerations. 7. Acknowledgements Thanks to Eve Maler, Joseph Holsten, Tim Brody, and the OAuth Working Group for feedback. 8. Normative References [I-D.ietf-oauth-v2] Richer Expires October 25, 2012 [Page 6] Internet-Draft oauth-xml April 2012 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 2.0 Authorization Protocol", draft-ietf-oauth-v2-23 (work in progress), January 2012. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. [W3C.CR-xml11-20021015] Cowan, J., "Extensible Markup Language (XML) 1.1", W3C CR CR-xml11-20021015, October 2002. Appendix A. General XML Encoding Rules This Appendix defines encodings for different parts of the JSON data model in XML equivalents to facilitate structured extensions to the OAuth2 JSON token response. Since this JSON response MAY include elements such as JSON objects or arrays, a server wishing to support such extended responses and XML encoding MUST use these encoding rules to translate them. A.1. Objects and Members JSON objects SHALL be encoded by using XML Elements. The object itself SHALL be represented by the root elment of an XML subtree. All members of the object SHALL be represented by sub-elements of the root element. The key of the member pair SHALL be the node name of the XML Element, and the value of the member pair SHALL be encoded as the content of the XML Element. A.2. Type Identifiers All elements MAY have an OPTIONAL "type" attribute, which has a valid value of "object", "string", "number", or "array". These attributes can be used to differentiate between otherwise potentially ambiguous encodings (Appendix A.6), though the most common cases will not need them. A.3. Strings and Numbers Strings and numbers SHALL be encoded as CDATA within their enclosing element. These values MUST be properly escaped XML CDATA, and MAY be represented using <[CDATA[ ... ]]> encoding. Richer Expires October 25, 2012 [Page 7] Internet-Draft oauth-xml April 2012 A.4. Arrays Arrays SHALL be represented using repeated, sibling XML Element nodes (nodes with the same node name). The order of the array is encoded using document order of the array elements. A.5. Namespace This extension does not define a required namespace for the OAuth XML encoding, and a supporting server SHOULD not use a namespace. A.6. Information Loss This encoding scheme is intended to give a clear an intuitive mapping between JSON and XML data structures. However, the mapping between the two formats is not exact and some information loss may occur, and round-trip translation between the two formats MUST NOT be depended upon. 1. Both strings and numbers (Appendix A.3) in JSON are represented as CDATA in XML. Without type identifiers (Appendix A.2) there is no clear way to differentiate between the two in the XML encoding. 2. Arrays (Appendix A.4) in JSON are represented by repeated elements in XML. There is therefore no reliable way to distinguish between a single-element array and a standalone string or number value in the XML encoding, as both would be encoded the same way. A.7. Examples Line breaks are for display purposes only. The example above, with type attributes (Appendix A.2) in place: HTTP/1.1 200 OK Content-Type: application/xml Cache-Control: no-store 2YotnFZFEjr1zCsicMWpAA example 3600 tGzv3JOkF0XG5Qx2TlKWIA example_value Richer Expires October 25, 2012 [Page 8] Internet-Draft oauth-xml April 2012 This example uses both objects and arrays to support a complicated, fictional example extension to the OAuth protocol: HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"example", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "ext_value": "extension", "ext_list": [ 1, 2, "three" ], "ext_object": { "member1": "value1", "memberlist": [ "A", "B", "C"], "member3": 3, "memberobj": { "a": "first", "b": "second", "c": "third" } } } Richer Expires October 25, 2012 [Page 9] Internet-Draft oauth-xml April 2012 The above is encoded into XML as follows (without using type attributes): HTTP/1.1 200 OK Content-Type: application/xml Cache-Control: no-store 2YotnFZFEjr1zCsicMWpAA example 3600 tGzv3JOkF0XG5Qx2TlKWIA extension 1 2 three value1 A B C 3 first second third Appendix B. General Form Encoding Rules This Appendix defines encodings for different parts of the JSON data model in form encoded equivalents to facilitate structured extensions to the OAuth2 JSON token response. Since this JSON response MAY include elements such as JSON objects or arrays, a server wishing to support such extended responses and form encoding MUST use these encoding rules to translate them. These encoding rules MAY be used to extend the response of the Authorization Endpoint in the Implicit flow. B.1. Objects and Members JSON objects SHALL be represented by encoding all members as separate form parameters. Sub-objects SHALL be encoded by a dot-notation Richer Expires October 25, 2012 [Page 10] Internet-Draft oauth-xml April 2012 syntax, with the member name of a sub-object being appended to the name of its containing object member, separated by a single period. B.2. Strings and Numbers All String and Number values SHALL be encoded as simple string values. B.3. Arrays Arrays SHALL be encoded by repeating the member name for each value in the array. The order of the array is encoded by the presentation order of the values in the response. B.4. Information Loss This encoding scheme is intended to give a clear an intuitive mapping between JSON and form encoded data structures. However, the mapping between the two formats is not exact and some information loss may occur, and round-trip translation between the two formats MUST NOT be depended upon. 1. Both strings and numbers (Appendix B.2) in JSON are represented as strings in the form encoding, and there is no clear way to differentiate between the two in the form encoding. 2. Arrays (Appendix B.3) in JSON are represented by repeated elements in the form encoding. There is therefore no reliable way to distinguish between a single-element array and a standalone string or number value in the form encoding, as both would be encoded the same way. Richer Expires October 25, 2012 [Page 11] Internet-Draft oauth-xml April 2012 B.5. Examples This example encodes the fictionally extended OAuth token response above. Line breaks are for display purposes only. HTTP/1.1 200 OK Content-Type: application/x-www-form-encoded Cache-Control: no-store access_token=2YotnFZFEjr1zCsicMWpAA&token_type=example& expires_in=3600&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA& ext_value=extension&ext_list=1&ext_list=2&ext_list=three& ext_object.member1=value1&ext_object.memberlist=A& ext_object.memberlist=B&ext_object.memberlist=C& ext_object.member3=3&ext_object.memberobj.a=first& ext_object.memberobj.b=second&ext_object.memberobj.c=third Author's Address Justin Richer (editor) The MITRE Corporation Email: jricher@mitre.org Richer Expires October 25, 2012 [Page 12]