API

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(...)

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, **kwargs)

Most of the constructor arguments are forwarded either to the flask.Blueprint constructor or the requests_oauthlib.OAuth1Session construtor, including **kwargs (which is forwarded to OAuth1Session). The only arguments that are specific to this class are base_url, request_token_url, authorization_url, access_token_url, login_url, authorized_url, redirect_url, and redirect_to.

Parameters:

• base_url (str, optional) – 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 (str) – 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 (str) – 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 (str) – 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 (str, optional) – 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 (str, optional) – 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 (str, optional) – When the OAuth dance is complete, redirect the user to this URL.
• redirect_to (str, optional) – When the OAuth dance is complete, redirect the user to the URL obtained by calling url_for() with this argument. You must specify either redirect_url or redirect_to. If you specify both, redirect_url will take precedence.

session

An OAuth1Session instance that automatically loads credentials for the OAuth provider (if the user has already gone through the OAuth dance).

token_getter(func)

A decorator used to indicate the function used to retrieve a stored token from a completed OAuth dance.

token_setter(func)

A decorator used to indicate the function used to store a token from a completed OAuth dance, so that it can be retrieved later.

token_deleter(func)

A decorator used to indicate the function used to delete a previously-stored OAuth token.

token

A proxy property for getting, setting, and deleting the stored OAuth token.

set_token_storage_session()

A helper method to set up the blueprint to store and retrieve OAuth tokens using the Flask session. This will overwrite any custom token accessors you’ve set up. This method is called by the constructor as a default – in general, you shouldn’t call this method yoursel.

set_token_storage_sqlalchemy(model, session, user=None, cache=None)

A helper method to set up the blueprint to store and retrieve OAuth tokens using SQLAlchemy. This will overwrite any custom token accessors you’ve set up.

Parameters:

• model – A class that represents a database table. At a minimum, it must have a token column and a provider column. If you’re using a User class, this model must also declare a user relation to that class. It is recommended, but not required, that your model inherit from flask_dance.models.OAuthMixin.
• session – A sqlalchemy.orm.session.Session object. If you’re using Flask-SQLAlchemy, this is db.session.
• user – The current logged in user, if any. This can also be a function that returns the current logged in user. This is argument is optional; if not provided, OAuth tokens will not be associated with specific users in your application.
• cache – An instance of Flask-Cache. This is optional, but highly recommended for performance reasons.

class flask_dance.consumer.OAuth2ConsumerBlueprint(...)

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, token_url=None, redirect_url=None, redirect_to=None, **kwargs)

Most of the constructor arguments are forwarded either to the flask.Blueprint constructor or the requests_oauthlib.OAuth2Session construtor, including **kwargs (which is forwarded to OAuth2Session). The only arguments that are specific to this class are base_url, authorization_url, token_url, login_url, authorized_url, redirect_url, and redirect_to.

Parameters:

• base_url (str, optional) – The base URL of the OAuth provider. If specified, all URLs passed to this instance will be resolved relative to this URL.
• authorization_url (str) – 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.
• token_url (str) – 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 (str, optional) – 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 (str, optional) – 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 (str, optional) – When the OAuth dance is complete, redirect the user to this URL.
• redirect_to (str, optional) – When the OAuth dance is complete, redirect the user to the URL obtained by calling url_for() with this argument. You must specify either redirect_url or redirect_to. If you specify both, redirect_url will take precedence.

session

An OAuth2Session instance that automatically loads credentials for the OAuth provider (if the user has already gone through the OAuth dance).

token_getter(func)

A decorator used to indicate the function used to retrieve a stored token from a completed OAuth dance.

token_setter(func)

A decorator used to indicate the function used to store a token from a completed OAuth dance, so that it can be retrieved later. This function will also be called when the token is refreshed.

token_deleter(func)

A decorator used to indicate the function used to delete a previously-stored OAuth token.

token

A proxy property for getting, setting, and deleting the stored OAuth token.

set_token_storage_session()

A helper method to set up the blueprint to store and retrieve OAuth tokens using the Flask session. This will overwrite any custom token accessors you’ve set up. This method is called by the constructor as a default – in general, you shouldn’t call this method yoursel.

set_token_storage_sqlalchemy(model, session, user=None, cache=None)

A helper method to set up the blueprint to store and retrieve OAuth tokens using SQLAlchemy. This will overwrite any custom token accessors you’ve set up.

Parameters:

• model – A class that represents a database table. At a minimum, it must have a token column and a provider column. If you’re using a User class, this model must also declare a user relation to that class. It is recommended, but not required, that your model inherit from flask_dance.models.OAuthMixin.
• session – A sqlalchemy.orm.session.Session object. If you’re using Flask-SQLAlchemy, this is db.session.
• user – The current logged in user, if any. This can also be a function that returns the current logged in user. This is argument is optional; if not provided, OAuth tokens will not be associated with specific users in your application.
• cache – An instance of Flask-Cache. This is optional, but highly recommended for performance reasons.

Models

class flask_dance.models.OAuthMixin

A SQLAlchemy declarative mixin with some suggested columns for a model to store OAuth tokens:

id

an integer primary key

provider

a short name to indicate which OAuth provider issued this token

created_on

an automatically generated datetime that indicates when the OAuth provider issued this token

token

a JSON field to store the actual token received from the OAuth provider