OAuth Extension for Response Data Format - Draft 1

Abstract

This memo describes how a Consumer can request the Service Provider to return the OAuth response data in a different format (ex. json, xml, etc.).

Table of Contents

1.  Contributors
2.  Notation and Conventions
3.  Definitions
4.  Description
5.  Parameter Specification
    5.1.  Response Data Format Type
6.  Extension Identifier
7.  Processing Rules
    7.1.  Indirect Requests
8.  Response Data Format
    8.1.  XML
    8.2.  JSON
    8.3.  YAML
    8.4.  PHP
    8.5.  AMF0
    8.6.  AMF3
Appendix A.  Response Data in XML Format with Service Specific Parameters
Appendix B.  Security considerations for xoauth_json_callback
9.  References
§  Author's Address

1.  Contributors

George Fletcher

2.  Notation and Conventions

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 [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.). Domain name examples use [RFC2606] (Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” June 1999.).

3.  Definitions

Service Provider:

A web application that allows access via OAuth.

Consumer:

A website or application that uses OAuth to access the Service Provider on behalf of the User.

User:

An individual who has an account with the Service Provider.

Response Data:

Parameters returned by the Service Provider in response to an OAuth request.

Response Code:

A numeric code returned by the Service Provider indicating the result of the request (Ex. success, failure, unauthorized, etc.). The Service Provider SHOULD use the response codes defined in [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) Section 10.

Direct Request:

A request is initiated by the Consumer to a Service Provider endpoint URL. Direct Request mechanism is used for the Request Token and Access Token requests as defined in OAuth Core 1.0 (OAuth, OCW., “OAuth Core 1.0,” December 2007.).

Indirect Request:

A request is initiated by the Consumer through an User-Agent to a Service Provider endpoint URL. Indirect Request mechanism is used for the Authorization request as defined in the OAuth Core 1.0 (OAuth, OCW., “OAuth Core 1.0,” December 2007.).

4.  Description

In certain cases it is necessary or prudent for the Consumer to request the Service Provider to return the response data in a different format in the response body (Ex. json, xml, amf3, php, yaml, etc.) in both direct (Request Token and Access Token) and indirect (Authorization) requests.

The most common use case is a Javascript based Consumer running in a browser on a domain (Ex. sampleblog.com) that's not the same as the Service Provider's domain (Ex. example.provider.com). In this case usually the Javascript Consumers use the <SCRIPT> tag injection mechanism (called 'JSONP') to make cross domain requests to the Service Provider. One of the side effects of using the JSONP mechanism is to have the response data also returned in 'JSON' [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.)format. Similar to 'JSON' there have been other data serialization formats defined to help applications built in other technologies like Flash, PHP, Java, C/C++, etc.. Some of them include 'amf0', 'amf3', and 'php' targeting specific technologies and some are more generic formats like 'yaml' and 'xml'.

This Response Data Format Specification addresses such requirements so a Consumer can request the Service Provider to return data in a specific format instead of the default format (a form-encoded string using '&' and '=' signs to separate name-value pairs) encoded as specified in the OAuth Core 1.0 Specification.[OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” December 2007.)

5.  Parameter Specification

This extension defines a new parameter that the Consumer can use to request the Service Provider to return the response data in a specific format instead of the default format as specified in the OAuth Core 1.0 Specification[OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” December 2007.) . Please see section Extension Identifier (Extension Identifier) for information on how the Service Provider can advertise the supported response data formats.

As specified in Section 5 & 5.1 in the OAuth Core 1.0 Specification[OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” December 2007.), all parameter names and values are case sensitive, and MUST be encoded to be URL safe.

5.1.  Response Data Format Type

The OAuth Response Data Format MUST be specified with the parameter name 'xoauth_response_format'. The value of the parameter MUST be a URI, which is used for referring to the response format values. Section 8 (Response Data Format) specifies the format of the data returned in the response body.

To identity the Response Data Format, each format is given a unique URI:

XML:

http://oauth.net/ext/response_data_format/types/xml

JSON:

http://oauth.net/ext/response_data_format/types/json

PHP:

