idnits 2.17.1 draft-hammer-oauth-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 5, 2010) is 5191 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Hammer-Lahav, Ed. 3 Internet-Draft February 5, 2010 4 Intended status: Informational 5 Expires: August 9, 2010 7 The OAuth 1.0 Protocol 8 draft-hammer-oauth-10 10 Abstract 12 OAuth provides a method for clients to access server resources on 13 behalf of a resource owner (such as a different client or an end- 14 user). It also provides a process for end-users to authorize third- 15 party access to their server resources without sharing their 16 credentials (typically, a username and password pair), using user- 17 agent redirections. 19 Status of this Memo 21 This Internet-Draft is submitted to IETF in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt. 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 This Internet-Draft will expire on August 9, 2010. 42 Copyright Notice 44 Copyright (c) 2010 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 61 1.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 1.3. Notational Conventions . . . . . . . . . . . . . . . . . . 9 63 2. Redirection-Based Authorization . . . . . . . . . . . . . . . 9 64 2.1. Temporary Credentials . . . . . . . . . . . . . . . . . . 10 65 2.2. Resource Owner Authorization . . . . . . . . . . . . . . . 12 66 2.3. Token Credentials . . . . . . . . . . . . . . . . . . . . 13 67 3. Authenticated Requests . . . . . . . . . . . . . . . . . . . . 15 68 3.1. Making Requests . . . . . . . . . . . . . . . . . . . . . 15 69 3.2. Verifying Requests . . . . . . . . . . . . . . . . . . . . 17 70 3.3. Nonce and Timestamp . . . . . . . . . . . . . . . . . . . 18 71 3.4. Signature . . . . . . . . . . . . . . . . . . . . . . . . 19 72 3.4.1. Signature Base String . . . . . . . . . . . . . . . . 19 73 3.4.2. HMAC-SHA1 . . . . . . . . . . . . . . . . . . . . . . 26 74 3.4.3. RSA-SHA1 . . . . . . . . . . . . . . . . . . . . . . . 26 75 3.4.4. PLAINTEXT . . . . . . . . . . . . . . . . . . . . . . 27 76 3.5. Parameter Transmission . . . . . . . . . . . . . . . . . . 28 77 3.5.1. Authorization Header . . . . . . . . . . . . . . . . . 28 78 3.5.2. Form-Encoded Body . . . . . . . . . . . . . . . . . . 29 79 3.5.3. Request URI Query . . . . . . . . . . . . . . . . . . 29 80 3.6. Percent Encoding . . . . . . . . . . . . . . . . . . . . . 30 81 4. Security Considerations . . . . . . . . . . . . . . . . . . . 31 82 4.1. RSA-SHA1 Signature Method . . . . . . . . . . . . . . . . 31 83 4.2. Confidentiality of Requests . . . . . . . . . . . . . . . 31 84 4.3. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 31 85 4.4. Proxying and Caching of Authenticated Content . . . . . . 31 86 4.5. Plaintext Storage of Credentials . . . . . . . . . . . . . 32 87 4.6. Secrecy of the Client Credentials . . . . . . . . . . . . 32 88 4.7. Phishing Attacks . . . . . . . . . . . . . . . . . . . . . 32 89 4.8. Scoping of Access Requests . . . . . . . . . . . . . . . . 33 90 4.9. Entropy of Secrets . . . . . . . . . . . . . . . . . . . . 33 91 4.10. Denial of Service / Resource Exhaustion Attacks . . . . . 33 92 4.11. SHA-1 Cryptographic Attacks . . . . . . . . . . . . . . . 34 93 4.12. Signature Base String Limitations . . . . . . . . . . . . 34 94 4.13. Cross-Site Request Forgery (CSRF) . . . . . . . . . . . . 34 95 4.14. User Interface Redress . . . . . . . . . . . . . . . . . . 35 96 4.15. Automatic Processing of Repeat Authorizations . . . . . . 35 97 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 98 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 36 99 Appendix A. Differences from the Community Edition . . . . . . . 36 100 Appendix B. Document History . . . . . . . . . . . . . . . . . . 37 101 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 102 7.1. Normative References . . . . . . . . . . . . . . . . . . . 41 103 7.2. Informative References . . . . . . . . . . . . . . . . . . 41 104 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 42 106 1. Introduction 108 The OAuth protocol was originally created by a small community of web 109 developers from a variety of websites and other Internet services, 110 who wanted to solve the common problem of enabling delegated access 111 to protected resources. The resulting OAuth protocol was stabilized 112 at version 1.0 in October 2007, revised in June 2009, and published 113 as [OAuth Core 1.0 Revision A]. 115 This specification provides an informational documentation of the 116 OAuth 1.0 protocol as revised in [OAuth Core 1.0 Revision A], and 117 includes several errata reported since that time, as well as numerous 118 editorial clarifications. The publication of this specification 119 represents the transfer of change control from the community to the 120 IETF by the authors of the original work. 122 In the traditional client-server authentication model, the client 123 uses its credentials to access its resources hosted by the server. 124 With the increasing use of distributed web services and cloud 125 computing, third-party applications require access to these server- 126 hosted resources. 128 OAuth introduces a third role to the traditional client-server 129 authentication model: the resource owner. In the OAuth model, the 130 client (which is not the resource owner, but is acting on its behalf) 131 requests access to resources controlled by the resource owner, but 132 hosted by the server. In addition, OAuth allows the server to verify 133 not only the resource owner authorization, but also the identity of 134 the client making the request. 136 OAuth provides a method for clients to access server resources on 137 behalf of a resource owner (such as a different client or an end- 138 user). It also provides a process for end-users to authorize third- 139 party access to their server resources without sharing their 140 credentials (typically, a username and password pair), using user- 141 agent redirections. 143 For example, a web user (resource owner) can grant a printing service 144 (client) access to her private photos stored at a photo sharing 145 service (server), without sharing her username and password with the 146 printing service. Instead, she authenticates directly with the photo 147 sharing service which issues the printing service delegation-specific 148 credentials. 150 In order for the client to access resources, it first has to obtain 151 permission from the resource owner. This permission is expressed in 152 the form of a token and matching shared-secret. The purpose of the 153 token is to make it unnecessary for the resource owner to share its 154 credentials with the client. Unlike the resource owner credentials, 155 tokens can be issued with a restricted scope and limited lifetime, 156 and revoked independently. 158 This specification consists of two parts. The first part defines a 159 redirection-based user-agent process for end-users to authorize 160 client access to their resources, by authenticating directly with the 161 server and provisioning tokens to the client for use with the 162 authentication method. The second part defines a method for making 163 authenticated HTTP [RFC2616] requests using two sets of credentials, 164 one identifying the client making the request, and a second 165 identifying the resource owner on whose behalf the request is being 166 made. 168 The use of OAuth with any other transport protocol than [RFC2616] is 169 undefined. 171 1.1. Terminology 173 client 174 An HTTP client (per [RFC2616]) capable of making OAuth- 175 authenticated requests (Section 3). 177 server 178 An HTTP server (per [RFC2616]) capable of accepting OAuth- 179 authenticated requests (Section 3). 181 protected resource 182 An access-restricted resource which can be obtained from the 183 server using an OAuth-authenticated request (Section 3). 185 resource owner 186 An entity capable of accessing and controlling protected 187 resources by using credentials to authenticate with the server. 189 credentials 190 Credentials are a pair of a unique identifier and a matching 191 shared secret. OAuth defines three classes of credentials: 192 client, temporary, and token, used to identify and authenticate 193 the client making the request, the authorization request, and 194 the access grant, respectively. 196 token 197 An unique identifier issued by the server and used by the 198 client to associate authenticated requests with the resource 199 owner whose authorization is requested or has been obtained by 200 the client. Tokens have a matching shared-secret that is used 201 by the client to establish its ownership of the token, and its 202 authority to represent the resource owner. 204 The original community specification used a somewhat different 205 terminology which maps to this specifications as follows (original 206 community terms provided on left): 208 Consumer: client 210 Service Provider: server 212 User: resource owner 214 Consumer Key and Secret: client credentials 216 Request Token and Secret: temporary credentials 218 Access Token and Secret: token credentials 220 1.2. Example 222 Jane (resource owner) has recently uploaded some private vacation 223 photos (protected resources) to her photo sharing site 224 'photos.example.net' (server). She would like to use the 225 'printer.example.com' website (client) to print one of these photos. 226 Typically, Jane signs-into 'photos.example.net' using her username 227 and password. 229 However, Jane does not wish to share her username and password with 230 the 'printer.example.com' website, which needs to access the photo in 231 order to print it. In order to provide its users with better 232 service, 'printer.example.com' has signed-up for a set of 233 'photos.example.net' client credentials ahead of time: 235 Client Identifier 236 dpf43f3p2l4k3l03 238 Client Shared-Secret: 239 kd94hf93k423kf44 241 The 'printer.example.com' website has also configured its application 242 to use the protocol endpoints listed in the 'photos.example.net' API 243 documentation, which use the "HMAC-SHA1" signature method: 245 Temporary Credential Request 246 https://photos.example.net/initiate 248 Resource Owner Authorization URI: 249 https://photos.example.net/authorize 251 Token Request URI: 252 https://photos.example.net/token 254 Before 'printer.example.com' can ask Jane to grant it access to the 255 photos, it must first establish a set of temporary credentials with 256 'photos.example.net' to identify the delegation request. To do so, 257 the client sends the following HTTPS [RFC2818] request to the server: 259 POST /initiate HTTP/1.1 260 Host: photos.example.net 261 Authorization: OAuth realm="Photos", 262 oauth_consumer_key="dpf43f3p2l4k3l03", 263 oauth_signature_method="HMAC-SHA1", 264 oauth_timestamp="137131200", 265 oauth_nonce="wIjqoS", 266 oauth_callback="http%3A%2F%2Fprinter.example.com%2Fready", 267 oauth_signature="74KNZJeDHnMBp0EMJ9ZHt%2FXKycU%3D" 269 The server validates the request and replies with a set of temporary 270 credentials in the body of the HTTP response (line breaks are for 271 display purposes only): 273 HTTP/1.1 200 OK 274 Content-Type: application/x-www-form-urlencoded 276 oauth_token=hh5s93j4hdidpola&oauth_token_secret=hdhd0244k9j7ao03& 277 oauth_callback_confirmed=true 279 The client redirects Jane's user-agent to the server's Resource Owner 280 Authorization endpoint to obtain Jane's approval for accessing her 281 private photos: 283 https://photos.example.net/authorize?oauth_token=hh5s93j4hdidpola 285 The server requests Jane to sign-in using her username and password 286 and if successful, asks her to approve granting 'printer.example.com' 287 access to her private photos. Jane approves the request and her 288 user-agent is redirected to the callback URI provided by the client 289 in the previous request (line breaks are for display purposes only): 291 http://printer.example.com/ready? 292 oauth_token=hh5s93j4hdidpola&oauth_verifier=hfdp7dh39dks9884 294 The callback request informs the client that Jane completed the 295 authorization process. The client then requests a set of token 296 credentials using its temporary credentials (over a secure TLS 297 channel): 299 POST /token HTTP/1.1 300 Host: photos.example.net 301 Authorization: OAuth realm="Photos", 302 oauth_consumer_key="dpf43f3p2l4k3l03", 303 oauth_token="hh5s93j4hdidpola", 304 oauth_signature_method="HMAC-SHA1", 305 oauth_timestamp="137131201", 306 oauth_nonce="walatlh", 307 oauth_verifier="hfdp7dh39dks9884", 308 oauth_signature="gKgrFCywp7rO0OXSjdot%2FIHF7IU%3D" 310 The server validates the request and replies with a set of token 311 credentials in the body of the HTTP response: 313 HTTP/1.1 200 OK 314 Content-Type: application/x-www-form-urlencoded 316 oauth_token=nnch734d00sl2jdk&oauth_token_secret=pfkkdhi9sl3r4s00 318 With a set of token credentials, the client is now ready to request 319 the private photo: 321 GET /photos?file=vacation.jpg&size=original HTTP/1.1 322 Host: photos.example.net 323 Authorization: OAuth realm="Photos", 324 oauth_consumer_key="dpf43f3p2l4k3l03", 325 oauth_token="nnch734d00sl2jdk", 326 oauth_signature_method="HMAC-SHA1", 327 oauth_timestamp="137131202", 328 oauth_nonce="chapoH", 329 oauth_signature="MdpQcU8iPSUjWoN%2FUDMsK2sui9I%3D" 331 The 'photos.example.net' server validates the request and responds 332 with the requested photo. 'printer.example.com' is able to continue 333 accessing Jane's private photos using the same set of token 334 credentials for the duration of Jane's authorization, or until Jane 335 revokes access. 337 1.3. Notational Conventions 339 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 340 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 341 document are to be interpreted as described in [RFC2119]. 343 2. Redirection-Based Authorization 345 OAuth uses tokens to represent the authorization granted to the 346 client by the resource owner. Typically, token credentials are 347 issued by the server at the resource owner's request, after 348 authenticating the resource owner's identity (usually using a 349 username and password). 351 There are many ways in which a server can facilitate the provisioning 352 of token credentials. This section defines one such way, using HTTP 353 redirections and the resource owner's user-agent. This redirection- 354 based authorization method includes three steps: 356 1. The client obtains a set of temporary credentials from the server 357 (in the form of an identifier and shared-secret). The temporary 358 credentials are used to identify the access request throughout 359 the authorization process. 361 2. The resource owner authorizes the server to grant the client's 362 access request (identified by the temporary credentials). 364 3. The client uses the temporary credentials to request a set of 365 token credentials from the server, which will enable it to access 366 the resource owner's protected resources. 368 The server MUST revoke the temporary credentials after being used 369 once to obtain the token credentials. It is RECOMMENDED that the 370 temporary credentials have a limited lifetime. Servers SHOULD enable 371 resource owners to revoke token credentials after they have been 372 issued to clients. 374 In order for the client to perform these steps, the server needs to 375 advertise the URIs of the following three endpoints: 377 Temporary Credential Request 378 The endpoint used by the client to obtain a set of temporary 379 credentials as described in Section 2.1. 381 Resource Owner Authorization 382 The endpoint to which the resource owner is redirected to grant 383 authorization as described in Section 2.2. 385 Token Request 386 The endpoint used by the client to request a set of token 387 credentials using the set of temporary credentials as described 388 in Section 2.3. 390 The three URIs advertised by the server MAY include a query component 391 as defined by [RFC3986] section 3, but if present, the query MUST NOT 392 contain any parameters beginning with the "oauth_" prefix, to avoid 393 conflicts with the protocol parameters added to the URIs when used. 395 The methods in which the server advertises and documents its three 396 endpoints are beyond the scope of this specification. Clients should 397 avoid making assumptions about the size of tokens and other server- 398 generated values, which are left undefined by this specification. In 399 addition, protocol parameters MAY include values which require 400 encoding when transmitted. Clients and servers should not make 401 assumptions about the possible range of their values. 403 2.1. Temporary Credentials 405 The client obtains a set of temporary credentials from the server by 406 making an authenticated (Section 3) HTTP "POST" request to the 407 Temporary Credential Request endpoint (unless the server advertises 408 another HTTP request method for the client to use). The client 409 constructs a request URI by adding the following REQUIRED parameter 410 to the request (in addition to the other protocol parameters, using 411 the same parameter transmission method): 413 oauth_callback: An absolute URI to which the server will redirect 414 the resource owner back when the Resource Owner Authorization 415 step (Section 2.2) is completed. If the client is unable to 416 receive callbacks or a callback URI has been established via 417 other means, the parameter value MUST be set to "oob" (case 418 sensitive), to indicate an out-of-band configuration. 420 Servers MAY specify additional parameters. 422 When making the request, the client authenticates using only the 423 client credentials. The client MAY omit the empty "oauth_token" 424 protocol parameter from the request and MUST use the empty string as 425 the token secret value. 427 Since the request results in the transmission of plain text 428 credentials in the HTTP response, the server MUST require the use of 429 a transport-layer mechanisms such as TLS or SSL (or a secure channel 430 with equivalent protections). 432 For example, the client makes the following HTTPS request: 434 POST /request_temp_credentials HTTP/1.1 435 Host: server.example.com 436 Authorization: OAuth realm="Example", 437 oauth_consumer_key="jd83jd92dhsh93js", 438 oauth_signature_method="PLAINTEXT", 439 oauth_callback="http%3A%2F%2Fclient.example.net%2Fcb%3Fx%3D1", 440 oauth_signature="ja893SD9%26" 442 The server MUST verify (Section 3.2) the request and if valid, 443 respond back to the client with a set of temporary credentials (in 444 the form of an identifier and shared-secret). The temporary 445 credentials are included in the HTTP response body using the 446 "application/x-www-form-urlencoded" content type as defined by 447 [W3C.REC-html40-19980424] with a 200 status code (OK). 449 The response contains the following REQUIRED parameters: 451 oauth_token 452 The temporary credentials identifier. 454 oauth_token_secret 455 The temporary credentials shared-secret. 457 oauth_callback_confirmed: MUST be present and set to "true". The 458 parameter is used to differentiate from previous versions of 459 the protocol. 461 Note that even though the parameter names include the term 'token', 462 these credentials are not token credentials, but are used in the next 463 two steps in a similar manner to token credentials. 465 For example (line breaks are for display purposes only): 467 HTTP/1.1 200 OK 468 Content-Type: application/x-www-form-urlencoded 470 oauth_token=hdk48Djdsa&oauth_token_secret=xyz4992k83j47x0b& 471 oauth_callback_confirmed=true 473 2.2. Resource Owner Authorization 475 Before the client requests a set of token credentials from the 476 server, it MUST send the user to the server to authorize the request. 477 The client constructs a request URI by adding the following REQUIRED 478 query parameter to the Resource Owner Authorization endpoint URI: 480 oauth_token 481 The temporary credentials identifier obtained in Section 2.1 in 482 the "oauth_token" parameter. Servers MAY declare this 483 parameter as OPTIONAL, in which case they MUST provide a way 484 for the resource owner to indicate the identifier through other 485 means. 487 Servers MAY specify additional parameters. 489 The client directs the resource owner to the constructed URI using an 490 HTTP redirection response, or by other means available to it via the 491 resource owner's user-agent. The request MUST use the HTTP "GET" 492 method. 494 For example, the client redirects the resource owner's user-agent to 495 make the following HTTPS request: 497 GET /authorize_access?oauth_token=hdk48Djdsa HTTP/1.1 498 Host: server.example.com 500 The way in which the server handles the authorization request, 501 including whether it uses a secure channel such as TLS/SSL is beyond 502 the scope of this specification. However, the server MUST first 503 verify the identity of the resource owner. 505 When asking the resource owner to authorize the requested access, the 506 server SHOULD present to the resource owner information about the 507 client requesting access based on the association of the temporary 508 credentials with the client identity. When displaying any such 509 information, the server SHOULD indicate if the information has been 510 verified. 512 After receiving an authorization decision from the resource owner, 513 the server redirects the resource owner to the callback URI if one 514 was provided in the "oauth_callback" parameter or by other means. 516 To make sure that the resource owner granting access is the same 517 resource owner returning back to the client to complete the process, 518 the server MUST generate a verification code: an unguessable value 519 passed to the client via the resource owner and REQUIRED to complete 520 the process. The server constructs the request URI by adding the 521 following REQUIRED parameters to the callback URI query component: 523 oauth_token 524 The temporary credentials identifier received from the client. 526 oauth_verifier 527 The verification code. 529 If the callback URI already includes a query component, the server 530 MUST append the OAuth parameters to the end of the existing query. 532 For example, the server redirects the resource owner's user-agent to 533 make the following HTTP request: 535 GET /cb?x=1&oauth_token=hdk48Djdsa&oauth_verifier=473f82d3 HTTP/1.1 536 Host: client.example.net 538 If the client did not provide a callback URI, the server SHOULD 539 display the value of the verification code, and instruct the resource 540 owner to manually inform the client that authorization is completed. 541 If the server knows a client to be running on a limited device it 542 SHOULD ensure that the verifier value is suitable for manual entry. 544 2.3. Token Credentials 546 The client obtains a set of token credentials from the server by 547 making an authenticated (Section 3) HTTP "POST" request to the Token 548 Request endpoint (unless the server advertises another HTTP request 549 method for the client to use). The client constructs a request URI 550 by adding the following REQUIRED parameter to the request (in 551 addition to the other protocol parameters, using the same parameter 552 transmission method): 554 oauth_verifier 555 The verification code received from the server in the previous 556 step. 558 When making the request, the client authenticates using the client 559 credentials as well as the temporary credentials. The temporary 560 credentials are used as a substitute for token credentials in the 561 authenticated request and transmitted using the "oauth_token" 562 parameter. 564 Since the request results in the transmission of plain text 565 credentials in the HTTP response, the server MUST require the use of 566 a transport-layer mechanisms such as TLS or SSL (or a secure channel 567 with equivalent protections). 569 For example, the client makes the following HTTPS request: 571 POST /request_token HTTP/1.1 572 Host: server.example.com 573 Authorization: OAuth realm="Example", 574 oauth_consumer_key="jd83jd92dhsh93js", 575 oauth_token="hdk48Djdsa", 576 oauth_signature_method="PLAINTEXT", 577 oauth_verifier="473f82d3", 578 oauth_signature="ja893SD9%26xyz4992k83j47x0b" 580 The server MUST verify (Section 3.2) the validity of the request, 581 ensure that the resource owner has authorized the provisioning of 582 token credentials to the client, and ensure that the temporary 583 credentials have not expired or been used before. The server MUST 584 also verify the verification code received from the client. If the 585 request is valid and authorized, the token credentials are included 586 in the HTTP response body using the 587 "application/x-www-form-urlencoded" content type as defined by 588 [W3C.REC-html40-19980424] with a 200 status code (OK). 590 The response contains the following REQUIRED parameters: 592 oauth_token 593 The token identifier. 595 oauth_token_secret 596 The token shared-secret. 598 For example: 600 HTTP/1.1 200 OK 601 Content-Type: application/x-www-form-urlencoded 603 oauth_token=j49ddk933skd9dks&oauth_token_secret=ll399dj47dskfjdk 605 The server must retain the scope, duration, and other attributes 606 approved by the resource owner, and enforce these restrictions when 607 receiving a client request made with the token credentials issued. 609 Once the client receives and stores the token credentials, it can 610 proceed to access protected resources on behalf of the resource owner 611 by making authenticated requests (Section 3) using the client 612 credentials together with the token credentials received. 614 3. Authenticated Requests 616 The HTTP authentication methods defined by [RFC2617], enable clients 617 to make authenticated HTTP requests. Clients using these methods 618 gain access to protected resources by using their credentials 619 (typically a username and password pair), which allow the server to 620 verify their authenticity. Using these methods for delegation 621 requires the client to assume the role of the resource owner. 623 OAuth provides a method designed to include two sets of credentials 624 with each request, one to identify the client, and another to 625 identify the resource owner. Before a client can make authenticated 626 requests on behalf of the resource owner, it must obtain a token 627 authorized by the resource owner. Section 2 provides one such method 628 through which the client can obtain a token authorized by the 629 resource owner. 631 The client credentials take the form of a unique identifier, and an 632 associated shared-secret or RSA key pair. Prior to making 633 authenticated requests, the client establishes a set of credentials 634 with the server. The process and requirements for provisioning these 635 are outside the scope of this specification. Implementers are urged 636 to consider the security ramifications of using client credentials, 637 some of which are described in Section 4.6. 639 Making authenticated requests requires prior knowledge of the 640 server's configuration. OAuth includes multiple methods for 641 transmitting protocol parameters with requests (Section 3.5), as well 642 as multiple methods for the client to prove its rightful ownership of 643 the credentials used (Section 3.4). The way in which clients 644 discover the required configuration is outside the scope of this 645 specification. 647 3.1. Making Requests 649 An authenticated request includes several protocol parameters. Each 650 parameter name begins with the "oauth_" prefix, and the parameter 651 names and values are case sensitive. Clients make authenticated 652 requests by calculating the values of a set of protocol parameters 653 and adding them to the HTTP request as follows: 655 1. The client assigns value to each of these REQUIRED (unless 656 specified otherwise) protocol parameters: 658 oauth_consumer_key 659 The identifier portion of the client credentials 660 (equivalent to a username). The parameter name reflects a 661 deprecated term (Consumer Key) used in previous revisions 662 of the specification, and has been retained to maintain 663 backward compatibility. 665 oauth_token 666 The token value used to associate the request with the 667 resource owner. If the request is not associated with a 668 resource owner (no token available), clients MAY omit the 669 parameter. 671 oauth_signature_method 672 The name of the signature method used by the client to sign 673 the request, as defined in Section 3.4. 675 oauth_timestamp 676 The timestamp value as defined in Section 3.3. The 677 parameter MAY be omitted when using the "PLAINTEXT" 678 signature method. 680 oauth_nonce 681 The nonce value as defined in Section 3.3. The parameter 682 MAY be omitted when using the "PLAINTEXT" signature method. 684 oauth_version 685 OPTIONAL. If present, MUST be set to "1.0". Provides the 686 version of the authentication process as defined in this 687 specification. 689 2. The protocol parameters are added to the request using one of the 690 transmission methods listed in Section 3.5. Each parameter MUST 691 NOT appear more than once per request. 693 3. The client calculates and assigns the value of the 694 "oauth_signature" parameter as described in Section 3.4 and adds 695 the parameter to the request using the same method used in the 696 previous step. 698 4. The client sends the authenticated HTTP request to the server. 700 For example, to make the following HTTP request authenticated (the 701 "c2&a3=2+q" string in the following examples is used to illustrate 702 the impact of a form-encoded entity-body) : 704 GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1 705 Host: example.com 706 Content-Type: application/x-www-form-urlencoded 708 c2&a3=2+q 710 The client assigns values to the following protocol parameters using 711 its client credentials, token credentials, the current timestamp, a 712 uniquely generated nonce, and indicates it will use the "HMAC-SHA1" 713 signature method: 715 oauth_consumer_key: 9djdj82h48djs9d2 716 oauth_token: kkk9d7dh3k39sjv7 717 oauth_signature_method: HMAC-SHA1 718 oauth_timestamp: 137131201 719 oauth_nonce: 7d8f3e4a 721 The client adds the protocol parameters to the request using the 722 OAuth HTTP Authorization header field: 724 Authorization: OAuth realm="Example", 725 oauth_consumer_key="9djdj82h48djs9d2", 726 oauth_token="kkk9d7dh3k39sjv7", 727 oauth_signature_method="HMAC-SHA1", 728 oauth_timestamp="137131201", 729 oauth_nonce="7d8f3e4a" 731 Then calculates the value of the "oauth_signature" parameter, adds it 732 to the request, and sends the HTTP request to the server: 734 GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1 735 Host: example.com 736 Content-Type: application/x-www-form-urlencoded 737 Authorization: OAuth realm="Example", 738 oauth_consumer_key="9djdj82h48djs9d2", 739 oauth_token="kkk9d7dh3k39sjv7", 740 oauth_signature_method="HMAC-SHA1", 741 oauth_timestamp="137131201", 742 oauth_nonce="7d8f3e4a", 743 oauth_signature="djosJKDKJSD8743243%2Fjdk33klY%3D" 745 c2&a3=2+q 747 3.2. Verifying Requests 749 Servers receiving an authenticated request MUST validate it by: 751 o Recalculate the request signature independently as described in 752 Section 3.4 and compare it to the value received from the client 753 via the "oauth_signature" parameter. 755 o If using the "HMAC-SHA1" or "RSA-SHA1" signature methods, ensure 756 that the combination of nonce/timestamp/token (if present) 757 received from the client has not been used before in a previous 758 request (the server MAY reject requests with stale timestamps as 759 described in Section 3.3). 761 o If a token is present, verify the scope and status of the client 762 authorization as represented by the token (the server MAY choose 763 to restrict token usage to the client to which it was issued). 765 o If the "oauth_version" parameter is present, ensure its value is 766 "1.0". 768 If the request fails verification, the server SHOULD respond with the 769 appropriate HTTP response status code. The server MAY include 770 further details about why the request was rejected in the response 771 body. 773 The server SHOULD return a 400 (bad request) status code when 774 receiving a request with unsupported parameters, unsupported 775 signature method, missing parameters, or duplicated protocol 776 parameters. The server SHOULD return a 401 (unauthorized) status 777 code when receiving a request with invalid client credentials, 778 invalid or expired token, invalid signature, or invalid or used 779 nonce. 781 3.3. Nonce and Timestamp 783 The timestamp value MUST be a positive integer. Unless otherwise 784 specified by the server's documentation, the timestamp is expressed 785 in the number of seconds since January 1, 1970 00:00:00 GMT. 787 A nonce is a random string, uniquely generated by the client to allow 788 the server to verify that a request has never been made before and 789 helps prevent replay attacks when requests are made over a non-secure 790 channel. The nonce value MUST be unique across all requests with the 791 same timestamp, client credentials, and token combinations. 793 To avoid the need to retain an infinite number of nonce values for 794 future checks, servers MAY choose to restrict the time period after 795 which a request with an old timestamp is rejected. Note that this 796 restriction implies a level of synchronization between the client's 797 and server's clocks. Servers applying such a restriction MAY provide 798 a way for the client to sync with the server's clock; alternatively 799 both systems could synchronize with a trusted time service. Details 800 of clock synchronization strategies are beyond the scope of this 801 specification. 803 3.4. Signature 805 OAuth-authenticated requests can have two sets of credentials: those 806 passed via the "oauth_consumer_key" parameter and those in the 807 "oauth_token" parameter. In order for the server to verify the 808 authenticity of the request and prevent unauthorized access, the 809 client needs to prove that it is the rightful owner of the 810 credentials. This is accomplished using the shared-secret (or RSA 811 key) part of each set of credentials. 813 OAuth provides three methods for the client to prove its rightful 814 ownership of the credentials: "HMAC-SHA1", "RSA-SHA1", and 815 "PLAINTEXT". These methods are generally referred to as signature 816 methods, even though "PLAINTEXT" does not involve a signature. In 817 addition, "RSA-SHA1" utilizes an RSA key instead of the shared- 818 secrets associated with the client credentials. 820 OAuth does not mandate a particular signature method, as each 821 implementation can have its own unique requirements. Servers are 822 free to implement and document their own custom methods. 823 Recommending any particular method is beyond the scope of this 824 specification. Implementers should review the Security 825 Considerations section (Section 4) before deciding on which method to 826 support. 828 The client declares which signature method is used via the 829 "oauth_signature_method" parameter. It then generates a signature 830 (or a string of an equivalent value), and includes it in the 831 "oauth_signature" parameter. The server verifies the signature as 832 specified for each method. 834 The signature process does not change the request or its parameters, 835 with the exception of the "oauth_signature" parameter. 837 3.4.1. Signature Base String 839 The signature base string is a consistent, reproducible concatenation 840 of several of the HTTP request elements into a single string. The 841 string is used as an input to the "HMAC-SHA1" and "RSA-SHA1" 842 signature methods. 844 The signature base string includes the following components of the 845 HTTP request: 847 o The HTTP request method (e.g. "GET", "POST", etc.). 849 o The authority as declared by the HTTP "Host" request header field. 851 o The path and query components of the request resource URI. 853 o The protocol parameters excluding the "oauth_signature". 855 o Parameters included in the request entity-body if they comply with 856 the strict restrictions defined in Section 3.4.1.3. 858 The signature base string does not cover the entire HTTP request. 859 Most notably, it does not include the entity-body in most requests, 860 nor does it include most HTTP entity-headers. It is important to 861 note that the server cannot verify the authenticity of the excluded 862 request components without using additional protections such as SSL/ 863 TLS or other methods. 865 3.4.1.1. String Construction 867 The signature base string is constructed by concatenating together, 868 in order, the following HTTP request elements: 870 1. The HTTP request method in uppercase. For example: "HEAD", 871 "GET", "POST", etc. If the request uses a custom HTTP method, it 872 MUST be encoded (Section 3.6). 874 2. An "&" character (ASCII code 38). 876 3. The base string URI from Section 3.4.1.2, after being encoded 877 (Section 3.6). 879 4. An "&" character (ASCII code 38). 881 5. The request parameters as normalized in Section 3.4.1.3.2, after 882 being encoded (Section 3.6). 884 For example, the HTTP request: 886 GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1 887 Host: example.com 888 Content-Type: application/x-www-form-urlencoded 889 Authorization: OAuth realm="Example", 890 oauth_consumer_key="9djdj82h48djs9d2", 891 oauth_token="kkk9d7dh3k39sjv7", 892 oauth_signature_method="HMAC-SHA1", 893 oauth_timestamp="137131201", 894 oauth_nonce="7d8f3e4a", 895 oauth_signature="djosJKDKJSD8743243%2Fjdk33klY%3D" 897 c2&a3=2+q 899 Is represented by the following signature base string (line breaks 900 are for display purposes only): 902 GET&http%3A%2F%2Fexample.com%2Frequest&a2%3Dr%2520b%26a3%3D2%2520q% 903 26a3%3Da%26b5%3D%253D%25253D%26c%2540%3D%26c2%3D%26oauth_consumer_k 904 ey%3D9djdj82h48djs9d2%26oauth_nonce%3D7d8f3e4a%26oauth_signature_me 905 thod%3DHMAC-SHA1%26oauth_timestamp%3D137131201%26oauth_token%3Dkkk9 906 d7dh3k39sjv7 908 3.4.1.2. Base String URI 910 The scheme, authority, and path of the request resource URI [RFC3986] 911 are included by constructing an "http" or "https" URI representing 912 the request resource (without the query or fragment) as follows: 914 1. The scheme and host MUST be in lowercase. 916 2. The host and port values MUST match the content of the HTTP 917 request "Host" header field. 919 3. The port MUST be included if it is not the default port for the 920 scheme, and MUST be excluded if it is the default. Specifically, 921 the port MUST be excluded when making an HTTP request [RFC2616] 922 to port 80 or when making an HTTPS request [RFC2818] to port 443. 923 All other non-default port numbers MUST be included. 925 For example, the HTTP request: 927 GET /r%20v/X?id=123 HTTP/1.1 928 Host: EXAMPLE.COM:80 930 is represented by the base string URI: "http://example.com/r%20v/X". 932 In another example, the HTTPS request: 934 GET /?q=1 HTTP/1.1 935 Host: www.example.net:8080 937 is represented by the base string URI: 938 "https://www.example.net:8080/". 940 3.4.1.3. Request Parameters 942 In order to guarantee a consistent and reproducible representation of 943 the request parameters, the parameters are collected and decoded to 944 their original decoded form. They are then sorted and encoded in a 945 particular manner which is often different from their original 946 encoding scheme, and concatenated into a single string. 948 3.4.1.3.1. Parameter Sources 950 The parameters from the following sources are collected into a single 951 list of name/value pairs: 953 o The query component of the HTTP request URI as defined by 954 [RFC3986] section 3.4. The query component is parsed into a list 955 of name/value pairs by treating it as an 956 "application/x-www-form-urlencoded" string, separating the names 957 and values and decoding them as defined by 958 [W3C.REC-html40-19980424] section 17.13.4. 960 o The OAuth HTTP Authorization header field (Section 3.5.1) if 961 present. The header's content is parsed into a list of name/value 962 pairs excluding the "realm" parameter if present. The parameter 963 values are decoded as defined by Section 3.5.1. 965 o The HTTP request entity-body, but only if all of the following 966 conditions are met: 968 * The entity-body is single-part. 970 * The entity-body follows the encoding requirements of the 971 "application/x-www-form-urlencoded" content-type as defined by 972 [W3C.REC-html40-19980424]. 974 * The HTTP request entity-header includes the "Content-Type" 975 header field set to "application/x-www-form-urlencoded". 977 The entity-body is parsed into a list of decoded name/value pairs 978 as described in [W3C.REC-html40-19980424] section 17.13.4. 980 The "oauth_signature" parameter MUST be excluded from the signature 981 base string if present. Parameters not explicitly included in the 982 request MUST be excluded from the signature base string (e.g. the 983 "oauth_version" parameter when omitted). 985 For example, the HTTP request: 987 GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1 988 Host: example.com 989 Content-Type: application/x-www-form-urlencoded 990 Authorization: OAuth realm="Example", 991 oauth_consumer_key="9djdj82h48djs9d2", 992 oauth_token="kkk9d7dh3k39sjv7", 993 oauth_signature_method="HMAC-SHA1", 994 oauth_timestamp="137131201", 995 oauth_nonce="7d8f3e4a", 996 oauth_signature="djosJKDKJSD8743243%2Fjdk33klY%3D" 998 c2&a3=2+q 1000 Contains the following (fully decoded) parameters used in the 1001 signature base sting: 1003 +------------------------+------------------+ 1004 | Name | Value | 1005 +------------------------+------------------+ 1006 | b5 | =%3D | 1007 | a3 | a | 1008 | c@ | | 1009 | a2 | r b | 1010 | oauth_consumer_key | 9djdj82h48djs9d2 | 1011 | oauth_token | kkk9d7dh3k39sjv7 | 1012 | oauth_signature_method | HMAC-SHA1 | 1013 | oauth_timestamp | 137131201 | 1014 | oauth_nonce | 7d8f3e4a | 1015 | c2 | | 1016 | a3 | 2 q | 1017 +------------------------+------------------+ 1019 Note that the value of "b5" is "=%3D" and not "==". Both "c@" and 1020 "c2" have empty values. While the encoding rules specified in this 1021 specification for the purpose of constructing the signature base 1022 string exclude the use of a "+" character (ASCII code 43) to 1023 represent an encoded space character (ASCII code 32), this practice 1024 is widely used in "application/x-www-form-urlencoded" encoded values, 1025 and MUST be properly decoded, as demonstrated by one of the "a3" 1026 parameter instances (the "a3" parameter is used twice in this 1027 request). 1029 3.4.1.3.2. Parameters Normalization 1031 The parameters collected in Section 3.4.1.3 are normalized into a 1032 single string as follows: 1034 1. First, the name and value of each parameter are encoded 1035 (Section 3.6). 1037 2. The parameters are sorted by name, using ascending byte value 1038 ordering. If two or more parameters share the same name, they 1039 are sorted by their value. 1041 3. The name of each parameter is concatenated to its corresponding 1042 value using an "=" character (ASCII code 61) as separator, even 1043 if the value is empty. 1045 4. The sorted name/value pairs are concatenated together into a 1046 single string by using an "&" character (ASCII code 38) as 1047 separator. 1049 For example, the list of parameters from the previous section would 1050 be normalized as follows: 1052 Encoded: 1054 +------------------------+------------------+ 1055 | Name | Value | 1056 +------------------------+------------------+ 1057 | b5 | %3D%253D | 1058 | a3 | a | 1059 | c%40 | | 1060 | a2 | r%20b | 1061 | oauth_consumer_key | 9djdj82h48djs9d2 | 1062 | oauth_token | kkk9d7dh3k39sjv7 | 1063 | oauth_signature_method | HMAC-SHA1 | 1064 | oauth_timestamp | 137131201 | 1065 | oauth_nonce | 7d8f3e4a | 1066 | c2 | | 1067 | a3 | 2%20q | 1068 +------------------------+------------------+ 1069 Sorted: 1071 +------------------------+------------------+ 1072 | Name | Value | 1073 +------------------------+------------------+ 1074 | a2 | r%20b | 1075 | a3 | 2%20q | 1076 | a3 | a | 1077 | b5 | %3D%253D | 1078 | c%40 | | 1079 | c2 | | 1080 | oauth_consumer_key | 9djdj82h48djs9d2 | 1081 | oauth_nonce | 7d8f3e4a | 1082 | oauth_signature_method | HMAC-SHA1 | 1083 | oauth_timestamp | 137131201 | 1084 | oauth_token | kkk9d7dh3k39sjv7 | 1085 +------------------------+------------------+ 1087 Concatenated Pairs: 1089 +-------------------------------------+ 1090 | Name=Value | 1091 +-------------------------------------+ 1092 | a2=r%20b | 1093 | a3=2%20q | 1094 | a3=a | 1095 | b5=%3D%253D | 1096 | c%40= | 1097 | c2= | 1098 | oauth_consumer_key=9djdj82h48djs9d2 | 1099 | oauth_nonce=7d8f3e4a | 1100 | oauth_signature_method=HMAC-SHA1 | 1101 | oauth_timestamp=137131201 | 1102 | oauth_token=kkk9d7dh3k39sjv7 | 1103 +-------------------------------------+ 1105 And concatenated together into a single string (line breaks are for 1106 display purposes only): 1108 a2=r%20b&a3=2%20q&a3=a&b5=%3D%253D&c%40=&c2=&oauth_consumer_key=9dj 1109 dj82h48djs9d2&oauth_nonce=7d8f3e4a&oauth_signature_method=HMAC-SHA1 1110 &oauth_timestamp=137131201&oauth_token=kkk9d7dh3k39sjv7 1112 3.4.2. HMAC-SHA1 1114 The "HMAC-SHA1" signature method uses the HMAC-SHA1 signature 1115 algorithm as defined in [RFC2104]: 1117 digest = HMAC-SHA1 (key, text) 1119 The HMAC-SHA1 function variables are used in following way: 1121 text 1122 is set to the value of the signature base string from 1123 Section 3.4.1.1. 1125 key 1126 is set to the concatenated values of: 1128 1. The client shared-secret, after being encoded 1129 (Section 3.6). 1131 2. An "&" character (ASCII code 38), which MUST be included 1132 even when either secret is empty. 1134 3. The token shared-secret, after being encoded 1135 (Section 3.6). 1137 digest 1138 is used to set the value of the "oauth_signature" protocol 1139 parameter, after the result octet string is base64-encoded per 1140 [RFC2045] section 6.8. 1142 3.4.3. RSA-SHA1 1144 The "RSA-SHA1" signature method uses the RSASSA-PKCS1-v1_5 signature 1145 algorithm as defined in [RFC3447] section 8.2 (also known as PKCS#1), 1146 using SHA-1 as the hash function for EMSA-PKCS1-v1_5. To use this 1147 method, the client MUST have established client credentials with the 1148 server which included its RSA public key (in a manner which is beyond 1149 the scope of this specification). 1151 The signature base string is signed using the client's RSA private 1152 key per [RFC3447] section 8.2.1: 1154 S = RSASSA-PKCS1-V1_5-SIGN (K, M) 1156 Where: 1158 K 1159 is set to the client's RSA private key, 1161 M 1162 is set to the value of the signature base string from 1163 Section 3.4.1.1, and 1165 S 1166 is the result signature used to set the value of the 1167 "oauth_signature" protocol parameter, after the result octet 1168 string is base64-encoded per [RFC2045] section 6.8. 1170 The server verifies the signature per [RFC3447] section 8.2.2: 1172 RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, S) 1174 Where: 1176 (n, e) 1177 is set to the client's RSA public key, 1179 M 1180 is set to the value of the signature base string from 1181 Section 3.4.1.1, and 1183 S 1184 is set to the octet string value of the "oauth_signature" 1185 protocol parameter received from the client. 1187 3.4.4. PLAINTEXT 1189 The "PLAINTEXT" method does not employ a signature algorithm. It 1190 MUST be used with a transport-layer mechanism such as TLS or SSL (or 1191 sent over a secure channel with equivalent protections). It does not 1192 utilize the signature base string nor the "oauth_timestamp" and 1193 "oauth_nonce" parameters. 1195 The "oauth_signature" protocol parameter is set to the concatenated 1196 value of: 1198 1. The client shared-secret, after being encoded (Section 3.6). 1200 2. An "&" character (ASCII code 38), which MUST be included even 1201 when either secret is empty. 1203 3. The token shared-secret, after being encoded (Section 3.6). 1205 3.5. Parameter Transmission 1207 When making an OAuth-authenticated request, protocol parameters as 1208 well as any other parameter using the "oauth_" prefix SHALL be 1209 included in the request using one and only one of the following 1210 locations, listed in order of decreasing preference: 1212 1. The HTTP "Authorization" header field as described in 1213 Section 3.5.1. 1215 2. The HTTP request entity-body as described in Section 3.5.2. 1217 3. The HTTP request URI query as described in Section 3.5.3. 1219 In addition to these three methods, future extensions MAY define 1220 other methods for including protocol parameters in the request. 1222 3.5.1. Authorization Header 1224 Protocol parameters can be transmitted using the HTTP "Authorization" 1225 header field as defined by [RFC2617] with the auth-scheme name set to 1226 "OAuth" (case-insensitive). 1228 For example: 1230 Authorization: OAuth realm="Example", 1231 oauth_consumer_key="0685bd9184jfhq22", 1232 oauth_token="ad180jjd733klru7", 1233 oauth_signature_method="HMAC-SHA1", 1234 oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D", 1235 oauth_timestamp="137131200", 1236 oauth_nonce="4572616e48616d6d65724c61686176", 1237 oauth_version="1.0" 1239 Protocol parameters SHALL be included in the "Authorization" header 1240 field as follows: 1242 1. Parameter names and values are encoded per Parameter Encoding 1243 (Section 3.6). 1245 2. Each parameter's name is immediately followed by an "=" character 1246 (ASCII code 61), a """ character (ASCII code 34), the parameter 1247 value (MAY be empty), and another """ character (ASCII code 34). 1249 3. Parameters are separated by a "," character (ASCII code 44) and 1250 OPTIONAL linear whitespace per [RFC2617]. 1252 4. The OPTIONAL "realm" parameter MAY be added and interpreted per 1253 [RFC2617] section 1.2. 1255 Servers MAY indicate their support for the "OAuth" auth-scheme by 1256 returning the HTTP "WWW-Authenticate" response header field upon 1257 client requests for protected resources. As per [RFC2617] such a 1258 response MAY include additional HTTP "WWW-Authenticate" header 1259 fields: 1261 For example: 1263 WWW-Authenticate: OAuth realm="http://server.example.com/" 1265 The realm parameter defines a protection realm per [RFC2617] section 1266 1.2. 1268 3.5.2. Form-Encoded Body 1270 Protocol parameters can be transmitted in the HTTP request entity- 1271 body, but only if the following REQUIRED conditions are met: 1273 o The entity-body is single-part. 1275 o The entity-body follows the encoding requirements of the 1276 "application/x-www-form-urlencoded" content-type as defined by 1277 [W3C.REC-html40-19980424]. 1279 o The HTTP request entity-header includes the "Content-Type" header 1280 field set to "application/x-www-form-urlencoded". 1282 For example (line breaks are for display purposes only): 1284 oauth_consumer_key=0685bd9184jfhq22&oauth_token=ad180jjd733klr 1285 u7&oauth_signature_method=HMAC-SHA1&oauth_signature=wOJIO9A2W5 1286 mFwDgiDvZbTSMK%2FPY%3D&oauth_timestamp=137131200&oauth_nonce=4 1287 572616e48616d6d65724c61686176&oauth_version=1.0 1289 The entity-body MAY include other request-specific parameters, in 1290 which case, the protocol parameters SHOULD be appended following the 1291 request-specific parameters, properly separated by an "&" character 1292 (ASCII code 38). 1294 3.5.3. Request URI Query 1296 Protocol parameters can be transmitted by being added to the HTTP 1297 request URI as a query parameter as defined by [RFC3986] section 3. 1299 For example (line breaks are for display purposes only): 1301 GET /example/path?oauth_consumer_key=0685bd9184jfhq22& 1302 oauth_token=ad180jjd733klru7&oauth_signature_method=HM 1303 AC-SHA1&oauth_signature=wOJIO9A2W5mFwDgiDvZbTSMK%2FPY% 1304 3D&oauth_timestamp=137131200&oauth_nonce=4572616e48616 1305 d6d65724c61686176&oauth_version=1.0 HTTP/1.1 1307 The request URI MAY include other request-specific query parameters, 1308 in which case, the protocol parameters SHOULD be appended following 1309 the request-specific parameters, properly separated by an "&" 1310 character (ASCII code 38). 1312 3.6. Percent Encoding 1314 Existing percent-encoding methods do not guarantee a consistent 1315 construction of the signature base string. The following percent- 1316 encoding method is not defined to replace the existing encoding 1317 methods defined by [RFC3986] and [W3C.REC-html40-19980424]. It is 1318 used only in the construction of the signature base string and the 1319 authorization header field (Section 3.5.1). 1321 This specification defines the following method for percent-encoding 1322 strings: 1324 1. Text values are first encoded as UTF-8 octets per [RFC3629] if 1325 they are not already. This does not include binary values which 1326 are not intended for human consumption. 1328 2. The values are then escaped using the [RFC3986] percent-encoding 1329 (%XX) mechanism as follows: 1331 * Characters in the unreserved character set as defined by 1332 [RFC3986] section 2.3 (ALPHA, DIGIT, "-", ".", "_", "~") MUST 1333 NOT be encoded. 1335 * All other characters MUST be encoded. 1337 * The two hexadecimal characters used to represent encoded 1338 characters MUST be upper case. 1340 This method is different from the encoding scheme used by the 1341 "application/x-www-form-urlencoded" content-type (for example, it 1342 encodes space characters as "%20" and not using the "+" character). 1343 It MAY be different from the percent-encoding functions provided by 1344 web development frameworks (e.g. encode different characters, use 1345 lower case hexadecimal characters). 1347 4. Security Considerations 1349 As stated in [RFC2617], the greatest sources of risks are usually 1350 found not in the core protocol itself but in policies and procedures 1351 surrounding its use. Implementers are strongly encouraged to assess 1352 how this protocol addresses their security requirements. 1354 4.1. RSA-SHA1 Signature Method 1356 Authenticated requests made with "RSA-SHA1" signatures do not use the 1357 token shared-secret, or any provisioned client shared-secret. This 1358 means the request relies completely on the secrecy of the private key 1359 used by the client to sign requests. 1361 4.2. Confidentiality of Requests 1363 While this protocol provides a mechanism for verifying the integrity 1364 of requests, it provides no guarantee of request confidentiality. 1365 Unless further precautions are taken, eavesdroppers will have full 1366 access to request content. Servers should carefully consider the 1367 kinds of data likely to be sent as part of such requests, and should 1368 employ transport-layer security mechanisms to protect sensitive 1369 resources. 1371 4.3. Spoofing by Counterfeit Servers 1373 This protocol makes no attempt to verify the authenticity of the 1374 server. A hostile party could take advantage of this by intercepting 1375 the client's requests and returning misleading or otherwise incorrect 1376 responses. Service providers should consider such attacks when 1377 developing services using this protocol, and should require 1378 transport-layer security for any requests where the authenticity of 1379 the server or of request responses is an issue. 1381 4.4. Proxying and Caching of Authenticated Content 1383 The HTTP Authorization scheme (Section 3.5.1) is optional. However, 1384 [RFC2616] relies on the "Authorization" and "WWW-Authenticate" header 1385 fields to distinguish authenticated content so that it can be 1386 protected. Proxies and caches, in particular, may fail to adequately 1387 protect requests not using these header fields. 1389 For example, private authenticated content may be stored in (and thus 1390 retrievable from) publicly-accessible caches. Servers not using the 1391 HTTP Authorization header field (Section 3.5.1) should take care to 1392 use other mechanisms, such as the "Cache-Control" header field, to 1393 ensure that authenticated content is protected. 1395 4.5. Plaintext Storage of Credentials 1397 The client shared-secret and token shared-secret function the same 1398 way passwords do in traditional authentication systems. In order to 1399 compute the signatures used in methods other than "RSA-SHA1", the 1400 server must have access to these secrets in plaintext form. This is 1401 in contrast, for example, to modern operating systems, which store 1402 only a one-way hash of user credentials. 1404 If an attacker were to gain access to these secrets - or worse, to 1405 the server's database of all such secrets - he or she would be able 1406 to perform any action on behalf of any resource owner. Accordingly, 1407 it is critical that servers protect these secrets from unauthorized 1408 access. 1410 4.6. Secrecy of the Client Credentials 1412 In many cases, the client application will be under the control of 1413 potentially untrusted parties. For example, if the client is a 1414 desktop application with freely available source code or an 1415 executable binary, an attacker may be able to download a copy for 1416 analysis. In such cases, attackers will be able to recover the 1417 client credentials. 1419 Accordingly, servers should not use the client credentials alone to 1420 verify the identity of the client. Where possible, other factors 1421 such as IP address should be used as well. 1423 4.7. Phishing Attacks 1425 Wide deployment of this and similar protocols may cause resource 1426 owners to become inured to the practice of being redirected to 1427 websites where they are asked to enter their passwords. If resource 1428 owners are not careful to verify the authenticity of these websites 1429 before entering their credentials, it will be possible for attackers 1430 to exploit this practice to steal resource owners' passwords. 1432 Servers should attempt to educate resource owners about the risks 1433 phishing attacks pose, and should provide mechanisms that make it 1434 easy for resource owners to confirm the authenticity of their sites. 1435 Client developers should consider the security implications of how 1436 they interact with a user-agent (e.g. separate window, embedded), and 1437 the ability of the end-user to verify the authenticity of the server 1438 website. 1440 4.8. Scoping of Access Requests 1442 By itself, this protocol does not provide any method for scoping the 1443 access rights granted to a client. However, most applications do 1444 require greater granularity of access rights. For example, servers 1445 may wish to make it possible to grant access to some protected 1446 resources but not others, or to grant only limited access (such as 1447 read-only access) to those protected resources. 1449 When implementing this protocol, servers should consider the types of 1450 access resource owners may wish to grant clients, and should provide 1451 mechanisms to do so. Servers should also take care to ensure that 1452 resource owners understand the access they are granting, as well as 1453 any risks that may be involved. 1455 4.9. Entropy of Secrets 1457 Unless a transport-layer security protocol is used, eavesdroppers 1458 will have full access to authenticated requests and signatures, and 1459 will thus be able to mount offline brute-force attacks to recover the 1460 credentials used. Servers should be careful to assign shared-secrets 1461 which are long enough, and random enough, to resist such attacks for 1462 at least the length of time that the shared-secrets are valid. 1464 For example, if shared-secrets are valid for two weeks, servers 1465 should ensure that it is not possible to mount a brute force attack 1466 that recovers the shared-secret in less than two weeks. Of course, 1467 servers are urged to err on the side of caution, and use the longest 1468 secrets reasonable. 1470 It is equally important that the pseudo-random number generator 1471 (PRNG) used to generate these secrets be of sufficiently high 1472 quality. Many PRNG implementations generate number sequences that 1473 may appear to be random, but which nevertheless exhibit patterns or 1474 other weaknesses which make cryptanalysis or brute force attacks 1475 easier. Implementers should be careful to use cryptographically 1476 secure PRNGs to avoid these problems. 1478 4.10. Denial of Service / Resource Exhaustion Attacks 1480 This specification includes a number of features which may make 1481 resource exhaustion attacks against servers possible. For example, 1482 this protocol requires servers to track used nonces. If an attacker 1483 is able to use many nonces quickly, the resources required to track 1484 them may exhaust available capacity. And again, this protocol can 1485 require servers to perform potentially expensive computations in 1486 order to verify the signature on incoming requests. An attacker may 1487 exploit this to perform a denial of service attack by sending a large 1488 number of invalid requests to the server. 1490 Resource Exhaustion attacks are by no means specific to this 1491 specification. However, implementers should be careful to consider 1492 the additional avenues of attack that this protocol exposes, and 1493 design their implementations accordingly. For example, entropy 1494 starvation typically results in either a complete denial of service 1495 while the system waits for new entropy or else in weak (easily 1496 guessable) secrets. When implementing this protocol, servers should 1497 consider which of these presents a more serious risk for their 1498 application and design accordingly. 1500 4.11. SHA-1 Cryptographic Attacks 1502 SHA-1, the hash algorithm used in "HMAC-SHA1" and "RSA-SHA1" 1503 signature methods, has been shown to have a number of cryptographic 1504 weaknesses that significantly reduce its resistance to collision 1505 attacks. While these weaknesses do not seem to affect the use of 1506 SHA-1 with the Hash-based Message Authentication Code (HMAC) and 1507 should not affect the "HMAC-SHA1" signature method, it may affect the 1508 use of the "RSA-SHA1" signature method. NIST has announced that it 1509 will phase out use of SHA-1 in digital signtures by 2010 [NIST SHA-1 1510 Comments]. 1512 Practically speaking, these weaknesses are difficult to exploit, and 1513 by themselves do not pose a significant risk to users of this 1514 protocol. They may, however, make more efficient attacks possible, 1515 and Servers should take this into account when considering whether 1516 SHA-1 provides an adequate level of security for their applications. 1518 4.12. Signature Base String Limitations 1520 The signature base string has been designed to support the signature 1521 methods defined in this specification. Those designing additional 1522 signature methods, should evaluated the compatibility of the 1523 signature base string with their security requirements. 1525 Since the signature base string does not cover the entire HTTP 1526 request, such as most request entity-body, most entity-headers, and 1527 the order in which parameters are sent, servers should employ 1528 additional mechanisms to protect such elements. 1530 4.13. Cross-Site Request Forgery (CSRF) 1532 Cross-Site Request Forgery (CSRF) is a web-based attack whereby HTTP 1533 requests are transmitted from a user that the website trusts or has 1534 authenticated. CSRF attacks on authorization approvals can allow an 1535 attacker to obtain authorization to protected resources without the 1536 consent of the User. Servers SHOULD strongly consider best practices 1537 in CSRF prevention at all the protocol authorization endpoints. 1539 CSRF attacks on OAuth callback URIs hosted by clients are also 1540 possible. Clients should prevent CSRF attacks on OAuth callback URIs 1541 by verifying that the resource owner at the client site intended to 1542 complete the OAuth negotiation with the server. The methods for 1543 preventing such CSRF attacks are beyond the scope of this 1544 specification. 1546 4.14. User Interface Redress 1548 Servers should protect the authorization process against UI Redress 1549 attacks (also known as "clickjacking"). As of the time of this 1550 writing, no complete defenses against UI redress are available. 1551 Servers can mitigate the risk of UI redress attacks through the 1552 following techniques: 1554 o Javascript frame busting. 1556 o Javascript frame busting, and requiring that browsers have 1557 javascript enabled on the authorization page. 1559 o Browser-specific anti-framing techniques. 1561 o Requiring password reentry before issuing OAuth tokens. 1563 4.15. Automatic Processing of Repeat Authorizations 1565 Servers may wish to automatically process authorization requests 1566 (Section 2.2) from clients which have been previously authorized by 1567 the resource owner. When the resource owner is redirected to the 1568 server to grant access, the server detects that the resource owner 1569 has already granted access to that particular client. Instead of 1570 prompting the resource owner for approval, the server automatically 1571 redirects the resource owner back to the client. 1573 If the client credentials are compromised, automatic processing 1574 creates additional security risks. An attacker can use the stolen 1575 client credentials to redirect the resource owner to the server with 1576 an authorization request. The server will then grant access to the 1577 resource owner's data without the resource owner's explicit approval, 1578 or even awareness of an attack. If no automatic approval is 1579 implemented, an attacker must use social engineering to convince the 1580 resource owner to approve access. 1582 Servers can mitigate the risks associated with automatic processing 1583 by limiting the scope of token credentials obtained through automated 1584 approvals. Tokens credentials obtained through explicit resource 1585 owner consent can remain unaffected. Clients can mitigate the risks 1586 associated with automatic processing by protecting their client 1587 credentials. 1589 5. IANA Considerations 1591 This memo includes no request to IANA. 1593 6. Acknowledgments 1595 This specification is directly based on the OAuth Core 1.0 Revision A 1596 community specification which in turn was modeled after existing 1597 proprietary protocols and best practices that have been independently 1598 implemented by various companies. 1600 The community specification was edited by Eran Hammer-Lahav and 1601 authored by: Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 1602 Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 1603 Kellan Elliott-McCrea, Larry Halff, Eran Hammer-Lahav, Ben Laurie, 1604 Chris Messina, John Panzer, Sam Quigley, David Recordon, Eran 1605 Sandler, Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy 1606 Smith. 1608 The editor would like to thank the following individuals for their 1609 invaluable contribution to the publication of this edition of the 1610 protocol: Lisa Dusseault, Justin Hart, Avshalom Houri, Chris Messina, 1611 Mark Nottingham, Tim Polk, Peter Saint-Andre, Joseph Smarr, and Paul 1612 Walker. 1614 Appendix A. Differences from the Community Edition 1616 This specification includes the following changes made to the 1617 original community document [OAuth Core 1.0 Revision A] in order to 1618 correct mistakes and omissions identified since the document has been 1619 published: 1621 o Changed using TLS/SSL when sending or requesting plain text 1622 credentials from SHOULD to MUST. This change affects any use of 1623 the "PLAINTEXT" signature method, as well as requesting temporary 1624 credentials (Section 2.1) and obtaining token credentials 1625 (Section 2.3). 1627 o Adjusted nonce language to indicate it is unique per token/ 1628 timestamp/client combination. 1630 o Removed the requirement for timestamps to be equal to or greater 1631 than the timestamp used in the previous request. 1633 o Changed the nonce and timestamp parameters to OPTIONAL when using 1634 the "PLAINTEXT" signature method. 1636 o Extended signature base string coverage which includes 1637 "application/x-www-form-urlencoded" entity-body parameters when 1638 the HTTP method used is other than "POST" and URI query parameters 1639 when the HTTP method used is other than "GET". 1641 o Incorporated corrections to the instructions in each signature 1642 method to encode the signature value before inserting it into the 1643 "oauth_signature" parameter, removing errors which would have 1644 caused double-encoded values. 1646 o Allowed omitting the "oauth_token" parameter when empty. 1648 o Permitted sending requests for temporary credentials with an empty 1649 "oauth_token" parameter. 1651 o Removed the restrictions from defining additional "oauth_" 1652 parameters. 1654 Appendix B. Document History 1656 [[ To be removed by the RFC editor before publication as an RFC. ]] 1658 -10 1660 o Added missing 'oauth_token' in exmaple. 1662 o Changed realm values from URI to string to make them more generic 1663 (since the protocol does not define any internal structure for 1664 them). 1666 -09 1668 o Added 'with a 200 status code (OK)' in two places. 1670 o Missing comma in example. 1672 o Corrected typos. 1674 o Changed the use of TLS/SSL when sending or receiving plain text 1675 credentials to a MUST. 1677 o Clarified text about change control moving from the community to 1678 the IETF. 1680 -08 1682 o Adjusted timestamp language to allow use of time servers for clock 1683 sync. 1685 o Revised security language for SHA-1 weakness and applicability. 1687 o Added link to the community specification. 1689 o Minor editorial changes. 1691 -07 1693 o Corrected typos. 1695 o Changed examples to use HTTPS in authorization step. 1697 o Clarified the use of 'oauth_' tokens in the three static endpoint 1698 URIs. 1700 o Edited abstract and introduction. 1702 -06 1704 o Moved parameter section into client instructions. 1706 o Added more examples in the delegation section, including more 1707 complete HTTP responses. 1709 o Removed language about restricting the use of the 'oauth_' prefix. 1711 o Changed the nonce and timestamp parameters to optional when using 1712 PLAINTEXT. 1714 o Allowed empty token in temporary credentials requests. 1716 -05 1718 o Replaced the word 'lexicographical' with 'ascending' in sorting 1719 instructions. 1721 o Added note that the 'a3' parameter appears twice in the example. 1723 o Made the note about the encoding scheme being different from most 1724 common implementations more explicit. 1726 o Moved and cleaned up the example from appendix to introduction. 1727 Removed crypto details from the example. 1729 -04 1731 o Corrected typo and other minor editorial changes. 1733 o Added warning about token sizes. 1735 o Clarified that all 'oauth_' parameters must be transmitted using 1736 the same method. 1738 o Added explicit requirement to exclude parameters not transmitted 1739 in a request in the signature base string (for example 1740 oauth_version when omitted). 1742 o Explicitly set OAuth to use HTTP 1.1. 1744 o Rearranged the signature base string section to provide a better 1745 narrative of how the HTTP request is normalized. Added the 1746 protocol parameters to the examples to better demonstrate how they 1747 are incorporated in practice. 1749 o Flipped the document order between authentication and 1750 authorization. 1752 o Removed the requirement for timestamps to be equal or greater than 1753 previous timestamps. 1755 -03 1757 o Updated draft with changes from OAuth Core 1.0 Revision A to fix a 1758 session fixation exploit. 1760 o Small editorial corrections. 1762 o Removed confusing language from 'Denial of Service / Resource 1763 Exhaustion Attacks'. 1765 o Added new 'Differences from the Community Edition' appendix. 1767 o Updated acknowledgements section. 1769 -02 1771 o Corrected mistake in parameter sorting order (c%40 comes before 1772 c2). 1774 o Added requirement to normalize empty paths as '/'. 1776 -01 1778 o Complete rewrite of the entire specification from scratch. 1779 Separated the spec structure into two parts and flipped their 1780 order. 1782 o Corrected errors in instructions to encode the signature base 1783 string by some methods. The signature value is encoded using the 1784 transport rules, not the spec method for encoding. 1786 o Replaced the entire terminology. 1788 -00 1790 o Initial draft based on the OAuth Core 1.0 community specification 1791 with the following changes. 1793 o Various changes required to accommodate the strict format 1794 requirements of the IETF, such as moving sections around 1795 (Security, Contributors, Introduction, etc.), cleaning references, 1796 adding IETF specific text, etc. 1798 o Moved the Parameter Encoding sub-section from section 5 1799 (Parameters) to section 9.1 (Signature Base String) to make it 1800 clear it only applies to the signature base string. 1802 o Nonce language adjusted to indicate it is unique per token/ 1803 timestamp/consumer combination. 1805 o Added security language regarding lack of token secrets in RSA- 1806 SHA1. 1808 o Fixed the bug in the Normalize Request Parameters section. 1809 Removed the "GET" limitation from the third bullet (query 1810 parameters). 1812 o Removed restriction of only signing application/ 1813 x-www-form-urlencoded in "POST" requests, allowing the entity-body 1814 to be used with all HTTP request methods. 1816 7. References 1817 7.1. Normative References 1819 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1820 Extensions (MIME) Part One: Format of Internet Message 1821 Bodies", RFC 2045, November 1996. 1823 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1824 Hashing for Message Authentication", RFC 2104, 1825 February 1997. 1827 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1828 Requirement Levels", BCP 14, RFC 2119, March 1997. 1830 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1831 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1832 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1834 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1835 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1836 Authentication: Basic and Digest Access Authentication", 1837 RFC 2617, June 1999. 1839 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1841 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1842 Standards (PKCS) #1: RSA Cryptography Specifications 1843 Version 2.1", RFC 3447, February 2003. 1845 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1846 10646", STD 63, RFC 3629, November 2003. 1848 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1849 Resource Identifier (URI): Generic Syntax", STD 66, 1850 RFC 3986, January 2005. 1852 [W3C.REC-html40-19980424] 1853 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.0 1854 Specification", World Wide Web Consortium 1855 Recommendation REC-html40-19980424, April 1998, 1856 . 1858 7.2. Informative References 1860 [NIST SHA-1 Comments] 1861 Burr, W., "NIST Comments on Cryptanalytic Attacks on 1862 SHA-1". 1864 [OAuth Core 1.0 Revision A] 1865 OAuth, OAuth Community., "OAuth Core 1.0 Revision A". 1867 Author's Address 1869 Eran Hammer-Lahav (editor) 1871 Email: eran@hueniverse.com 1872 URI: http://hueniverse.com