From f1613bb437bf9ee14a459a9fa2ac961b646f7639 Mon Sep 17 00:00:00 2001 From: Justin Richer Date: Sat, 3 Nov 2012 10:38:16 -0400 Subject: [PATCH] restructure, added form encoding --- draft-richer-oauth-xml.xml | 418 ++++++++++++++++++++++++++----------- 1 file changed, 295 insertions(+), 123 deletions(-) diff --git a/draft-richer-oauth-xml.xml b/draft-richer-oauth-xml.xml index df8fbe0..74b4edb 100644 --- a/draft-richer-oauth-xml.xml +++ b/draft-richer-oauth-xml.xml @@ -10,9 +10,10 @@ - + - XML Encoding for OAuth 2 + Alternate Encoding for OAuth 2 Token + Responses @@ -23,12 +24,12 @@ - + - This document describes a method of translating JSON structured - values to XML structured values in the context of the OAuth 2 - protocol. + This document describes a method of representing the JSON structured + responses from the OAuth 2 Token Endpoint into XML and form encoded + responses. @@ -41,38 +42,215 @@
- The OAuth 2 Protocol makes - use of JSON encoding for its structured - return values, as defined by section 4.2 of the OAuth specification. - However, JSON encoding is not always desirable, particularly when OAuth - is being used as part of an XML API. - - This extension describes a means for the client to request a - particular format and a method for the token endpoint to encode its - return values as XML documents as opposed to the default JSON - objects. + The OAuth 2 Protocol defines + a standard JSON 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, 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.
-
- To select XML encoding, the client sends the following OPTIONAL - parameter - - - OPTIONAL. The format parameter - specifies the client's desired format for responses from the token - endpoint. Valid values are "json" and "xml", though other extensions - MAY define other valid values. If omitted, the parameter value - defaults to "json" and behavior is as defined in OAuth 2. - The server SHALL respond to a valid access grant containing an - XML format request with an HTTP 200 response and content type of application/xml. +
+ 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. + +
+ In this method, the client sends the following OPTIONAL form + parameter in any request to the Token Endpoint to indicate its + encoding preference. + + + 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. + + 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. +
+ +
+ 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. +
+
+ +
+ All alternate forms of encoding MUST account for all elements of a + token as specified in OAuth2. + +
+ For a full description of the transformation rules, see 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. + + 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. +
+ +
+ For a full description of the transformation rules, see 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. +
+
+ +
+ Below are examples of encoding different OAuth JSON objects with XML. + All line breaks are for display purposes only. + +
+
+ A standard OAuth JSON-encoded token response (example from + OAuth2 Core): + + +
+ +
+ Can be encoded in as the following XML response + document: + + + 2YotnFZFEjr1zCsicMWpAA + example + 3600 + tGzv3JOkF0XG5Qx2TlKWIA + example_value + + + ]]> +
+ +
+ The same response can be encoded in form encoding a + follows: + + +
+
+
+ +
+ This document makes no request of IANA.
-
- This section defines encodings for different parts of the JSON data - model in XML equivalents. +
+ There are no additional security considerations. +
+ +
+ Thanks to Eve Maler, Joseph Holsten, Tim Brody, and the OAuth Working + Group for feedback. +
+ + + + + + + + + + + + + +
+ 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.
JSON objects SHALL be encoded by using XML Elements. The object @@ -80,14 +258,7 @@ 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. The root element of the overall JSON - object -
- -
- The token endpoint SHALL use the root element with a node name - oauth to represent the anonymous root JSON - object specified in the OAuth specification. + content of the XML Element.
@@ -112,12 +283,12 @@
This extension does not define a required namespace for the OAuth - XML encoding. + XML encoding, and a supporting server SHOULD not use a namespace.
This encoding scheme is intended to give a clear an intuitive - mapping between OAuth and XML data structures. However, the mapping + 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. @@ -133,52 +304,12 @@ same way.
-
-
- Below are examples of encoding different OAuth JSON objects with - XML. +
+ Line breaks are for display purposes only. -
- A standard OAuth JSON-encoded token response: - - -
- -
- Can be encoded in as the following XML response - document: - - - SlAV32hkKG - 3600 - 8xLOxBtZp8 - - - ]]> -
- -
- Or, with optional type + The example above, with type attributes in place: - SlAV32hkKG + 2YotnFZFEjr1zCsicMWpAA + example 3600 - 8xLOxBtZp8 + tGzv3JOkF0XG5Qx2TlKWIA + example_value - - - ]]> + + ]]>
-
- -
- Extensions to the OAuth protocol MAY make use of JSON's extensible - data representation capabilities, including both objects and arrays, - to extend the data returned with the token. Using the encoding rules recursively, one can represent - the same structures in XML.
This example uses both objects and arrays to support a @@ -217,9 +341,10 @@ Cache-Control: no-store { - "access_token":"SlAV32hkKG", + "access_token":"2YotnFZFEjr1zCsicMWpAA", + "token_type":"example", "expires_in":3600, - "refresh_token":"8xLOxBtZp8", + "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "ext_value": "extension", "ext_list": [ 1, 2, "three" ], "ext_object": { @@ -248,9 +373,10 @@ Cache-Control: no-store - SlAV32hkKG + 2YotnFZFEjr1zCsicMWpAA + example 3600 - 8xLOxBtZp8 + tGzv3JOkF0XG5Qx2TlKWIA extension 1 2 @@ -274,29 +400,75 @@
-
- This document makes no request of IANA. -
+
+ 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. + +
+ JSON objects SHALL be represented by encoding all members as + separate form parameters. Sub-objects SHALL be encoded by a + dot-notation syntax, with the member name of a sub-object being + appended to the name of its containing object member, separated by a + single period. +
-
- There are no additional security considerations. -
+
+ All String and Number values SHALL be encoded as simple string + values. +
-
- Thanks to Eve Maler, Joseph Holsten, and the OAuth Working Group for - feedback. -
- +
+ 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. +
- - - +
+ 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. + Both strings and numbers 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. + + Arrays 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. + +
- +
+
+ This example encodes the fictionally extended OAuth token + response above. Line breaks are for display purposes + only. - + - + 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 + ]]> +
+
+