Subject: [OAUTH-WG] application/x-www-form-urlencoded vs JSON

From: Dick Hardt <[email-masked]>
Date: Sun, 18 Apr 2010 21:30:13 -0700

The AS token endpoint response is encoded as application/x-www-form-urlencoded

While this reuses a well known and understood encoding standard, it is uncommon for a client to receive a message encoded like this. Most server responses are encoded as XML or JSON. Libraries are NOT reedily available to parse application/x-www-form-urlencoded results as this is something that is typically done in the web servers framework. While parsing the name value pairs and URL un-encoding them is not hard, many developers have been caught just splitting the parameters and forgetting to URL decode the token. Since the token is opaque and may contain characters that are escaped, it is a difficult bug to detect.

Potential options:

1) Do nothing, developers should read the specs and do the right thing.

2) Require that all parameters are URL safe so that there is no encoding issue.

3) Return results as JSON, and recommend that parameters be URL safe.

-- Dick

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Sun, 18 Apr 2010 22:13:01 -0700

Every format requires some encoding, and if we limit the character set we will just be pushing the problem elsewhere (forcing servers to encode or define encoding for clients). Right now the assumption is that developers will implement the format (form-encoded) correctly, which will take care of any unexpected value. We can be more explicit about warning them no to assume anything about the values they receive.

Interop requires that servers always use the format defined by the spec, but may offer more formats per client request. This requires an extension parameter or a preference in the client configuration.

I don't have a preference between JSON and form-encoded, but will point out that form-encoded is MUCH easier to parse without a library than JSON or XML. We can also offer both and define a client request parameter (as long as the server is required to make at least one format available).

EHL

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Dick Hardt
> Sent: Sunday, April 18, 2010 9:30 PM
> To: OAuth WG
> Subject: [OAUTH-WG] application/x-www-form-urlencoded vs JSON
> 
> While this reuses a well known and understood encoding standard, it is
> uncommon for a client to receive a message encoded like this. Most server
> responses are encoded as XML or JSON. Libraries are NOT reedily available to
> parse application/x-www-form-urlencoded results as this is something that is
> typically done in the web servers framework. While parsing the name value
> pairs and URL un-encoding them is not hard, many developers have been
> caught just splitting the parameters and forgetting to URL decode the token.
> Since the token is opaque and may contain characters that are escaped, it is a
> difficult bug to detect.
> 
> Potential options:
> 
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Torsten Lodderstedt <[email-masked]>
Date: Mon, 19 Apr 2010 13:48:25 +0200

> We can also offer both and define a client request parameter (as  
> long as the server is required to make at least one format available).

+1 on this

regards,
Torsten.

---

From: Mike Moore <[email-masked]>
Date: Mon, 19 Apr 2010 08:57:16 -0600

On Mon, Apr 19, 2010 at 5:48 AM, Torsten Lodderstedt <
[email-masked]> wrote:

>
>  We can also offer both and define a client request parameter (as long as
>> the server is required to make at least one format available).
>>
>
> +1 on this
>

-1  on this. As a client I don't want to have to support both form encoding
and json. Just make a single good decision and stick to it, please.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 19 Apr 2010 08:25:20 -0700

You are missing the point. The server will be required to support one of
these, but allowed to offer more. If your client is limited, just support
the required format. This is good for clients as it guarantees both interop
and flexibility.

The downside, like anything else, is a more complex protocol. BUT, if most
vendors are going to add such alternative formats, we should codify it.

For those who want this, the next step is to suggest language for other
encoding formats just as JSON or XML.

EHL

On 4/19/10 7:57 AM, "Mike Moore" <[email-masked]> wrote:

> On Mon, Apr 19, 2010 at 5:48 AM, Torsten Lodderstedt <[email-masked]>
> wrote:
>> 
>>> We can also offer both and define a client request parameter (as long as the
>>> server is required to make at least one format available).
>> 
>> +1 on this
>

---

From: Mike Moore <[email-masked]>
Date: Mon, 19 Apr 2010 09:59:03 -0600

On Mon, Apr 19, 2010 at 9:25 AM, Eran Hammer-Lahav <[email-masked]>wrote:

> You are missing the point.
>

No, I get it. But what I like about OAuth 1.0 was its simplicity. I don't
see how allowing either the server or client to suggest alternate encodings
allows OAuth 2.0 to do more. I don't think the added complexity is worth it.
Not everything needs to be configurable.

---

From: Torsten Lodderstedt <[email-masked]>
Date: Mon, 19 Apr 2010 21:03:47 +0200

