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+%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
_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth
