Debian Codegraph @

docs/logout.rst

raw
1 Logging Out
2 ===========
3
4 Many websites use OAuth as an authentication system (see :doc:`multi-user`
5 for more information). Although this can work quite well, it gets more
6 complicated when you want to allow the user to log out of your website.
7 For starters, we need to understand what "logging out" even *means*.
8
9 Local Accounts vs Provider Accounts
10 -----------------------------------
11
12 When you use OAuth as an authentication system, your users still have
13 local accounts on your system. OAuth allows your users to log in
14 with a provider (such as Google or Facebook), and use their provider
15 login to authenticate to your local account. Essentially, the
16 exchange looks something like this, if we assume that "CustomSite"
17 is the name of your website, and it's using the Google provider:
18
19 1. User: Hey CustomSite, I'm user ShinyStar99. Let me in.
20 2. CustomSite: Sorry user, anyone could claim that and I don't trust you.
21 How do I know you're telling the truth?
22 3. User: My friend Google can back me up. You trust Google, right?
23 4. CustomSite: Yes, I trust Google. Hey Google, who is this user?
24 5. Google: Hold on, I need to ask my user if I have permission to
25 give you any information at all. Hey User, CustomSite wants
26 to know who you are. Do you want me to tell CustomSite some
27 basic information about you?
28 6. User: Yes, please.
29 7. Google: Alright CustomSite, I can tell you that on *my* website,
30 this user has the ID 987654.
31 8. CustomSite: Alright, let me check my database.
32 Google user ID 987654 matches up with one of my local users,
33 with ID 12345. And it looks like that local user is ShinyStar99!
34 9. User: You see? I told you so!
35 10. CustomSite: Come in, ShinyStar99. Who's next?
36
37 In this exchange, you can see that there are two *different* user accounts
38 involved: one user account on Google, and one user account on CustomSite.
39 They have different user IDs, and could contain different sets of information,
40 even though they both represent the same user.
41
42 So if you want to cause a user to log out, what exactly do you mean?
43 We'll go step-by-step through the different options.
44
45 Log Out Local Account
46 ---------------------
47
48 If you want to cause a user to log out of their local user account,
49 check the documentation for whatever system you're using to manage
50 local accounts. If you're using `Flask-Login`_ (or `Flask-Security`_,
51 which is built on top of Flask-Login), you can import and call the
52 :func:`flask_login.logout_user` function, like this:
53
54 .. code-block:: python
55 :emphasize-lines: 6
56
57 from flask_login import logout_user
58 # other imports as necessary
59
60 @app.route("/logout")
61 def logout():
62 logout_user()
63 return redirect(somewhere)
64
65 After you do this, your application will treat the user like any other
66 anonymous user. However, logging out your user from their local account
67 doesn't do anything about the provider account. As a result, if the
68 user tries to log in again after you've logged them out this way,
69 the conversation will look like this:
70
71 1. User: Hey CustomSite, I'm user ShinyStar99. Let me in.
72 Ask Google if you don't believe me.
73 2. CustomSite: Hey Google, who is this user?
74 3. Google: My user already gave me permission to tell you some
75 basic information. On *my* website, this user has the ID 987654.
76 4. CustomSite: Oh right, it's ShinyStar99 again. Go ahead.
77
78 In most cases, this is what you want. However, sometimes you want to
79 really reset things back to the start, as though the user had never
80 granted consent to share information in the first place.
81
82 Revoking Access with the Provider
83 ---------------------------------
84
85 Undoing the user's permission to share information from the provider
86 to your custom site is called "revoking access". Unfortunately,
87 every provider has a different way of doing this, so you'll need
88 to check the OAuth documentation provided by your OAuth provider.
89
90 When you are granted access by a user, the provider will give your
91 application a "token" that is used for making subsequent API requests.
92 In order to revoke access for a user, you may need to include this
93 token as an argument, so the provider knows which token to revoke.
94 You can get this information by checking the ``token`` property of the
95 Flask-Dance blueprint.
96
97 We'll use Google as an example. First, check
98 `Google's documentation for how to revoke access via OAuth2
99 <https://developers.google.com/identity/protocols/OAuth2WebServer#tokenrevoke>`_.
100 Notice that you do indeed need to provide the token in order to revoke it.
101
102 Here's some sample code that works with Google:
103
104 .. code-block:: python
105 :emphasize-lines: 12-16
106
107 from flask import Flask, redirect
108 from flask_dance.contrib.google import make_google_blueprint, google
109 from flask_login import logout_user
110
111 app = Flask(__name__)
112 blueprint = make_google_blueprint()
113 app.register_blueprint(blueprint, url_prefix="/login")
114
115 @app.route("/logout")
116 def logout():
117 token = blueprint.token["access_token"]
118 resp = google.post(
119 "https://accounts.google.com/o/oauth2/revoke",
120 params={"token": token},
121 headers={"Content-Type": "application/x-www-form-urlencoded"}
122 )
123 assert resp.ok, resp.text
124 logout_user() # Delete Flask-Login's session cookie
125 del blueprint.token # Delete OAuth token from storage
126 return redirect(somewhere)
127
128 After the user uses this method to log out, Google will not remember that they
129 granted consent to share information with your website.
130
131 .. warning::
132
133 In this sample code, we are using an :keyword:`assert` statement.
134 This works fine for debugging, but not for production. Be sure to modify
135 this code to appropriately handle cases where there is an API failure
136 when trying to revoke the token.
137
138 .. note::
139
140 In this code, we already have a reference to the ``blueprint`` object,
141 so we could grab the token easily. But what if you don't have access
142 to that object? Instead, you can use the :data:`flask.current_app` proxy
143 to pull out the blueprint object you need. For example, instead of
144 this line:
145
146 .. code-block:: python
147
148 token = blueprint.token["access_token"]
149
150 You could use this line instead:
151
152 .. code-block:: python
153
154 token = current_app.blueprints["google"].token["access_token"]
155
156
157 Log Out Provider Account
158 ------------------------
159
160 You can log out the user from their local account, and you can revoke access
161 with the provider. But what about logging the user out from their provider
162 account? Can you force the user to type their password into Google again
163 if they want to log in to your website in the future?
164
165 The short answer is: no, you can't. You can't control how a user interacts
166 with other websites, except for in the ways that those other websites
167 specifically allow you to. And since this could potentially be used as
168 part of a security exploit, websites will generally *not* allow you
169 to force users to log out.
170
171 .. _Flask-Login: https://flask-login.readthedocs.io/
172 .. _Flask-Security: https://pythonhosted.org/Flask-Security/