Re: [OAUTH-WG] application/x-www-form-urlencoded vs JSON (Proposal)

[Torsten Lodderstedt <[e-mail]>]

Hi all,

please find below a proposal for adding support for multiple response 
formats to the specification. I have taken the current version of the 
draft 
http://github.com/theRazorBlade/draft-ietf-oauth/raw/master/draft-ietf-oauth.txt 
and added some modifications indicated by dashed lines. Proposed changes 
to section 3.5.2 should be applied to 3.5.3, 3.6.1., 3.7.1., 3.7.2, and 
4., too.

Basically, the idea is that clients indicate the desired format using 
Accept headers (default) or request parameters (User-Agent flow) and the 
response is delivered accordingly. The formats considered are 
application/json, text/xml, and application/x-www-form-urlencoded. And 
as suggested by Joseph, parameters are encoded straight-forward as flat 
JSON object or XML document, respectively.

I would appriciate
regards,
Torsten.

3.5.2.  Web Server Flow
3.5.2.2.  Client Requests Access Token

    The client obtains an access token from the authorization server by
<snip>
    secret_type
          OPTIONAL.  The access token secret type as described by
          Section 5.3.  If omitted, the authorization server will issue a
          bearer token (an access token without a matching secret) as
          described by Section 5.2.

--------
A client may indicate the desired response format using an Accept-Header 
specifying
one of the following mime types: application/x-www-form-urlencoded, 
application/xml,
or application/json. If not specified, the default response format is 
application/json.
(Alternatively, the response format could be specified by a query parameter)
--------

    For example, the client makes the following HTTPS request (line
    breaks are for display purposes only):

      POST /token HTTP/1.1
      Host: server.example.com
      Content-Type: application/x-www-form-urlencoded
--------
      Accept: application/json
--------

      type=web_server&client_id=s6BhdRkqt3&
      client_secret=gX1fBat3bV&code=i1WsRn1uB1&
      redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb


    The authorization server MUST verify that the verification code,
    client identity, client secret, and redirection URI are all valid and
    match its stored association.  If the request is valid, the
    authorization server issues an access token and delivers it to the
    client in the HTTP response body using
--------
    the mime type as requested by the client or "application/json"
--------
with a 200 status code (OK).

    The response contains the following parameters:

    access_token
          REQUIRED.  The access token issued by the authorization server.

    expires_in
          OPTIONAL.  The duration in seconds of the access token
          lifetime.

    refresh_token
          OPTIONAL.  The refresh token used to obtain new access tokens
          using the same end user access grant as described in Section 4.

    access_token_secret
          REQUIRED if requested by the client.  The corresponding access
          token secret as requested by the client.

--------
    The response format depends on the requested mime type. The
    content-type header field indicates mime type and may optionaly
    indicate charset.

    "application/json": All parameters are encoded as one flat JSON object
with one key/value pair per parameter.

    For example:

      HTTP/1.1 200 OK
      Content-Type: application/json

      { "access_token": "SlAV32hkKG", "expires_in": "3600", 
"refresh_token": "8xLOxBtZp8" }

    "text/xml": All parameters are encoded as one XML document with the 
root element
<token_response>. For each parameter there is a corresponding 
sub-element with
the parameter name containing the respectives parameters value.

    For example:

      HTTP/1.1 200 OK
      Content-Type: text/xml

<token_response>
<access_token>SlAV32hkKG
<expires_in>3600</expires_in>
<refresh_token>8xLOxBtZp8</refresh_token>
</token_response>

    "application/x-www-form-urlencoded": parameters are encoded as 
name/value pairs
--------
    For example:

      HTTP/1.1 200 OK
      Content-Type: application/x-www-form-urlencoded

      access_token=SlAV32hkKG&expires_in=3600&refresh_token=8xLOxBtZp8


    If the request is invalid, the authorization server returns an error
    message in the HTTP response body using the
--------
    the mime type as requested by the client or "application/json"
