Debian Codegraph @

docs/how-oauth-works.rst

raw
1 How OAuth Works
2 ===============
3
4 Definitions
5 -----------
6
7 OAuth uses a series of specially-crafted HTTP views and redirects to allow
8 websites to share information with each other securely, and with the user's
9 consent [#oauth-user]_. There are four roles in an OAuth interaction:
10
11 provider
12 A website that has information about a user. Well-known OAuth providers
13 include Google, Facebook, GitHub etc.
14 consumer
15 A website that wants to obtain some information about a user from the
16 provider.
17 user
18 An actual person who controls information stored with the provider.
19 client
20 A program (usually a web browser) that interacts with the provider and
21 consumer on behalf of the user.
22
23 In order to securely interact with each other, the provider and consumer must
24 exchange secrets ahead of time, before any OAuth communication actually happens.
25 Generally, this happens when someone who runs the consumer website goes to the
26 provider website and registers an application with the provider, putting
27 in information about the name and URL of the consumer website. The provider
28 then gives the consumer a "client secret", which is a random string of letters
29 and numbers. By presenting this client secret in future OAuth communication,
30 the provider website can verify that the consumer is who they say they are,
31 and not some other website trying to intercept the communication.
32
33 .. note::
34 Even though it is called a "client secret", the secret represents the
35 consumer website, not the client (the user's web browser).
36
37 After the consumer has registered an application with the provider and gotten
38 a client secret, the consumer can do the "OAuth dance" to get consent from a
39 user to share information with the consumer. There are two different versions
40 of the dance: OAuth 1, which is the original version; and OAuth 2, the successor
41 to OAuth 1 which is more flexible and more widely used today.
42
43 OAuth 2
44 -------
45
46 .. seqdiag::
47
48 seqdiag {
49 Client -> Consumer [label = "start dance"];
50 Client <- Consumer [label = "redirect to provider,\nwith secret, scopes, & state"];
51 Client -> Provider [label = "follow redirect", rightnote="user\ngrants\n consent"];
52 Client <- Provider [label = "redirect to consumer, with authorization code and state"];
53 Client -> Consumer [label = "follow redirect"];
54 Consumer --> Provider [label = "send secret and\nauthorization code"];
55 Consumer <-- Provider [label = "return access token"];
56 Client <-- Consumer [label = "render page or redirect"];
57 }
58
59 1. The client visits the consumer at a special URL, indicating that they
60 want to connect to the provider with OAuth. Typically, there is a button
61 on the consumer's website labeled "Log In with Google" or similar, which
62 takes the user to this special URL.
63
64 2. The consumer decides how much of the user's data they want to access,
65 using specific keywords called "scopes". The consumer also makes up a random
66 string of letters and numbers, called a "state" token. The consumer crafts
67 a special URL that points to the provider, but has the client secret,
68 the scopes, the state token embedded in it. The consumer asks the client
69 to visit the provider using this special URL.
70
71 3. When the client visits the provider at that URL, the provider notices the
72 client secret, and looks up the consumer that it belongs to.
73 The provider also notices the scopes that the consumer is requesting.
74 The provider displays a page informing the user what information the
75 consumer wants access to -- it may be all of the user's information, or
76 just some of the user's information. The user gets to decide if this is
77 OK or not. If the user decides that this is not OK, the dance is over.
78
79 4. If the user grants consent, the provider makes up a new secret, called
80 the "authorization code". The provider crafts a special URL that points to
81 the consumer, but has the authorization code and the state token
82 embedded in it. The provider asks the client to visit the consumer
83 using this special URL.
84
85 5. When the client visits the consumer at that URL, the consumer first checks
86 the state token to be sure that it hasn't changed, just to verify that
87 no one has tampered with the request. Then, the consumer makes a separate
88 request to the provider, passing along the client secret and the
89 authorization code. If everything looks good to the provider, the provider
90 makes up one final secret, called the "access token", and sends it back
91 to the consumer. This completes the dance.
92
93 OAuth 1
94 -------
95
96 .. seqdiag::
97
98 seqdiag {
99 Client -> Consumer [label = "start dance"];
100 Consumer --> Provider [label = "send client secret"];
101 Consumer <-- Provider [label = "return request token"];
102 Client <- Consumer [label = "redirect, with request token"];
103 Client -> Provider [label = "follow redirect", rightnote="user\ngrants\nconsent"];
104 Client <- Provider [label = "redirect, with authorization code"];
105 Client -> Consumer [label = "follow redirect"];
106 Consumer --> Provider [label = "send client secret\n& authorization code"];
107 Consumer <-- Provider [label = "return access token"];
108 Client <-- Consumer [label = "render page or redirect"];
109 }
110
111 1. The client visits the consumer at a special URL, indicating that they
112 want to connect to the provider with OAuth. Typically, there is a button
113 on the consumer's website labeled "Log In with Google" or similar, which
114 takes the user to this special URL.
115
116 2. The consumer tells the provider that they're about to do the OAuth dance.
117 The consumer gives the provider the client secret, to verify that
118 everything's cool. The provider checks the OAuth secret, and if it
119 looks good, the provider makes up a new secret called a
120 "request token", and gives it to the consumer.
121
122 3. The consumer crafts a special URL that points to the provider, but has the
123 client secret and request token embedded in it. The consumer asks the client
124 to visit the provider using this special URL.
125
126 4. When the client visits the provider at that URL, the provider notices the
127 request token, and looks up the consumer that it belongs to.
128 The provider tells the user that this consumer wants to access some or all
129 of the user's information. The user gets to decide if this is OK or not.
130 If the user decides that this is not OK, the dance is over.
131
132 5. If the user grants consent, the provider makes up another new secret, called
133 the "authorization code". The provider crafts a special URL that points to
134 the consumer, but has the authorization code embedded in it.
135 The provider asks the client to go visit the consumer at that special URL.
136
137 6. When the client visits the consumer at that URL, the consumer notices the
138 authorization code. The consumer makes another request to the provider,
139 passing along the client secret and the authorization code.
140 If everything looks good to the provider, the provider makes up one
141 final secret, called the "access token", and sends it back to the consumer.
142 This completes the dance.
143
144 Dance Complete
145 --------------
146
147 Phew, that was complicated! But the end result is, the consumer has an access
148 token, which proves that the user has given consent for the provider to give
149 the consumer information about that user. Now, whenever the consumer needs
150 information from the provider about the user, the consumer simply makes an
151 API request to the provider and passes the access token along with the request.
152 The provider sees the access token, looks up the user that granted consent,
153 and determines whether the requested information falls within what the user
154 authorized. If so, the provider returns that information to the consumer.
155 In effect, the consumer is now the user's client!
156
157 .. warning::
158 Keep your access tokens secure! Treat a user's access token like you would
159 treat their password.
160
161 .. note::
162 The OAuth dance normally only needs to be performed once per user.
163 Once the consumer has an access token, that access token can be used
164 to make many API requests on behalf of the user. Some OAuth
165 implementations put a lifespan on the access token, after which it must
166 be refreshed, but refreshing an access token does not require any
167 interaction from the user.
168
169 .. [#oauth-user] Not all OAuth interactions share information about specific
170 users. When no user-specific information is involved, then the consumer
171 is able to get information from the provider without getting a user's
172 consent, since there is no one to get consent from. In practice, however,
173 most OAuth interactions are about sharing information about users, so this
174 documentation assumes that use-case.