Am 19.04.2010 17:59, schrieb Mike Moore:
> On Mon, Apr 19, 2010 at 9:25 AM, Eran Hammer-Lahav 
> <[email-masked] <mailto:[email-masked]>> wrote:
>
> No, I get it. But what I like about OAuth 1.0 was its simplicity. I 
> don't see how allowing either the server or client 
> to suggest alternate encodings allows OAuth 2.0 to do more. I don't 
> think the added complexity is worth it. Not everything needs to be 
> configurable.

So what should be the singlemost encoding to be standardized? I would be 
unable to choose one.

 From my experiences, the optimal encoding primarily depends on the 
capabilities and style guides of a particular client platform. JSON is 
fine for JavaScript client, XML might be better for other client 
platforms, command line scripts can probably easier be implemented using 
plain text.

Our (proprietary) security token service offers different types of 
transport encoding, e.g. json and xml. This is highly appreciated by the 
client developers.

regards,
Torsten.

---

From: Mike Moore <[email-masked]>
Date: Mon, 19 Apr 2010 13:37:48 -0600

> So what should be the singlemost encoding to be standardized? I would be

I think form encoding is just fine. Its lightweight, minimalistic, and easy
to implement. I don't see a reason to switch from the 1.0 spec.

If the issue is poor implementations or devs not reading the spec, then
perhaps we should discuss a series of executable specs or a reference
implementation. (I know I sure could have used that when I implemented
OAuth.) Just my two cents.

---

From: Richard Barnes <[email-masked]>
Date: Mon, 19 Apr 2010 17:29:11 -0400

On the other hand, if you've already got a JSON or XML library on hand  
(as many apps these days do), then JSON/XML is a lot easier to handle  
than form-encoded.  Plus, if you're not re-using form-encoding, then  
there's no risk of being confused with actual "forms" / request  
parameters.  Not trying to argue one side or the other, just noting  
that there are trade-offs.

To refine Eran's point a little, how about this proposal?
1. Define N encodings of the OAuth parameters
2. Require servers to support *all* encodings
3. Require clients to support *one* encoding (and to send only one at  
a time!)
4. Require servers to respond in the encoding they receive

Seems like that would minimize the burden on clients, without placing  
a huge burden on servers.

--Richard

On Apr 19, 2010, at 3:37 PM, Mike Moore wrote:

> On Mon, Apr 19, 2010 at 1:03 PM, Torsten Lodderstedt <[email-masked] 
> > wrote:
>
> So what should be the singlemost encoding to be standardized? I  
> would be unable to choose one.
>
> I think form encoding is just fine. Its lightweight, minimalistic,  
> and easy to implement. I don't see a reason to switch from the 1.0  
> spec.
>
> If the issue is poor implementations or devs not reading the spec,  
> then perhaps we should discuss a series of executable specs or a  
> reference implementation. (I know I sure could have used that when I  
> implemented OAuth.) Just my two cents.

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 19 Apr 2010 14:40:50 -0700

> Of Richard Barnes
> Sent: Monday, April 19, 2010 2:29 PM
> To: Mike Moore
> Cc: OAuth WG
> Subject: Re: [OAUTH-WG] application/x-www-form-urlencoded vs JSON
> 
> On the other hand, if you've already got a JSON or XML library on hand (as
> many apps these days do), then JSON/XML is a lot easier to handle than
> form-encoded.  Plus, if you're not re-using form-encoding, then there's no
> risk of being confused with actual "forms" / request parameters.  Not trying
> to argue one side or the other, just noting that there are trade-offs.
> 

My point is that it doesn't have to cause client problems. I am not advocating (or objecting) to this approach.

> 1. Define N encodings of the OAuth parameters 2. Require servers to support
> *all* encodings 3. Require clients to support *one* encoding (and to send
> only one at a time!) 4. Require servers to respond in the encoding they
> receive
> 
> Seems like that would minimize the burden on clients, without placing a huge
> burden on servers.

This looks like a good way to do it, but it does add complexity.

EHL

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 20 Apr 2010 08:10:52 -0700

There seems to be support for this idea with some concerns about complexity. Someone needs to propose text for this including defining the request parameter and schema of the various reply formats.

EHL

> From: Torsten Lodderstedt [mailto:[email-masked]]
> Sent: Monday, April 19, 2010 4:48 AM
> To: Eran Hammer-Lahav
> Cc: Dick Hardt; OAuth WG
> > We can also offer both and define a client request parameter (as long
> > as the server is required to make at least one format available).
> 
> +1 on this
> 
> regards,
> Torsten.
> 
> >
> > EHL
> >
> >> From: [email-masked] [mailto:[email-masked]] On
> >> Behalf Of Dick Hardt
> >> While this reuses a well known and understood encoding standard, it
> >> is uncommon for a client to receive a message encoded like this. Most
> >> server responses are encoded as XML or JSON. Libraries are NOT
> >> reedily available to parse application/x-www-form-urlencoded results
> >> as this is something that is typically done in the web servers
> >> framework. While parsing the name value pairs and URL un-encoding
> >> them is not hard, many developers have been caught just splitting the
> parameters and forgetting to URL decode the token.
> >> Since the token is opaque and may contain characters that are
> >> escaped, it is a difficult bug to detect.
> >>
> >> Potential options:
> >>

