draft-ietf-oauth-v2-bearer-05.txt   draft-ietf-oauth-v2-bearer-06.txt 
Network Working Group M. Jones Network Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track D. Hardt Intended status: Standards Track D. Hardt
Expires: November 22, 2011 independent Expires: December 23, 2011 independent
D. Recordon D. Recordon
Facebook Facebook
May 21, 2011 Jun 21, 2011
The OAuth 2.0 Protocol: Bearer Tokens The OAuth 2.0 Protocol: Bearer Tokens
draft-ietf-oauth-v2-bearer-05 draft-ietf-oauth-v2-bearer-06
Abstract Abstract
This specification describes how to use bearer tokens when accessing This specification describes how to use bearer tokens when accessing
OAuth 2.0 protected resources. OAuth 2.0 protected resources.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
skipping to change at page 1, line 34 skipping to change at page 1, line 34
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 22, 2011. This Internet-Draft will expire on December 23, 2011.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 5, line 51 skipping to change at page 5, line 51
quoted-char = ALPHA / DIGIT / quoted-char = ALPHA / DIGIT /
"!" / "#" / "$" / "%" / "&" / "'" / "(" / ")" / "!" / "#" / "$" / "%" / "&" / "'" / "(" / ")" /
"*" / "+" / "-" / "." / "/" / ":" / "<" / "=" / "*" / "+" / "-" / "." / "/" / ":" / "<" / "=" /
">" / "?" / "@" / "[" / "]" / "^" / "_" / "`" / ">" / "?" / "@" / "[" / "]" / "^" / "_" / "`" /
"{" / "|" / "}" / "~" / "\" / "," / ";" "{" / "|" / "}" / "~" / "\" / "," / ";"
2.2. Form-Encoded Body Parameter 2.2. Form-Encoded Body Parameter
When including the access token in the HTTP request entity-body, the When including the access token in the HTTP request entity-body, the
client adds the access token to the request body using the client adds the access token to the request body using the
"bearer_token" parameter. The client MUST NOT use this method unless "access_token" parameter. The client MUST NOT use this method unless
the following conditions are met: the following conditions are met:
o The HTTP request entity-body is single-part. o The HTTP request entity-body is single-part.
o The entity-body follows the encoding requirements of the o The entity-body follows the encoding requirements of the
"application/x-www-form-urlencoded" content-type as defined by "application/x-www-form-urlencoded" content-type as defined by
[W3C.REC-html401-19991224]. [W3C.REC-html401-19991224].
o The HTTP request entity-header includes the "Content-Type" header o The HTTP request entity-header includes the "Content-Type" header
field set to "application/x-www-form-urlencoded". field set to "application/x-www-form-urlencoded".
o The HTTP request method is one for which a body is permitted to be o The HTTP request method is one for which a body is permitted to be
present in the request. In particular, this means that the "GET" present in the request. In particular, this means that the "GET"
method MUST NOT be used. method MUST NOT be used.
The entity-body can include other request-specific parameters, in The entity-body can include other request-specific parameters, in
which case, the "bearer_token" parameter MUST be properly separated which case, the "access_token" parameter MUST be properly separated
from the request-specific parameters by an "&" character (ASCII code from the request-specific parameters by an "&" character (ASCII code
38). 38).
For example, the client makes the following HTTP request using For example, the client makes the following HTTP request using
transport-layer security: transport-layer security:
POST /resource HTTP/1.1 POST /resource HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
bearer_token=vF9dft4qmT access_token=vF9dft4qmT
The "application/x-www-form-urlencoded" method SHOULD NOT be used The "application/x-www-form-urlencoded" method SHOULD NOT be used
except in application contexts where participating browsers do not except in application contexts where participating browsers do not
have access to the "Authorization" request header field. have access to the "Authorization" request header field.
2.3. URI Query Parameter 2.3. URI Query Parameter
When including the access token in the HTTP request URI, the client When including the access token in the HTTP request URI, the client
adds the access token to the request URI query component as defined adds the access token to the request URI query component as defined
by [RFC3986] using the "bearer_token" parameter. by [RFC3986] using the "access_token" parameter.
For example, the client makes the following HTTP request using For example, the client makes the following HTTP request using
transport-layer security: transport-layer security:
GET /resource?bearer_token=vF9dft4qmT HTTP/1.1 GET /resource?access_token=vF9dft4qmT HTTP/1.1
Host: server.example.com Host: server.example.com
The HTTP request URI query can include other request-specific The HTTP request URI query can include other request-specific
parameters, in which case, the "bearer_token" parameter MUST be parameters, in which case, the "access_token" parameter MUST be
properly separated from the request-specific parameters by an "&" properly separated from the request-specific parameters by an "&"
character (ASCII code 38). character (ASCII code 38).
For example: For example:
http://example.com/resource?x=y&bearer_token=vF9dft4qmT http://example.com/resource?x=y&access_token=vF9dft4qmT
Because of the Security Considerations (Section 3) associated with Because of the Security Considerations (Section 3) associated with
the URI method, it SHOULD NOT be used unless no other method is the URI method, it SHOULD NOT be used unless no other method is
feasible. feasible.
2.4. The WWW-Authenticate Response Header Field 2.4. The WWW-Authenticate Response Header Field
If the protected resource request does not include authentication If the protected resource request does not include authentication
credentials or contains an invalid access token, the resource server credentials or contains an invalid access token, the resource server
MUST include the HTTP "WWW-Authenticate" response header field; it MUST include the HTTP "WWW-Authenticate" response header field; it
skipping to change at page 8, line 34 skipping to change at page 8, line 34
When a request fails, the resource server responds using the When a request fails, the resource server responds using the
appropriate HTTP status code (typically, 400, 401, or 403), and appropriate HTTP status code (typically, 400, 401, or 403), and
includes one of the following error codes in the response: includes one of the following error codes in the response:
invalid_request invalid_request
The request is missing a required parameter, includes an The request is missing a required parameter, includes an
unsupported parameter or parameter value, repeats the same unsupported parameter or parameter value, repeats the same
parameter, uses more than one method for including an access parameter, uses more than one method for including an access
token, or is otherwise malformed. The resource server SHOULD token, or is otherwise malformed. The resource server SHOULD
respond with the HTTP 401 (Unauthorized) status code. respond with the HTTP 400 (Bad Request) status code.
invalid_token invalid_token
The access token provided is expired, revoked, malformed, or The access token provided is expired, revoked, malformed, or
invalid for other reasons. The resource SHOULD respond with invalid for other reasons. The resource SHOULD respond with
the HTTP 401 (Unauthorized) status code. The client MAY the HTTP 401 (Unauthorized) status code. The client MAY
request a new access token and retry the protected resource request a new access token and retry the protected resource
request. request.
insufficient_scope insufficient_scope
The request requires higher privileges than provided by the The request requires higher privileges than provided by the
skipping to change at page 14, line 11 skipping to change at page 14, line 11
Hara, Michael B. Jones, Torsten Lodderstedt, Eve Maler, James Manger, Hara, Michael B. Jones, Torsten Lodderstedt, Eve Maler, James Manger,
Laurence Miao, Chuck Mortimore, Anthony Nadalin, Justin Richer, Peter Laurence Miao, Chuck Mortimore, Anthony Nadalin, Justin Richer, Peter
Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah,
Justin Smith, Jeremy Suriel, Christian Stuebner, Paul Tarjan, and Justin Smith, Jeremy Suriel, Christian Stuebner, Paul Tarjan, and
Franklin Tse. Franklin Tse.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
-06
o Changed parameter name "bearer_token" to "access_token", per
working group consensus.
o Changed HTTP status code for "invalid_request" error code from
HTTP 401 (Unauthorized) back to HTTP 400 (Bad Request), per input
from HTTP working group experts.
-05 -05
o Removed OAuth Errors Registry, per design team input. o Removed OAuth Errors Registry, per design team input.
o Changed HTTP status code for "invalid_request" error code from o Changed HTTP status code for "invalid_request" error code from
HTTP 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP HTTP 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP
usage [[ change pending working group consensus ]]. usage [[ change pending working group consensus ]].
o Added missing quotation marks in error-uri definition. o Added missing quotation marks in error-uri definition.
 End of changes. 13 change blocks. 
12 lines changed or deleted 21 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/