http://oauth.net/ext/response_data_format/types/php

YAML:

http://oauth.net/ext/response_data_format/types/yaml

AMF0:

http://oauth.net/ext/response_data_format/types/amf0

AMF3:

http://oauth.net/ext/response_data_format/types/amf3

OAUTH [default - same as when xoauth_response_format is not specified]:

http://oauth.net/ext/response_data_format/types/oauth

Ex.

xoauth_response_format = http%3A//schema.oauth.net/ext/response_data_format/types/json

6.  Extension Identifier

The Service Provider can advertise that it supports this extension by listing the following URI in the public documentation that also describes the public endpoints. When using OAuth Discovery as defined in [OAuth Discovery 1.0] (Hammer-Lahav, E., “OAuth Discovery 1.0 Draft 1,” December 2007.), the Response Data Format Type extension service type URI is: http://oauth.net/ext/response_data_format/1.0. It follows the same rules and workflow as the http://oauth.net/core/1.0/endpoint/resource service type.

The Service Provider can also advertise the response formats that are supported by specifying the response data format values as defined in Response Data Format (Response Data Format Type) section.

Sample Discovery entry:

      <Service>
        <Type>http://oauth.net/ext/response_data_format/1.0</Type>
        <Type>http://oauth.net/ext/response_data_format/types/xml</Type>
        <Type>http://oauth.net/ext/response_data_format/types/json</Type>
        <Type>http://oauth.net/ext/response_data_format/types/oauth</Type>
      </Service>

7.  Processing Rules

If the response format value provided by the Consumer is not supported by the Service Provider, the Service Provider MUST format the response data as defined in the OAuth Core 1.0 Specification.[OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” December 2007.)

The Consumer MAY specify the response data format by adding the xoauth_response_format parameter to any Service Provider endpoints (both direct and indirect requests) that supports the extension. However it is recommended that the Consumer SHOULD first determine if the Service Provider supports the extension before adding the parameter.

When requesting the response data format as "JSON", the Consumers MAY pass the 'xoauth_json_callback' with the JSONP callback and the Service Provider MUST return a JSONP callback using the value from the 'xoauth_json_callback' parameter.

When returning response data in the format requested by the Consumer, the Service Provider MUST set the HTTP 'Content-Type' header with the appropriate value that corresponds to the response data format. The 'Content-Type' header SHOULD also include a 'CharSet' to let the Consumer know which character set is used in the response data.

It is RECOMMENDED that the Service Providers SHOULD also return the response data in the same format in case of errors and MAY return Service Provider specific data in the same format to make it easy for the Consumers to handle the response data in a consistent way.

7.1.  Indirect Requests

Service Providers MUST support "xoauth_response_format" parameter in the Indirect Requests only if the Consumer provides the "oauth_callback" parameter and HTTP POST method (not using 301/302/303 redirects) is used to redirect the user back to the Consumer.

• If the Service Provider is using a HTTP POST method to redirect the user back to the Consumer's "oauth_callback" URL, then the response data in the requested format as specified in the "xoauth_response_format" parameter, goes in the HTTP POST body.
• If the Service Provider is using a HTTP GET method (a redirect based on HTTP status codes 301/302/303) to redirect the user back to the Consumer's "oauth_callback" URL, the "xoauth_response_format" MUST be ignored and the response data SHOULD be returned in the default format (form encoded parameters) as defined in the [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” December 2007.)

8.  Response Data Format

The following sections define the format of the response data for the different format types defined in the Response Data Format Type (Response Data Format Type) section. When the Consumer requests the response data in a different format than the default format specified in OAuth Core 1.0 (OAuth, OCW., “OAuth Core 1.0,” December 2007.), the Service Provider (if it supports this extension) MUST return the response data as specified below. The Service Provider MAY add additional parameters in the response data but they MUST be included inside the 'response' object as per the given response data format. The Service Providers SHALL document the additional parameters if any in their own documentation.

Below is the XML Schema representation of the response data format. The response data in other (non-xml) formats MUST follow the same schema and convert it to it's language specifics as described below.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="response">
	<xs:complexType>
	<xs:sequence>
		<xs:element name="oauth_parameter" minOccurs="0" maxOccurs="unbounded">
			<xs:complexType>
				<xs:simpleContent>
					<xs:extension base="xs:string">
						<xs:attribute name="name" type="xs:string" use="required"/>
					</xs:extension>
				</xs:simpleContent>
			</xs:complexType>
		</xs:element>
		<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
	</xs:sequence>
	</xs:complexType>
</xs:element>
</xs:schema>

8.1.  XML

The XML format directly derives from the XML Schema defined above. Service Providers may add their service specific parameters in the response. Please refer to [xml] (, “XML,” .) for more information on XML format.

<response>
	<oauth_parameter name="oauth_token">token</oauth_parameter>
	<oauth_parameter name="oauth_token_secret">secret</oauth_parameter>
</response>

'Content-Type' HTTP response header value MUST be:

Content-Type: text/xml

8.2.  JSON

The JSON format represents data as JavaScript literals. The object literal produced by JSON can be directly evaluated by a JSON parser. Please refer to [json] (, “JSON,” .) for more information on JSON format.

{"response":{"oauth_parameter":{ "oauth_token": "token", "oauth_token_secret": "secret"	}}}

'Content-Type' HTTP response header value MUST be :

Content-Type: text/json

If the Consumer needs the response as a callback (JSONP), the xoauth_json_callback parameter MUST be passed as one of the input parameter as defined in the Processing Rules section (Processing Rules).

8.3.  YAML

YAML is a human-friendly, cross language, Unicode based data serialization language designed around the common native data strutures of modern programming languages. [yaml] (, “YAML,” .)

'response' => {
    'oauth_parameter' => {
		'oauth_token' => 'token',
		'oauth_token_secet' => 'secret'
	}
}

'Content-Type' HTTP response header value MUST be :

Content-Type: text/yaml

8.4.  PHP

Serialized PHP is a data encoding format for PHP programming language to easily store and transmit data. The Serialized PHP data can be directly evaluated by using the built in 'unserialize' function in PHP. The general format of the PHP data is:

<data type>:<length>:<value>

Please refer to [serialized_php] (, “Serialized PHP,” .) and [serialized_php_yahoo] (, “Using Serialized PHP with Yahoo! Web Services,” .) for more information on Serialized PHP data encoding format.

a:1:{s:14:"response";a:1:{s:14:"oauth_parameter";a:2:{s:11:"oauth_token";s:5:"token";s:18:"oauth_token_secret";s::"secret"}}

'Content-Type' HTTP response header value MUST be :

Content-Type: text/php

8.5.  AMF0

AMF0 is a binary data format Flash uses to transfer information from and to a server. ActionScript 2.0 and earlier versions use AMF0 format.

response (object) {
    oauth_parameter (object) {
		oauth_token (string) = 'token'
		oauth_token_secet (string) = 'secret'
	}
}

'Content-Type' HTTP response header value MUST be :

Content-Type: application/x-amf

8.6.  AMF3

AMF3 is a binary data format Flash uses to transfer information from and to a server. ActionScript 3 uses AMF3 format.[amf3_spec] (Adobe Systems Inc., “Action Message Format -- AMF3,” .)

response (object) {
    oauth_parameter (object) {
		oauth_token (string) = 'token'
		oauth_token_secet (string) = 'secret'
	}
}

'Content-Type' HTTP response header value MUST be :

Content-Type: application/x-amf

Appendix A.  Response Data in XML Format with Service Specific Parameters

This is an example of sample response data in XML format from a Service Provider with some provider specific parameters.

<response>
	<oauth_parameter name="oauth_token">token</oauth_parameter>
	<oauth_parameter name="oauth_token_secret">secret</oauth_parameter>
	<sp_parameter1>value1</sp_parameter>
	<sp_data>
		<somethingelse>data</somethingelse>
	</sp_data>
</response>

Appendix B.  Security considerations for xoauth_json_callback

Service Providers SHOULD apply necessary security filters on the xoauth_json_callback parameter value provided by the Consumers to prevent XSS attacks.

9. References

Author's Address