Debian Codegraph @

docs/understanding-the-magic.rst

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