-
Notifications
You must be signed in to change notification settings - Fork 73
/
rfc5849.txt
2131 lines (1378 loc) · 78.9 KB
/
rfc5849.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Internet Engineering Task Force (IETF) E. Hammer-Lahav, Ed.
Request for Comments: 5849 April 2010
Category: Informational
ISSN: 2070-1721
The OAuth 1.0 Protocol
Abstract
OAuth provides a method for clients to access server resources on
behalf of a resource owner (such as a different client or an end-
user). It also provides a process for end-users to authorize third-
party access to their server resources without sharing their
credentials (typically, a username and password pair), using user-
agent redirections.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Not all documents
approved by the IESG are a candidate for any level of Internet
Standard; see Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc5849.
Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Hammer-Lahav Informational [Page 1]
RFC 5849 OAuth 1.0 April 2010
Table of Contents
1. Introduction ....................................................3
1.1. Terminology ................................................4
1.2. Example ....................................................5
1.3. Notational Conventions .....................................7
2. Redirection-Based Authorization .................................8
2.1. Temporary Credentials ......................................9
2.2. Resource Owner Authorization ..............................10
2.3. Token Credentials .........................................12
3. Authenticated Requests .........................................14
3.1. Making Requests ...........................................14
3.2. Verifying Requests ........................................16
3.3. Nonce and Timestamp .......................................17
3.4. Signature .................................................18
3.4.1. Signature Base String ..............................18
3.4.2. HMAC-SHA1 ..........................................25
3.4.3. RSA-SHA1 ...........................................25
3.4.4. PLAINTEXT ..........................................26
3.5. Parameter Transmission ....................................26
3.5.1. Authorization Header ...............................27
3.5.2. Form-Encoded Body ..................................28
3.5.3. Request URI Query ..................................28
3.6. Percent Encoding ..........................................29
4. Security Considerations ........................................29
4.1. RSA-SHA1 Signature Method .................................29
4.2. Confidentiality of Requests ...............................30
4.3. Spoofing by Counterfeit Servers ...........................30
4.4. Proxying and Caching of Authenticated Content .............30
4.5. Plaintext Storage of Credentials ..........................30
4.6. Secrecy of the Client Credentials .........................31
4.7. Phishing Attacks ..........................................31
4.8. Scoping of Access Requests ................................31
4.9. Entropy of Secrets ........................................32
4.10. Denial-of-Service / Resource-Exhaustion Attacks ..........32
4.11. SHA-1 Cryptographic Attacks ..............................33
4.12. Signature Base String Limitations ........................33
4.13. Cross-Site Request Forgery (CSRF) ........................33
4.14. User Interface Redress ...................................34
4.15. Automatic Processing of Repeat Authorizations ............34
5. Acknowledgments ................................................35
Appendix A. Differences from the Community Edition ...............36
6. References .....................................................37
6.1. Normative References ......................................37
6.2. Informative References ....................................38
Hammer-Lahav Informational [Page 2]
RFC 5849 OAuth 1.0 April 2010
1. Introduction
The OAuth protocol was originally created by a small community of web
developers from a variety of websites and other Internet services who
wanted to solve the common problem of enabling delegated access to
protected resources. The resulting OAuth protocol was stabilized at
version 1.0 in October 2007, and revised in June 2009 (Revision A) as
published at <http://oauth.net/core/1.0a>.
This specification provides an informational documentation of OAuth
Core 1.0 Revision A, addresses several errata reported since that
time, and makes numerous editorial clarifications. While this
specification is not an item of the IETF's OAuth Working Group, which
at the time of writing is working on an OAuth version that can be
appropriate for publication on the standards track, it has been
transferred to the IETF for change control by authors of the original
work.
In the traditional client-server authentication model, the client
uses its credentials to access its resources hosted by the server.
With the increasing use of distributed web services and cloud
computing, third-party applications require access to these server-
hosted resources.
OAuth introduces a third role to the traditional client-server
authentication model: the resource owner. In the OAuth model, the
client (which is not the resource owner, but is acting on its behalf)
requests access to resources controlled by the resource owner, but
hosted by the server. In addition, OAuth allows the server to verify
not only the resource owner authorization, but also the identity of
the client making the request.
OAuth provides a method for clients to access server resources on
behalf of a resource owner (such as a different client or an end-
user). It also provides a process for end-users to authorize third-
party access to their server resources without sharing their
credentials (typically, a username and password pair), using user-
agent redirections.
For example, a web user (resource owner) can grant a printing service
(client) access to her private photos stored at a photo sharing
service (server), without sharing her username and password with the
printing service. Instead, she authenticates directly with the photo
sharing service which issues the printing service delegation-specific
credentials.
Hammer-Lahav Informational [Page 3]
RFC 5849 OAuth 1.0 April 2010
In order for the client to access resources, it first has to obtain
permission from the resource owner. This permission is expressed in
the form of a token and matching shared-secret. The purpose of the
token is to make it unnecessary for the resource owner to share its
credentials with the client. Unlike the resource owner credentials,
tokens can be issued with a restricted scope and limited lifetime,
and revoked independently.
This specification consists of two parts. The first part defines a
redirection-based user-agent process for end-users to authorize
client access to their resources, by authenticating directly with the
server and provisioning tokens to the client for use with the
authentication method. The second part defines a method for making
authenticated HTTP [RFC2616] requests using two sets of credentials,
one identifying the client making the request, and a second
identifying the resource owner on whose behalf the request is being
made.
The use of OAuth with any transport protocol other than [RFC2616] is
undefined.
1.1. Terminology
client
An HTTP client (per [RFC2616]) capable of making OAuth-
authenticated requests (Section 3).
server
An HTTP server (per [RFC2616]) capable of accepting OAuth-
authenticated requests (Section 3).
protected resource
An access-restricted resource that can be obtained from the
server using an OAuth-authenticated request (Section 3).
resource owner
An entity capable of accessing and controlling protected
resources by using credentials to authenticate with the server.
credentials
Credentials are a pair of a unique identifier and a matching
shared secret. OAuth defines three classes of credentials:
client, temporary, and token, used to identify and authenticate
the client making the request, the authorization request, and
the access grant, respectively.
Hammer-Lahav Informational [Page 4]
RFC 5849 OAuth 1.0 April 2010
token
A unique identifier issued by the server and used by the client
to associate authenticated requests with the resource owner
whose authorization is requested or has been obtained by the
client. Tokens have a matching shared-secret that is used by
the client to establish its ownership of the token, and its
authority to represent the resource owner.
The original community specification used a somewhat different
terminology that maps to this specifications as follows (original
community terms provided on left):
Consumer: client
Service Provider: server
User: resource owner
Consumer Key and Secret: client credentials
Request Token and Secret: temporary credentials
Access Token and Secret: token credentials
1.2. Example
Jane (resource owner) has recently uploaded some private vacation
photos (protected resources) to her photo sharing site
'photos.example.net' (server). She would like to use the
'printer.example.com' website (client) to print one of these photos.
Typically, Jane signs into 'photos.example.net' using her username
and password.
However, Jane does not wish to share her username and password with
the 'printer.example.com' website, which needs to access the photo in
order to print it. In order to provide its users with better
service, 'printer.example.com' has signed up for a set of
'photos.example.net' client credentials ahead of time:
Client Identifier
dpf43f3p2l4k3l03
Client Shared-Secret:
kd94hf93k423kf44
The 'printer.example.com' website has also configured its application
to use the protocol endpoints listed in the 'photos.example.net' API
documentation, which use the "HMAC-SHA1" signature method:
Hammer-Lahav Informational [Page 5]
RFC 5849 OAuth 1.0 April 2010
Temporary Credential Request
https://photos.example.net/initiate
Resource Owner Authorization URI:
https://photos.example.net/authorize
Token Request URI:
https://photos.example.net/token
Before 'printer.example.com' can ask Jane to grant it access to the
photos, it must first establish a set of temporary credentials with
'photos.example.net' to identify the delegation request. To do so,
the client sends the following HTTPS [RFC2818] request to the server:
POST /initiate HTTP/1.1
Host: photos.example.net
Authorization: OAuth realm="Photos",
oauth_consumer_key="dpf43f3p2l4k3l03",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131200",
oauth_nonce="wIjqoS",
oauth_callback="http%3A%2F%2Fprinter.example.com%2Fready",
oauth_signature="74KNZJeDHnMBp0EMJ9ZHt%2FXKycU%3D"
The server validates the request and replies with a set of temporary
credentials in the body of the HTTP response (line breaks are for
display purposes only):
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
oauth_token=hh5s93j4hdidpola&oauth_token_secret=hdhd0244k9j7ao03&
oauth_callback_confirmed=true
The client redirects Jane's user-agent to the server's Resource Owner
Authorization endpoint to obtain Jane's approval for accessing her
private photos:
https://photos.example.net/authorize?oauth_token=hh5s93j4hdidpola
The server requests Jane to sign in using her username and password
and if successful, asks her to approve granting 'printer.example.com'
access to her private photos. Jane approves the request and her
user-agent is redirected to the callback URI provided by the client
in the previous request (line breaks are for display purposes only):
http://printer.example.com/ready?
oauth_token=hh5s93j4hdidpola&oauth_verifier=hfdp7dh39dks9884
Hammer-Lahav Informational [Page 6]
RFC 5849 OAuth 1.0 April 2010
The callback request informs the client that Jane completed the
authorization process. The client then requests a set of token
credentials using its temporary credentials (over a secure Transport
Layer Security (TLS) channel):
POST /token HTTP/1.1
Host: photos.example.net
Authorization: OAuth realm="Photos",
oauth_consumer_key="dpf43f3p2l4k3l03",
oauth_token="hh5s93j4hdidpola",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131201",
oauth_nonce="walatlh",
oauth_verifier="hfdp7dh39dks9884",
oauth_signature="gKgrFCywp7rO0OXSjdot%2FIHF7IU%3D"
The server validates the request and replies with a set of token
credentials in the body of the HTTP response:
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
oauth_token=nnch734d00sl2jdk&oauth_token_secret=pfkkdhi9sl3r4s00
With a set of token credentials, the client is now ready to request
the private photo:
GET /photos?file=vacation.jpg&size=original HTTP/1.1
Host: photos.example.net
Authorization: OAuth realm="Photos",
oauth_consumer_key="dpf43f3p2l4k3l03",
oauth_token="nnch734d00sl2jdk",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131202",
oauth_nonce="chapoH",
oauth_signature="MdpQcU8iPSUjWoN%2FUDMsK2sui9I%3D"
The 'photos.example.net' server validates the request and responds
with the requested photo. 'printer.example.com' is able to continue
accessing Jane's private photos using the same set of token
credentials for the duration of Jane's authorization, or until Jane
revokes access.
1.3. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
Hammer-Lahav Informational [Page 7]
RFC 5849 OAuth 1.0 April 2010
2. Redirection-Based Authorization
OAuth uses tokens to represent the authorization granted to the
client by the resource owner. Typically, token credentials are
issued by the server at the resource owner's request, after
authenticating the resource owner's identity (usually using a
username and password).
There are many ways in which a server can facilitate the provisioning
of token credentials. This section defines one such way, using HTTP
redirections and the resource owner's user-agent. This redirection-
based authorization method includes three steps:
1. The client obtains a set of temporary credentials from the server
(in the form of an identifier and shared-secret). The temporary
credentials are used to identify the access request throughout
the authorization process.
2. The resource owner authorizes the server to grant the client's
access request (identified by the temporary credentials).
3. The client uses the temporary credentials to request a set of
token credentials from the server, which will enable it to access
the resource owner's protected resources.
The server MUST revoke the temporary credentials after being used
once to obtain the token credentials. It is RECOMMENDED that the
temporary credentials have a limited lifetime. Servers SHOULD enable
resource owners to revoke token credentials after they have been
issued to clients.
In order for the client to perform these steps, the server needs to
advertise the URIs of the following three endpoints:
Temporary Credential Request
The endpoint used by the client to obtain a set of temporary
credentials as described in Section 2.1.
Resource Owner Authorization
The endpoint to which the resource owner is redirected to grant
authorization as described in Section 2.2.
Token Request
The endpoint used by the client to request a set of token
credentials using the set of temporary credentials as described
in Section 2.3.
Hammer-Lahav Informational [Page 8]
RFC 5849 OAuth 1.0 April 2010
The three URIs advertised by the server MAY include a query component
as defined by [RFC3986], Section 3, but if present, the query MUST
NOT contain any parameters beginning with the "oauth_" prefix, to
avoid conflicts with the protocol parameters added to the URIs when
used.
The methods in which the server advertises and documents its three
endpoints are beyond the scope of this specification. Clients should
avoid making assumptions about the size of tokens and other server-
generated values, which are left undefined by this specification. In
addition, protocol parameters MAY include values that require
encoding when transmitted. Clients and servers should not make
assumptions about the possible range of their values.
2.1. Temporary Credentials
The client obtains a set of temporary credentials from the server by
making an authenticated (Section 3) HTTP "POST" request to the
Temporary Credential Request endpoint (unless the server advertises
another HTTP request method for the client to use). The client
constructs a request URI by adding the following REQUIRED parameter
to the request (in addition to the other protocol parameters, using
the same parameter transmission method):
oauth_callback: An absolute URI back to which the server will
redirect the resource owner when the Resource Owner
Authorization step (Section 2.2) is completed. If
the client is unable to receive callbacks or a
callback URI has been established via other means,
the parameter value MUST be set to "oob" (case
sensitive), to indicate an out-of-band
configuration.
Servers MAY specify additional parameters.
When making the request, the client authenticates using only the
client credentials. The client MAY omit the empty "oauth_token"
protocol parameter from the request and MUST use the empty string as
the token secret value.
Since the request results in the transmission of plain text
credentials in the HTTP response, the server MUST require the use of
a transport-layer mechanisms such as TLS or Secure Socket Layer (SSL)
(or a secure channel with equivalent protections).
Hammer-Lahav Informational [Page 9]
RFC 5849 OAuth 1.0 April 2010
For example, the client makes the following HTTPS request:
POST /request_temp_credentials HTTP/1.1
Host: server.example.com
Authorization: OAuth realm="Example",
oauth_consumer_key="jd83jd92dhsh93js",
oauth_signature_method="PLAINTEXT",
oauth_callback="http%3A%2F%2Fclient.example.net%2Fcb%3Fx%3D1",
oauth_signature="ja893SD9%26"
The server MUST verify (Section 3.2) the request and if valid,
respond back to the client with a set of temporary credentials (in
the form of an identifier and shared-secret). The temporary
credentials are included in the HTTP response body using the
"application/x-www-form-urlencoded" content type as defined by
[W3C.REC-html40-19980424] with a 200 status code (OK).
The response contains the following REQUIRED parameters:
oauth_token
The temporary credentials identifier.
oauth_token_secret
The temporary credentials shared-secret.
oauth_callback_confirmed
MUST be present and set to "true". The parameter is used to
differentiate from previous versions of the protocol.
Note that even though the parameter names include the term 'token',
these credentials are not token credentials, but are used in the next
two steps in a similar manner to token credentials.
For example (line breaks are for display purposes only):
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
oauth_token=hdk48Djdsa&oauth_token_secret=xyz4992k83j47x0b&
oauth_callback_confirmed=true
2.2. Resource Owner Authorization
Before the client requests a set of token credentials from the
server, it MUST send the user to the server to authorize the request.
The client constructs a request URI by adding the following REQUIRED
query parameter to the Resource Owner Authorization endpoint URI:
Hammer-Lahav Informational [Page 10]
RFC 5849 OAuth 1.0 April 2010
oauth_token
The temporary credentials identifier obtained in Section 2.1 in
the "oauth_token" parameter. Servers MAY declare this
parameter as OPTIONAL, in which case they MUST provide a way
for the resource owner to indicate the identifier through other
means.
Servers MAY specify additional parameters.
The client directs the resource owner to the constructed URI using an
HTTP redirection response, or by other means available to it via the
resource owner's user-agent. The request MUST use the HTTP "GET"
method.
For example, the client redirects the resource owner's user-agent to
make the following HTTPS request:
GET /authorize_access?oauth_token=hdk48Djdsa HTTP/1.1
Host: server.example.com
The way in which the server handles the authorization request,
including whether it uses a secure channel such as TLS/SSL is beyond
the scope of this specification. However, the server MUST first
verify the identity of the resource owner.
When asking the resource owner to authorize the requested access, the
server SHOULD present to the resource owner information about the
client requesting access based on the association of the temporary
credentials with the client identity. When displaying any such
information, the server SHOULD indicate if the information has been
verified.
After receiving an authorization decision from the resource owner,
the server redirects the resource owner to the callback URI if one
was provided in the "oauth_callback" parameter or by other means.
To make sure that the resource owner granting access is the same
resource owner returning back to the client to complete the process,
the server MUST generate a verification code: an unguessable value
passed to the client via the resource owner and REQUIRED to complete
the process. The server constructs the request URI by adding the
following REQUIRED parameters to the callback URI query component:
oauth_token
The temporary credentials identifier received from the client.
Hammer-Lahav Informational [Page 11]
RFC 5849 OAuth 1.0 April 2010
oauth_verifier
The verification code.
If the callback URI already includes a query component, the server
MUST append the OAuth parameters to the end of the existing query.
For example, the server redirects the resource owner's user-agent to
make the following HTTP request:
GET /cb?x=1&oauth_token=hdk48Djdsa&oauth_verifier=473f82d3 HTTP/1.1
Host: client.example.net
If the client did not provide a callback URI, the server SHOULD
display the value of the verification code, and instruct the resource
owner to manually inform the client that authorization is completed.
If the server knows a client to be running on a limited device, it
SHOULD ensure that the verifier value is suitable for manual entry.
2.3. Token Credentials
The client obtains a set of token credentials from the server by
making an authenticated (Section 3) HTTP "POST" request to the Token
Request endpoint (unless the server advertises another HTTP request
method for the client to use). The client constructs a request URI
by adding the following REQUIRED parameter to the request (in
addition to the other protocol parameters, using the same parameter
transmission method):
oauth_verifier
The verification code received from the server in the previous
step.
When making the request, the client authenticates using the client
credentials as well as the temporary credentials. The temporary
credentials are used as a substitute for token credentials in the
authenticated request and transmitted using the "oauth_token"
parameter.
Since the request results in the transmission of plain text
credentials in the HTTP response, the server MUST require the use of
a transport-layer mechanism such as TLS or SSL (or a secure channel
with equivalent protections).
Hammer-Lahav Informational [Page 12]
RFC 5849 OAuth 1.0 April 2010
For example, the client makes the following HTTPS request:
POST /request_token HTTP/1.1
Host: server.example.com
Authorization: OAuth realm="Example",
oauth_consumer_key="jd83jd92dhsh93js",
oauth_token="hdk48Djdsa",
oauth_signature_method="PLAINTEXT",
oauth_verifier="473f82d3",
oauth_signature="ja893SD9%26xyz4992k83j47x0b"
The server MUST verify (Section 3.2) the validity of the request,
ensure that the resource owner has authorized the provisioning of
token credentials to the client, and ensure that the temporary
credentials have not expired or been used before. The server MUST
also verify the verification code received from the client. If the
request is valid and authorized, the token credentials are included
in the HTTP response body using the
"application/x-www-form-urlencoded" content type as defined by
[W3C.REC-html40-19980424] with a 200 status code (OK).
The response contains the following REQUIRED parameters:
oauth_token
The token identifier.
oauth_token_secret
The token shared-secret.
For example:
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
oauth_token=j49ddk933skd9dks&oauth_token_secret=ll399dj47dskfjdk
The server must retain the scope, duration, and other attributes
approved by the resource owner, and enforce these restrictions when
receiving a client request made with the token credentials issued.
Once the client receives and stores the token credentials, it can
proceed to access protected resources on behalf of the resource owner
by making authenticated requests (Section 3) using the client
credentials together with the token credentials received.
Hammer-Lahav Informational [Page 13]
RFC 5849 OAuth 1.0 April 2010
3. Authenticated Requests
The HTTP authentication methods defined by [RFC2617] enable clients
to make authenticated HTTP requests. Clients using these methods
gain access to protected resources by using their credentials
(typically, a username and password pair), which allow the server to
verify their authenticity. Using these methods for delegation
requires the client to assume the role of the resource owner.
OAuth provides a method designed to include two sets of credentials
with each request, one to identify the client, and another to
identify the resource owner. Before a client can make authenticated
requests on behalf of the resource owner, it must obtain a token
authorized by the resource owner. Section 2 provides one such method
through which the client can obtain a token authorized by the
resource owner.
The client credentials take the form of a unique identifier and an
associated shared-secret or RSA key pair. Prior to making
authenticated requests, the client establishes a set of credentials
with the server. The process and requirements for provisioning these
are outside the scope of this specification. Implementers are urged
to consider the security ramifications of using client credentials,
some of which are described in Section 4.6.
Making authenticated requests requires prior knowledge of the
server's configuration. OAuth includes multiple methods for
transmitting protocol parameters with requests (Section 3.5), as well
as multiple methods for the client to prove its rightful ownership of
the credentials used (Section 3.4). The way in which clients
discover the required configuration is outside the scope of this
specification.
3.1. Making Requests
An authenticated request includes several protocol parameters. Each
parameter name begins with the "oauth_" prefix, and the parameter
names and values are case sensitive. Clients make authenticated
requests by calculating the values of a set of protocol parameters
and adding them to the HTTP request as follows:
1. The client assigns value to each of these REQUIRED (unless
specified otherwise) protocol parameters:
Hammer-Lahav Informational [Page 14]
RFC 5849 OAuth 1.0 April 2010
oauth_consumer_key
The identifier portion of the client credentials (equivalent to
a username). The parameter name reflects a deprecated term
(Consumer Key) used in previous revisions of the specification,
and has been retained to maintain backward compatibility.
oauth_token
The token value used to associate the request with the resource
owner. If the request is not associated with a resource owner
(no token available), clients MAY omit the parameter.
oauth_signature_method
The name of the signature method used by the client to sign the
request, as defined in Section 3.4.
oauth_timestamp
The timestamp value as defined in Section 3.3. The parameter
MAY be omitted when using the "PLAINTEXT" signature method.
oauth_nonce
The nonce value as defined in Section 3.3. The parameter MAY
be omitted when using the "PLAINTEXT" signature method.
oauth_version
OPTIONAL. If present, MUST be set to "1.0". Provides the
version of the authentication process as defined in this
specification.
2. The protocol parameters are added to the request using one of the
transmission methods listed in Section 3.5. Each parameter MUST
NOT appear more than once per request.
3. The client calculates and assigns the value of the
"oauth_signature" parameter as described in Section 3.4 and adds
the parameter to the request using the same method as in the
previous step.
4. The client sends the authenticated HTTP request to the server.
For example, to make the following HTTP request authenticated (the
"c2&a3=2+q" string in the following examples is used to illustrate
the impact of a form-encoded entity-body):
POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
c2&a3=2+q
Hammer-Lahav Informational [Page 15]
RFC 5849 OAuth 1.0 April 2010
The client assigns values to the following protocol parameters using
its client credentials, token credentials, the current timestamp, a
uniquely generated nonce, and indicates that it will use the
"HMAC-SHA1" signature method:
oauth_consumer_key: 9djdj82h48djs9d2
oauth_token: kkk9d7dh3k39sjv7
oauth_signature_method: HMAC-SHA1
oauth_timestamp: 137131201
oauth_nonce: 7d8f3e4a
The client adds the protocol parameters to the request using the
OAuth HTTP "Authorization" header field:
Authorization: OAuth realm="Example",
oauth_consumer_key="9djdj82h48djs9d2",
oauth_token="kkk9d7dh3k39sjv7",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131201",
oauth_nonce="7d8f3e4a"
Then, it calculates the value of the "oauth_signature" parameter
(using client secret "j49sk3j29djd" and token secret "dh893hdasih9"),
adds it to the request, and sends the HTTP request to the server:
POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth realm="Example",
oauth_consumer_key="9djdj82h48djs9d2",
oauth_token="kkk9d7dh3k39sjv7",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="137131201",
oauth_nonce="7d8f3e4a",
oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D"
c2&a3=2+q
3.2. Verifying Requests
Servers receiving an authenticated request MUST validate it by:
o Recalculating the request signature independently as described in
Section 3.4 and comparing it to the value received from the client
via the "oauth_signature" parameter.
Hammer-Lahav Informational [Page 16]
RFC 5849 OAuth 1.0 April 2010
o If using the "HMAC-SHA1" or "RSA-SHA1" signature methods, ensuring
that the combination of nonce/timestamp/token (if present)
received from the client has not been used before in a previous
request (the server MAY reject requests with stale timestamps as
described in Section 3.3).
o If a token is present, verifying the scope and status of the
client authorization as represented by the token (the server MAY
choose to restrict token usage to the client to which it was
issued).
o If the "oauth_version" parameter is present, ensuring its value is
"1.0".
If the request fails verification, the server SHOULD respond with the
appropriate HTTP response status code. The server MAY include
further details about why the request was rejected in the response
body.
The server SHOULD return a 400 (Bad Request) status code when
receiving a request with unsupported parameters, an unsupported
signature method, missing parameters, or duplicated protocol
parameters. The server SHOULD return a 401 (Unauthorized) status
code when receiving a request with invalid client credentials, an
invalid or expired token, an invalid signature, or an invalid or used
nonce.
3.3. Nonce and Timestamp
The timestamp value MUST be a positive integer. Unless otherwise
specified by the server's documentation, the timestamp is expressed
in the number of seconds since January 1, 1970 00:00:00 GMT.
A nonce is a random string, uniquely generated by the client to allow
the server to verify that a request has never been made before and
helps prevent replay attacks when requests are made over a non-secure
channel. The nonce value MUST be unique across all requests with the
same timestamp, client credentials, and token combinations.
To avoid the need to retain an infinite number of nonce values for
future checks, servers MAY choose to restrict the time period after
which a request with an old timestamp is rejected. Note that this
restriction implies a level of synchronization between the client's
and server's clocks. Servers applying such a restriction MAY provide
a way for the client to sync with the server's clock; alternatively,
both systems could synchronize with a trusted time service. Details
of clock synchronization strategies are beyond the scope of this
specification.
Hammer-Lahav Informational [Page 17]
RFC 5849 OAuth 1.0 April 2010
3.4. Signature
OAuth-authenticated requests can have two sets of credentials: those
passed via the "oauth_consumer_key" parameter and those in the
"oauth_token" parameter. In order for the server to verify the
authenticity of the request and prevent unauthorized access, the
client needs to prove that it is the rightful owner of the
credentials. This is accomplished using the shared-secret (or RSA
key) part of each set of credentials.
OAuth provides three methods for the client to prove its rightful
ownership of the credentials: "HMAC-SHA1", "RSA-SHA1", and
"PLAINTEXT". These methods are generally referred to as signature
methods, even though "PLAINTEXT" does not involve a signature. In
addition, "RSA-SHA1" utilizes an RSA key instead of the shared-
secrets associated with the client credentials.
OAuth does not mandate a particular signature method, as each
implementation can have its own unique requirements. Servers are
free to implement and document their own custom methods.
Recommending any particular method is beyond the scope of this
specification. Implementers should review the Security
Considerations section (Section 4) before deciding on which method to
support.
The client declares which signature method is used via the
"oauth_signature_method" parameter. It then generates a signature
(or a string of an equivalent value) and includes it in the
"oauth_signature" parameter. The server verifies the signature as
specified for each method.
The signature process does not change the request or its parameters,
with the exception of the "oauth_signature" parameter.
3.4.1. Signature Base String
The signature base string is a consistent, reproducible concatenation
of several of the HTTP request elements into a single string. The
string is used as an input to the "HMAC-SHA1" and "RSA-SHA1"
signature methods.
The signature base string includes the following components of the