---

From: Joseph Smarr <[email-masked]>
Date: Tue, 20 Apr 2010 09:24:50 -0700

+1 to including JSON format, and perhaps making it the required format. In
my experience helping numerous developers debug their OAuth implementations,
url-encoding/decoding was often a source of bugs, since a) the libraries are
usually hand-built, b) url-encoding is known to be funky/inconsistent wrt +
vs. %20 and other such things, and c) it's very sensitive to things like a
trailing newline at the end of the response, which can easily be tokenized
as part of the the last value (since the normal implementations just split
on & and =). In contrast, I've never heard of any problems parsing JSON, nor
any encoding/decoding bugs related to working with JSON in other APIs
(something I *cannot* say about XML, which is way more finicky about
requiring its values to be properly encoded or escaped in CDATA etc.; I've
also seen way more inconsistency in support of XML parsers and their output
formats, whereas JSON always works exactly the same way and always "just
works").

So in conclusion, url-encoding has caused a lot of pain in OAuth 1.0, and
JSON is already widely supported (presumably including by most APIs that
you're building OAuth support to be able to access!), so I think it would
simplify the spec and increase ease/success of development to use JSON as a
request format. In fact, I think I'd like to push for it to be the
default/required format, given the positive attributes above. Does anyone
object, and if so, why?

Thanks, js

On Tue, Apr 20, 2010 at 8:10 AM, Eran Hammer-Lahav <[email-masked]>wrote:

> There seems to be support for this idea with some concerns about
> complexity. Someone needs to propose text for this including defining the
> request parameter and schema of the various reply formats.
>
> EHL
>

---

From: Joseph Smarr <[email-masked]>
Date: Tue, 20 Apr 2010 09:27:32 -0700

...and of course by "request format", I mean "response format". :)

BTW, note that the "trailing newline problem" with url-encoding is
particularly pernicious because a) it messes up the signature, and b) you
often can't see it when you print out your variables, so everything looks ok
and yet the signature is garbled. I've seen this multiple times, and IMO
that alone is reason enough to get rid of this serialization format in favor
of something more robust and widely implemented like JSON.

---

From: Marius Scurtescu <[email-masked]>
Date: Tue, 20 Apr 2010 09:40:06 -0700

How about encoding requests as well. The request json blob could be
then URL encoded and added to the endpoint/callback URL with a
parameter like "oauth_json_request". This would solve the
prefix/collision problem.

Marius

---

From: David Recordon <[email-masked]>
Date: Tue, 20 Apr 2010 12:45:05 -0700

Having written an implementation last night against the web server
flow, I'm worried about adding JSON as a requirement for the response.
While it might be easier for environments with JSON libraries, it's
drastically more complex for environments (like embedded hardware)
which doesn't support JSON. And writing basic form encoded parsing
code really isn't that hard – especially if I can do it!

---

From: "Paul C. Bryan" <[email-masked]>
Date: Tue, 20 Apr 2010 12:56:03 -0700

I'm struggling to imagine hardware that on the one hand would support
OAuth, but on the other would be incapable of supporting JSON...

---

From: Joseph Smarr <[email-masked]>
Date: Tue, 20 Apr 2010 14:17:36 -0700

On the one hand, I'm sympathetic to the "easy to write a parser yourself"
argument for url-encoding, since in general I think you want to minimize any
toolchain/library requirements to maximize adoption. On the other hand, I'd
argue that OAuth 1.0 has shows url-encoding to be "deceptively easy" to
implement yourself, plus there are *fewer* easy/good parsing libraries
available, and that leads more developers to try and hand-code parsers that
actually contain bugs.

Now David, I'm sure your implementation has no bugs, but lots of "official
OAuth libraries" did have bugs in their parsers, whereas JSON does have
widely available, high-quality support, and it's just complex enough that
you're not tempted to try and write a (buggy) version yourself, yet not so
painful that it would be unthinkable to do so (compared to, say, a compliant
XML parser).

Thanks, js

On Tue, Apr 20, 2010 at 12:56 PM, Paul C. Bryan <[email-masked]> wrote:

> long
> >> > >> The AS token endpoint response is encoded as
> application/x-www-form-
> >> > >> urlencoded
> >> > >>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 20 Apr 2010 14:31:26 -0700

All the issues around encoding in 1.0 were about signatures. This is no longer an issue.

