The IETF I-D submission is closed at the moment, so I'm attaching a draft extension to this email for now. It is my intention for this to become a working group item, and am looking forward to discussing this at IIW.
-- Justin PS: This and the instance draft are my first time using the RFC formats, so I'll gladly take advice and help in getting these correct.Title: XML Encoding for OAuth 2
| TOC |
|
XML Encoding for OAuth 2
draft-richer-oauth-xml-00
Abstract
This document describes a method of translating JSON structured values to XML structured values in the context of the OAuth 2 protocol.
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 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [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 April 10, 2011.
Copyright Notice
Copyright (c) 2010 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 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
2.
Transport
3.
Encoding
3.1.
Objects and Members
3.2.
Root Element
3.3.
Type Identifiers
3.4.
Strings and Numbers
3.5.
Arrays
3.6.
Namespace
4.
Examples
4.1.
Standard OAuth Token
4.2.
Extensions
5.
IANA Considerations
6.
Security Considerations
7.
Acknowledgements
8.
Normative References
§
Author's Address
| TOC |
1. Introduction
The OAuth 2 Protocol (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.) [I‑D.ietf‑oauth‑v2] makes use of JSON (Crockford, D., “The application/json Media Type for _javascript_ Object Notation (JSON),” July 2006.) [RFC4627] encoding for its structured return values, as defined by section 4.2 of the OAuth specification. JSON encoding is not always desirable, particularly when OAuth is being used as part of an XML (Cowan, J., “Extensible Markup Language (XML) 1.1,” October 2002.) [W3C.CR‑xml11‑20021015] stream. This extension describes a method for the token endpoint to encode its return values as XML documents as opposed to JSON objects.
| TOC |
2. Transport
To select XML encoding, the client sends the following OPTIONAL parameter
- format
- OPTIONAL. The format parameter specifies the client's desired format for responses from the token endpoint. Valid values are "json" and "xml". If omitted, the parameter value defaults to "json".
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.
| TOC |
3. Encoding
This section defines encodings for different parts of the JSON data model in XML equivalents.
| TOC |
3.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. The root element of the overall JSON object
| TOC |
3.2. Root Element
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.
| TOC |
3.3. Type Identifiers
All elements MAY have an OPTIONAL "type" attribute, which has a valid value of "object", "string", "number", or "array".
| TOC |
3.4. 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 the <[CDATA[ ... ]]> encoding.
| TOC |
3.5. 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. Note that there is no viable distinction between a single-element list and a raw value using this encoding.
| TOC |
3.6. Namespace
This extension does not define a required namespace for the OAuth XML encoding.
| TOC |
4. Examples
Below are examples of encoding different OAuth JSON objects with XML.
| TOC |
4.1. Standard OAuth Token
A standard OAuth JSON-encoded token response:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token":"SlAV32hkKG",
"expires_in":3600,
"refresh_token":"8xLOxBtZp8"
}
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>SlAV32hkKG</access_token>
<expires_in>3600</expires_in>
<refresh_token>8xLOxBtZp8</refresh_token>
</oauth>
Or, with optional type attributes (Type Identifiers) in place:
HTTP/1.1 200 OK
Content-Type: application/xml
Cache-Control: no-store
<oauth type="object">
<access_token type="string">SlAV32hkKG</access_token>
<expires_in type="number">3600</expires_in>
<refresh_token type="string">8xLOxBtZp8</refresh_token>
</oauth>
| TOC |
4.2. Extensions
Extensions to the OAuth protocol could make use of JSON's extensible data representation capabilities, including both objects and arrays. Using the encoding rules (Encoding) recursively, one can represent the same structures in XML.
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":"SlAV32hkKG",
"expires_in":3600,
"refresh_token":"8xLOxBtZp8",
"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"
}
}
}
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>SlAV32hkKG</access_token>
<expires_in>3600</expires_in>
<refresh_token>8xLOxBtZp8"</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>
| TOC |
5. IANA Considerations
This document makes no request of IANA.
| TOC |
6. Security Considerations
There are no additional security considerations.
| TOC |
7. Acknowledgements
| TOC |
8. Normative References
| [I-D.ietf-oauth-v2] | Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” draft-ietf-oauth-v2-10 (work in progress), July 2010 (TXT). |
| [RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
| [RFC4627] | Crockford, D., “The application/json Media Type for _javascript_ Object Notation (JSON),” RFC 4627, July 2006 (TXT). |
| [W3C.CR-xml11-20021015] | Cowan, J., “Extensible Markup Language (XML) 1.1,” W3C CR CR-xml11-20021015, October 2002. |
| TOC |
Author's Address
| Justin Richer (editor) | |
| The MITRE Corporation | |
| Email: | [email protected] |
Network Working Group J. Richer, Ed.
Internet-Draft The MITRE Corporation
Intended status: Experimental October 7, 2010
Expires: April 10, 2011
XML Encoding for OAuth 2
draft-richer-oauth-xml-00
Abstract
This document describes a method of translating JSON structured
values to XML structured values in the context of the OAuth 2
protocol.
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 April 10, 2011.
Copyright Notice
Copyright (c) 2010 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 April 10, 2011 [Page 1]
Internet-Draft oauth-xml October 2010
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. Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Objects and Members . . . . . . . . . . . . . . . . . . . . 3
3.2. Root Element . . . . . . . . . . . . . . . . . . . . . . . 3
3.3. Type Identifiers . . . . . . . . . . . . . . . . . . . . . 4
3.4. Strings and Numbers . . . . . . . . . . . . . . . . . . . . 4
3.5. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.6. Namespace . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.1. Standard OAuth Token . . . . . . . . . . . . . . . . . . . 4
4.2. Extensions . . . . . . . . . . . . . . . . . . . . . . . . 5
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
6. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7
8. Normative References . . . . . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8
Richer Expires April 10, 2011 [Page 2]
Internet-Draft oauth-xml October 2010
1. Introduction
The OAuth 2 Protocol [I-D.ietf-oauth-v2] makes use of JSON [RFC4627]
encoding for its structured return values, as defined by section 4.2
of the OAuth specification. JSON encoding is not always desirable,
particularly when OAuth is being used as part of an XML
[W3C.CR-xml11-20021015] stream. This extension describes a method
for the token endpoint to encode its return values as XML documents
as opposed to JSON objects.
2. Transport
To select XML encoding, the client sends the following OPTIONAL
parameter
format
OPTIONAL. The format parameter specifies the client's desired
format for responses from the token endpoint. Valid values are
"json" and "xml". If omitted, the parameter value defaults to
"json".
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".
3. Encoding
This section defines encodings for different parts of the JSON data
model in XML equivalents.
3.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. The root element of the overall JSON
object
3.2. Root Element
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.
Richer Expires April 10, 2011 [Page 3]
Internet-Draft oauth-xml October 2010
3.3. Type Identifiers
All elements MAY have an OPTIONAL "type" attribute, which has a valid
value of "object", "string", "number", or "array".
3.4. 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 the <[CDATA[ ... ]]> encoding.
3.5. 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. Note that there is no
viable distinction between a single-element list and a raw value
using this encoding.
3.6. Namespace
This extension does not define a required namespace for the OAuth XML
encoding.
4. Examples
Below are examples of encoding different OAuth JSON objects with XML.
4.1. Standard OAuth Token
A standard OAuth JSON-encoded token response:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token":"SlAV32hkKG",
"expires_in":3600,
"refresh_token":"8xLOxBtZp8"
}
Richer Expires April 10, 2011 [Page 4]
Internet-Draft oauth-xml October 2010
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>SlAV32hkKG</access_token>
<expires_in>3600</expires_in>
<refresh_token>8xLOxBtZp8</refresh_token>
</oauth>
Or, with optional type attributes (Section 3.3) in place:
HTTP/1.1 200 OK
Content-Type: application/xml
Cache-Control: no-store
<oauth type="object">
<access_token type="string">SlAV32hkKG</access_token>
<expires_in type="number">3600</expires_in>
<refresh_token type="string">8xLOxBtZp8</refresh_token>
</oauth>
4.2. Extensions
Extensions to the OAuth protocol could make use of JSON's extensible
data representation capabilities, including both objects and arrays.
Using the encoding rules (Section 3) recursively, one can represent
the same structures in XML.
Richer Expires April 10, 2011 [Page 5]
Internet-Draft oauth-xml October 2010
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":"SlAV32hkKG",
"expires_in":3600,
"refresh_token":"8xLOxBtZp8",
"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 April 10, 2011 [Page 6]
Internet-Draft oauth-xml October 2010
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>SlAV32hkKG</access_token>
<expires_in>3600</expires_in>
<refresh_token>8xLOxBtZp8"</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>
5. IANA Considerations
This document makes no request of IANA.
6. Security Considerations
There are no additional security considerations.
7. Acknowledgements
Richer Expires April 10, 2011 [Page 7]
Internet-Draft oauth-xml October 2010
8. Normative References
[I-D.ietf-oauth-v2]
Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth
2.0 Protocol", draft-ietf-oauth-v2-10 (work in progress),
July 2010.
[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.
Author's Address
Justin Richer (editor)
The MITRE Corporation
Email: [email protected]
Richer Expires April 10, 2011 [Page 8]
draft-richer-oauth-xml-01.xml
Description: XML document
_______________________________________________ OAuth mailing list [email protected] https://www.ietf.org/mailman/listinfo/oauth
