| 1 |
Understanding the Magic |
| 2 |
======================= |
| 3 |
|
| 4 |
.. currentmodule:: flask_dance.consumer |
| 5 |
|
| 6 |
Flask-Dance might initially seem like magic ("it just works!"), |
| 7 |
but it's just code. It's complicated, but understandable. This page |
| 8 |
will teach you how Flask-Dance works. |
| 9 |
|
| 10 |
Making the Blueprint |
| 11 |
-------------------- |
| 12 |
|
| 13 |
The first thing you do with Flask-Dance is make a blueprint. This is |
| 14 |
an instance of |
| 15 |
:class:`OAuth1ConsumerBlueprint` or :class:`OAuth2ConsumerBlueprint`, |
| 16 |
depending on if you're using OAuth 1 or OAuth 2. (Most providers use |
| 17 |
OAuth 2.) |
| 18 |
|
| 19 |
When you make your blueprint, you can either pass your client ID |
| 20 |
and client secret to the blueprint directly, or teach your blueprint |
| 21 |
where to find those values on its own using the |
| 22 |
:attr:`~OAuth2ConsumerBlueprint.from_config` dictionary. Using this |
| 23 |
dictionary is usually a good idea, since it allows you to specify |
| 24 |
these values in your application configuration instead of in |
| 25 |
your code. |
| 26 |
|
| 27 |
After you've made the blueprint, you need to register it on your |
| 28 |
Flask application, just like you would with any other blueprint. |
| 29 |
|
| 30 |
Using the Requests Session |
| 31 |
-------------------------- |
| 32 |
|
| 33 |
The Flask-Dance blueprints have a :attr:`~OAuth2ConsumerBlueprint.session` |
| 34 |
attribute. When you access this attribute, the blueprint |
| 35 |
will create and return a :class:`requests.Session` object, |
| 36 |
properly configured for OAuth authentication. You can use this object |
| 37 |
in exactly the same way as you would normally use the Requests |
| 38 |
library for making HTTP requests. |
| 39 |
|
| 40 |
The pre-set configurations also allow you to import special objects |
| 41 |
that refer to these Requests session objects. For example, |
| 42 |
if you run this code: |
| 43 |
|
| 44 |
.. code-block:: python |
| 45 |
|
| 46 |
from flask_dance.contrib.github import github |
| 47 |
|
| 48 |
You can then call ``github.get()`` just like you do with Requests. |
| 49 |
However, this ``github`` object is not actually a Requests session -- |
| 50 |
it's something called a :class:`~werkzeug.local.LocalProxy`. |
| 51 |
This allows you to access the session within the context of an incoming |
| 52 |
HTTP request, but it will *not* allow you access it outside that |
| 53 |
context. |
| 54 |
|
| 55 |
Checking Authorization |
| 56 |
---------------------- |
| 57 |
|
| 58 |
When your application starts up, Flask-Dance will check your token |
| 59 |
storage to see if there is an OAuth token already saved |
| 60 |
there. If so, the ``authorized`` property on your Requests |
| 61 |
Session object will be ``True``; if not, it will be ``False``. |
| 62 |
You can use this to determine if the user needs to go through the |
| 63 |
OAuth dance or not. |
| 64 |
|
| 65 |
.. warning:: |
| 66 |
|
| 67 |
If the OAuth token is expired or invalid, it will not work. |
| 68 |
However, this ``authorized`` property can not check this for |
| 69 |
you! It only checks if the token *exists*. |
| 70 |
|
| 71 |
Starting the Dance |
| 72 |
------------------ |
| 73 |
|
| 74 |
In order to start the OAuth dance, redirect the user to the |
| 75 |
:meth:`~OAuth2ConsumerBlueprint.login` view from your blueprint. |
| 76 |
You will need to provide the name of your blueprint when calling |
| 77 |
Flask's :func:`~flask.url_for` function. For example, for the |
| 78 |
GitHub contrib: |
| 79 |
|
| 80 |
.. code-block:: python |
| 81 |
|
| 82 |
from flask import redirect, url_for |
| 83 |
|
| 84 |
def my_view_func(): |
| 85 |
# ... implement whatever logic you want here |
| 86 |
return redirect(url_for("github.login")) |
| 87 |
|
| 88 |
State & Security |
| 89 |
~~~~~~~~~~~~~~~~ |
| 90 |
|
| 91 |
One of the key features of :attr:`OAuth2ConsumerBlueprint.session` is that |
| 92 |
the requests it generates use a ``state`` variable to ensure that the source |
| 93 |
of OAuth authorization callbacks is in fact your intended OAuth provider. |
| 94 |
By default, the state is a random 30-character string, as provided by |
| 95 |
:func:`oauthlib.common.generate_token`. This protects your app against one |
| 96 |
kind of CSRF attack. For more information, see `section 10.12 of the |
| 97 |
OAuth 2 spec <https://tools.ietf.org/html/rfc6749#section-10.12>`_. |
| 98 |
|
| 99 |
Finishing the Dance |
| 100 |
------------------- |
| 101 |
|
| 102 |
After the user finishes the OAuth dance, they will be redirected |
| 103 |
back to the :meth:`~OAuth2ConsumerBlueprint.authorized` view |
| 104 |
from your blueprint. This will save the OAuth token to whatever |
| 105 |
token storage you are using, and will then redirect the user |
| 106 |
to a different page on your website. |
| 107 |
|
| 108 |
By default, the user will be redirected back to the root page (``/``). |
| 109 |
However, you can set the ``redirect_url`` or ``redirect_to`` arguments |
| 110 |
in your blueprint to change this. |
| 111 |
|
| 112 |
If you want a dynamic redirect, where the URL isn't known until |
| 113 |
the user finishes the OAuth dance, hook into the |
| 114 |
:data:`~flask_dance.consumer.oauth_authorized` |
| 115 |
signal and return the redirect from your subscriber function. |
| 116 |
For example: |
| 117 |
|
| 118 |
.. code-block:: python |
| 119 |
|
| 120 |
import flask |
| 121 |
from flask_dance.consumer import oauth_authorized |
| 122 |
|
| 123 |
@oauth_authorized.connect |
| 124 |
def redirect_to_next_url(blueprint, token): |
| 125 |
# set OAuth token in the token storage backend |
| 126 |
blueprint.token = token |
| 127 |
# retrieve `next_url` from Flask's session cookie |
| 128 |
next_url = flask.session["next_url"] |
| 129 |
# redirect the user to `next_url` |
| 130 |
return flask.redirect(next_url) |