idnits 2.17.1 draft-hammer-oauth-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 1390. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1401. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1408. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1414. 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 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 (September 30, 2008) is 5679 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational RFC: RFC 2104 ** 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 3447 (Obsoleted by RFC 8017) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 7 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 B. Cook 4 Intended status: Standards Track September 30, 2008 5 Expires: April 3, 2009 7 OAuth: HTTP Authorization Delegation Protocol 8 draft-hammer-oauth-00 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on April 3, 2009. 35 Abstract 37 This document specifies OAuth, an HTTP authorization delegation 38 protocol for accessing protected resources. 40 Table of Contents 42 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 43 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 4 44 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 45 4. Documentation and Registration . . . . . . . . . . . . . . . . 5 46 4.1. Request URLs . . . . . . . . . . . . . . . . . . . . . . 5 47 4.2. Service Providers . . . . . . . . . . . . . . . . . . . . 6 48 4.3. Consumers . . . . . . . . . . . . . . . . . . . . . . . . 6 49 5. Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 6 50 5.1. Consumer Request Parameters . . . . . . . . . . . . . . . 7 51 5.2. Service Provider Response Parameters . . . . . . . . . . 7 52 5.3. OAuth HTTP Authorization Scheme . . . . . . . . . . . . . 7 53 5.3.1. Authorization Header . . . . . . . . . . . . . . . . . 7 54 5.3.2. WWW-Authenticate Header . . . . . . . . . . . . . . . 8 55 6. Authenticating with OAuth . . . . . . . . . . . . . . . . . . 8 56 6.1. Obtaining an Unauthorized Request Token . . . . . . . . . 9 57 6.1.1. Consumer Obtains a Request Token . . . . . . . . . . . 9 58 6.1.2. Service Provider Issues an Unauthorized Request 59 Token . . . . . . . . . . . . . . . . . . . . . . . . 10 60 6.2. Obtaining User Authorization . . . . . . . . . . . . . . 10 61 6.2.1. Consumer Directs the User to the Service Provider . . 10 62 6.2.2. Service Provider Authenticates the User and 63 Obtains Consent . . . . . . . . . . . . . . . . . . . 11 64 6.2.3. Service Provider Directs the User Back to the 65 Consumer . . . . . . . . . . . . . . . . . . . . . . . 12 66 6.3. Obtaining an Access Token . . . . . . . . . . . . . . . . 12 67 6.3.1. Consumer Requests an Access Token . . . . . . . . . . 12 68 6.3.2. Service Provider Grants an Access Token . . . . . . . 13 69 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 14 70 8. Nonce and Timestamp . . . . . . . . . . . . . . . . . . . . . 14 71 9. Signing Requests . . . . . . . . . . . . . . . . . . . . . . . 15 72 9.1. Signature Base String . . . . . . . . . . . . . . . . . . 15 73 9.1.1. Parameter Encoding . . . . . . . . . . . . . . . . . . 15 74 9.1.2. Normalize Request Parameters . . . . . . . . . . . . . 16 75 9.1.3. Construct Request URL . . . . . . . . . . . . . . . . 17 76 9.1.4. Concatenate Request Elements . . . . . . . . . . . . . 17 77 9.2. HMAC-SHA1 . . . . . . . . . . . . . . . . . . . . . . . . 17 78 9.2.1. Generating Signature . . . . . . . . . . . . . . . . . 18 79 9.2.2. Verifying Signature . . . . . . . . . . . . . . . . . 18 80 9.3. RSA-SHA1 . . . . . . . . . . . . . . . . . . . . . . . . 18 81 9.3.1. Generating Signature . . . . . . . . . . . . . . . . . 18 82 9.3.2. Verifying Signature . . . . . . . . . . . . . . . . . 18 83 9.4. PLAINTEXT . . . . . . . . . . . . . . . . . . . . . . . . 19 84 9.4.1. Generating Signature . . . . . . . . . . . . . . . . . 19 85 9.4.2. Verifying Signature . . . . . . . . . . . . . . . . . 19 86 10. HTTP Response Codes . . . . . . . . . . . . . . . . . . . . . 19 87 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 88 12. Security Considerations . . . . . . . . . . . . . . . . . . . 20 89 12.1. Credentials and Token Exchange . . . . . . . . . . . . . 20 90 12.2. RSA-SHA1 Signature Method . . . . . . . . . . . . . . . . 20 91 12.3. PLAINTEXT Signature Method . . . . . . . . . . . . . . . 20 92 12.4. Confidentiality of Requests . . . . . . . . . . . . . . . 21 93 12.5. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 21 94 12.6. Proxying and Caching of Authenticated Content . . . . . . 21 95 12.7. Plaintext Storage of Credentials . . . . . . . . . . . . 21 96 12.8. Secrecy of the Consumer Secret . . . . . . . . . . . . . 22 97 12.9. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 22 98 12.10. Scoping of Access Requests . . . . . . . . . . . . . . . 22 99 12.11. Entropy of Secrets . . . . . . . . . . . . . . . . . . . 22 100 12.12. Denial of Service / Resource Exhaustion Attacks . . . . . 23 101 12.13. Cryptographic Attacks . . . . . . . . . . . . . . . . . . 24 102 12.14. Signature Base String Compatibility . . . . . . . . . . . 24 103 Appendix A. Appendix A - Protocol Example . . . . . . . . . . 24 104 Appendix A.1. Documentation and Registration . . . . . . . . . . 24 105 Appendix A.2. Obtaining a Request Token . . . . . . . . . . . . 25 106 Appendix A.3. Requesting User Authorization . . . . . . . . . . 26 107 Appendix A.4. Obtaining an Access Token . . . . . . . . . . . . 26 108 Appendix A.5. Accessing Protected Resources . . . . . . . . . . 26 109 Appendix A.5.1. Generating Signature Base String . . . . . . . . . 26 110 Appendix A.5.2. Calculating Signature Value . . . . . . . . . . . 27 111 Appendix A.5.3. Requesting Protected Resource . . . . . . . . . . 27 112 Appendix B. Contributors . . . . . . . . . . . . . . . . . . . 28 113 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 114 13.1. Normative References . . . . . . . . . . . . . . . . . . 29 115 13.2. Informative References . . . . . . . . . . . . . . . . . 30 116 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 117 Intellectual Property and Copyright Statements . . . . . . . . . . 31 119 1. Introduction 121 The OAuth protocol enables websites or applications (Consumers) to 122 access Protected Resources from a web service (Service Provider) via 123 an API, without requiring Users to disclose their Service Provider 124 credentials to the Consumers. More generally, OAuth creates a 125 freely-implementable and generic methodology for API authentication. 127 An example use case is allowing printing service printer.example.com 128 (the Consumer), to access private photos stored on photos.example.net 129 (the Service Provider) without requiring Users to provide their 130 photos.example.net credentials to printer.example.com. 132 OAuth does not require a specific user interface or interaction 133 pattern, nor does it specify how Service Providers authenticate 134 Users, making the protocol ideally suited for cases where 135 authentication credentials are unavailable to the Consumer, such as 136 with OpenID. 138 OAuth aims to unify the experience and implementation of delegated 139 web service authentication into a single, community-driven protocol. 140 OAuth builds on existing protocols and best practices that have been 141 independently implemented by various websites. An open standard, 142 supported by large and small providers alike, promotes a consistent 143 and trusted experience for both application developers and the users 144 of those applications. 146 Discussion of this draft should take place on the OAuth mailing list 147 located at oauth@googlegroups.com. To join the list, visit 148 http://groups.google.com/group/oauth (you will be asked to provide a 149 reason to join solely as a spam filter). 151 2. Requirements Language 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 155 document are to be interpreted as described in [RFC2119]. 157 3. Definitions 159 Service Provider: A web application that allows access via OAuth. 161 User: An individual who has an account with the Service Provider. 163 Consumer: A website or application that uses OAuth to access the 164 Service Provider on behalf of the User. 166 Protected Resource(s): Data controlled by the Service Provider, 167 which the Consumer can access through authentication. 169 Consumer Developer: An individual or organization that implements a 170 Consumer. 172 Consumer Key: A value used by the Consumer to identify itself to the 173 Service Provider. 175 Consumer Secret: A secret used by the Consumer to establish 176 ownership of the Consumer Key. 178 Request Token: A value used by the Consumer to obtain authorization 179 from the User, and exchanged for an Access Token. 181 Access Token: A value used by the Consumer to gain access to the 182 Protected Resources on behalf of the User, instead of using the 183 User's Service Provider credentials. 185 Token Secret: A secret used by the Consumer to establish ownership 186 of a given Token. 188 OAuth Protocol Parameters: Parameters with names beginning with 189 "oauth_". 191 4. Documentation and Registration 193 OAuth includes a Consumer Key and matching Consumer Secret that 194 together authenticate the Consumer (as opposed to the User) with the 195 Service Provider. Consumer-specific identification allows the 196 Service Provider to vary access levels to Consumers (such as un- 197 throttled access to resources). 199 Service Providers SHOULD NOT rely on the Consumer Secret as a method 200 to verify the Consumer identity, unless the Consumer Secret is known 201 to be inaccessible to anyone other than the Consumer and the Service 202 Provider. The Consumer Secret MAY be an empty string (for example 203 when no Consumer verification is needed, or when verification is 204 achieved through other means such as RSA). 206 4.1. Request URLs 208 OAuth defines three request URLs: 210 Request Token URL: The URL used to obtain an unauthorized Request 211 Token, described in Section 6.1. 213 User Authorization URL: The URL used to obtain User authorization 214 for Consumer access, described in Section 6.2. 216 Access Token URL: The URL used to exchange the User-authorized 217 Request Token for an Access Token, described in Section 6.3. 219 The three URLs MUST include scheme, authority, and path, and MAY 220 include query and fragment as defined by [RFC3986] section 3. The 221 request URL query MUST NOT contain any OAuth Protocol Parameters. 222 For example: 224 http://sp.example.com/authorize 226 4.2. Service Providers 228 The Service Provider's responsibility is to enable Consumer 229 Developers to establish a Consumer Key and Consumer Secret. The 230 process and requirements for provisioning these are entirely up to 231 the Service Providers. 233 The Service Provider's documentation includes: 235 1. The URLs (Section 4.1) the Consumer will use when making OAuth 236 requests, and the HTTP methods (i.e. GET, POST, etc.) used in 237 the Request Token URL and Access Token URL. 239 2. Signature methods supported by the Service Provider. 241 3. Any additional request parameters that the Service Provider 242 requires in order to obtain a Token. Service Provider specific 243 parameters MUST NOT begin with "oauth_". 245 4.3. Consumers 247 The Consumer Developer MUST establish a Consumer Key and a Consumer 248 Secret with the Service Provider. The Consumer Developer MAY also be 249 required to provide additional information to the Service Provider 250 upon registration. 252 5. Parameters 254 OAuth Protocol Parameter names and values are case sensitive. Each 255 OAuth Protocol Parameters MUST NOT appear more than once per request, 256 and are REQUIRED unless otherwise noted. 258 5.1. Consumer Request Parameters 260 OAuth Protocol Parameters are sent from the Consumer to the Service 261 Provider in one of three methods, in order of decreasing preference: 263 1. In the HTTP "Authorization" header as defined in OAuth HTTP 264 Authorization Scheme (Section 5.3). 266 2. As the HTTP request body with a " content-type " of 267 "application/x-www-form-urlencoded" as defined by 268 [W3C.REC-html40-19980424]. 270 3. Added to the URLs in the query part (as defined by [RFC3986] 271 section 3). 273 In addition to these defined methods, future extensions may describe 274 alternate methods for sending the OAuth Protocol Parameters. The 275 methods for sending other request parameters are left undefined, but 276 SHOULD NOT use the OAuth HTTP Authorization Scheme (Section 5.3) 277 header. 279 5.2. Service Provider Response Parameters 281 Response parameters such as Tokens and Token Secrets are sent by the 282 Service Provider to the Consumer in the HTTP response body using the 283 "application/x-www-form-urlencoded" content type as defined by 284 [W3C.REC-html40-19980424]. For example: 286 oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=xyz4992k83j47x0b 288 5.3. OAuth HTTP Authorization Scheme 290 This section defines an [RFC2617] extension to support OAuth. It 291 uses the standard HTTP "Authorization" and "WWW-Authenticate" headers 292 to pass OAuth Protocol Parameters. 294 It is RECOMMENDED that Service Providers accept the HTTP 295 "Authorization" header. Consumers SHOULD be able to send OAuth 296 Protocol Parameters in the OAuth "Authorization" header. 298 The extension auth-scheme (as defined by [RFC2617]) is "OAuth" and is 299 case-insensitive. 301 5.3.1. Authorization Header 303 The OAuth Protocol Parameters are sent in the "Authorization" header 304 the following way: 306 1. Parameter names and values are encoded per Parameter Encoding 307 (Section 9.1.1). 309 2. For each parameter, the name is immediately followed by an '=' 310 character (ASCII code 61), a '"' character (ASCII code 34), the 311 parameter value (MAY be empty), and another '"' character (ASCII 312 code 34). 314 3. Parameters are separated by a comma character (ASCII code 44) and 315 OPTIONAL linear whitespace per [RFC2617]. 317 4. The OPTIONAL "realm" parameter is added and interpreted per 318 [RFC2617], section 1.2. 320 For example: 322 Authorization: OAuth realm="http://sp.example.com/", 323 oauth_consumer_key="0685bd9184jfhq22", 324 oauth_token="ad180jjd733klru7", 325 oauth_signature_method="HMAC-SHA1", 326 oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D", 327 oauth_timestamp="137131200", 328 oauth_nonce="4572616e48616d6d65724c61686176", 329 oauth_version="1.0" 331 5.3.2. WWW-Authenticate Header 333 Service Providers MAY indicate their support for the extension by 334 returning the OAuth HTTP "WWW-Authenticate" header upon Consumer 335 requests for Protected Resources. As per [RFC2617] such a response 336 MAY include additional HTTP "WWW-Authenticate" headers: 338 For example: 340 WWW-Authenticate: OAuth realm="http://sp.example.com/" 342 The realm parameter defines a protection realm per [RFC2617], section 343 1.2. 345 6. Authenticating with OAuth 347 OAuth authentication is the process in which Users grant access to 348 their Protected Resources without sharing their credentials with the 349 Consumer. OAuth uses Tokens generated by the Service Provider 350 instead of the User's credentials in Protected Resources requests. 351 The process uses two Token types: 353 Request Token: Used by the Consumer to ask the User to authorize 354 access to the Protected Resources. The User-authorized Request 355 Token is exchanged for an Access Token, MUST only be used once, 356 and MUST NOT be used for any other purpose. It is RECOMMENDED 357 that Request Tokens have a limited lifetime. 359 Access Token: Used by the Consumer to access the Protected Resources 360 on behalf of the User. Access Tokens MAY limit access to certain 361 Protected Resources, and MAY have a limited lifetime. Service 362 Providers SHOULD allow Users to revoke Access Tokens. Only the 363 Access Token SHALL be used to access the Protect Resources. 365 OAuth Authentication is done in three steps: 367 1. The Consumer obtains an unauthorized Request Token. 369 2. The User authorizes the Request Token. 371 3. The Consumer exchanges the Request Token for an Access Token. 373 6.1. Obtaining an Unauthorized Request Token 375 The Consumer obtains an unauthorized Request Token by asking the 376 Service Provider to issue a Token. The Request Token's sole purpose 377 is to receive User approval and can only be used to obtain an Access 378 Token. The Request Token process goes as follows: 380 6.1.1. Consumer Obtains a Request Token 382 To obtain a Request Token, the Consumer sends an HTTP request to the 383 Service Provider's Request Token URL. The Service Provider 384 documentation specifies the HTTP method for this request, and HTTP 385 POST is RECOMMENDED. The request MUST be signed and contains the 386 following parameters: 388 oauth_consumer_key: The Consumer Key. 390 oauth_signature_method: The signature method the Consumer used to 391 sign the request. 393 oauth_signature: The signature as defined in Signing Requests 394 (Section 9). 396 oauth_timestamp: As defined in Nonce and Timestamp (Section 8). 398 oauth_nonce: As defined in Nonce and Timestamp (Section 8). 400 oauth_version: OPTIONAL. If present, value MUST be " 1.0 ". 401 Service Providers MUST assume the protocol version to be "1.0" if 402 this parameter is not present. Service Providers' response to 403 non-"1.0" value is left undefined. 405 Additional parameters: Any additional parameters, as defined by the 406 Service Provider. 408 6.1.2. Service Provider Issues an Unauthorized Request Token 410 The Service Provider verifies the signature and Consumer Key. If 411 successful, it generates a Request Token and Token Secret and returns 412 them to the Consumer in the HTTP response body as defined in Service 413 Provider Response Parameters (Section 5.2). The Service Provider 414 MUST ensure the Request Token cannot be exchanged for an Access Token 415 until the User successfully grants access in Obtaining User 416 Authorization (Section 6.2). 418 The response contains the following parameters: 420 oauth_token: The Request Token. 422 oauth_token_secret: The Token Secret. 424 Additional parameters: Any additional parameters, as defined by the 425 Service Provider. 427 If the request fails verification or is rejected for other reasons, 428 the Service Provider SHOULD respond with the appropriate response 429 code as defined in HTTP Response Codes (Section 10). The Service 430 Provider MAY include some further details about why the request was 431 rejected in the HTTP response body as defined in Service Provider 432 Response Parameters (Section 5.2). 434 6.2. Obtaining User Authorization 436 The Consumer cannot use the Request Token until it has been 437 authorized by the User. Obtaining User authorization includes the 438 following steps: 440 6.2.1. Consumer Directs the User to the Service Provider 442 In order for the Consumer to be able to exchange the Request Token 443 for an Access Token, the Consumer MUST obtain approval from the User 444 by directing the User to the Service Provider. The Consumer 445 constructs an HTTP GET request to the Service Provider's User 446 Authorization URL with the following parameter: 448 oauth_token: OPTIONAL. The Request Token obtained in the previous 449 step. The Service Provider MAY declare this parameter as 450 REQUIRED, or accept requests to the User Authorization URL without 451 it, in which case it will prompt the User to enter it manually. 453 oauth_callback: OPTIONAL. The Consumer MAY specify a URL the 454 Service Provider will use to redirect the User back to the 455 Consumer when Obtaining User Authorization (Section 6.2) is 456 complete. 458 Additional parameters: Any additional parameters, as defined by the 459 Service Provider. 461 Once the request URL has been constructed the Consumer redirects the 462 User to the URL via the User's web browser. If the Consumer is 463 incapable of automatic HTTP redirection, the Consumer SHALL notify 464 the User how to manually go to the constructed request URL. 466 Note: If a Service Provider knows a Consumer to be running on a 467 mobile device or set-top box, the Service Provider SHOULD ensure that 468 the User Authorization URL and Request Token are suitable for manual 469 entry. 471 6.2.2. Service Provider Authenticates the User and Obtains Consent 473 The Service Provider verifies the User's identity and asks for 474 consent as detailed. OAuth does not specify how the Service Provider 475 authenticates the User. However, it does define a set of REQUIRED 476 steps: 478 o The Service Provider MUST first verify the User's identity before 479 asking for consent. It MAY prompt the User to sign in if the User 480 has not already done so. 482 o The Service Provider presents to the User information about the 483 Consumer requesting access (as registered by the Consumer 484 Developer). The information includes the duration of the access 485 and the Protected Resources provided. The information MAY include 486 other details specific to the Service Provider. 488 o The User MUST grant or deny permission for the Service Provider to 489 give the Consumer access to the Protected Resources on behalf of 490 the User. If the User denies the Consumer access, the Service 491 Provider MUST NOT allow access to the Protected Resources. 493 When displaying any identifying information about the Consumer to the 494 User based on the Consumer Key, the Service Provider MUST inform the 495 User if it is unable to assure the Consumer's true identity. The 496 method in which the Service Provider informs the User and the quality 497 of the identity assurance is beyond the scope of this specification. 499 6.2.3. Service Provider Directs the User Back to the Consumer 501 After the User authenticates with the Service Provider and grants 502 permission for Consumer access, the Consumer MUST be notified that 503 the Request Token has been authorized and ready to be exchanged for 504 an Access Token. If the User denies access, the Consumer MAY be 505 notified that the Request Token has been revoked. 507 If the Consumer provided a callback URL in "oauth_callback" (as 508 described in Consumer Directs the User to the Service Provider 509 (Section 6.2.1)), the Service Provider constructs an HTTP GET request 510 URL, and redirects the User's web browser to that URL with the 511 following parameters: 513 oauth_token: The Request Token the User authorized or denied. 515 The callback URL MAY include Consumer provided query parameters. The 516 Service Provider MUST retain them unmodified and append the 517 "oauth_token" parameter to the existing query. 519 If no callback URL was provided, the Service Provider instructs the 520 User to manually inform the Consumer that authorization has 521 completed. 523 6.3. Obtaining an Access Token 525 The Consumer exchanges the Request Token for an Access Token capable 526 of accessing the Protected Resources. Obtaining an Access Token 527 includes the following steps: 529 6.3.1. Consumer Requests an Access Token 531 The Request Token and Token Secret MUST be exchanged for an Access 532 Token and Token Secret. 534 To request an Access Token, the Consumer makes an HTTP request to the 535 Service Provider's Access Token URL. The Service Provider 536 documentation specifies the HTTP method for this request, and HTTP 537 POST is RECOMMENDED. The request MUST be signed per Signing Requests 538 (Section 9), and contains the following parameters: 540 oauth_consumer_key: The Consumer Key. 542 oauth_token: The Request Token obtained previously. 544 oauth_signature_method: The signature method the Consumer used to 545 sign the request. 547 oauth_signature: The signature as defined in Signing Requests 548 (Section 9). 550 oauth_timestamp: As defined in Nonce and Timestamp (Section 8). 552 oauth_nonce: As defined in Nonce and Timestamp (Section 8). 554 oauth_version: OPTIONAL. If present, value MUST be " 1.0 ". 555 Service Providers MUST assume the protocol version to be "1.0" if 556 this parameter is not present. Service Providers' response to 557 non-"1.0" value is left undefined. 559 No additional Service Provider specific parameters are allowed when 560 requesting an Access Token to ensure all Token related information is 561 present prior to seeking User approval. 563 6.3.2. Service Provider Grants an Access Token 565 The Service Provider MUST ensure that: 567 o The request signature has been successfully verified. 569 o The Request Token has never been exchanged for an Access Token. 571 o The Request Token matches the Consumer Key. 573 If successful, the Service Provider generates an Access Token and 574 Token Secret and returns them in the HTTP response body as defined in 575 Service Provider Response Parameters (Section 5.2). The Access Token 576 and Token Secret are stored by the Consumer and used when signing 577 Protected Resources requests. The response contains the following 578 parameters: 580 oauth_token: The Access Token. 582 oauth_token_secret: The Token Secret. 584 Additional parameters: Any additional parameters, as defined by the 585 Service Provider. 587 If the request fails verification or is rejected for other reasons, 588 the Service Provider SHOULD respond with the appropriate response 589 code as defined in HTTP Response Codes (Section 10). The Service 590 Provider MAY include some further details about why the request was 591 rejected in the HTTP response body as defined in Service Provider 592 Response Parameters (Section 5.2). 594 7. Accessing Protected Resources 596 After successfully receiving the Access Token and Token Secret, the 597 Consumer is able to access the Protected Resources on behalf of the 598 User. The request MUST be signed per Signing Requests (Section 9), 599 and contains the following parameters: 601 oauth_consumer_key: The Consumer Key. 603 oauth_token: The Access Token. 605 oauth_signature_method: The signature method the Consumer used to 606 sign the request. 608 oauth_signature: The signature as defined in Signing Requests 609 (Section 9). 611 oauth_timestamp: As defined in Nonce and Timestamp (Section 8). 613 oauth_nonce: As defined in Nonce and Timestamp (Section 8). 615 oauth_version: OPTIONAL. If present, value MUST be "1.0". Service 616 Providers MUST assume the protocol version to be "1.0" if this 617 parameter is not present. Service Providers' response to 618 non-"1.0" value is left undefined. 620 Additional parameters: Any additional parameters, as defined by the 621 Service Provider. 623 8. Nonce and Timestamp 625 Unless otherwise specified by the Service Provider, the timestamp is 626 expressed in the number of seconds since January 1, 1970 00:00:00 627 GMT. The timestamp value MUST be a positive integer and MUST be 628 equal or greater than the timestamp used in previous requests. 630 The Consumer SHALL then generate a Nonce value that is unique for all 631 requests with that timestamp, Consumer Key, and Token combination. A 632 nonce is a random string, uniquely generated for each request. The 633 nonce allows the Service Provider to verify that a request has never 634 been made before and helps prevent replay attacks when requests are 635 made over a non-secure channel (such as HTTP). 637 9. Signing Requests 639 All Token requests and Protected Resources requests MUST be signed by 640 the Consumer and verified by the Service Provider. The purpose of 641 signing requests is to prevent unauthorized parties from using the 642 Consumer Key and Tokens when making Token requests or Protected 643 Resources requests. The signature process encodes the Consumer 644 Secret and Token Secret into a verifiable value which is included 645 with the request. 647 OAuth does not mandate a particular signature method, as each 648 implementation can have its own unique requirements. The protocol 649 defines three signature methods: "HMAC-SHA1", "RSA-SHA1", and 650 "PLAINTEXT", but Service Providers are free to implement and document 651 their own methods. Recommending any particular method is beyond the 652 scope of this specification. 654 The Consumer declares a signature method in the 655 "oauth_signature_method" parameter, generates a signature, and stores 656 it in the "oauth_signature" parameter. The Service Provider verifies 657 the signature as specified in each method. When verifying a Consumer 658 signature, the Service Provider SHOULD check the request nonce to 659 ensure it has not been used in a previous Consumer request. 661 The signature process MUST NOT change the request parameter names or 662 values, with the exception of the "oauth_signature" parameter. 664 9.1. Signature Base String 666 The Signature Base String is a consistent reproducible concatenation 667 of the request elements into a single string. The string is used as 668 an input in hashing or signing algorithms. The "HMAC-SHA1" signature 669 method provides both a standard and an example of using the Signature 670 Base String with a signing algorithm to generate signatures. 672 9.1.1. Parameter Encoding 674 All parameter names and values MUST be encoded prior to constructing 675 the Signature Base String. The encoding process uses the parameters 676 in their original decoded form. It is essential that parameters are 677 encoded in a certain way and need to be processed without any prior 678 encoding. 680 Text names and values are first encoded as UTF-8 octets per 682 [RFC3629]. All parameter names and values are then escaped using the 683 [RFC3986] percent-encoding (%XX) mechanism as follows: 685 o Characters not in the unreserved character set ([RFC3986] section 686 2.3) MUST be encoded. 688 o Characters in the unreserved character set MUST NOT be encoded. 690 o Hexadecimal characters in encodings MUST be upper case. 692 unreserved = ALPHA, DIGIT, '-', '.', '_', '~' 694 9.1.2. Normalize Request Parameters 696 The request parameters are collected, sorted and concatenated into a 697 normalized string: 699 o Parameters in the OAuth HTTP Authorization header (Section 5.3.1) 700 excluding the "realm" parameter. 702 o Parameters in the HTTP POST request body (with a "content-type" of 703 "application/x-www-form-urlencoded"). 705 o Added to the URLs in the query part (as defined by [RFC3986] 706 section 3). 708 The "oauth_signature" parameter MUST be excluded. 710 The parameters are normalized into a single string as follows: 712 1. Parameters are sorted by name, using lexicographical byte value 713 ordering. If two or more parameters share the same name, they 714 are sorted by their value. For example: 716 a=1, c=hi%20there, f=25, f=50, f=a, z=p, z=t 718 2. Parameters are concatenated in their sorted order into a single 719 string. For each parameter, the name is separated from the 720 corresponding value by an '=' character (ASCII code 61), even if 721 the value is empty. Each name-value pair is separated by an '&' 722 character (ASCII code 38). For example: 724 a=1&c=hi%20there&f=25&f=50&f=a&z=p&z=t 726 9.1.3. Construct Request URL 728 The Signature Base String includes the request absolute URL, tying 729 the signature to a specific endpoint. The URL used in the Signature 730 Base String MUST include the scheme, authority, and path, and MUST 731 exclude the query and fragment as defined by [RFC3986] section 3. 733 If the absolute request URL is not available to the Service Provider 734 (it is always available to the Consumer), it can be constructed by 735 combining the scheme being used, the HTTP "Host" header, and the 736 relative HTTP request URL. If the "Host" header is not available, 737 the Service Provider SHOULD use the host name communicated to the 738 Consumer in the documentation or other means. 740 The Service Provider SHOULD document the form of URL used in the 741 Signature Base String to avoid ambiguity due to URL normalization. 742 Unless specified, URL scheme and authority MUST be lowercase and 743 include the port number; "http" default port 80 and "https" default 744 port 443 MUST be excluded. 746 For example, the request: 748 HTTP://Example.com:80/resource?id=123 750 Is included in the Signature Base String as: 752 http://example.com/resource 754 9.1.4. Concatenate Request Elements 756 The following items MUST be concatenated in order into a single 757 string. Each item is encoded (Section 9.1.1) and separated by an '&' 758 character (ASCII code 38), even if empty. 760 1. The HTTP request method used to send the request. Value MUST be 761 uppercase, for example: "HEAD", " GET ", "POST", etc. 763 2. The request URL from Section 9.1.3. 765 3. The normalized request parameters string from Section 9.1.2. 767 See Signature Base String example in Appendix A.5.1. 769 9.2. HMAC-SHA1 771 The "HMAC-SHA1" signature method uses the HMAC-SHA1 signature 772 algorithm as defined in [RFC2104] where the Signature Base String is 773 the "text" and the "key" is the concatenated values (each first 774 encoded per Parameter Encoding (Section 9.1.1)) of the Consumer 775 Secret and Token Secret, separated by an '&' character (ASCII code 776 38) even if empty. 778 9.2.1. Generating Signature 780 "oauth_signature" is set to the calculated "digest" octet string, 781 first base64-encoded per [RFC2045] section 6.8, then URL-encoded per 782 Parameter Encoding (Section 9.1.1). 784 9.2.2. Verifying Signature 786 The Service Provider verifies the request by generating a new request 787 signature octet string, and comparing it to the signature provided by 788 the Consumer, first URL-decoded per Parameter Encoding 789 (Section 9.1.1), then base64-decoded per [RFC2045] section 6.8. The 790 signature is generated using the request parameters as provided by 791 the Consumer, and the Consumer Secret and Token Secret as stored by 792 the Service Provider. 794 9.3. RSA-SHA1 796 The "RSA-SHA1" signature method uses the RSASSA-PKCS1-v1_5 signature 797 algorithm as defined in [RFC3447] section 8.2 (more simply known as 798 PKCS#1), using SHA-1 as the hash function for EMSA-PKCS1-v1_5. It is 799 assumed that the Consumer has provided its RSA public key in a 800 verified way to the Service Provider, in a manner which is beyond the 801 scope of this specification. 803 9.3.1. Generating Signature 805 The Signature Base String is signed using the Consumer's RSA private 806 key per [RFC3447] section 8.2.1, where "K" is the Consumer's RSA 807 private key, "M" the Signature Base String, and "S" is the result 808 signature octet string: 810 S = RSASSA-PKCS1-V1_5-SIGN (K, M) 812 "oauth_signature" is set to "S", first base64-encoded per [RFC2045] 813 section 6.8, then URL-encoded per Parameter Encoding (Section 9.1.1). 815 9.3.2. Verifying Signature 817 The Service Provider verifies the signature per [RFC3447] section 818 8.2.2, where " (n, e) " is the Consumer's RSA public key, "M" is the 819 Signature Base String, and "S" is the octet string representation of 820 the "oauth_signature" value: 822 RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, S) 824 9.4. PLAINTEXT 826 The " PLAINTEXT " method does not provide any security protection and 827 SHOULD only be used over a secure channel such as HTTPS. It does not 828 use the Signature Base String. 830 9.4.1. Generating Signature 832 "oauth_signature" is set to the concatenated encoded values of the 833 Consumer Secret and Token Secret, separated by a '&' character (ASCII 834 code 38), even if either secret is empty. The result MUST be encoded 835 again. 837 These examples show the value of "oauth_signature" for Consumer 838 Secret "djr9rjt0jd78jf88" and 3 different Token Secrets: 840 jjd999tj88uiths3: 841 "oauth_signature"="djr9rjt0jd78jf88%26jjd999tj88uiths3" 843 jjd99$tj88uiths3: 844 "oauth_signature"="djr9rjt0jd78jf88%26jjd99%2524tj88uiths3" 846 Empty: "oauth_signature"="djr9rjt0jd78jf88%26" 848 9.4.2. Verifying Signature 850 The Service Provider verifies the request by breaking the signature 851 value into the Consumer Secret and Token Secret, and ensures they 852 match the secrets stored locally. 854 10. HTTP Response Codes 856 This section applies only to the Request Token and Access Token 857 requests. In general, the Service Provider SHOULD use the response 858 codes defined in [RFC2616] Section 10. When the Service Provider 859 rejects a Consumer request, it SHOULD respond with HTTP 400 Bad 860 Request or HTTP 401 Unauthorized. 862 o HTTP 400 Bad Request 864 * Unsupported parameter 866 * Unsupported signature method 867 * Missing required parameter 869 * Duplicated OAuth Protocol Parameter 871 o HTTP 401 Unauthorized 873 * Invalid Consumer Key 875 * Invalid / expired Token 877 * Invalid signature 879 * Invalid / used nonce 881 11. IANA Considerations 883 This memo includes no request to IANA. 885 12. Security Considerations 887 12.1. Credentials and Token Exchange 889 The OAuth specification does not describe any mechanism for 890 protecting Tokens and secrets from eavesdroppers when they are 891 transmitted from the Service Provider to the Consumer in 892 Section 6.1.2 and Section 6.3.2. Service Providers should ensure 893 that these transmissions are protected using transport-layer 894 mechanisms such as TLS or SSL. 896 12.2. RSA-SHA1 Signature Method 898 When used with "RSA-SHA1" signatures, the OAuth protocol does not use 899 the Consumer Secret and Token Secret. This means the protocol relies 900 completely on the secrecy of the Private Key used by the Consumer to 901 sign requests. 903 12.3. PLAINTEXT Signature Method 905 When used with "PLAINTEXT" signatures, the OAuth protocol makes no 906 attempts to protect User credentials from eavesdroppers or man-in- 907 the-middle attacks. The "PLAINTEXT" signature algorithm is only 908 intended to be used in conjunction with a transport-layer security 909 mechanism such as TLS or SSL which does provide such protection. If 910 transport-layer protection is unavailable, the "PLAINTEXT" signature 911 method should not be used. 913 12.4. Confidentiality of Requests 915 While OAuth provides a mechanism for verifying the integrity of 916 requests, it provides no guarantee of request confidentiality. 917 Unless further precautions are taken, eavesdroppers will have full 918 access to request content. Service Providers should carefully 919 consider the kinds of data likely to be sent as part of such 920 requests, and should employ transport-layer security mechanisms to 921 protect sensitive resources. 923 12.5. Spoofing by Counterfeit Servers 925 OAuth makes no attempt to verify the authenticity of the Service 926 Provider. A hostile party could take advantage of this by 927 intercepting the Consumer's requests and returning misleading or 928 otherwise incorrect responses. Service providers should consider 929 such attacks when developing services based on OAuth, and should 930 require transport-layer security for any requests where the 931 authenticity of the Service Provider or of request responses is an 932 issue. 934 12.6. Proxying and Caching of Authenticated Content 936 The HTTP Authorization scheme (Section 5.3) is optional. However, 937 [RFC2616] relies on the "Authorization" and "WWW-Authenticate" 938 headers to distinguish authenticated content so that it can be 939 protected. Proxies and caches, in particular, may fail to adequately 940 protect requests not using these headers. 942 For example, private authenticated content may be stored in (and thus 943 retrievable from) publicly-accessible caches. Service Providers not 944 using the HTTP Authorization scheme (Section 5.3) should take care to 945 use other mechanisms, such as the "Cache-Control" header, to ensure 946 that authenticated content is protected. 948 12.7. Plaintext Storage of Credentials 950 The Consumer Secret and Token Secret function the same way passwords 951 do in traditional authentication systems. In order to compute the 952 signatures used in the non-"PLAINTEXT" methods, the Service Provider 953 must have access to these secrets in plaintext form. This is in 954 contrast, for example, to modern operating systems, which store only 955 a one-way hash of user credentials. 957 If an attacker were to gain access to these secrets - or worse, to 958 the Service Provider's database of all such secrets - he or she would 959 be able to perform any action on behalf of any User. Accordingly, it 960 is critical that Service Providers protect these secrets from 961 unauthorized access. 963 12.8. Secrecy of the Consumer Secret 965 In many applications, the Consumer application will be under the 966 control of potentially untrusted parties. For example, if the 967 Consumer is a freely available desktop application, an attacker may 968 be able to download a copy for analysis. In such cases, attackers 969 will be able to recover the Consumer Secret used to authenticate the 970 Consumer to the Service Provider. 972 Accordingly, Service Providers should not use the Consumer Secret 973 alone to verify the identity of the Consumer. Where possible, other 974 factors such as IP address should be used as well. 976 12.9. Phishing Attacks 978 Wide deployment of OAuth and similar protocols may cause Users to 979 become inured to the practice of being redirected to websites where 980 they are asked to enter their passwords. If Users are not careful to 981 verify the authenticity of these websites before entering their 982 credentials, it will be possible for attackers to exploit this 983 practice to steal Users' passwords. 985 Service Providers should attempt to educate Users about the risks 986 phishing attacks pose, and should provide mechanisms that make it 987 easy for Users to confirm the authenticity of their sites. 989 12.10. Scoping of Access Requests 991 By itself, OAuth does not provide any method for scoping the access 992 rights granted to a Consumer. A Consumer either has access to 993 Protected Resources or it doesn't. Many applications will, however, 994 require greater granularity of access rights. For example, Service 995 Providers may wish to make it possible to grant access to some 996 Protected Resources but not others, or to grant only limited access 997 (such as read-only access) to those Protected Resources. 999 When implementing OAuth, Service Providers should consider the types 1000 of access Users may wish to grant Consumers, and should provide 1001 mechanisms to do so. Service Providers should also take care to 1002 ensure that Users understand the access they are granting, as well as 1003 any risks that may be involved. 1005 12.11. Entropy of Secrets 1007 Unless a transport-layer security protocol is used, eavesdroppers 1008 will have full access to OAuth requests and signatures, and will thus 1009 be able to mount offline brute-force attacks to recover the 1010 Consumer's credentials used. Service Providers should be careful to 1011 assign Token Secrets and Consumer Secrets which are long enough - and 1012 random enough - to resist such attacks for at least the length of 1013 time that the secrets are valid. 1015 For example, if Token Secrets are valid for two weeks, Service 1016 Providers should ensure that it is not possible to mount a brute 1017 force attack that recovers the Token Secret in less than two weeks. 1018 Of course, Service Providers are urged to err on the side of caution, 1019 and use the longest secrets reasonable. 1021 It is equally important that the pseudo-random number generator 1022 (PRNG) used to generate these secrets be of sufficiently high 1023 quality. Many PRNG implementations generate number sequences that 1024 may appear to be random, but which nevertheless exhibit patterns or 1025 other weaknesses which make cryptanalysis or brute force attacks 1026 easier. Implementors should be careful to use cryptographically 1027 secure PRNGs to avoid these problems. 1029 12.12. Denial of Service / Resource Exhaustion Attacks 1031 The OAuth protocol has a number of features which may make resource 1032 exhaustion attacks against Service Providers possible. For example, 1033 if a Service Provider includes a nontrivial amount of entropy in 1034 Token Secrets as recommended above, then an attacker may be able to 1035 exhaust the Service Provider's entropy pool very quickly by 1036 repeatedly obtaining Request Tokens from the Service Provider. 1038 Similarly, OAuth requires Service Providers to track used nonces. If 1039 an attacker is able to use many nonces quickly, the resources 1040 required to track them may exhaust available capacity. And again, 1041 OAuth can require Service Providers to perform potentially expensive 1042 computations in order to verify the signature on incoming requests. 1043 An attacker may exploit this to perform a denial of service attack by 1044 sending a large number of invalid requests to the Service Provider. 1046 Resource Exhaustion attacks are by no means specific to OAuth. 1047 However, OAuth implementors should be careful to consider the 1048 additional avenues of attack that OAuth exposes, and design their 1049 implementations accordingly. For example, entropy starvation 1050 typically results in either a complete denial of service while the 1051 system waits for new entropy or else in weak (easily guessable) 1052 secrets. When implementing OAuth, Service Providers should consider 1053 which of these presents a more serious risk for their application and 1054 design accordingly. 1056 12.13. Cryptographic Attacks 1058 SHA-1, the hash algorithm used in "HMAC-SHA1" signatures, has been 1059 shown [SHA1-CHARACTERISTICS] to have a number of cryptographic 1060 weaknesses that significantly reduce its resistance to collision 1061 attacks. Practically speaking, these weaknesses are difficult to 1062 exploit, and by themselves do not pose a significant risk to users of 1063 OAuth. They may, however, make more efficient attacks possible, and 1064 NIST has announced [SHA-COMMENTS] that it will phase out use of SHA-1 1065 by 2010. Service Providers should take this into account when 1066 considering whether SHA-1 provides an adequate level of security for 1067 their applications. 1069 12.14. Signature Base String Compatibility 1071 The Signature Base String has been designed to support the signature 1072 methods defined in this specification. When designing additional 1073 signature methods, the Signature Base String should be evaluated to 1074 ensure compatibility with the algorithms used. 1076 The Signature Base String cannot guarantee the order in which 1077 parameters are sent. If parameter ordering is important and affects 1078 the result of a request, the Signature Base String will not protect 1079 against request manipulation. 1081 Appendix A. Appendix A - Protocol Example 1083 In this example, the Service Provider photos.example.net is a photo 1084 sharing website, and the Consumer printer.example.com is a photo 1085 printing website. Jane, the User, would like printer.example.com to 1086 print the private photo " vacation.jpg " stored at 1087 photos.example.net. 1089 When Jane signs-into photos.example.net using her username and 1090 password, she can access the photo by going to the URL 1091 "http://photos.example.net/photo?file=vacation.jpg". Other Users 1092 cannot access that photo, and Jane does not want to share her 1093 username and password with printer.example.com. 1095 The requests in this example use the URL query method when sending 1096 parameters. This is done to simplify the example and should not be 1097 taken as an endorsement of one method over the others. 1099 Appendix A.1. Documentation and Registration 1101 The Service Provider documentation explains how to register for a 1102 Consumer Key and Consumer Secret, and declares the following URLs: 1104 Request Token URL: https://photos.example.net/request_token, using 1105 HTTP POST 1107 User Authorization URL: http://photos.example.net/authorize, using 1108 HTTP GET 1110 Access Token URL: https://photos.example.net/access_token, using 1111 HTTP POST 1113 Photo (Protected Resource) URL: http://photos.example.net/photo with 1114 required parameter "file" and optional parameter "size" 1116 The Service Provider declares support for the " HMAC-SHA1 " signature 1117 method for all requests, and "PLAINTEXT" only for secure (HTTPS) 1118 requests. 1120 The Consumer printer.example.com already established a Consumer Key 1121 and Consumer Secret with photos.example.net and advertizes its 1122 printing services for photos stored on photos.example.net. The 1123 Consumer registration is: 1125 Consumer Key: " dpf43f3p2l4k3l03 " 1127 Consumer Secret: "kd94hf93k423kf44" 1129 Appendix A.2. Obtaining a Request Token 1131 After Jane informs printer.example.com that she would like to print 1132 her vacation photo stored at photos.example.net, the printer website 1133 tries to access the photo and receives HTTP 401 Unauthorized 1134 indicating it is private. The Service Provider includes the 1135 following header with the response: 1137 WWW-Authenticate: OAuth realm="http://photos.example.net/" 1139 The Consumer sends the following HTTP POST request to the Service 1140 Provider: 1142 https://photos.example.net/request_token? 1143 oauth_consumer_key=dpf43f3p2l4k3l03&oauth_signature_method=PLAINTEXT& 1144 oauth_signature=kd94hf93k423kf44%26&oauth_timestamp=1191242090& 1145 oauth_nonce=hsu94j3884jdopsl&oauth_version=1.0 1147 The Service Provider checks the signature and replies with an 1148 unauthorized Request Token in the body of the HTTP response: 1150 oauth_token=hh5s93j4hdidpola&oauth_token_secret=hdhd0244k9j7ao03 1152 Appendix A.3. Requesting User Authorization 1154 The Consumer redirects Jane's browser to the Service Provider User 1155 Authorization URL to obtain Jane's approval for accessing her private 1156 photos. 1158 http://photos.example.net/authorize?oauth_token=hh5s93j4hdidpola& 1159 oauth_callback=http%3A%2F%2Fprinter.example.com%2Frequest_token_ready 1161 The Service Provider asks Jane to sign-in using her username and 1162 password and, if successful, asks her if she approves granting 1163 printer.example.com access to her private photos. If Jane approves 1164 the request, the Service Provider redirects her back to the 1165 Consumer's callback URL: 1167 http://printer.example.com/request_token_ready? 1168 oauth_token=hh5s93j4hdidpola 1170 Appendix A.4. Obtaining an Access Token 1172 Now that the Consumer knows Jane approved the Request Token, it asks 1173 the Service Provider to exchange it for an Access Token: 1175 https://photos.example.net/access_token? 1176 oauth_consumer_key=dpf43f3p2l4k3l03& 1177 oauth_token=hh5s93j4hdidpola&oauth_signature_method=PLAINTEXT& 1178 oauth_signature=kd94hf93k423kf44%26hdhd0244k9j7ao03& 1179 oauth_timestamp=1191242092& 1180 oauth_nonce=dji430splmx33448&oauth_version=1.0 1182 The Service Provider checks the signature and replies with an Access 1183 Token in the body of the HTTP response: 1185 oauth_token=nnch734d00sl2jdk&oauth_token_secret=pfkkdhi9sl3r4s00 1187 Appendix A.5. Accessing Protected Resources 1189 The Consumer is now ready to request the private photo. Since the 1190 photo URL is not secure (HTTP), it must use "HMAC-SHA1". 1192 Appendix A.5.1. Generating Signature Base String 1194 To generate the signature, it first needs to generate the Signature 1195 Base String. The request contains the following parameters 1196 ("oauth_signature" excluded) which are ordered and concatenated into 1197 a normalized string: 1199 oauth_consumer_key: "dpf43f3p2l4k3l03" 1201 oauth_token: "nnch734d00sl2jdk" 1203 oauth_signature_method: "HMAC-SHA1" 1205 oauth_timestamp: "1191242096" 1207 oauth_nonce: "kllo9940pd9333jh" 1209 oauth_version: "1.0" 1211 file: "vacation.jpg" 1213 size: "original" 1215 The following inputs are used to generate the Signature Base String: 1217 1. "GET" 1219 2. "http://photos.example.net/photos" 1221 3. "file=vacation.jpg&oauth_consumer_key=dpf43f3p2l4k3l03&oauth_nonc 1222 e=kllo9940pd9333jh&oauth_signature_method=HMAC-SHA1&oauth_timesta 1223 mp=1191242096&oauth_token=nnch734d00sl2jdk&oauth_version=1.0&size 1224 =original" 1226 The Signature Base String is: 1228 GET&http%3A%2F%2Fphotos.example.net%2Fphotos&file%3Dvacation.jpg%26 1229 oauth_consumer_key%3Ddpf43f3p2l4k3l03%26 1230 oauth_nonce%3Dkllo9940pd9333jh%26 1231 oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1191242096%26 1232 oauth_token%3Dnnch734d00sl2jdk%26oauth_version%3D1.0%26size%3Doriginal 1234 Appendix A.5.2. Calculating Signature Value 1236 HMAC-SHA1 produces the following "digest" value as a base64-encoded 1237 string (using the Signature Base String as "text" and " 1238 kd94hf93k423kf44&pfkkdhi9sl3r4s00 " as "key"): 1240 tR3+Ty81lMeYAr/Fid0kMTYa/WM= 1242 Appendix A.5.3. Requesting Protected Resource 1244 All together, the Consumer request for the photo is: 1246 http://photos.example.net/photos?file=vacation.jpg&size=original 1248 Authorization: OAuth realm="http://photos.example.net/", 1249 oauth_consumer_key="dpf43f3p2l4k3l03", 1250 oauth_token="nnch734d00sl2jdk", 1251 oauth_signature_method="HMAC-SHA1", 1252 oauth_signature="tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D", 1253 oauth_timestamp="1191242096", 1254 oauth_nonce="kllo9940pd9333jh", 1255 oauth_version="1.0" 1257 And if using query parameters: 1259 http://photos.example.net/photos?file=vacation.jpg&size=original& 1260 oauth_consumer_key=dpf43f3p2l4k3l03&oauth_token=nnch734d00sl2jdk& 1261 oauth_signature_method=HMAC-SHA1& 1262 oauth_signature=tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D& 1263 oauth_timestamp=1191242096& 1264 oauth_nonce=kllo9940pd9333jh&oauth_version=1.0 1266 photos.example.net checks the signature and responds with the 1267 requested photo. 1269 Appendix B. Contributors 1271 The content and concepts within are a product of the OAuth community. 1272 It has been originally published as the [OAuth Core 1.0] community 1273 specification and was authored by: 1275 Mark Atwood (me@mark.atwood.name) 1277 Richard M. Conlan (zeveck@google.com) 1279 Blaine Cook (romeda@gmail.com) 1281 Leah Culver (leah@pownce.com) 1283 Kellan Elliott-McCrea (kellan@flickr.com) 1285 Larry Halff (larry@ma.gnolia.com) 1287 Eran Hammer-Lahav (eran@hueniverse.com) 1289 Ben Laurie (benl@google.com) 1291 Chris Messina (chris@citizenagency.com) 1292 John Panzer (jpanzer@acm.org) 1294 Sam Quigley (quigley@emerose.com) 1296 David Recordon (david@sixapart.com) 1298 Eran Sandler (eran@yedda.com) 1300 Jonathan Sergent (sergent@google.com) 1302 Todd Sieling (todd@ma.gnolia.com) 1304 Brian Slesinsky (brian-oauth@slesinsky.org) 1306 Andy Smith (andy@jaiku.com) 1308 13. References 1310 13.1. Normative References 1312 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1313 Extensions (MIME) Part One: Format of Internet Message 1314 Bodies", RFC 2045, November 1996. 1316 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1317 Hashing for Message Authentication", RFC 2104, 1318 February 1997. 1320 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1321 Requirement Levels", BCP 14, RFC 2119, March 1997. 1323 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1324 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1325 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1327 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1328 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1329 Authentication: Basic and Digest Access Authentication", 1330 RFC 2617, June 1999. 1332 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1333 Standards (PKCS) #1: RSA Cryptography Specifications 1334 Version 2.1", RFC 3447, February 2003. 1336 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1337 10646", STD 63, RFC 3629, November 2003. 1339 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1340 Resource Identifier (URI): Generic Syntax", STD 66, 1341 RFC 3986, January 2005. 1343 [W3C.REC-html40-19980424] 1344 Raggett, D., Jacobs, I., and A. Hors, "HTML 4.0 1345 Specification", World Wide Web Consortium 1346 Recommendation REC-html40-19980424, April 1998, 1347 . 1349 13.2. Informative References 1351 [OAuth Core 1.0] 1352 OAuth, OCW., "OAuth Core 1.0". 1354 [SHA-COMMENTS] 1355 National Institute of Standards and Technolog, NIST., 1356 "NIST Brief Comments on Recent Cryptanalytic Attacks on 1357 Secure Hashing Functions and the Continued Security 1358 Provided by SHA-1, August, 2004.". 1360 [SHA1-CHARACTERISTICS] 1361 De Canniere, C. and C. Rechberger, "Finding SHA-1 1362 Characteristics: General Results and Applications". 1364 Authors' Addresses 1366 Eran Hammer-Lahav (editor) 1368 Email: eran@hueniverse.com 1369 URI: http://hueniverse.com 1371 Blaine Cook 1373 Email: romeda@gmail.com 1374 URI: http://romeda.org/ 1376 Full Copyright Statement 1378 Copyright (C) The IETF Trust (2008). 1380 This document is subject to the rights, licenses and restrictions 1381 contained in BCP 78, and except as set forth therein, the authors 1382 retain all their rights. 1384 This document and the information contained herein are provided on an 1385 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1386 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1387 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1388 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1389 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1390 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1392 Intellectual Property 1394 The IETF takes no position regarding the validity or scope of any 1395 Intellectual Property Rights or other rights that might be claimed to 1396 pertain to the implementation or use of the technology described in 1397 this document or the extent to which any license under such rights 1398 might or might not be available; nor does it represent that it has 1399 made any independent effort to identify any such rights. Information 1400 on the procedures with respect to rights in RFC documents can be 1401 found in BCP 78 and BCP 79. 1403 Copies of IPR disclosures made to the IETF Secretariat and any 1404 assurances of licenses to be made available, or the result of an 1405 attempt made to obtain a general license or permission for the use of 1406 such proprietary rights by implementers or users of this 1407 specification can be obtained from the IETF on-line IPR repository at 1408 http://www.ietf.org/ipr. 1410 The IETF invites any interested party to bring to its attention any 1411 copyrights, patents or patent applications, or other proprietary 1412 rights that may cover technology that may be required to implement 1413 this standard. Please address the information to the IETF at 1414 ietf-ipr@ietf.org.