idnits 2.17.1 draft-ietf-oauth-web-delegation-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. 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 date (July 6, 2009) is 5401 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) ** 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) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). 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 Yahoo! 4 Intended status: Standards Track July 6, 2009 5 Expires: January 7, 2010 7 The OAuth Protocol: Web Delegation 8 draft-ietf-oauth-web-delegation-00 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on January 7, 2010. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 This document specifies the OAuth protocol web delegation method. 47 OAuth allows clients to access server resources on behalf of another 48 party (such a different client or an end user). This document 49 defines a redirection-based user-agent process for end users to 50 authorize access to clients by substituting their credentials 51 (typically, a username and password pair) with a different set of 52 delegation-specific credentials. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 4 59 3. Redirection-Based Authorization . . . . . . . . . . . . . . . 4 60 3.1. Temporary Credentials . . . . . . . . . . . . . . . . . . 5 61 3.2. Resource Owner Authorization . . . . . . . . . . . . . . . 6 62 3.3. Token Credentials . . . . . . . . . . . . . . . . . . . . 8 63 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 65 5.1. Credentials Transmission . . . . . . . . . . . . . . . . . 9 66 5.2. Phishing Attacks . . . . . . . . . . . . . . . . . . . . . 9 67 5.3. Scoping of Access Requests . . . . . . . . . . . . . . . . 10 68 5.4. Entropy of Secrets . . . . . . . . . . . . . . . . . . . . 10 69 5.5. Denial of Service / Resource Exhaustion Attacks . . . . . 10 70 5.6. Cross-Site Request Forgery (CSRF) . . . . . . . . . . . . 11 71 5.7. User Interface Redress . . . . . . . . . . . . . . . . . . 11 72 5.8. Automatic Processing of Repeat Authorizations . . . . . . 12 73 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . 12 74 Appendix A.1. Obtaining Temporary Credentials . . . . . . . . . 13 75 Appendix A.2. Requesting Resource Owner Authorization . . . . . 14 76 Appendix A.3. Obtaining Token Credentials . . . . . . . . . . . 14 77 Appendix A.4. Accessing protected resources . . . . . . . . . . 14 78 Appendix A.4.1. Generating Signature Base String . . . . . . . . . 14 79 Appendix A.4.2. Calculating Signature Value . . . . . . . . . . . 16 80 Appendix A.4.3. Requesting protected resource . . . . . . . . . . 16 81 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . 16 82 Appendix C. Document History . . . . . . . . . . . . . . . . . 16 83 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 84 6.1. Normative References . . . . . . . . . . . . . . . . . . . 17 85 6.2. Informative References . . . . . . . . . . . . . . . . . . 17 86 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 18 88 1. Introduction 90 The OAuth protocol provides a method for servers to allow third-party 91 access to protected resources, without forcing their end users to 92 share their credentials. This pattern is common among services that 93 allow third-party developers to extend the service functionality, by 94 building applications using an open API. 96 For example, a web user (resource owner) can grant a printing service 97 (client) access to its private photos stored at a photo sharing 98 service (server), without sharing its credentials with the printing 99 service. Instead, the user authenticates directly with the photo 100 sharing service and issue the printing service delegation-specific 101 credentials. 103 OAuth introduces a third role to the traditional client-server 104 authentication model: the resource owner. In the OAuth model, the 105 client requests access to resources hosted by the server but not 106 controlled by the client, but by the resource owner. In addition, 107 OAuth allows the server to verify not only the resource owner's 108 credentials, but also those of the client making the request. 110 In order for the client to access resources, it first has to obtain 111 permission from the resource owner. This permission is expressed in 112 the form of a token and matching shared-secret. The purpose of the 113 token is to substitute the need for the resource owner to share its 114 server credentials (usually a username and password pair) with the 115 client. Unlike server credentials, tokens can be issued with a 116 restricted scope and limited lifetime. 118 This specification consists of two parts. 119 [draft-ietf-oauth-authentication] defines a method for making 120 authenticated HTTP requests using two sets of credentials, one 121 identifying the client making the request, and a second identifying 122 the resource owner on whose behalf the request is being made. 124 This document defines a redirection-based user agent process for end 125 users to authorize client access to their resources, by 126 authenticating directly with the server and provisioning tokens to 127 the client for use with the authentication method. 129 1.1. Terminology 131 client 132 An HTTP client (per [RFC2616]) capable of making OAuth- 133 authenticated requests per [draft-ietf-oauth-authentication]. 135 server 136 An HTTP server (per [RFC2616]) capable of accepting OAuth- 137 authenticated requests per [draft-ietf-oauth-authentication]. 139 protected resource 140 An access-restricted resource (per [RFC2616]) which can be 141 obtained from the server using an OAuth-authenticated request 142 per [draft-ietf-oauth-authentication]. 144 resource owner 145 An entity capable of accessing and controlling protected 146 resources by using credentials to authenticate with the server. 148 token 149 An unique identifier issued by the server and used by the 150 client to associate authenticated requests with the resource 151 owner whose authorization is requested or has been obtained by 152 the client. Tokens have a matching shared-secret that is used 153 by the client to establish its ownership of the token, and its 154 authority to represent the resource owner. 156 2. Notational Conventions 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 160 document are to be interpreted as described in [RFC2119]. 162 3. Redirection-Based Authorization 164 OAuth uses a set of token credentials to represent the authorization 165 granted to the client by the resource owner. Typically, token 166 credentials are issued by the server at the resource owner's request, 167 after authenticating the resource owner's identity using its server 168 credentials (usually a username and password pair). 170 There are many ways in which a resource owner can facilitate the 171 provisioning of token credentials. This section defines one such 172 way, using HTTP redirections and the resource owner's user agent. 173 This redirection-based authorization method includes three steps: 175 1. The client obtains a set of temporary credentials from the 176 server. 178 2. The resource owner authorizes the server to issue token 179 credentials to the client using the temporary credentials. 181 3. The client uses the temporary credentials to request a set of 182 token credentials from the server, which will enable it to access 183 the resource owner's protected resources. The temporary 184 credentials discarded. 186 The temporary credentials MUST be revoked after being used once to 187 obtain the token credentials. It is RECOMMENDED that the temporary 188 credentials have a limited lifetime. Servers SHOULD enable resource 189 owners to revoke token credentials after they have been issued to 190 clients. 192 In order for the client to perform these steps, the server needs to 193 advertise the URIs of these three endpoints, as well as the HTTP 194 method (GET, POST, etc.) used to make each requests. To assist in 195 communicating these endpoint, each is given a name: 197 Temporary Credential Request 198 The endpoint used by the client to obtain temporary credentials 199 as described in Section 3.1. 201 Resource Owner Authorization 202 The endpoint to which the resource owner is redirected to grant 203 authorization as described in Section 3.2. 205 Token Request 206 The endpoint used by the client to request a set of token 207 credentials using the temporary credentials as described in 208 Section 3.3. 210 The three URIs MAY include a query component as defined by [RFC3986] 211 section 3, but if present, the query MUST NOT contain any parameters 212 beginning with the "oauth_" prefix. 214 The method in which the server advertises its three endpoint is 215 beyond the scope of this specification. 217 3.1. Temporary Credentials 219 The client obtains a set of temporary credentials from the server by 220 making an authenticated request per 221 [draft-ietf-oauth-authentication]. The client MUST use the HTTP 222 method advertised by the server. The HTTP POST method is 223 RECOMMENDED. The client constructs a request URI by adding the 224 following parameter to the Temporary Credential Request endpoint URI: 226 oauth_callback: An absolute URL to which the server will redirect 227 the resource owner back when the Resource Owner Authorization 228 step (Section 3.2) is completed. If the client is unable to 229 receive callbacks or a callback URI has been established via 230 other means, the parameter value MUST be set to "oob" (case 231 sensitive), to indicate an out-of-band configuration. 233 Servers MAY specify additional parameters. 235 When making the request, the client authenticates using only the 236 client credentials. The client MUST omit the "oauth_token" protocol 237 parameter from the request and use an empty string as the token 238 secret value. 240 The server MUST verify that the request is valid per 241 [draft-ietf-oauth-authentication] and respond back to the client with 242 a set of temporary credentials. The temporary credentials are 243 included in the HTTP response body using the 244 "application/x-www-form-urlencoded" content type as defined by 245 [W3C.REC-html40-19980424]. 247 The response contains the following parameters: 249 oauth_token 250 The temporary credentials identifier. 252 oauth_token_secret 253 The temporary credentials shared-secret. 255 oauth_callback_confirmed: MUST be present and set to "true". The 256 client MAY use this to confirm that the server received the 257 callback value. 259 Note that even though the parameter names include the term 'token', 260 these credentials are not token credentials, but are used in the next 261 two steps in a similar manner to token credentials. 263 For example (line breaks are for display purposes only): 265 oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=xyz4992k83j47x0b& 266 oauth_callback_confirmed=true 268 3.2. Resource Owner Authorization 270 Before the client requests a set of token credentials from the 271 server, it MUST send the user to the server to authorize the request. 272 The client constructs a request URI by adding the following 273 parameters to the Resource Owner Authorization endpoint URI: 275 oauth_token 276 REQUIRED. The temporary credentials identifier obtained in 277 Section 3.1 in the "oauth_token" parameter. Servers MAY 278 declare this parameter as OPTIONAL, in which case they MUST 279 provide a way for the resource owner to indicate the identifier 280 through other means. 282 Servers MAY specify additional parameters. 284 The client redirects the resource owner to the constructed URI using 285 an HTTP redirection response, or by other means available to it via 286 the resource owner's user agent. The request MUST use the HTTP GET 287 method. 289 The way in which the server handles the authorization request is 290 beyond the scope of this specification. However, the server MUST 291 first verify the identity of the resource owner. 293 When asking the resource owner to authorize the requested access, the 294 server SHOULD present to the resource owner information about the 295 client requesting access based on the association of the temporary 296 credentials with the client identity. When displaying any such 297 information, the server SHOULD indicate if the information has been 298 verified. 300 After receiving an authorization decision from the resource owner, 301 the server redirects the resource owner to the callback URI if one 302 was provided in the "oauth_callback" parameter or by other means. 304 To make sure that the resource owner granting access is the same 305 resource owner returning back to the client to complete the process, 306 the server MUST generate a verification code: an unguessable value 307 passed to the client via the resource owner and REQUIRED to complete 308 the process. The server constructs the request URI by adding the 309 following parameter to the callback URI query component: 311 oauth_token 312 The temporary credentials identifier the resource owner 313 authorized or denied access to. 315 oauth_verifier: The verification code. 317 If the callback URI already includes a query component, the server 318 MUST append the OAuth parameters to the end of the existing query. 320 For example (line breaks are for display purposes only): 322 http://client.example.net/cb?state=1&oauth_token=ab3cd9j4ks73hf7g& 323 oauth_verifier=473829k9302sa 325 If the client did not provide a callback URI, the server SHOULD 326 display the value of the verification code, and instruct the resource 327 owner to manually inform the client that authorization is completed. 328 If the server knows a client to be running on a limited device it 329 SHOULD ensure that the verifier value is suitable for manual entry. 331 3.3. Token Credentials 333 The client obtains a set of token credentials from the server by 334 making an authenticated request per 335 [draft-ietf-oauth-authentication]. The client MUST use the HTTP 336 method advertised by the server. The HTTP POST method is 337 RECOMMENDED. The client constructs a request URI by adding the 338 following parameter to the Token Request endpoint URI: 340 oauth_verifier: The verification code received from the server in 341 the previous step. 343 When making the request, the client authenticates using the client 344 credentials as well as the temporary credentials. The temporary 345 credentials are used as a substitution for token credentials in the 346 authenticated request. 348 The server MUST verify the validity of the request per 349 [draft-ietf-oauth-authentication], ensure that the resource owner has 350 authorized the provisioning of token credentials to the client, and 351 that the temporary credentials have not expired or used before. The 352 server MUST also verify the verification code received from the 353 client. If the request is valid and authorized, the token 354 credentials are included in the HTTP response body using the 355 "application/x-www-form-urlencoded" content type as defined by 356 [W3C.REC-html40-19980424]. 358 The response contains the following parameters: 360 oauth_token 361 The token identifier. 363 oauth_token_secret 364 The token shared-secret. 366 For example: 368 oauth_token=j49ddk933skd9dks&oauth_token_secret=ll399dj47dskfjdk 370 The token credentials issued by the server MUST reflect the exact 371 scope, duration, and other attributes approved by the resource owner. 373 Once the client receives the token credentials, it can proceed to 374 access protected resources on behalf of the resource owner by making 375 an authenticated request per [draft-ietf-oauth-authentication] using 376 the client credentials and the token credentials received. 378 4. IANA Considerations 380 This memo includes no request to IANA. 382 5. Security Considerations 384 As stated in [RFC2617], the greatest sources of risks are usually 385 found not in the core protocol itself but in policies and procedures 386 surrounding its use. Implementers are strongly encouraged to assess 387 how this protocol addresses their security requirements. 389 5.1. Credentials Transmission 391 The OAuth specification does not describe any mechanism for 392 protecting tokens and shared-secrets from eavesdroppers when they are 393 transmitted from the server to the client during the authorization 394 phase. Servers should ensure that these transmissions are protected 395 using transport-layer mechanisms such as TLS or SSL. 397 5.2. Phishing Attacks 399 Wide deployment of OAuth and similar protocols may cause resource 400 owners to become inured to the practice of being redirected to 401 websites where they are asked to enter their passwords. If resource 402 owners are not careful to verify the authenticity of these websites 403 before entering their credentials, it will be possible for attackers 404 to exploit this practice to steal resource owners' passwords. 406 Servers should attempt to educate resource owners about the risks 407 phishing attacks pose, and should provide mechanisms that make it 408 easy for resource owners to confirm the authenticity of their sites. 410 5.3. Scoping of Access Requests 412 By itself, OAuth does not provide any method for scoping the access 413 rights granted to a client. However, most applications do require 414 greater granularity of access rights. For example, servers may wish 415 to make it possible to grant access to some protected resources but 416 not others, or to grant only limited access (such as read-only 417 access) to those protected resources. 419 When implementing OAuth, servers should consider the types of access 420 resource owners may wish to grant clients, and should provide 421 mechanisms to do so. Servers should also take care to ensure that 422 resource owners understand the access they are granting, as well as 423 any risks that may be involved. 425 5.4. Entropy of Secrets 427 Unless a transport-layer security protocol is used, eavesdroppers 428 will have full access to OAuth requests and signatures, and will thus 429 be able to mount offline brute-force attacks to recover the 430 credentials used. Servers should be careful to assign shared-secrets 431 which are long enough, and random enough, to resist such attacks for 432 at least the length of time that the shared-secrets are valid. 434 For example, if shared-secrets are valid for two weeks, servers 435 should ensure that it is not possible to mount a brute force attack 436 that recovers the shared-secret in less than two weeks. Of course, 437 servers are urged to err on the side of caution, and use the longest 438 secrets reasonable. 440 It is equally important that the pseudo-random number generator 441 (PRNG) used to generate these secrets be of sufficiently high 442 quality. Many PRNG implementations generate number sequences that 443 may appear to be random, but which nevertheless exhibit patterns or 444 other weaknesses which make cryptanalysis or brute force attacks 445 easier. Implementers should be careful to use cryptographically 446 secure PRNGs to avoid these problems. 448 5.5. Denial of Service / Resource Exhaustion Attacks 450 The OAuth protocol has a number of features which may make resource 451 exhaustion attacks against servers possible. For example, if a 452 server includes a nontrivial amount of entropy in token shared- 453 secrets as recommended above, then an attacker may be able to exhaust 454 the server's entropy pool very quickly by repeatedly obtaining 455 temporary credentials from the server. 457 Similarly, OAuth requires servers to track used nonces. If an 458 attacker is able to use many nonces quickly, the resources required 459 to track them may exhaust available capacity. And again, OAuth can 460 require servers to perform potentially expensive computations in 461 order to verify the signature on incoming requests. An attacker may 462 exploit this to perform a denial of service attack by sending a large 463 number of invalid requests to the server. 465 Resource Exhaustion attacks are by no means specific to OAuth. 466 However, OAuth implementers should be careful to consider the 467 additional avenues of attack that OAuth exposes, and design their 468 implementations accordingly. For example, entropy starvation 469 typically results in either a complete denial of service while the 470 system waits for new entropy or else in weak (easily guessable) 471 secrets. When implementing OAuth, servers should consider which of 472 these presents a more serious risk for their application and design 473 accordingly. 475 5.6. Cross-Site Request Forgery (CSRF) 477 Cross-Site Request Forgery (CSRF) is a web-based attack whereby HTTP 478 requests are transmitted from a user that the website trusts or has 479 authenticated. CSRF attacks on OAuth approvals can allow an attacker 480 to obtain authorization to protected resources without the consent of 481 the User. Servers SHOULD strongly consider best practices in CSRF 482 prevention at all OAuth endpoints. 484 CSRF attacks on OAuth callback URIs hosted by client are also 485 possible. Clients should prevent CSRF attacks on OAuth callback URIs 486 by verifying that the resource owner at the client site intended to 487 complete the OAuth negotiation with the server. 489 5.7. User Interface Redress 491 Servers should protect the authorization process against UI Redress 492 attacks (also known as "clickjacking"). As of the time of this 493 writing, no complete defenses against UI redress are available. 494 Servers can mitigate the risk of UI redress attacks through the 495 following techniques: 497 o Javascript frame busting. 499 o Javascript frame busting, and requiring that browsers have 500 javascript enabled on the authorization page. 502 o Browser-specific anti-framing techniques. 504 o Requiring password reentry before issuing OAuth tokens. 506 5.8. Automatic Processing of Repeat Authorizations 508 Servers may wish to automatically process authorization requests 509 (Section 3.2) from clients which have been previously authorized by 510 the resource owner. When the resource owner is redirected to the 511 server to grant access, the server detects that the resource owner 512 has already granted access to that particular client. Instead of 513 prompting the resource owner for approval, the server automatically 514 redirects the resource owner back to the client. 516 If the client credentials are compromised, automatic processing 517 creates additional security risks. An attacker can use the stolen 518 client credentials to redirect the resource owner to the server with 519 an authorization request. The server will then grant access to the 520 resource owner's data without the resource owner's explicit approval, 521 or even awareness of an attack. If no automatic approval is 522 implemented, an attacker must use social engineering to convince the 523 resource owner to approve access. 525 Servers can mitigate the risks associated with automatic processing 526 by limiting the scope of token credentials obtained through automated 527 approvals. Tokens credentials obtained through explicit resource 528 owner consent can remain unaffected. clients can mitigate the risks 529 associated with automatic processing by protecting their client 530 credentials. 532 Appendix A. Examples 534 In this example, photos.example.net is a photo sharing website 535 (server), and printer.example.com is a photo printing service 536 (client). Jane (resource owner) would like printer.example.com to 537 print a private photo stored at photos.example.net. 539 When Jane signs-into photos.example.net using her username and 540 password, she can access the photo by requesting the URI 541 "http://photos.example.net/photo?file=vacation.jpg" (which also 542 supports the optional "size" parameter). Jane does not want to share 543 her username and password with printer.example.com, but would like it 544 to access the photo and print it. 546 The server documentation advertises support for the "HMAC-SHA1" and 547 "PLAINTEXT" methods, with "PLAINTEXT" restricted to secure (HTTPS) 548 requests. It also advertises the following endpoint URIs: 550 Temporary Credential Request 551 https://photos.example.net/initiate, using HTTP POST 553 Resource Owner Authorization URI: 554 http://photos.example.net/authorize, using HTTP GET 556 Token Request URI: 557 https://photos.example.net/token, using HTTP POST 559 The printer.example.com has already established client credentials 560 with photos.example.net: 562 Client Identifier 563 "dpf43f3p2l4k3l03" 565 Client Shared-Secret: 566 "kd94hf93k423kf44" 568 When printer.example.com attempts to print the request photo, it 569 receives an HTTP response with a 401 (Unauthorized) status code, and 570 a challenge to use OAuth: 572 WWW-Authenticate: OAuth realm="http://photos.example.net/" 574 Appendix A.1. Obtaining Temporary Credentials 576 The client sends the following HTTPS POST request to the server: 578 POST /initiate HTTP/1.1 579 Host: photos.example.net 580 Authorization: OAuth realm="http://photos.example.com/", 581 oauth_consumer_key="dpf43f3p2l4k3l03", 582 oauth_signature_method="PLAINTEXT", 583 oauth_signature="kd94hf93k423kf44%26", 584 oauth_timestamp="1191242090", 585 oauth_nonce="hsu94j3884jdopsl", 586 oauth_version="1.0", 587 oauth_callback="http%3A%2F%2Fprinter.example.com%2Fready" 589 The server validates the request and replies with a set of temporary 590 credentials in the body of the HTTP response: 592 oauth_token=hh5s93j4hdidpola&oauth_token_secret=hdhd0244k9j7ao03& 593 oauth_callback_confirmed=true 595 Appendix A.2. Requesting Resource Owner Authorization 597 The client redirects Jane's browser to the server's Resource Owner 598 Authorization endpoint URI to obtain Jane's approval for accessing 599 her private photos. 601 http://photos.example.net/authorize?oauth_token=hh5s93j4hdidpola 603 The server asks Jane to sign-in using her username and password and 604 if successful, asks her if she approves granting printer.example.com 605 access to her private photos. Jane approves the request and is 606 redirects her back to the client's callback URI: 608 http://printer.example.com/ready? 609 oauth_token=hh5s93j4hdidpola&oauth_verifier=hfdp7dh39dks9884 611 Appendix A.3. Obtaining Token Credentials 613 After being informed by the callback request that Jane approved 614 authorized access, printer.example.com requests a set of token 615 credentials using its temporary credentials: 617 POST /token HTTP/1.1 618 Host: photos.example.net 619 Authorization: OAuth realm="http://photos.example.com/", 620 oauth_consumer_key="dpf43f3p2l4k3l03", 621 oauth_token="hh5s93j4hdidpola", 622 oauth_signature_method="PLAINTEXT", 623 oauth_signature="kd94hf93k423kf44%26hdhd0244k9j7ao03", 624 oauth_timestamp="1191242092", 625 oauth_nonce="dji430splmx33448", 626 oauth_version="1.0" 627 oauth_verifier="hfdp7dh39dks9884" 629 The server validates the request and replies with a set of token 630 credentials in the body of the HTTP response: 632 oauth_token=nnch734d00sl2jdk&oauth_token_secret=pfkkdhi9sl3r4s00 634 Appendix A.4. Accessing protected resources 636 The printer is now ready to request the private photo. Since the 637 photo URI does not use HTTPS, the "HMAC-SHA1" method is required. 639 Appendix A.4.1. Generating Signature Base String 641 To generate the signature, it first needs to generate the signature 642 base string. The request contains the following parameters 643 ("oauth_signature" excluded) which need to be ordered and 644 concatenated into a normalized string: 646 oauth_consumer_key 647 "dpf43f3p2l4k3l03" 649 oauth_token 650 "nnch734d00sl2jdk" 652 oauth_signature_method 653 "HMAC-SHA1" 655 oauth_timestamp 656 "1191242096" 658 oauth_nonce 659 "kllo9940pd9333jh" 661 oauth_version 662 "1.0" 664 file 665 "vacation.jpg" 667 size 668 "original" 670 The following inputs are used to generate the signature base string: 672 1. The HTTP request method: "GET" 674 2. The request URI: "http://photos.example.net/photos" 676 3. The encoded normalized request parameters string: "file=vacation. 677 jpg&oauth_consumer_key=dpf43f3p2l4k3l03&oauth_nonce=kllo9940pd933 678 3jh&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1191242096&o 679 auth_token=nnch734d00sl2jdk&oauth_version=1.0&size=original" 681 The signature base string is (line breaks are for display purposes 682 only): 684 GET&http%3A%2F%2Fphotos.example.net%2Fphotos&file%3Dvacation.jpg%26 685 oauth_consumer_key%3Ddpf43f3p2l4k3l03%26oauth_nonce%3Dkllo9940pd933 686 3jh%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D119124 687 2096%26oauth_token%3Dnnch734d00sl2jdk%26oauth_version%3D1.0%26size% 688 3Doriginal 690 Appendix A.4.2. Calculating Signature Value 692 HMAC-SHA1 produces the following "digest" value as a base64-encoded 693 string (using the signature base string as "text" and 694 "kd94hf93k423kf44&pfkkdhi9sl3r4s00" as "key"): 696 tR3+Ty81lMeYAr/Fid0kMTYa/WM= 698 Appendix A.4.3. Requesting protected resource 700 All together, the client request for the photo is: 702 GET /photos?file=vacation.jpg&size=original HTTP/1.1 703 Host: photos.example.com 704 Authorization: OAuth realm="http://photos.example.net/", 705 oauth_consumer_key="dpf43f3p2l4k3l03", 706 oauth_token="nnch734d00sl2jdk", 707 oauth_signature_method="HMAC-SHA1", 708 oauth_signature="tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D", 709 oauth_timestamp="1191242096", 710 oauth_nonce="kllo9940pd9333jh", 711 oauth_version="1.0" 713 The photos.example.net sever validates the request and responds with 714 the requested photo. 716 Appendix B. Acknowledgments 718 This specification is directly based on the [OAuth Core 1.0 Revision 719 A] community specification which was the product of the OAuth 720 community. OAuth was modeled after existing proprietary protocols 721 and best practices that have been independently implemented by 722 various web sites. This specification was orignially authored by: 723 Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. Conlan, Blaine 724 Cook, Leah Culver, Breno de Medeiros, Brian Eaton, Kellan Elliott- 725 McCrea, Larry Halff, Eran Hammer-Lahav, Ben Laurie, Chris Messina, 726 John Panzer, Sam Quigley, David Recordon, Eran Sandler, Jonathan 727 Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. 729 Appendix C. Document History 731 [[ To be removed by the RFC editor before publication as an RFC. ]] 733 -00 734 o Transitioned from the individual submission draft-hammer-oauth-02 735 to working group draft. 737 o Split draft-hammer-oauth-02 into two drafts, one dealing with web 738 delegation (this draft) and another dealing with authentication 739 draft-ietf-oauth-web-authentication. 741 o Updated draft with changes from OAuth Core 1.0 Revision A to fix a 742 session fixation exploit. 744 6. References 746 6.1. Normative References 748 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 749 Requirement Levels", BCP 14, RFC 2119, March 1997. 751 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 752 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 753 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 755 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 756 Leach, P., Luotonen, A., and L. Stewart, "HTTP 757 Authentication: Basic and Digest Access Authentication", 758 RFC 2617, June 1999. 760 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 761 Resource Identifier (URI): Generic Syntax", STD 66, 762 RFC 3986, January 2005. 764 [W3C.REC-html40-19980424] 765 Hors, A., Jacobs, I., and D. Raggett, "HTML 4.0 766 Specification", World Wide Web Consortium 767 Recommendation REC-html40-19980424, April 1998, 768 . 770 [draft-ietf-oauth-authentication] 771 Hammer-Lahav, E., Ed., "The OAuth Protocol: 772 Authentication". 774 6.2. Informative References 776 [OAuth Core 1.0 Revision A] 777 OAuth, OCW., "OAuth Core 1.0". 779 Author's Address 781 Eran Hammer-Lahav (editor) 782 Yahoo! 784 Email: eran@hueniverse.com 785 URI: http://hueniverse.com