On Thu, Apr 29, 2010 at 2:49 PM, Yaron Goland <yar...@microsoft.com> wrote:
> Can we please just have one format, not 3? The more choices we give the > more interoperability suffers. +∞ > > -----Original Message----- > > From: oauth-boun...@ietf.org [mailto:oauth-boun...@ietf.org] On Behalf > > Of Torsten Lodderstedt > > Sent: Thursday, April 29, 2010 12:46 PM > > To: Robert Sayre > > Cc: jsm...@stanfordalumni.org; oauth@ietf.org > > 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 > > OAuth@ietf.org > > https://www.ietf.org/mailman/listinfo/oauth > > _______________________________________________ > OAuth mailing list > OAuth@ietf.org > https://www.ietf.org/mailman/listinfo/oauth >
_______________________________________________ OAuth mailing list OAuth@ietf.org https://www.ietf.org/mailman/listinfo/oauth
