Signals¶
Flask-Dance supports signals, just as Flask does. Signals are perfect for custom processing code that you want to run at a certain point in the OAuth dance. For example, after the dance is complete, you might need to update the user’s profile, kick off a long-running task, or simply flash a message to let the user know that the login was successful. It’s easy, just import the appropriate signal of the ones listed below, and connect your custom processing code to the signal.
The following signals exist in Flask-Dance:
-
flask_dance.consumer.
oauth_before_login
¶ New in version 1.4.0.
This signal is sent before redirecting to the provider login page. The signal is sent with a
url
parameter specifying the redirect URL. This signal is mostly useful for doing things like session construction/deconstruction before the user is redirected.Example subscriber:
import flask from flask_dance.consumer import oauth_before_login @oauth_before_login.connect def before_login(blueprint, url): flask.session["next_url"] = flask.request.args.get("next_url")
This signal is sent when a user completes the OAuth dance by receiving a response from the OAuth provider’s authorize URL. The signal is invoked with the blueprint instance as the first argument (the sender), and with a dict of the OAuth provider’s response (the token).
Example subscriber:
from flask import flash from flask_dance.consumer import oauth_authorized @oauth_authorized.connect def logged_in(blueprint, token): flash("Signed in successfully with {name}!".format( name=blueprint.name.capitalize() ))
If you are linking OAuth records to User records, you must implement an
@oauth_authorized
subscriber that creates newUser
andOAuth
database entries for any new users, and links those two new records via theOAuth
table’suser_id
field.If you’re using OAuth 2, the user may grant you different scopes from the ones you requested: check the
scope
key in the token dict to determine what scopes were actually granted. If you don’t want the token to be stored, simply returnFalse
from one of your signal receiver functions – this can be useful if the user has declined to authorize your OAuth request, has granted insufficient scopes, or in some other way has given you a token that you don’t want.You can also return a
Response
instance from an event subscriber. If you do, that response will be returned to the user instead of the normal redirect. For example:from flask import redirect, url_for @oauth_authorized.connect def logged_in(blueprint, token): return redirect(url_for("after_oauth"))
-
flask_dance.consumer.
oauth_error
¶ This signal is sent when the OAuth provider indicates that there was an error with the OAuth dance. This can happen if your application is misconfigured somehow. The user will be redirected to the
redirect_url
anyway, so it is your responsibility to hook into this signal and inform the user that there was an error.