EHL

On Apr 20, 2010, at 14:19, "Joseph Smarr" <[email-masked]<mailto:[email-masked]>> wrote:

On the one hand, I'm sympathetic to the "easy to write a parser yourself" argument for url-encoding, since in general I think you want to minimize any toolchain/library requirements to maximize adoption. On the other hand, I'd argue that OAuth 1.0 has shows url-encoding to be "deceptively easy" to implement yourself, plus there are *fewer* easy/good parsing libraries available, and that leads more developers to try and hand-code parsers that actually contain bugs.

Now David, I'm sure your implementation has no bugs, but lots of "official OAuth libraries" did have bugs in their parsers, whereas JSON does have widely available, high-quality support, and it's just complex enough that you're not tempted to try and write a (buggy) version yourself, yet not so painful that it would be unthinkable to do so (compared to, say, a compliant XML parser).

Thanks, js

On Tue, Apr 20, 2010 at 12:56 PM, Paul C. Bryan <<mailto:[email-masked]>[email-masked]<mailto:[email-masked]>> wrote:
I'm struggling to imagine hardware that on the one hand would support
OAuth, but on the other would be incapable of supporting JSON...

-----Original Message-----
From: David Recordon <<mailto:[email-masked]>[email-masked]<mailto:[email-masked]>>
To: <mailto:[email-masked]> [email-masked]<mailto:[email-masked]>
Cc: OAuth WG <<mailto:[email-masked]>[email-masked]<mailto:[email-masked]>>
Subject: Re: [OAUTH-WG] application/x-www-form-urlencoded vs JSON
Date: Tue, 20 Apr 2010 12:45:05 -0700

On Tue, Apr 20, 2010 at 9:24 AM, Joseph Smarr <<mailto:[email-masked]>[email-masked]<mailto:[email-masked]>> wrote:
> On Tue, Apr 20, 2010 at 8:10 AM, Eran Hammer-Lahav <<mailto:[email-masked]>[email-masked]<mailto:[email-masked]>>
> wrote:
>>
>> > From: Torsten Lodderstedt [mailto:<mailto:[email-masked]>[email-masked]<mailto:[email-masked]>]
>> > >> From: <mailto:[email-masked]> [email-masked]<mailto:[email-masked]> [mailto:<mailto:[email-masked]>[email-masked]<mailto:[email-masked]>] On
>> > >> Behalf Of Dick Hardt
>> > >> <mailto:[email-masked]> [email-masked]<mailto:[email-masked]>
>> > >> <https://www.ietf.org/mailman/listinfo/oauth> https://www.ietf.org/mailman/listinfo/oauth
>> > > <mailto:[email-masked]> [email-masked]<mailto:[email-masked]>
>> > > <https://www.ietf.org/mailman/listinfo/oauth> https://www.ietf.org/mailman/listinfo/oauth
>> > >
>> >
>> >
>> >
>>
>> <mailto:[email-masked]> [email-masked]<mailto:[email-masked]>
>> <https://www.ietf.org/mailman/listinfo/oauth> https://www.ietf.org/mailman/listinfo/oauth
>
>
> <mailto:[email-masked]> [email-masked]<mailto:[email-masked]>
> <https://www.ietf.org/mailman/listinfo/oauth> https://www.ietf.org/mailman/listinfo/oauth
>
>
_______________________________________________
OAuth mailing list
<mailto:[email-masked]>[email-masked]<mailto:[email-masked]>
<https://www.ietf.org/mailman/listinfo/oauth>https://www.ietf.org/mailman/listinfo/oauth

<ATT00001..txt>

---

From: "Manger, James H" <[email-masked]>
Date: Wed, 21 Apr 2010 10:04:50 +1000

+1 to JSON as the one and only response format.

It is common enough. It is simple enough. It is flexible enough. It is unambiguously specified enough.

I suggested a structure in the “application/credentials” thread.

http://www.ietf.org/mail-archive/web/oauth/current/msg01920.html

--

James Manger

---

From: Torsten Lodderstedt <[email-masked]>
Date: Wed, 21 Apr 2010 07:43:26 +0200

I'm indetermined. Using JSON exclusively instead of form encoded 
parameters would give us the possibility to use structured parameters 
(in and outbound) instead of a flat parameter list, which I would like 
very much. But there are propably use cases where form encoded 
parameters are better suited.

regards,
Torsten.

---

From: Gaurav Rastogi <[email-masked]>
Date: Wed, 21 Apr 2010 11:36:40 -0700

+1 on not requiring JSON exclusively. There are enough number of small embedded software stack where JSON is not an option.

---

From: Torsten Lodderstedt <[email-masked]>
Date: Sat, 24 Apr 2010 09:44:50 +0200

