Developer Interface¶
Consumers¶
An OAuth consumer is a website that allows users to log in with other websites (known as OAuth providers). Once a user has gone through the OAuth dance, the consumer website is allowed to interact with the provider website on behalf of the user.
-
class
flask_dance.consumer.
OAuth1ConsumerBlueprint
(...)[source]¶ A subclass of
flask.Blueprint
that sets up OAuth 1 authentication.-
__init__
(name, import_name, client_key=None, client_secret=None, signature_method=u'HMAC-SHA1', signature_type=u'AUTH_HEADER', rsa_key=None, client_class=None, force_include_body=False, static_folder=None, static_url_path=None, template_folder=None, url_prefix=None, subdomain=None, url_defaults=None, root_path=None, login_url=None, authorized_url=None, base_url=None, request_token_url=None, authorization_url=None, access_token_url=None, redirect_url=None, redirect_to=None, session_class=None, backend=None, **kwargs)[source]¶ Most of the constructor arguments are forwarded either to the
flask.Blueprint
constructor or therequests_oauthlib.OAuth1Session
construtor, including**kwargs
(which is forwarded toOAuth1Session
). Only the arguments that are relevant to Flask-Dance are documented here.Parameters: - base_url – The base URL of the OAuth provider. If specified, all URLs passed to this instance will be resolved relative to this URL.
- request_token_url – The URL specified by the OAuth provider for
obtaining a
request token.
This can be an fully-qualified URL, or a path that is
resolved relative to the
base_url
. - authorization_url – The URL specified by the OAuth provider for
the user to
grant token authorization.
This can be an fully-qualified URL, or a path that is
resolved relative to the
base_url
. - access_token_url – The URL specified by the OAuth provider for
obtaining an
access token.
This can be an fully-qualified URL, or a path that is
resolved relative to the
base_url
. - login_url – The URL route for the
login
view that kicks off the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to/{bp.name}
, so that the URL is based on the name of the blueprint. - authorized_url – The URL route for the
authorized
view that completes the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to/{bp.name}/authorized
, so that the URL is based on the name of the blueprint. - redirect_url – When the OAuth dance is complete, redirect the user to this URL.
- redirect_to – When the OAuth dance is complete,
redirect the user to the URL obtained by calling
url_for()
with this argument. If you do not specify eitherredirect_url
orredirect_to
, the user will be redirected to the root path (/
). - session_class – The class to use for creating a
Requests session. Defaults to
OAuth1Session
. - backend – A storage backend class, or an instance of a storage
backend class, to use for this blueprint. Defaults to
SessionBackend
.
-
session
[source]¶ An
OAuth1Session
instance that automatically loads tokens for the OAuth provider from the backend. This instance is automatically created the first time it is referenced for each request to your Flask application.
-
backend
¶ The token storage backend that this blueprint uses.
-
config
¶ A special dictionary that holds information about the current state of the application, which the backend can use to look up the correct OAuth token from storage. For example, in a multi-user system, where each user has their own OAuth token, information about which user is currently logged in for this request is stored in this dictionary. This dictionary is special because it automatically alerts the backend when any attribute in the dictionary is changed, so that the backend’s caches are appropriately invalidated.
-
from_config
¶ A dictionary used to dynamically load variables from the Flask application config into the blueprint at the start of each request. To tell this blueprint to pull configuration from the app, set key-value pairs on this dict. Keys are the name of the local variable to set on the blueprint object, and values are the variable name in the Flask application config. Variable names can be a dotpath. For example:
blueprint.from_config["session.client_id"] = "GITHUB_OAUTH_CLIENT_ID"
Which will cause this line to execute at the start of every request:
blueprint.session.client_id = app.config["GITHUB_OAUTH_CLIENT_ID"]
-
-
class
flask_dance.consumer.
OAuth2ConsumerBlueprint
(...)[source]¶ A subclass of
flask.Blueprint
that sets up OAuth 2 authentication.-
__init__
(name, import_name, client_id=None, client_secret=None, client=None, auto_refresh_url=None, auto_refresh_kwargs=None, scope=None, state=None, static_folder=None, static_url_path=None, template_folder=None, url_prefix=None, subdomain=None, url_defaults=None, root_path=None, login_url=None, authorized_url=None, base_url=None, authorization_url=None, authorization_url_params=None, token_url=None, token_url_params=None, redirect_url=None, redirect_to=None, session_class=None, backend=None, **kwargs)[source]¶ Most of the constructor arguments are forwarded either to the
flask.Blueprint
constructor or therequests_oauthlib.OAuth2Session
construtor, including**kwargs
(which is forwarded toOAuth2Session
). Only the arguments that are relevant to Flask-Dance are documented here.Parameters: - base_url – The base URL of the OAuth provider. If specified, all URLs passed to this instance will be resolved relative to this URL.
- authorization_url – The URL specified by the OAuth provider for
obtaining an
authorization grant.
This can be an fully-qualified URL, or a path that is
resolved relative to the
base_url
. - authorization_url_params (dict) – A dict of extra
key-value pairs to include in the query string of the
authorization_url
, beyond those necessary for a standard OAuth 2 authorization grant request. - token_url –
The URL specified by the OAuth provider for obtaining an access token. This can be an fully-qualified URL, or a path that is resolved relative to the
base_url
. - token_url_params (dict) – A dict of extra
key-value pairs to include in the query string of the
token_url
, beyond those necessary for a standard OAuth 2 access token request. - login_url – The URL route for the
login
view that kicks off the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to/{bp.name}
, so that the URL is based on the name of the blueprint. - authorized_url – The URL route for the
authorized
view that completes the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to/{bp.name}/authorized
, so that the URL is based on the name of the blueprint. - redirect_url – When the OAuth dance is complete, redirect the user to this URL.
- redirect_to – When the OAuth dance is complete,
redirect the user to the URL obtained by calling
url_for()
with this argument. If you do not specify eitherredirect_url
orredirect_to
, the user will be redirected to the root path (/
). - session_class – The class to use for creating a
Requests session. Defaults to
OAuth2Session
. - backend – A storage backend class, or an instance of a storage
backend class, to use for this blueprint. Defaults to
SessionBackend
.
-
session
[source]¶ An
OAuth2Session
instance that automatically loads tokens for the OAuth provider from the backend. This instance is automatically created the first time it is referenced for each request to your Flask application.
-
backend
¶ The token storage backend that this blueprint uses.
-
config
¶ A special dictionary that holds information about the current state of the application, which the backend can use to look up the correct OAuth token from storage. For example, in a multi-user system, where each user has their own OAuth token, information about which user is currently logged in for this request is stored in this dictionary. This dictionary is special because it automatically alerts the backend when any attribute in the dictionary is changed, so that the backend’s caches are appropriately invalidated.
-
from_config
¶ A dictionary used to dynamically load variables from the Flask application config into the blueprint at the start of each request. To tell this blueprint to pull configuration from the app, set key-value pairs on this dict. Keys are the name of the local variable to set on the blueprint object, and values are the variable name in the Flask application config. Variable names can be a dotpath. For example:
blueprint.from_config["session.client_id"] = "GITHUB_OAUTH_CLIENT_ID"
Which will cause this line to execute at the start of every request:
blueprint.session.client_id = app.config["GITHUB_OAUTH_CLIENT_ID"]
-
Backends¶
-
class
flask_dance.consumer.backend.session.
SessionBackend
(...)[source]¶ The default storage backend. Stores and retrieves OAuth tokens using the Flask session.
-
__init__
(key='{bp.name}_oauth_token')[source]¶ Parameters: key (str) – The name to use as a key for storing the OAuth token in the Flask session. This string will have .format(bp=self.blueprint)
called on it before it is used. so you can refer to information on the blueprint as part of the key. For example,{bp.name}
will be replaced with the name of the blueprint.
-
-
class
flask_dance.consumer.backend.sqla.
SQLAlchemyBackend
(...)[source]¶ Stores and retrieves OAuth tokens using a relational database through the SQLAlchemy ORM.
-
__init__
(model, session, user=None, user_id=None, anon_user=None, cache=None)[source]¶ Parameters: - model – The SQLAlchemy model class that represents the OAuth token
table in the database. At a minimum, it must have a
provider
column and atoken
column. If tokens are to be associated with individual users in the application, it must also have auser
relationship to your User model. It is recommended, though not required, that your model class inherit fromOAuthConsumerMixin
. - session – The
SQLAlchemy session
for the database. If you’re using Flask-SQLAlchemy, this isdb.session
. - user – If you want OAuth tokens to be associated with individual users
in your application, this is a reference to the user that you
want to use for the current request. It can be an actual User
object, a function that returns a User object, or a proxy to the
User object. If you’re using Flask-Login, this is
current_user
. - user_id – If you want to pass an identifier for a user instead of an actual
User object, use this argument instead. Sometimes it can save
a database query or two. If both
user
anduser_id
are provided,user_id
will take precendence. - anon_user – If anonymous users are represented by a class in your application,
provide that class here. If you are using Flask-Login,
anonymous users are represented by the
flask_login.AnonymousUserMixin
class, but you don’t have to provide that – Flask-Dance treats it as the default. - cache – An instance of Flask-Cache. Providing a caching system is highly recommended, but not required.
- model – The SQLAlchemy model class that represents the OAuth token
table in the database. At a minimum, it must have a
-