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

[Eran Hammer-Lahav <[e-mail]>]

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</expires_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!

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-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+%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