--------
    with a 400 status code (Bad Request).

    The response contains the following parameter:

    error
          OPTIONAL.  The parameter value MUST be set to either
          "redirect_uri_mismatch" or "expired_verification_code" (case
          sensitive).

--------
    The response format depends on the requested mime type. The response
rendering follows the rules as specified above.
--------
For example:

--------
      HTTP/1.1 400 Bad Request
      Content-Type: application/json

      { "error"="expired_verification_code" }

--------
3.5.1.  User-Agent Flow
3.5.1.1.  Client Requests Authorization

    In order for the end user to grant the client access, the client
    sends the end user to the authorization server.  The client
    constructs the request URI by adding the following URI query
    parameters to the user authorization endpoint URI:
<snip>
--------
response_format
          OPTIONAL. Indicates the format used to deliver token data and
          errors to the client. The parameter value MUST be set to 
"text/xml",
          "application/json", or "application/x-www-form-urlencoded". 
Defaults
          to "application/json" if omitted.

--------
3.5.1.1.1.  End User Grants Authorization

    If the end user authorizes the access request, the authorization
    server issues an access token and delivers it to the client by adding
    the following parameters, using the
--------
    mime type as indicated by "response_format"
--------
to the redirection URI fragment:

    access_token
          REQUIRED.  The access token.

    expires_in
          OPTIONAL.  The duration in seconds of the access token
          lifetime.

    refresh_token
          OPTIONAL.  The refresh token.

    state
          REQUIRED if the "state" parameter was present in the client
          authorization request.  Set to the exact value received from
          the client.

    access_token_secret
          REQUIRED if requested by the client.  The corresponding access
          token secret as requested by the client.
--------
    The way and format parameters are added to the fragment depend on 
the requested mime type.

    "application/json": All parameters are encoded as one flat JSON object
with one key/value pair per parameter. This document is URL encoded and
added as parameter "oauth_response" to the fragment.

    For example, the authorization server redirects the end user's user-
    agent by sending the following HTTP response:

     HTTP/1.1 302 Found
     Location: 
http://example.com/rd#oauth_response=%7B+%22access_token%22%3A+%22SlAV32hkKG%22%2C+%22expires_in%22%3A+%223600%22%2C+%22refresh_token%22%3A+%228xLOxBtZp8%22+%7D

    "text/xml": All parameters are encoded as one XML document with the 
root element
<token_response>. For each parameter there is a corresponding 
sub-element with
the parameter name containing the respectives parameters value. The XML 
document
is URL encoded and added as parameter "oauth_response" to the fragment.

     For example:

     HTTP/1.1 302 Found
     Location: 
http://example.com/rd#oauth_response=%3Ctoken_response%3E%3Caccess_token%3ESlAV32hkKG%3Cexpires_in%3E3600%3C%2Fexpires_in%3E%3Crefresh_token%3E8xLOxBtZp8%3C%2Frefresh_token%3E%3C%2Ftoken_response%3E

    "application/x-www-form-urlencoded": All parameter are directly 
added as
    parameters to the redirection URI fragment.
--------
    For example:

     HTTP/1.1 302 Found
     Location: http://example.com/rd#access_token=FJQbwq9&expires_in=3600

3.5.1.1.2.  End User Denies Authorization

    If the end user denied the access request, the authorization server
    responds to the client by adding the following parameters, using the
--------
    mime type as indicated by "response_format"
--------
to the redirection URI fragment:

    error
          REQUIRED.  The parameter value MUST be set to "user_denied"
          (case sensitive).

    state
          REQUIRED if the "state" parameter was present in the client
          authorization request.  Set to the exact value received from
          the client.
--------
     The way and format parameters are added to the fragment depend on the
requested mime type and follows the same rules as specified above.
--------
    For example, the authorization server responds with the following:

      HTTP/1.1 302 Found
      Location: 
http://example.com/rd#oauth_response=%7b+%22error%22%3d%22user%5fdenied%22%7d