> There seems to be support for this idea with some concerns about complexity. Someone needs to propose text for this including defining the request parameter and schema of the various reply formats.

I would like to prepare some text. Beforehand, I would like to discuss 
some ideas in order to come to a rough consensous.

Basically, I would suggest to only consider cases where the 
implementation platform does not directly support URI query parameter 
decoding. From my point of view, this are all HTTP responses a client 
will need to process. All request parameters, e.g. redirect back to the 
web server in the web server flow, will still be delivered as 
"application/x-www-form-urlencoded" only, since the web container 
automatically prepares this parameters for easy access in the web 
application.

I have compiled a list of candidates:

3.5.1.  User-Agent Flow
3.5.1.1.  Client Requests Authorization

fragement of the redirect URL. Change this to base64 encoded XML/JSON, 
desired format as request parameter

3.5.2.  Web Server Flow
3.5.2.2.  Client Requests Access Token

response formats: application/x-www-form-urlencoded, application/xml, or 
application/json
desired format as request parameter
response mime type indicates response format

3.5.3.  Device Flow
3.5.3.1.  Client Requests Authorization

proposal see 3.5.2.2.  Client Requests Access Token

3.5.3.2.  Client Requests Access Token

proposal see 3.5.2.2.  Client Requests Access Token

3.6.1.  Username and Password Flow
3.6.1.1.  Client Requests Access Token

proposal see 3.5.2.2.  Client Requests Access Token

3.7.1.  Client Credentials Flow
3.7.1.1.  Client Requests Access Token

proposal see 3.5.2.2.  Client Requests Access Token

3.7.2.  Assertion Flow
3.7.2.1.  Client Requests Access Token

proposal see 3.5.2.2.  Client Requests Access Token

4.  Refreshing an Access Token

proposal see 3.5.2.2.  Client Requests Access Token

Any comments?

regards,
Torsten.

---

From: Torsten Lodderstedt <[email-masked]>
Date: Wed, 28 Apr 2010 21:03:54 +0200

no one interested any longer in this topic? I would like to prepare a 
proposal, but I need some feedback.

regards,
Torsten.

Am 24.04.2010 09:44, schrieb Torsten Lodderstedt:
>> complexity. Someone needs to propose text for this including defining 
>> the request parameter and schema of the various reply formats.
>>
>
> will need to process. All request parameters, e.g. redirect back to 
> the web server in the web server flow, will still be delivered as 
> response formats: application/x-www-form-urlencoded, application/xml, 
> or application/json

---

From: Joseph Smarr <[email-masked]>
Date: Wed, 28 Apr 2010 17:25:27 -0400

I agree we need JSON formatting for all the currently url-encoded responses,
but not for the requests, since that stuff will be handled by normal web
servers. That's all you were saying right? We still need a proposed format
for the JSON, but my strawman would just be take all the key/value pairs
returned currently and encode them as one flat JSON object with those same
exact key/value pairs.

So, using the example in 3.5.2.2, instead of the response body being:

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

It would be:

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

Any reason that wouldn't work?

Thanks, js

On Wed, Apr 28, 2010 at 3:03 PM, Torsten Lodderstedt <
[email-masked]> wrote:

>> Basically, I would suggest to only consider cases where the implementation
>> platform does not directly support URI query parameter decoding. From my
>> point of view, this are all HTTP responses a client will need to process.
>> All request parameters, e.g. redirect back to the web server in the web
>> server flow, will still be delivered as "application/x-www-form-urlencoded"
>> only, since the web container automatically prepares this parameters for
>> easy access in the web application.
>>

---

From: Robert Sayre <[email-masked]>
Date: Wed, 28 Apr 2010 23:44:19 -0400

> Any reason that wouldn't work?

Form encoding allows duplicate keys. So, transforming such message
bodies to JSON should be defined.

But, really, I think the group should just pick one and avoid the
hassle. I would pick JSON, since JSON implementations bring reasonable
Unicode conformance.

-- 

Robert Sayre

"I would have written a shorter letter, but I did not have the time."

---

From: Torsten Lodderstedt <[email-masked]>
Date: Thu, 29 Apr 2010 21:45:39 +0200

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

    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

    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

    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

---

From: Yaron Goland <[email-masked]>
Date: Thu, 29 Apr 2010 20:49:08 +0000

Can we please just have one format, not 3? The more choices we give the more interoperability suffers.

