Simple security for Flask applications combining Flask-Login, Flask-Principal, Flask-WTF, passlib, and your choice of datastore. Currently SQLAlchemy via Flask-SQLAlchemy and MongoEngine via Flask-MongoEngine are supported out of the box. You will need to install the necessary Flask extensions that you'll be using. Additionally, you may need to install an encryption library such as py-bcrypt to support bcrypt passwords.
Flask-Security does a few things that Flask-Login and Flask-Principal don't provide out of the box. They are:
- Setting up login and logout endpoints
- Authenticating users based on username or email
- Limiting access based on user 'roles'
- User and role creation
- Password encryption
That being said, you can still hook into things such as the Flask-Login and Flask-Principal signals if need be.
First, install Flask-Security:
$ mkvirtualenv app-name
$ pip install https://github.com/mattupstate/flask-security/tarball/master
Then install your datastore requirement.
SQLAlchemy:
$ pip install Flask-SQLAlchemy
MongoEngine:
$ pip install https://github.com/sbook/flask-mongoengine/tarball/master
Beyond this, the best place to get started at the moment is to look at the example application(s) and corresponding tests. The example apps are currently used to test Flask-Security as well so they are solid examples of most, if not all, features. Configuration options are illustrated in the tests as well. To run the example run do the following:
$ mkvirtualenv flask-security
$ git clone git://github.com/mattupstate/flask-security.git
$ cd flask-security
$ pip install Flask Flask-Login Flask-Principal Flask-SQLALchemy passlib
$ pip install https://github.com/sbook/flask-mongoengine/tarball/master
$ python example/app.py
If you don't want to checkout the example quite yet, here are some hypothetical examples to give you a sense of how Flask-Security works:
from flask import Flask
from flask.ext.security import Security
from flask.ext.security.datastore.sqlalchemy import SQLAlchemyDatastore
from flask.ext.sqlalchemy import SQLAlchemy
app = Flask(__name__)
app.config['SECRET_KEY'] = 'something'
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///:memory:'
db = SQLALchemy(app)
Security(app, SQLAlchemyDatastore(db))
from flask import render_template
from flask.ext.security import login_required
… application setup …
@app.route('/profile')
@login_required
def profile():
return render_template('profile.html')
from flask import render_template
from flask.ext.security import roles_required
… application setup …
@app.route('/admin')
@roles_required('admin')
def admin():
return render_template('admin/index.html')
from flask import render_template
from flask.ext.security import roles_accepted
… application setup …
@app.route('/admin')
@roles_accepted('admin', 'editor', 'author')
def admin():
return render_template('admin/index.html')
{% if current_user.has_role('admin') %}
<a href="{{ url_for('admin.index') }}">Admin Panel</a>
{$ endif %}
Flask-Security comes packed with a few Flask-Script commands. They are:
flask.ext.security.script.CreateUserCommandflask.ext.security.script.AddRoleCommandflask.ext.security.script.RemoveRoleCommandflask.ext.security.script.DeactivateUserCommandflask.ext.security.script.ActivateUserCommand
Register these on your script manager for pure convenience.
Feel free to fork and contribute. If you decided to do so, just be sure to include relevant tests that you feel are necessary. To run the tests, please provide instructions for any requirements. For instance, if you write a new datastore implementation, please provide instructions on how best to setup a connection when testing.
If you plan on running all the provided tests you'll need a local installation of MongoDB running on the standard port 27017 without username/password protection.