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 May 11, 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
    3.7.  Information Loss
4.  Examples
    4.1.  Standard OAuth Token
    4.2.  Extensions
5.  IANA Considerations
6.  Security Considerations
7.  Acknowledgements
8.  Normative References
§  Author's Address

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. However, 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] 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.

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", though other extensions MAY define other valid values. If omitted, the parameter value defaults to "json" and behavior is as defined in OAuth 2 (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.) [I‑D.ietf‑oauth‑v2].

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.

3.3.  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 (Information Loss), though the most common cases will not need them.

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 <[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.

3.6.  Namespace

This extension does not define a required namespace for the OAuth XML encoding.

3.7.  Information Loss

This encoding scheme is intended to give a clear an intuitive mapping between OAuth 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 (Strings and Numbers) in JSON are represented as CDATA in XML. Without type identifiers (Type Identifiers) there is no clear way to differentiate between the two in the XML encoding.
2. Arrays (Arrays) 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.

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"
  }

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>

4.2.  Extensions

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 (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>

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, and the OAuth Working Group for feedback.

8. Normative References

Author's Address