> Of Torsten Lodderstedt
> Sent: Thursday, April 29, 2010 12:46 PM
> To: Robert Sayre
> Cc: [email-masked]; [email-masked]
> (Proposal)
> formats to the specification. I have taken the current version of the draft
> 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
> 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
>     The client obtains an access token from the authorization server by <snip>
>     secret_type
> specifying one of the following mime types: application/x-www-form-
> urlencoded,
> application/xml,
> 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
>           errors to the client. The parameter value MUST be set to "text/xml",
> requested mime type.
> http://example.com/rd#oauth_response=%7B+%22access_token%22%3A+
> %22SlAV32hkKG%22%2C+%22expires_in%22%3A+%223600%22%2C+%22refr
> esh_token%22%3A+%228xLOxBtZp8%22+%7D
> 
> 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%3Cacce
> ss_token%3ESlAV32hkKG%3Cexpires_in%3E3600%3C%2Fexpires_in%3E%3Cr
> efresh_token%3E8xLOxBtZp8%3C%2Frefresh_token%3E%3C%2Ftoken_resp
> onse%3E
> 
>     "application/x-www-form-urlencoded": All parameter are directly added as
> http://example.com/rd#access_token=FJQbwq9&expires_in=3600
>

---

From: Mike Moore <[email-masked]>
Date: Thu, 29 Apr 2010 15:40:40 -0600

> more interoperability suffers.

+∞

> Accept
> the

---

From: Brian Eaton <[email-masked]>
Date: Thu, 29 Apr 2010 15:09:33 -0700

>> more interoperability suffers.

Yes.  The number of parsers needed to make a working system is
important.  The spec has too many already.

I'd like to see authorization servers returning JSON or XML, since
that's what the resource servers are doing.

...and given a choice between JSON and XML, I'd pick JSON.

Cheers,
Brian

---

From: Marius Scurtescu <[email-masked]>
Date: Thu, 29 Apr 2010 17:22:09 -0700

>     redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Why not allow the request to be JSON encoded as well?

The only non-JSON requests and responses are those that go through the
User Agent as query parameters. How about encoding with JSON in these
cases as well and putting the whole JSON blob into a query parameter
named like oauth_request/oauth_response? This would make all
requests/responses  consistent and eliminate possible collisions.

Do we still have to support application/x-www-form-urlencoded?

Marius

---

From: "Manger, James H" <[email-masked]>
Date: Fri, 30 Apr 2010 11:50:57 +1000

> multiple response formats

Quite a few people (most?) have (often strongly) favoured a single response format, and most of them prefer JSON. I agree: JSON for responses, application/x-www-form-urlencoded for requests.

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

I hope we can reduce the duplication by describing the format once only.

> parameters are encoded straight-forward as flat JSON object

It would be better to use the basic JSON types, not just strings for everything.
For instance, 
  "expires_in": 3600
Instead of
  "expires_in": "3600"
Forcing all values to be strings may simplify mapping between multiple formats, but it hinders idiomatic use of the formats (which is important). This is another reason to pick a single format.

> application/json

There are lots of application/XXXX+xml media types that are better to use than the generic application/xml. <http://tools.ietf.org/html/rfc3023#appendix-A>
Is the same true for JSON?
I think an application/credential media type would be more helpful (perhaps with a "+json" suffix if that is common practise).

--
James Manger

---

From: Torsten Lodderstedt <[email-masked]>
Date: Fri, 30 Apr 2010 10:59:35 +0200

> ...and given a choice between JSON and XML, I'd pick JSON.

I agree. At Deutsche Telekom, we try to align our authorization APIs with the
APIs provided by the resource servers. Authorization is "just" a small, but
important, portion of the overall process and aligning it with the rest
increases acceptance and decreases error rate.

None of the APIs we provide uses form encoding, most of them use JSON,  
some XML.
Based on that observation I would like to see at least JSON support in OAuth.
So JSON as the only would be fine with me.

My proposal is based on the observation that the WG did not come to a  
consensus
about the one and only format.

I have collected the following opinions from the thread:

pro additional support for JSON and XML - Marius Scurtescu, John  
Jawed, Richard Barnes, Brian Eaton, Torsten Lodderstedt
pro additional support for JSON - Dick Hardt (initiated the thread),  
Joseph Smarr
still support application/x-www-form-urlencoded (unclear whether  
exclusively) - David Recordon, Gaurav Rastogi
one format only (preference unclear) - Yaron Goland
JSON as the only format (if forced to decide for a single format) -  
Brian Eaton, Torsten Lodderstedt
JSON as the only format - James Manger, Robert Sayre
application/x-www-form-urlencoded as the only format - Mike Moore
JSON for responses as well - Marius Scurtescu

Here are some representative comments from the thread:

Joseph Smarr - "JSON is already widely supported (presumably including  
by most APIs that you're building OAuth support to be able to access!"

David Recordon - "it's drastically more complex for environments (like  
embedded hardware)
which doesn't support JSON."

Paul C. Bryan - "I'm struggling to imagine hardware that on the one  
hand would support
OAuth, but on the other would be incapable of supporting JSON..."

Gaurav Rastogi - "There are enough number of small embedded software  
stack where JSON is not an option."

So we have at least 9 votes pro JSON, but also 1 vote for  
application/x-www-form-urlencoded only.

How shall we proceed? Can we come to a consensus?

regards,
Torsten.

---

From: Yaron Goland <[email-masked]>
Date: Fri, 30 Apr 2010 16:02:31 +0000

I actually have a preference for application/x-www-form-urlencoded but it's not overwhelming, the key thing I believe we need to do is have exactly one request/response format. In other words, I don't believe we should use one format for requests and another for responses. Just pick one for both.
	Thanks,
		Yaron

> Sent: Friday, April 30, 2010 2:00 AM
> To: Brian Eaton
> Cc: [email-masked]
> consensus about the one and only format.
> 
> pro additional support for JSON and XML - Marius Scurtescu, John Jawed,
> Richard Barnes, Brian Eaton, Torsten Lodderstedt pro additional support for
> JSON - Dick Hardt (initiated the thread), Joseph Smarr still support
> application/x-www-form-urlencoded (unclear whether
> exclusively) - David Recordon, Gaurav Rastogi one format only (preference
> unclear) - Yaron Goland JSON as the only format (if forced to decide for a
> single format) - Brian Eaton, Torsten Lodderstedt JSON as the only format -
> James Manger, Robert Sayre application/x-www-form-urlencoded as the
> only format - Mike Moore JSON for responses as well - Marius Scurtescu
> 
> Joseph Smarr - "JSON is already widely supported (presumably including by
> most APIs that you're building OAuth support to be able to access!"
> 
> embedded hardware) which doesn't support JSON."
> 
> Paul C. Bryan - "I'm struggling to imagine hardware that on the one hand
> would support OAuth, but on the other would be incapable of supporting
> JSON..."
> 
> So we have at least 9 votes pro JSON, but also 1 vote for application/x-www-
> form-urlencoded only.
>

---

From: Mike Moore <[email-masked]>
Date: Fri, 30 Apr 2010 10:12:32 -0600

I fully agree with Yaron. My preference for x-www-form-urlencoded is slight,
and mostly because I haven't seen a compelling reason to change. I'm fine
with choosing JSON (or even XML) as long as there is one format.

On Fri, Apr 30, 2010 at 10:02 AM, Yaron Goland <[email-masked]> wrote:

> I actually have a preference for application/x-www-form-urlencoded but it's
> not overwhelming, the key thing I believe we need to do is have exactly one
> request/response format. In other words, I don't believe we should use one
> format for requests and another for responses. Just pick one for both.
>        Thanks,
>                 Yaron
>

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 30 Apr 2010 10:12:53 -0700

I don't think the two are related. Request format is based on common HTTP request practice and is built-in every web client. Adding a list of parameters to a request URI is trivial. Response format on the other hand is less consistent on the client and we can improve this by specifying a well-define serialization.

I don't care about which format to use or whether we support more than one.

EHL

> Of Yaron Goland
> Sent: Friday, April 30, 2010 9:03 AM
> To: Torsten Lodderstedt; Brian Eaton
> Cc: [email-masked]
> > >> On Thu, Apr 29, 2010 at 2:49 PM, Yaron Goland
> > >> <[email-masked]>
> > wrote:
> > >>>
> > I agree. At Deutsche Telekom, we try to align our authorization APIs
> > with the APIs provided by the resource servers. Authorization is
> > "just" a small, but important, portion of the overall process and
> > aligning it with the rest increases acceptance and decreases error rate.
> >
> > Jawed, Richard Barnes, Brian Eaton, Torsten Lodderstedt pro additional
> > support for JSON - Dick Hardt (initiated the thread), Joseph Smarr
> > unclear) - Yaron Goland JSON as the only format (if forced to decide
> > for a single format) - Brian Eaton, Torsten Lodderstedt JSON as the
> > only format - James Manger, Robert Sayre
> > hand would support OAuth, but on the other would be incapable of
> > supporting JSON..."
> >
> > application/x-www- form-urlencoded only.
> >

---

From: Mike Moore <[email-masked]>
Date: Fri, 30 Apr 2010 11:22:17 -0600

On Fri, Apr 30, 2010 at 11:12 AM, Eran Hammer-Lahav <[email-masked]>wrote:

> I don't think the two are related. Request format is based on common HTTP
> request practice and is built-in every web client. Adding a list of
> parameters to a request URI is trivial. Response format on the other hand is
> less consistent on the client and we can improve this by specifying a
> well-define serialization.
>

Oops, I misread Yaron's message. I thought this was only about the response
format. I agree the request format should stay as it is.

> I don't care about which format to use or whether we support more than one.

