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, session_class=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, redirect_to, and session_class.

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. If you do not specify either redirect_url or redirect_to, the user will be redirected to the root path (/).
• session_class (class, optional) – The class to use for creating a Requests session. Defaults to OAuth1Session.

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 yourself.

set_token_storage_sqlalchemy(model, session, user=None, user_id=None, anon_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.OAuthConsumerMixin.
• 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 argument is optional; if not provided, OAuth tokens will not be associated with specific users in your application. If you’re using Flask-Login, this is current_user.
• user_id – The ID of the current logged in user, if any. This argument is optional, and is used in the same way as the user argument. You do not need to specify both.
• anon_user – A class that specifies an anonymous user, as opposed to an actual logged-in user. This defaults to flask_login.AnonymousUserMixin if Flask-Login is installed.
• 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, authorization_url_params=None, token_url=None, token_url_params=None, redirect_url=None, redirect_to=None, session_class=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, redirect_to, and session_class.

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.
• authorization_url_params (dict, optional) – 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 (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.

• token_url_params (dict, optional) – 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 (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. If you do not specify either redirect_url or redirect_to, the user will be redirected to the root path (/).
• session_class (class, optional) – The class to use for creating a Requests session. Defaults to OAuth2Session.

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 yourself.

set_token_storage_sqlalchemy(model, session, user=None, user_id=None, anon_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.OAuthConsumerMixin.
• 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 argument is optional; if not provided, OAuth tokens will not be associated with specific users in your application. If you’re using Flask-Login, this is current_user.
• user_id – The ID of the current logged in user, if any. This argument is optional, and is used in the same way as the user argument. You do not need to specify both.
• anon_user – A class that specifies an anonymous user, as opposed to an actual logged-in user. This defaults to flask_login.AnonymousUserMixin if Flask-Login is installed.
• cache – An instance of Flask-Cache. This is optional, but highly recommended for performance reasons.

Models

class flask_dance.models.OAuthConsumerMixin

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_at

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