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

[Mike Moore <[e-mail]>]

On Thu, Apr 29, 2010 at 2:49 PM, Yaron Goland <[e-mail]> wrote:

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


+∞


> > -----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
>
> _______________________________________________
> OAuth mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/oauth
>