Agreed.

---

From: Allen Tom <[email-masked]>
Date: Fri, 30 Apr 2010 11:45:16 -0700

> interoperability suffers.

+1

I vote for JSON, and I'm not a fan of XML, however my main preference is
that we just pick one.

One of the primary goals of OAuth-WRAP was to make things simple - and
having more than one way to express the same thing increases complexity and
reduces interop.

Allen

---

From: Dick Hardt <[email-masked]>
Date: Fri, 30 Apr 2010 18:48:43 -0700

> I actually have a preference for application/x-www-form-urlencoded but it's not overwhelming, the key thing I believe we need to do is have exactly one request/response format. In other words, I do…

Using JSON for both seems weird relative to existing implementations. Look at the Facebook Open Graph API. Given FB's presence, a pattern that will be widely adopted and understood. Parameters are on the query line, and results are in JSON. If we changed the response from the AS to JSON, it would seem natural to a FB developer. Now they have to decode responses to the AS as being  application/x-www-form-urlencoded, and the other are JSON.

-- Dick

---

From: Dick Hardt <[email-masked]>
Date: Fri, 30 Apr 2010 18:50:32 -0700

Given how simple the JSON response object would be, I don't think it would be much harder to write a parser than  application/x-www-form-urlencoded.

If the embedded software is going to call Facebook's Open Graph API or many other modern API's, it will need a JSON parser anyway.

-- Dick

---

From: Dick Hardt <[email-masked]>
Date: Fri, 30 Apr 2010 18:51:02 -0700

> All the issues around encoding in 1.0 were about signatures. This is no longer an issue. 

Don't we still support signatures? I still see if in the spec. :)

-- Dick

---

From: Dick Hardt <[email-masked]>
Date: Fri, 30 Apr 2010 18:51:32 -0700

+1 to JSON being the only format.

On 2010-04-20, at 9:24 AM, Joseph Smarr wrote:

> +1 to including JSON format, and perhaps making it the required format. In my experience helping numerous developers debug their OAuth implementations, url-encoding/decoding was often a source of bugs, since a) the libraries are usually hand-built, b) url-encoding is known to be funky/inconsistent wrt + vs. %20 and other such things, and c) it's very sensitive to things like a trailing newline at the end of the response, which can easily be tokenized as part of the the last value (since the normal implementations just split on & and =). In contrast, I've never heard of any problems parsing JSON, nor any encoding/decoding bugs related to working with JSON in other APIs (something I *cannot* say about XML, which is way more finicky about requiring its values to be properly encoded or escaped in CDATA etc.; I've also seen way more inconsistency in support of XML parsers and their output formats, whereas JSON always works exactly the same way and always "just works").
> 
> So in conclusion, url-encoding has caused a lot of pain in OAuth 1.0, and JSON is already widely supported (presumably including by most APIs that you're building OAuth support to be able to access!), so I think it would simplify the spec and increase ease/success of development to use JSON as a request format. In fact, I think I'd like to push for it to be the default/required format, given the positive attributes above. Does anyone object, and if so, why?
> 
> Thanks, js
> 
> On Tue, Apr 20, 2010 at 8:10 AM, Eran Hammer-Lahav <[email-masked]> wrote:

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 30 Apr 2010 19:32:28 -0700

Well, take a look at the current proposal and tell me if encoding is still an issue...

EHL

> From: Dick Hardt [mailto:[email-masked]]
> Sent: Friday, April 30, 2010 6:51 PM
> To: Eran Hammer-Lahav
> Cc: [email-masked]; OAuth WG

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 30 Apr 2010 19:33:26 -0700

If we end up with JSON as the only *core* format, we can still extend the protocol in another spec to add a format request parameter with other serializations.

EHL

From: Dick Hardt [mailto:[email-masked]]
Sent: Friday, April 30, 2010 6:52 PM
To: [email-masked]
Cc: Eran Hammer-Lahav; OAuth WG
Subject: Re: [OAUTH-WG] application/x-www-form-urlencoded vs JSON

Thanks, js
On Tue, Apr 20, 2010 at 8:10 AM, Eran Hammer-Lahav <[email-masked]<mailto:[email-masked]>> wrote:
There seems to be support for this idea with some concerns about complexity. Someone needs to propose text for this including defining the request parameter and schema of the various reply formats.

EHL

> From: Torsten Lodderstedt [mailto:[email-masked]<mailto:[email-masked]>]
> >> From: [email-masked]<mailto:[email-masked]> [mailto:[email-masked]<mailto:[email-masked]>] On
> >> Behalf Of Dick Hardt
> >> [email-masked]<mailto:[email-masked]>
> > [email-masked]<mailto:[email-masked]>

_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth

_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth