< draft-hammer-oauth-09.txt   draft-hammer-oauth-10.txt >
Network Working Group E. Hammer-Lahav, Ed. Network Working Group E. Hammer-Lahav, Ed.
Internet-Draft February 4, 2010 Internet-Draft February 5, 2010
Intended status: Informational Intended status: Informational
Expires: August 8, 2010 Expires: August 9, 2010
The OAuth 1.0 Protocol The OAuth 1.0 Protocol
draft-hammer-oauth-09 draft-hammer-oauth-10
Abstract Abstract
OAuth provides a method for clients to access server resources on OAuth provides a method for clients to access server resources on
behalf of a resource owner (such as a different client or an end- behalf of a resource owner (such as a different client or an end-
user). It also provides a process for end-users to authorize third- user). It also provides a process for end-users to authorize third-
party access to their server resources without sharing their party access to their server resources without sharing their
credentials (typically, a username and password pair), using user- credentials (typically, a username and password pair), using user-
agent redirections. agent redirections.
skipping to change at page 1, line 41 skipping to change at page 1, line 41
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."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 8, 2010. This Internet-Draft will expire on August 9, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 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 3, line 9 skipping to change at page 3, line 9
4.10. Denial of Service / Resource Exhaustion Attacks . . . . . 33 4.10. Denial of Service / Resource Exhaustion Attacks . . . . . 33
4.11. SHA-1 Cryptographic Attacks . . . . . . . . . . . . . . . 34 4.11. SHA-1 Cryptographic Attacks . . . . . . . . . . . . . . . 34
4.12. Signature Base String Limitations . . . . . . . . . . . . 34 4.12. Signature Base String Limitations . . . . . . . . . . . . 34
4.13. Cross-Site Request Forgery (CSRF) . . . . . . . . . . . . 34 4.13. Cross-Site Request Forgery (CSRF) . . . . . . . . . . . . 34
4.14. User Interface Redress . . . . . . . . . . . . . . . . . . 35 4.14. User Interface Redress . . . . . . . . . . . . . . . . . . 35
4.15. Automatic Processing of Repeat Authorizations . . . . . . 35 4.15. Automatic Processing of Repeat Authorizations . . . . . . 35
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36
6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 36 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 36
Appendix A. Differences from the Community Edition . . . . . . . 36 Appendix A. Differences from the Community Edition . . . . . . . 36
Appendix B. Document History . . . . . . . . . . . . . . . . . . 37 Appendix B. Document History . . . . . . . . . . . . . . . . . . 37
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 40 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.1. Normative References . . . . . . . . . . . . . . . . . . . 40 7.1. Normative References . . . . . . . . . . . . . . . . . . . 41
7.2. Informative References . . . . . . . . . . . . . . . . . . 41 7.2. Informative References . . . . . . . . . . . . . . . . . . 41
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 41 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 42
1. Introduction 1. Introduction
The OAuth protocol was originally created by a small community of web The OAuth protocol was originally created by a small community of web
developers from a variety of websites and other Internet services, developers from a variety of websites and other Internet services,
who wanted to solve the common problem of enabling delegated access who wanted to solve the common problem of enabling delegated access
to protected resources. The resulting OAuth protocol was stabilized to protected resources. The resulting OAuth protocol was stabilized
at version 1.0 in October 2007, revised in June 2009, and published at version 1.0 in October 2007, revised in June 2009, and published
as [OAuth Core 1.0 Revision A]. as [OAuth Core 1.0 Revision A].
skipping to change at page 7, line 18 skipping to change at page 7, line 18
Token Request URI: Token Request URI:
https://photos.example.net/token https://photos.example.net/token
Before 'printer.example.com' can ask Jane to grant it access to the Before 'printer.example.com' can ask Jane to grant it access to the
photos, it must first establish a set of temporary credentials with photos, it must first establish a set of temporary credentials with
'photos.example.net' to identify the delegation request. To do so, 'photos.example.net' to identify the delegation request. To do so,
the client sends the following HTTPS [RFC2818] request to the server: the client sends the following HTTPS [RFC2818] request to the server:
POST /initiate HTTP/1.1 POST /initiate HTTP/1.1
Host: photos.example.net Host: photos.example.net
Authorization: OAuth realm="http://photos.example.net/", Authorization: OAuth realm="Photos",
oauth_consumer_key="dpf43f3p2l4k3l03", oauth_consumer_key="dpf43f3p2l4k3l03",
oauth_signature_method="HMAC-SHA1", oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131200", oauth_timestamp="137131200",
oauth_nonce="wIjqoS", oauth_nonce="wIjqoS",
oauth_callback="http%3A%2F%2Fprinter.example.com%2Fready", oauth_callback="http%3A%2F%2Fprinter.example.com%2Fready",
oauth_signature="74KNZJeDHnMBp0EMJ9ZHt%2FXKycU%3D" oauth_signature="74KNZJeDHnMBp0EMJ9ZHt%2FXKycU%3D"
The server validates the request and replies with a set of temporary The server validates the request and replies with a set of temporary
credentials in the body of the HTTP response (line breaks are for credentials in the body of the HTTP response (line breaks are for
display purposes only): display purposes only):
skipping to change at page 8, line 12 skipping to change at page 8, line 12
http://printer.example.com/ready? http://printer.example.com/ready?
oauth_token=hh5s93j4hdidpola&oauth_verifier=hfdp7dh39dks9884 oauth_token=hh5s93j4hdidpola&oauth_verifier=hfdp7dh39dks9884
The callback request informs the client that Jane completed the The callback request informs the client that Jane completed the
authorization process. The client then requests a set of token authorization process. The client then requests a set of token
credentials using its temporary credentials (over a secure TLS credentials using its temporary credentials (over a secure TLS
channel): channel):
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: photos.example.net Host: photos.example.net
Authorization: OAuth realm="http://photos.example.net/", Authorization: OAuth realm="Photos",
oauth_consumer_key="dpf43f3p2l4k3l03", oauth_consumer_key="dpf43f3p2l4k3l03",
oauth_token="hh5s93j4hdidpola", oauth_token="hh5s93j4hdidpola",
oauth_signature_method="HMAC-SHA1", oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131201", oauth_timestamp="137131201",
oauth_nonce="walatlh", oauth_nonce="walatlh",
oauth_verifier="hfdp7dh39dks9884", oauth_verifier="hfdp7dh39dks9884",
oauth_signature="gKgrFCywp7rO0OXSjdot%2FIHF7IU%3D" oauth_signature="gKgrFCywp7rO0OXSjdot%2FIHF7IU%3D"
The server validates the request and replies with a set of token The server validates the request and replies with a set of token
credentials in the body of the HTTP response: credentials in the body of the HTTP response:
skipping to change at page 8, line 34 skipping to change at page 8, line 34
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
oauth_token=nnch734d00sl2jdk&oauth_token_secret=pfkkdhi9sl3r4s00 oauth_token=nnch734d00sl2jdk&oauth_token_secret=pfkkdhi9sl3r4s00
With a set of token credentials, the client is now ready to request With a set of token credentials, the client is now ready to request
the private photo: the private photo:
GET /photos?file=vacation.jpg&size=original HTTP/1.1 GET /photos?file=vacation.jpg&size=original HTTP/1.1
Host: photos.example.net Host: photos.example.net
Authorization: OAuth realm="http://photos.example.net/", Authorization: OAuth realm="Photos",
oauth_consumer_key="dpf43f3p2l4k3l03", oauth_consumer_key="dpf43f3p2l4k3l03",
oauth_token="nnch734d00sl2jdk", oauth_token="nnch734d00sl2jdk",
oauth_signature_method="HMAC-SHA1", oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131202", oauth_timestamp="137131202",
oauth_nonce="chapoH", oauth_nonce="chapoH",
oauth_signature="MdpQcU8iPSUjWoN%2FUDMsK2sui9I%3D" oauth_signature="MdpQcU8iPSUjWoN%2FUDMsK2sui9I%3D"
The 'photos.example.net' server validates the request and responds The 'photos.example.net' server validates the request and responds
with the requested photo. 'printer.example.com' is able to continue with the requested photo. 'printer.example.com' is able to continue
accessing Jane's private photos using the same set of token accessing Jane's private photos using the same set of token
skipping to change at page 11, line 11 skipping to change at page 11, line 11
Since the request results in the transmission of plain text Since the request results in the transmission of plain text
credentials in the HTTP response, the server MUST require the use of credentials in the HTTP response, the server MUST require the use of
a transport-layer mechanisms such as TLS or SSL (or a secure channel a transport-layer mechanisms such as TLS or SSL (or a secure channel
with equivalent protections). with equivalent protections).
For example, the client makes the following HTTPS request: For example, the client makes the following HTTPS request:
POST /request_temp_credentials HTTP/1.1 POST /request_temp_credentials HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: OAuth realm="http://server.example.com/", Authorization: OAuth realm="Example",
oauth_consumer_key="jd83jd92dhsh93js", oauth_consumer_key="jd83jd92dhsh93js",
oauth_signature_method="PLAINTEXT", oauth_signature_method="PLAINTEXT",
oauth_callback="http%3A%2F%2Fclient.example.net%2Fcb%3Fx%3D1", oauth_callback="http%3A%2F%2Fclient.example.net%2Fcb%3Fx%3D1",
oauth_signature="ja893SD9%26" oauth_signature="ja893SD9%26"
The server MUST verify (Section 3.2) the request and if valid, The server MUST verify (Section 3.2) the request and if valid,
respond back to the client with a set of temporary credentials (in respond back to the client with a set of temporary credentials (in
the form of an identifier and shared-secret). The temporary the form of an identifier and shared-secret). The temporary
credentials are included in the HTTP response body using the credentials are included in the HTTP response body using the
"application/x-www-form-urlencoded" content type as defined by "application/x-www-form-urlencoded" content type as defined by
skipping to change at page 14, line 10 skipping to change at page 14, line 10
Since the request results in the transmission of plain text Since the request results in the transmission of plain text
credentials in the HTTP response, the server MUST require the use of credentials in the HTTP response, the server MUST require the use of
a transport-layer mechanisms such as TLS or SSL (or a secure channel a transport-layer mechanisms such as TLS or SSL (or a secure channel
with equivalent protections). with equivalent protections).
For example, the client makes the following HTTPS request: For example, the client makes the following HTTPS request:
POST /request_token HTTP/1.1 POST /request_token HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: OAuth realm="http://server.example.com/", Authorization: OAuth realm="Example",
oauth_consumer_key="jd83jd92dhsh93js", oauth_consumer_key="jd83jd92dhsh93js",
oauth_token="hdk48Djdsa",
oauth_signature_method="PLAINTEXT", oauth_signature_method="PLAINTEXT",
oauth_verifier="473f82d3", oauth_verifier="473f82d3",
oauth_signature="ja893SD9%26xyz4992k83j47x0b" oauth_signature="ja893SD9%26xyz4992k83j47x0b"
The server MUST verify (Section 3.2) the validity of the request, The server MUST verify (Section 3.2) the validity of the request,
ensure that the resource owner has authorized the provisioning of ensure that the resource owner has authorized the provisioning of
token credentials to the client, and ensure that the temporary token credentials to the client, and ensure that the temporary
credentials have not expired or been used before. The server MUST credentials have not expired or been used before. The server MUST
also verify the verification code received from the client. If the also verify the verification code received from the client. If the
request is valid and authorized, the token credentials are included request is valid and authorized, the token credentials are included
skipping to change at page 17, line 19 skipping to change at page 17, line 19
oauth_consumer_key: 9djdj82h48djs9d2 oauth_consumer_key: 9djdj82h48djs9d2
oauth_token: kkk9d7dh3k39sjv7 oauth_token: kkk9d7dh3k39sjv7
oauth_signature_method: HMAC-SHA1 oauth_signature_method: HMAC-SHA1
oauth_timestamp: 137131201 oauth_timestamp: 137131201
oauth_nonce: 7d8f3e4a oauth_nonce: 7d8f3e4a
The client adds the protocol parameters to the request using the The client adds the protocol parameters to the request using the
OAuth HTTP Authorization header field: OAuth HTTP Authorization header field:
Authorization: OAuth realm="http://example.com/", Authorization: OAuth realm="Example",
oauth_consumer_key="9djdj82h48djs9d2", oauth_consumer_key="9djdj82h48djs9d2",
oauth_token="kkk9d7dh3k39sjv7", oauth_token="kkk9d7dh3k39sjv7",
oauth_signature_method="HMAC-SHA1", oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131201", oauth_timestamp="137131201",
oauth_nonce="7d8f3e4a" oauth_nonce="7d8f3e4a"
Then calculates the value of the "oauth_signature" parameter, adds it Then calculates the value of the "oauth_signature" parameter, adds it
to the request, and sends the HTTP request to the server: to the request, and sends the HTTP request to the server:
GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1 GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
Authorization: OAuth realm="http://example.com/", Authorization: OAuth realm="Example",
oauth_consumer_key="9djdj82h48djs9d2", oauth_consumer_key="9djdj82h48djs9d2",
oauth_token="kkk9d7dh3k39sjv7", oauth_token="kkk9d7dh3k39sjv7",
oauth_signature_method="HMAC-SHA1", oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131201", oauth_timestamp="137131201",
oauth_nonce="7d8f3e4a", oauth_nonce="7d8f3e4a",
oauth_signature="djosJKDKJSD8743243%2Fjdk33klY%3D" oauth_signature="djosJKDKJSD8743243%2Fjdk33klY%3D"
c2&a3=2+q c2&a3=2+q
3.2. Verifying Requests 3.2. Verifying Requests
skipping to change at page 20, line 43 skipping to change at page 20, line 43
4. An "&" character (ASCII code 38). 4. An "&" character (ASCII code 38).
5. The request parameters as normalized in Section 3.4.1.3.2, after 5. The request parameters as normalized in Section 3.4.1.3.2, after
being encoded (Section 3.6). being encoded (Section 3.6).
For example, the HTTP request: For example, the HTTP request:
GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1 GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
Authorization: OAuth realm="http://example.com/", Authorization: OAuth realm="Example",
oauth_consumer_key="9djdj82h48djs9d2", oauth_consumer_key="9djdj82h48djs9d2",
oauth_token="kkk9d7dh3k39sjv7", oauth_token="kkk9d7dh3k39sjv7",
oauth_signature_method="HMAC-SHA1", oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131201", oauth_timestamp="137131201",
oauth_nonce="7d8f3e4a", oauth_nonce="7d8f3e4a",
oauth_signature="djosJKDKJSD8743243%2Fjdk33klY%3D" oauth_signature="djosJKDKJSD8743243%2Fjdk33klY%3D"
c2&a3=2+q c2&a3=2+q
Is represented by the following signature base string (line breaks Is represented by the following signature base string (line breaks
skipping to change at page 23, line 10 skipping to change at page 23, line 10
The "oauth_signature" parameter MUST be excluded from the signature The "oauth_signature" parameter MUST be excluded from the signature
base string if present. Parameters not explicitly included in the base string if present. Parameters not explicitly included in the
request MUST be excluded from the signature base string (e.g. the request MUST be excluded from the signature base string (e.g. the
"oauth_version" parameter when omitted). "oauth_version" parameter when omitted).
For example, the HTTP request: For example, the HTTP request:
GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1 GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
Authorization: OAuth realm="http://example.com/", Authorization: OAuth realm="Example",
oauth_consumer_key="9djdj82h48djs9d2", oauth_consumer_key="9djdj82h48djs9d2",
oauth_token="kkk9d7dh3k39sjv7", oauth_token="kkk9d7dh3k39sjv7",
oauth_signature_method="HMAC-SHA1", oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131201", oauth_timestamp="137131201",
oauth_nonce="7d8f3e4a", oauth_nonce="7d8f3e4a",
oauth_signature="djosJKDKJSD8743243%2Fjdk33klY%3D" oauth_signature="djosJKDKJSD8743243%2Fjdk33klY%3D"
c2&a3=2+q c2&a3=2+q
Contains the following (fully decoded) parameters used in the Contains the following (fully decoded) parameters used in the
skipping to change at page 28, line 30 skipping to change at page 28, line 30
other methods for including protocol parameters in the request. other methods for including protocol parameters in the request.
3.5.1. Authorization Header 3.5.1. Authorization Header
Protocol parameters can be transmitted using the HTTP "Authorization" Protocol parameters can be transmitted using the HTTP "Authorization"
header field as defined by [RFC2617] with the auth-scheme name set to header field as defined by [RFC2617] with the auth-scheme name set to
"OAuth" (case-insensitive). "OAuth" (case-insensitive).
For example: For example:
Authorization: OAuth realm="http://server.example.com/", Authorization: OAuth realm="Example",
oauth_consumer_key="0685bd9184jfhq22", oauth_consumer_key="0685bd9184jfhq22",
oauth_token="ad180jjd733klru7", oauth_token="ad180jjd733klru7",
oauth_signature_method="HMAC-SHA1", oauth_signature_method="HMAC-SHA1",
oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D", oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
oauth_timestamp="137131200", oauth_timestamp="137131200",
oauth_nonce="4572616e48616d6d65724c61686176", oauth_nonce="4572616e48616d6d65724c61686176",
oauth_version="1.0" oauth_version="1.0"
Protocol parameters SHALL be included in the "Authorization" header Protocol parameters SHALL be included in the "Authorization" header
field as follows: field as follows:
skipping to change at page 37, line 33 skipping to change at page 37, line 33
o Permitted sending requests for temporary credentials with an empty o Permitted sending requests for temporary credentials with an empty
"oauth_token" parameter. "oauth_token" parameter.
o Removed the restrictions from defining additional "oauth_" o Removed the restrictions from defining additional "oauth_"
parameters. parameters.
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. ]]
-10
o Added missing 'oauth_token' in exmaple.
o Changed realm values from URI to string to make them more generic
(since the protocol does not define any internal structure for
them).
-09 -09
o Added 'with a 200 status code (OK)' in two places. o Added 'with a 200 status code (OK)' in two places.
o Missing comma in example. o Missing comma in example.
o Corrected typos. o Corrected typos.
o Changed the use of TLS/SSL when sending or receiving plain text o Changed the use of TLS/SSL when sending or receiving plain text
credentials to a MUST. credentials to a MUST.
skipping to change at page 41, line 29 skipping to change at page 41, line 40
Version 2.1", RFC 3447, February 2003. Version 2.1", RFC 3447, February 2003.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[W3C.REC-html40-19980424] [W3C.REC-html40-19980424]
Jacobs, I., Hors, A., and D. Raggett, "HTML 4.0 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.0
Specification", World Wide Web Consortium Specification", World Wide Web Consortium
Recommendation REC-html40-19980424, April 1998, Recommendation REC-html40-19980424, April 1998,
<http://www.w3.org/TR/1998/REC-html40-19980424>. <http://www.w3.org/TR/1998/REC-html40-19980424>.
7.2. Informative References 7.2. Informative References
[NIST SHA-1 Comments] [NIST SHA-1 Comments]
Burr, W., "NIST Comments on Cryptanalytic Attacks on Burr, W., "NIST Comments on Cryptanalytic Attacks on
SHA-1". SHA-1".
 End of changes. 19 change blocks. 
18 lines changed or deleted 27 lines changed or added

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