Internet DRAFT - draft-richer-oauth-xml
draft-richer-oauth-xml
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
<oauth>
<access_token>2YotnFZFEjr1zCsicMWpAA</access_token>
<token_type>example</token_type>
<expires_in>3600</expires_in>
<refresh_token>tGzv3JOkF0XG5Qx2TlKWIA</refresh_token>
<example_parameter>example_value</example_parameter>
</oauth>
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
<oauth type="object">
<access_token type="string">2YotnFZFEjr1zCsicMWpAA</access_token>
<token_type type="string">example</token_type>
<expires_in type="number">3600</expires_in>
<refresh_token type="string">tGzv3JOkF0XG5Qx2TlKWIA</refresh_token>
<example_parameter type="string">example_value</example_paramter>
</oauth>
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
<oauth>
<access_token>2YotnFZFEjr1zCsicMWpAA</access_token>
<token_type>example</token_type>
<expires_in>3600</expires_in>
<refresh_token>tGzv3JOkF0XG5Qx2TlKWIA</refresh_token>
<ext_value>extension</ext_value>
<ext_list>1</ext_list>
<ext_list>2</ext_list>
<ext_list>three</ext_list>
<ext_object>
<member1>value1</member>
<memberlist>A</memberlist>
<memberlist>B</memberlist>
<memberlist>C</memberlist>
<member3>3</member3>
<memberobj>
<a>first</a>
<b>second</b>
<c>third</c>
</memberobj>
</ext_object>
</oauth>
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]
