Understanding the Magic¶
Flask-Dance might initially seem like magic (“it just works!”), but it’s just code. It’s complicated, but understandable. This page will teach you how Flask-Dance works.
Making the Blueprint¶
The first thing you do with Flask-Dance is make a blueprint. This is
an instance of
depending on if you’re using OAuth 1 or OAuth 2. (Most providers use
When you make your blueprint, you can either pass your client ID
and client secret to the blueprint directly, or teach your blueprint
where to find those values on its own using the
from_config dictionary. Using this
dictionary is usually a good idea, since it allows you to specify
these values in your application configuration instead of in
After you’ve made the blueprint, you need to register it on your Flask application, just like you would with any other blueprint.
Using the Requests Session¶
The Flask-Dance blueprints have a
attribute. When you access this attribute, the blueprint
will create and return a
properly configured for OAuth authentication. You can use this object
in exactly the same way as you would normally use the Requests
library for making HTTP requests.
The pre-set configurations also allow you to import special objects that refer to these Requests session objects. For example, if you run this code:
from flask_dance.contrib.github import github
You can then call
github.get() just like you do with Requests.
github object is not actually a Requests session –
it’s something called a
This allows you to access the session within the context of an incoming
HTTP request, but it will not allow you access it outside that
Starting the Dance¶
In order to start the OAuth dance, redirect the user to the
login() view from your blueprint.
You will need to provide the name of your blueprint when calling
url_for() function. For example, for the
from flask import redirect, url_for def my_view_func(): # ... implement whatever logic you want here return redirect(url_for("github.login"))
State & Security¶
One of the key features of
OAuth2ConsumerBlueprint.session is that
the requests it generates use a
state variable to ensure that the source
of OAuth authorization callbacks is in fact your intended OAuth provider.
By default, the state is a random 30-character string, as provided by
oauthlib.common.generate_token(). This protects your app against one
kind of CSRF attack. For more information, see section 10.12 of the
OAuth 2 spec.
Finishing the Dance¶
After the user finishes the OAuth dance, they will be redirected
back to the
from your blueprint. This will save the OAuth token to whatever
token storage you are using, and will then redirect the user
to a different page on your website.
By default, the user will be redirected back to the root page (
However, you can set the
in your blueprint to change this.
If you want a dynamic redirect, where the URL isn’t known until
the user finishes the OAuth dance, hook into the
signal and return the redirect from your subscriber function.
import flask from flask_dance.consumer import oauth_authorized @oauth_authorized.connect def redirect_to_next_url(blueprint, token): # set OAuth token in the token storage backend blueprint.token = token # retrieve `next_url` from Flask's session cookie next_url = flask.session["next_url"] # redirect the user to `next_url` return flask.redirect(next_url)