| 1 |
.. module:: flask_dance.consumer |
| 2 |
|
| 3 |
Signals |
| 4 |
======= |
| 5 |
|
| 6 |
Flask-Dance supports signals, :doc:`just as Flask does <flask:signals>`. |
| 7 |
Signals are perfect for custom processing code that you want to run at a certain |
| 8 |
point in the OAuth dance. For example, after the dance is complete, you might |
| 9 |
need to update the user's profile, kick off a long-running task, or simply |
| 10 |
:doc:`flash a message <flask:patterns/flashing>` to let the user know |
| 11 |
that the login was successful. It's easy, just import the appropriate signal of |
| 12 |
the ones listed below, and connect your custom processing code to the signal. |
| 13 |
|
| 14 |
The following signals exist in Flask-Dance: |
| 15 |
|
| 16 |
.. data:: oauth_before_login |
| 17 |
|
| 18 |
.. versionadded:: 1.4.0 |
| 19 |
|
| 20 |
This signal is sent before redirecting to the provider login page. The signal |
| 21 |
is sent with a ``url`` parameter specifying the redirect URL. This signal is mostly |
| 22 |
useful for doing things like session construction/deconstruction before the user |
| 23 |
is redirected. |
| 24 |
|
| 25 |
Example subscriber:: |
| 26 |
|
| 27 |
import flask |
| 28 |
from flask_dance.consumer import oauth_before_login |
| 29 |
|
| 30 |
@oauth_before_login.connect |
| 31 |
def before_login(blueprint, url): |
| 32 |
flask.session["next_url"] = flask.request.args.get("next_url") |
| 33 |
|
| 34 |
.. data:: oauth_authorized |
| 35 |
|
| 36 |
This signal is sent when a user completes the OAuth dance by receiving a |
| 37 |
response from the OAuth provider's authorize URL. The signal is invoked |
| 38 |
with the blueprint instance as the first argument (the *sender*), and with |
| 39 |
a dict of the OAuth provider's response (the *token*). |
| 40 |
|
| 41 |
Example subscriber:: |
| 42 |
|
| 43 |
from flask import flash |
| 44 |
from flask_dance.consumer import oauth_authorized |
| 45 |
|
| 46 |
@oauth_authorized.connect |
| 47 |
def logged_in(blueprint, token): |
| 48 |
flash("Signed in successfully with {name}!".format( |
| 49 |
name=blueprint.name.capitalize() |
| 50 |
)) |
| 51 |
|
| 52 |
If you are linking OAuth records to User records, you *must* implement an |
| 53 |
``@oauth_authorized`` subscriber that creates new ``User`` and ``OAuth`` |
| 54 |
database entries for any new users, and links those two new records via |
| 55 |
the ``OAuth`` table's ``user_id`` field. |
| 56 |
|
| 57 |
If you're using OAuth 2, the user may grant you different scopes from the |
| 58 |
ones you requested: check the ``scope`` key in the *token* dict to |
| 59 |
determine what scopes were actually granted. If you don't want the *token* |
| 60 |
to be :doc:`stored <storages>`, simply return ``False`` from one of your |
| 61 |
signal receiver functions -- this can be useful if the user has declined |
| 62 |
to authorize your OAuth request, has granted insufficient scopes, or in some |
| 63 |
other way has given you a token that you don't want. |
| 64 |
|
| 65 |
You can also return a :class:`~flask.Response` instance from an event |
| 66 |
subscriber. If you do, that response will be returned to the user instead |
| 67 |
of the normal redirect. For example:: |
| 68 |
|
| 69 |
from flask import redirect, url_for |
| 70 |
|
| 71 |
@oauth_authorized.connect |
| 72 |
def logged_in(blueprint, token): |
| 73 |
return redirect(url_for("after_oauth")) |
| 74 |
|
| 75 |
.. data:: oauth_error |
| 76 |
|
| 77 |
This signal is sent when the OAuth provider indicates that there was an |
| 78 |
error with the OAuth dance. This can happen if your application is |
| 79 |
misconfigured somehow. The user will be redirected to the ``redirect_url`` |
| 80 |
anyway, so it is your responsibility to hook into this signal and inform |
| 81 |
the user that there was an error. |
| 82 |
|
| 83 |
You can also return a :class:`~flask.Response` instance from an event |
| 84 |
subscriber. If you do, that response will be returned to the user instead |
| 85 |
of the normal redirect. For example:: |
| 86 |
|
| 87 |
from flask import redirect, url_for |
| 88 |
|
| 89 |
@oauth_error.connect |
| 90 |
def handle_error(blueprint, error, error_description=None, error_uri=None): |
| 91 |
return redirect(url_for("custom_error_page")) |
| 92 |
|
| 93 |
.. _flash a message: http://flask.pocoo.org/docs/latest/patterns/flashing/ |
| 94 |
.. _blinker: http://pythonhosted.org/blinker/ |