| 1 |
.. module:: flask_dance.consumer.storage |
| 2 |
|
| 3 |
Token Storages |
| 4 |
============== |
| 5 |
|
| 6 |
A Flask-Dance blueprint has a token storage associated with it, |
| 7 |
which is an object that knows how to store and retrieve OAuth tokens |
| 8 |
from some kind of persistent storage. A storage is most often |
| 9 |
some kind of database, but it doesn't have to be. |
| 10 |
|
| 11 |
.. _flask-session-storage: |
| 12 |
|
| 13 |
Flask Session |
| 14 |
------------- |
| 15 |
|
| 16 |
The default token storage uses the |
| 17 |
:ref:`Flask session <flask:sessions>` to store OAuth tokens, which is simple |
| 18 |
and requires no configuration. However, when the user closes |
| 19 |
their browser, their OAuth token will be lost, so its not a good choice for |
| 20 |
production usage. |
| 21 |
|
| 22 |
This is a great option for hobby projects, and for a "proof of concept" |
| 23 |
to show that an idea is viable. |
| 24 |
|
| 25 |
.. _sqlalchemy-storage: |
| 26 |
|
| 27 |
SQLAlchemy |
| 28 |
---------- |
| 29 |
|
| 30 |
SQLAlchemy is the "standard" ORM_ for Flask applications, and Flask-Dance |
| 31 |
has great support for it. First, define your database model with a ``token`` |
| 32 |
column and a ``provider`` column. Flask-Dance includes a |
| 33 |
:class:`~flask_dance.consumer.storage.sqla.OAuthConsumerMixin` |
| 34 |
class to make this easier:: |
| 35 |
|
| 36 |
from flask_sqlalchemy import SQLAlchemy |
| 37 |
from flask_dance.consumer.storage.sqla import OAuthConsumerMixin |
| 38 |
|
| 39 |
db = SQLAlchemy() |
| 40 |
class OAuth(OAuthConsumerMixin, db.Model): |
| 41 |
pass |
| 42 |
|
| 43 |
Next, create an instance of the SQLAlchemy storage |
| 44 |
and assign it to your blueprint:: |
| 45 |
|
| 46 |
from flask_dance.consumer.storage.sqla import SQLAlchemyStorage |
| 47 |
|
| 48 |
blueprint.storage = SQLAlchemyStorage(OAuth, db.session) |
| 49 |
|
| 50 |
And that's all you need -- if you don't have user accounts in your application. |
| 51 |
If you do, it's slightly more complicated:: |
| 52 |
|
| 53 |
from flask_sqlalchemy import SQLAlchemy |
| 54 |
from flask_login import current_user |
| 55 |
from flask_dance.consumer.storage.sqla import OAuthConsumerMixin, SQLAlchemyStorage |
| 56 |
|
| 57 |
db = SQLAlchemy() |
| 58 |
|
| 59 |
class User(db.Model): |
| 60 |
id = db.Column(db.Integer, primary_key=True) |
| 61 |
# ... other columns as needed |
| 62 |
|
| 63 |
class OAuth(OAuthConsumerMixin, db.Model): |
| 64 |
user_id = db.Column(db.Integer, db.ForeignKey(User.id)) |
| 65 |
user = db.relationship(User) |
| 66 |
|
| 67 |
blueprint.storage = SQLAlchemyStorage(OAuth, db.session, user=current_user) |
| 68 |
|
| 69 |
There are two things to notice here. One, the model that you use for storing |
| 70 |
OAuth tokens must have a :attr:`user` relationship to the user |
| 71 |
that it is associated with. |
| 72 |
Two, you must pass a reference to the currently logged-in user (if any) |
| 73 |
to :class:`~flask_dance.consumer.storage.sqla.SQLAlchemyStorage`. |
| 74 |
If you're using `Flask-Login`_, the :attr:`current_user` proxy works great, |
| 75 |
but you could instead pass a function that returns the current |
| 76 |
user, if you want. |
| 77 |
|
| 78 |
You also probably want to use a caching system for your database, so that it |
| 79 |
is more performant under heavy load. The SQLAlchemy token storage |
| 80 |
also integrates with `Flask-Caching`_ if you pass an instance of |
| 81 |
Flask-Caching to the storage, like this:: |
| 82 |
|
| 83 |
from flask import Flask |
| 84 |
from flask_caching import Cache |
| 85 |
|
| 86 |
app = Flask(__name__) |
| 87 |
cache = Cache(app) |
| 88 |
|
| 89 |
# setup Flask-Dance with SQLAlchemy models... |
| 90 |
|
| 91 |
blueprint.storage = SQLAlchemyStorage(OAuth, db.session, cache=cache) |
| 92 |
|
| 93 |
|
| 94 |
.. _SQLAlchemy: http://www.sqlalchemy.org/ |
| 95 |
.. _Flask-Login: https://flask-login.readthedocs.io/ |
| 96 |
.. _Flask-Caching: https://flask-caching.readthedocs.io/ |
| 97 |
|
| 98 |
Custom |
| 99 |
------ |
| 100 |
|
| 101 |
Of course, you don't have to use `SQLAlchemy`_, you're free to use whatever |
| 102 |
storage system you want. Writing a custom token storage is easy: |
| 103 |
just subclass :class:`flask_dance.consumer.storage.BaseStorage` and |
| 104 |
override the :meth:`get`, :meth:`set`, and :meth:`delete` methods. |
| 105 |
For example, here's a storage that uses a file on disk:: |
| 106 |
|
| 107 |
import os |
| 108 |
import os.path |
| 109 |
import json |
| 110 |
from flask_dance.consumer.storage import BaseStorage |
| 111 |
|
| 112 |
class FileStorage(BaseStorage): |
| 113 |
def __init__(self, filepath): |
| 114 |
super(FileStorage, self).__init__() |
| 115 |
self.filepath = filepath |
| 116 |
|
| 117 |
def get(self, blueprint): |
| 118 |
if not os.path.exists(self.filepath): |
| 119 |
return None |
| 120 |
with open(self.filepath) as f: |
| 121 |
return json.load(f) |
| 122 |
|
| 123 |
def set(self, blueprint, token): |
| 124 |
with open(self.filepath, "w") as f: |
| 125 |
json.dump(token, f) |
| 126 |
|
| 127 |
def delete(self, blueprint): |
| 128 |
os.remove(self.filepath) |
| 129 |
|
| 130 |
Then, just create an instance of your storage and assign it to the |
| 131 |
:attr:`storage` attribute of your blueprint, and Flask-Dance will use it. |
| 132 |
|
| 133 |
.. _ORM: https://docs.python.org/3.4/howto/webservers.html#data-persistence |