Debian Codegraph @

docs/concepts.rst

raw
1 Concepts
2 ========
3
4 In order to use OAuth and Flask-Dance correctly, there are a few
5 basic concepts you need to understand. This page will summarize
6 these concepts, and provide links for further information.
7
8 OAuth
9 -----
10
11 OAuth is a system that allows two websites to securely share information.
12 Usually (but not always), OAuth is used to allow users to grant permission
13 to share information from one website to another website.
14
15 An OAuth **provider** is a website that *provides* information about users
16 to other websites. An OAuth **consumer** is a website that requests information
17 from an OAuth provider. Before an OAuth provider will provide information about
18 a user to an OAuth consumer, the provider must ask the user to grant permission
19 to share that information with the consumer.
20
21 Before an OAuth provider will even speak to a consumer, the consumer must get
22 a **client ID** and **client secret** from that provider. It's a bit like
23 how some website require you to create an account before you can do anything
24 else. OAuth providers do this so that they keep track of which consumers
25 they are sharing information with. If a consumer starts using information to do
26 evil things (like hacking or impersonating users), the provider can use
27 this information to deactivate that consumer's access to the provider's API.
28
29 After a user grants permission to share their data with a consumer, the
30 provider gives that consumer an **OAuth token**. This token records the fact
31 that the consumer has permission to access the information, and the consumer
32 must provide this token on *every API request*. If the consumer ever loses
33 this token, it has to get a new one, which might involve asking the user
34 for permission again. As a result, OAuth tokens must be stored somewhere
35 and retrieved as necessary.
36
37 .. warning::
38
39 If an attacker manages to steal an OAuth token from a consumer,
40 the attacker can use that token to do evil things to the user
41 that granted permission for that token. This could cause the
42 OAuth provider to deactivate the consumer from their API.
43 Be careful with OAuth tokens, and store them securely! If you don't,
44 you could lose access to your provider's API!
45
46 User Management
47 ---------------
48
49 The most well-known use for OAuth is for bypassing user registration:
50 users can "sign in" with a well-known OAuth provider like Google or Facebook
51 in order to avoid creating another username and password. However, this is
52 not the *only* use for OAuth. In fact, it's entirely possible to use
53 OAuth without even having a user management system on your website at all!
54
55 For example, let's say you want to create a Twitter account that is completely
56 public. Anyone in the world should be able to post a tweet, without any
57 identifying information attached to it. You build a simple website that has
58 a text field and a "submit" button, but no user management system at all.
59 Whenever anyone submits a tweet to your website, it uses the Twitter API
60 to post that tweet to your Twitter account -- which requires using OAuth.
61
62 Flask-Dance does *not* assume that your website has a user management system.
63 It's easy to use Flask-Dance with a user management system if you want to,
64 though! Read the documentation on :doc:`multi-user` if you plan to use a
65 user management system.
66
67 Local Accounts vs Provider Accounts
68 -----------------------------------
69
70 It's a common misconception that, because a user can log in to your website
71 using OAuth instead of creating a new username/password combination,
72 that means they do not have a user account on your website. This is false.
73 Logging in with OAuth *does create a local user account*, and that user account
74 will have some kind of identifier (or ``user_id``). The ``user_id`` on this
75 local account does *not* have to match that user's ID on Google,
76 or Facebook, or Twitter, or whatever OAuth provider(s) you choose to use.
77
78 The distinction between a local account and a provider account is especially
79 important when :doc:`implementing logout <logout>`.
80
81 Blueprints
82 ----------
83
84 A :doc:`Flask blueprint <flask:blueprints>` is component of a
85 Flask application. Because Flask-Dance is designed to be the OAuth component
86 of your Flask application, it is built using blueprints. As a result,
87 Flask-Dance supports all the features that any blueprint supports,
88 including registering the blueprint at any URL prefix or subdomain
89 you want, url routing, and custom error handlers. Read the
90 :doc:`Flask documentation about blueprints <flask:blueprints>`
91 for more information.
92
93 Signals
94 -------
95
96 Flask uses the `blinker`_ library to provide support for
97 :doc:`signals <flask:signals>`. Signals allow you to subscribe to certain
98 events that occur in your application, so that you can respond instantly
99 when those events happen.
100
101 Signals are an important part of Flask-Dance, because they allow you to
102 do whatever custom processing you want in response to certain events.
103 For example, when a user successfully completes the OAuth dance, you probably
104 want to flash a welcome message or kick off some kind of data import task.
105 Signals allow you to do that without modifying the code in Flask-Dance.
106 Read the :doc:`signals page <signals>` for more information.
107
108 .. _blinker: https://blinker.readthedocs.io