Quick Start =========== - `Basic SQLAlchemy Application <#basic-sqlalchemy-application>`_ - `Basic SQLAlchemy Application with session <#basic-sqlalchemy-application-with-session>`_ - `Basic MongoEngine Application <#basic-mongoengine-application>`_ - `Basic Peewee Application <#basic-peewee-application>`_ - `Mail Configuration <#mail-configuration>`_ - `Proxy Configuration <#proxy-configuration>`_ Basic SQLAlchemy Application ============================= SQLAlchemy Install requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: $ mkvirtualenv $ pip install flask-security flask-sqlalchemy SQLAlchemy Application ~~~~~~~~~~~~~~~~~~~~~~ The following code sample illustrates how to get started as quickly as possible using SQLAlchemy: :: from flask import Flask, render_template from flask_sqlalchemy import SQLAlchemy from flask_security import Security, SQLAlchemyUserDatastore, \ UserMixin, RoleMixin, login_required # Create app app = Flask(__name__) app.config['DEBUG'] = True app.config['SECRET_KEY'] = 'super-secret' app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite://' # Create database connection object db = SQLAlchemy(app) # Define models roles_users = db.Table('roles_users', db.Column('user_id', db.Integer(), db.ForeignKey('user.id')), db.Column('role_id', db.Integer(), db.ForeignKey('role.id'))) class Role(db.Model, RoleMixin): id = db.Column(db.Integer(), primary_key=True) name = db.Column(db.String(80), unique=True) description = db.Column(db.String(255)) class User(db.Model, UserMixin): id = db.Column(db.Integer, primary_key=True) email = db.Column(db.String(255), unique=True) password = db.Column(db.String(255)) active = db.Column(db.Boolean()) confirmed_at = db.Column(db.DateTime()) roles = db.relationship('Role', secondary=roles_users, backref=db.backref('users', lazy='dynamic')) # Setup Flask-Security user_datastore = SQLAlchemyUserDatastore(db, User, Role) security = Security(app, user_datastore) # Create a user to test with @app.before_first_request def create_user(): db.create_all() user_datastore.create_user(email='matt@nobien.net', password='password') db.session.commit() # Views @app.route('/') @login_required def home(): return render_template('index.html') if __name__ == '__main__': app.run() Basic SQLAlchemy Application with session ========================================= SQLAlchemy Install requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: $ mkvirtualenv $ pip install flask-security sqlalchemy Also, you can use the extension `Flask-SQLAlchemy-Session documentation `_. SQLAlchemy Application ~~~~~~~~~~~~~~~~~~~~~~ The following code sample illustrates how to get started as quickly as possible using `SQLAlchemy in a declarative way `_: We are gonna split the application at least in three files: app.py, database.py and models.py. You can also do the models a folder and spread your tables there. - app.py :: from flask import Flask from flask_security import Security, login_required, \ SQLAlchemySessionUserDatastore from database import db_session, init_db from models import User, Role # Create app app = Flask(__name__) app.config['DEBUG'] = True app.config['SECRET_KEY'] = 'super-secret' # Setup Flask-Security user_datastore = SQLAlchemySessionUserDatastore(db_session, User, Role) security = Security(app, user_datastore) # Create a user to test with @app.before_first_request def create_user(): init_db() user_datastore.create_user(email='matt@nobien.net', password='password') db_session.commit() # Views @app.route('/') @login_required def home(): return render('Here you go!') if __name__ == '__main__': app.run() - database.py :: from sqlalchemy import create_engine from sqlalchemy.orm import scoped_session, sessionmaker from sqlalchemy.ext.declarative import declarative_base engine = create_engine('sqlite:////tmp/test.db', \ convert_unicode=True) db_session = scoped_session(sessionmaker(autocommit=False, autoflush=False, bind=engine)) Base = declarative_base() Base.query = db_session.query_property() def init_db(): # import all modules here that might define models so that # they will be registered properly on the metadata. Otherwise # you will have to import them first before calling init_db() import models Base.metadata.create_all(bind=engine) - models.py :: from database import Base from flask_security import UserMixin, RoleMixin from sqlalchemy import create_engine from sqlalchemy.orm import relationship, backref from sqlalchemy import Boolean, DateTime, Column, Integer, \ String, ForeignKey class RolesUsers(Base): __tablename__ = 'roles_users' id = Column(Integer(), primary_key=True) user_id = Column('user_id', Integer(), ForeignKey('user.id')) role_id = Column('role_id', Integer(), ForeignKey('role.id')) class Role(Base, RoleMixin): __tablename__ = 'role' id = Column(Integer(), primary_key=True) name = Column(String(80), unique=True) description = Column(String(255)) class User(Base, UserMixin): __tablename__ = 'user' id = Column(Integer, primary_key=True) email = Column(String(255), unique=True) username = Column(String(255)) password = Column(String(255)) last_login_at = Column(DateTime()) current_login_at = Column(DateTime()) last_login_ip = Column(String(100)) current_login_ip = Column(String(100)) login_count = Column(Integer) active = Column(Boolean()) confirmed_at = Column(DateTime()) roles = relationship('Role', secondary='roles_users', backref=backref('users', lazy='dynamic')) Basic MongoEngine Application ============================== MongoEngine Install requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: $ mkvirtualenv $ pip install flask-security flask-mongoengine MongoEngine Application ~~~~~~~~~~~~~~~~~~~~~~~ The following code sample illustrates how to get started as quickly as possible using MongoEngine: :: from flask import Flask, render_template from flask_mongoengine import MongoEngine from flask_security import Security, MongoEngineUserDatastore, \ UserMixin, RoleMixin, login_required # Create app app = Flask(__name__) app.config['DEBUG'] = True app.config['SECRET_KEY'] = 'super-secret' # MongoDB Config app.config['MONGODB_DB'] = 'mydatabase' app.config['MONGODB_HOST'] = 'localhost' app.config['MONGODB_PORT'] = 27017 # Create database connection object db = MongoEngine(app) class Role(db.Document, RoleMixin): name = db.StringField(max_length=80, unique=True) description = db.StringField(max_length=255) class User(db.Document, UserMixin): email = db.StringField(max_length=255) password = db.StringField(max_length=255) active = db.BooleanField(default=True) confirmed_at = db.DateTimeField() roles = db.ListField(db.ReferenceField(Role), default=[]) # Setup Flask-Security user_datastore = MongoEngineUserDatastore(db, User, Role) security = Security(app, user_datastore) # Create a user to test with @app.before_first_request def create_user(): user_datastore.create_user(email='matt@nobien.net', password='password') # Views @app.route('/') @login_required def home(): return render_template('index.html') if __name__ == '__main__': app.run() Basic Peewee Application ======================== Peewee Install requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: $ mkvirtualenv $ pip install flask-security flask-peewee Peewee Application ~~~~~~~~~~~~~~~~~~ The following code sample illustrates how to get started as quickly as possible using Peewee: :: from flask import Flask, render_template from flask_peewee.db import Database from peewee import * from flask_security import Security, PeeweeUserDatastore, \ UserMixin, RoleMixin, login_required # Create app app = Flask(__name__) app.config['DEBUG'] = True app.config['SECRET_KEY'] = 'super-secret' app.config['DATABASE'] = { 'name': 'example.db', 'engine': 'peewee.SqliteDatabase', } # Create database connection object db = Database(app) class Role(db.Model, RoleMixin): name = CharField(unique=True) description = TextField(null=True) class User(db.Model, UserMixin): email = TextField() password = TextField() active = BooleanField(default=True) confirmed_at = DateTimeField(null=True) class UserRoles(db.Model): # Because peewee does not come with built-in many-to-many # relationships, we need this intermediary class to link # user to roles. user = ForeignKeyField(User, related_name='roles') role = ForeignKeyField(Role, related_name='users') name = property(lambda self: self.role.name) description = property(lambda self: self.role.description) # Setup Flask-Security user_datastore = PeeweeUserDatastore(db, User, Role, UserRoles) security = Security(app, user_datastore) # Create a user to test with @app.before_first_request def create_user(): for Model in (Role, User, UserRoles): Model.drop_table(fail_silently=True) Model.create_table(fail_silently=True) user_datastore.create_user(email='matt@nobien.net', password='password') # Views @app.route('/') @login_required def home(): return render_template('index.html') if __name__ == '__main__': app.run() Mail Configuration =================== Flask-Security integrates with Flask-Mail to handle all email communications between user and site, so it's important to configure Flask-Mail with your email server details so Flask-Security can talk with Flask-Mail correctly. The following code illustrates a basic setup, which could be added to the basic application code in the previous section:: # At top of file from flask_mail import Mail # After 'Create app' app.config['MAIL_SERVER'] = 'smtp.example.com' app.config['MAIL_PORT'] = 465 app.config['MAIL_USE_SSL'] = True app.config['MAIL_USERNAME'] = 'username' app.config['MAIL_PASSWORD'] = 'password' mail = Mail(app) To learn more about the various Flask-Mail settings to configure it to work with your particular email server configuration, please see the `Flask-Mail documentation `_. Proxy Configuration =================== The user tracking features need an additional configuration in HTTP proxy environment. The following code illustrates a setup with a single HTTP proxy in front of the web application:: # At top of file from werkzeug.config.fixers import ProxyFix # After 'Create app' app.wsgi_app = ProxyFix(app.wsgi_app, num_proxies=1) To learn more about the ``ProxyFix`` middleware, please see the `Werkzeug documentation `_.