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

[Yaron Goland <[e-mail]>]

Every format we add increases the probability of failing to interoperate. 

I believe as a working group we need to specify exactly one format and only one format. That doesn't preclude later extensions that support more formats but if our goal is interoperability then the fewer options the more likely we get interoperability.

So please, just one format.

	Yaron

P.S. My personal vote for that format is urlencoded but I see that as a secondary issue to supporting exactly one format.

> -----Original Message-----
> From: [e-mail] [mailto:[e-mail]] On Behalf
> Of Pid
> Sent: Friday, May 07, 2010 8:46 AM
> To: [e-mail]
> Subject: Re: [OAUTH-WG] application/x-www-form-urlencoded vs JSON
> (Proposal)
> 
> On 07/05/2010 16:28, Eran Hammer-Lahav wrote:
> > This approach seems the most reasonable to me.
> >
> > Server MUST support all three formats.
> > Client MUST support one but MAY support more formats.
> >
> > This puts a little extra work on the server but since this is on the serializing
> side, no parser is needed. On the client side it adds no additional complexity -
> it reduces it because it allows the client to work in its native format (XML,
> JSON, text).
> >
> > Those arguing for a single format have not made a compelling argument
> why having a default format with 2 other optional formats, where the client
> gets complete flexibility on the parsing side is bad or too complex.
> >
> > Again, for the server, this is just a single printf() statement per format:
> >
> > printf("{\"access_token\":\"%s\",\"expires_in\":%d}", token, expires);
> >
> printf("<oauth><access_token>%s</access_token><expires_in>%d</expire
> s_
> > in></oauth>", token, expires);
> >
> > For the client, if they don't like the default, you can use the Accept header
> or a 'format' query parameter.
> >
> > Show me where this is more complex!
> 
> +1  Fair enough.
> 
> Flexibility via multiple formats is an entirely different proposal and one that I
> think is very reasonable.
> 
> I just can't find a way to justify JSON as the only permitted format for
> response body content.
> 
> 
> p
> 
> 
> > EHL
> >
> >> -----Original Message-----
> >> From: [e-mail] [mailto:[e-mail]] On
> >> Behalf Of Torsten Lodderstedt
> >> Sent: Thursday, April 29, 2010 12:46 PM
> >> To: Robert Sayre
> >> Cc: [e-mail]; [e-mail]
> >> Subject: Re: [OAUTH-WG] application/x-www-form-urlencoded vs JSON
> >> (Proposal)
> >>
> >> 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-iet
> >> f-
> >> 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+%22refr
> >> esh_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%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
> >>     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
> >>
> >> _______________________________________________
> >> OAuth mailing list
> >> [e-mail]
> >> https://www.ietf.org/mailman/listinfo/oauth
> > _______________________________________________
> > OAuth mailing list
> > [e-mail]
> > https://www.ietf.org/mailman/listinfo/oauth
>