| 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 |