diff --git a/README.rst b/README.rst index caf3b42..d6a46a1 100644 --- a/README.rst +++ b/README.rst @@ -3,8 +3,7 @@ Flask-Security .. image:: https://secure.travis-ci.org/mattupstate/flask-security.png?branch=develop -Flask-Security is a Flask extension that aims to add quick and simple security -to your Flask applications. +Flask-Security quickly adds security features to your Flask application. Resources --------- diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..ce4d0d8 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,78 @@ +API +=== + +Core +---- +.. autoclass:: flask_security.core.Security + :members: + +.. data:: flask_security.core.current_user + + A proxy for the current user. + + +Protecting Views +---------------- +.. autofunction:: flask_security.decorators.login_required + +.. autofunction:: flask_security.decorators.roles_required + +.. autofunction:: flask_security.decorators.roles_accepted + +.. autofunction:: flask_security.decorators.http_auth_required + +.. autofunction:: flask_security.decorators.auth_token_required + + +User Object Helpers +------------------- +.. autoclass:: flask_security.core.UserMixin + :members: + +.. autoclass:: flask_security.core.RoleMixin + :members: + +.. autoclass:: flask_security.core.AnonymousUser + :members: + + +Datastores +---------- +.. autoclass:: flask_security.datastore.UserDatastore + :members: + +.. autoclass:: flask_security.datastore.SQLAlchemyUserDatastore + :members: + :inherited-members: + +.. autoclass:: flask_security.datastore.MongoEngineUserDatastore + :members: + :inherited-members: + + +Exceptions +---------- +.. autoexception:: flask_security.exceptions.BadCredentialsError + +.. autoexception:: flask_security.exceptions.AuthenticationError + +.. autoexception:: flask_security.exceptions.UserNotFoundError + +.. autoexception:: flask_security.exceptions.RoleNotFoundError + +.. autoexception:: flask_security.exceptions.UserDatastoreError + +.. autoexception:: flask_security.exceptions.UserCreationError + +.. autoexception:: flask_security.exceptions.RoleCreationError + +.. autoexception:: flask_security.exceptions.ConfirmationError + +.. autoexception:: flask_security.exceptions.ResetPasswordError + + +Signals +------- +See the documentation for the signals provided by the Flask-Login and +Flask-Principal extensions. Flask-Security does not provide any additional +signals. \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 6bc7776..64f49a5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -92,14 +92,14 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. Major themes that come with # Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = 'flask_small' +html_theme = 'flask' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - 'github_fork': 'mattupstate/flask-security', - 'index_logo': False + #'github_fork': 'mattupstate/flask-security', + #'index_logo': False } # Add any paths that contain custom themes here, relative to this directory. diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 0000000..24f4e17 --- /dev/null +++ b/docs/configuration.rst @@ -0,0 +1,63 @@ +Configuration +============= + +Flask-Security configuration options. + +* :attr:`SECURITY_URL_PREFIX`: Specifies the URL prefix for the Security + blueprint. +* :attr:`SECURITY_FLASH_MESSAGES`: Specifies wether or not to flash messages + during security mechanisms. +* :attr:`SECURITY_PASSWORD_HASH`: Specifies the encryption method to use. e.g.: + plaintext, bcrypt, etc. +* :attr:`SECURITY_AUTH_URL`: Specifies the URL to to handle authentication. +* :attr:`SECURITY_LOGOUT_URL`: Specifies the URL to process a logout request. +* :attr:`SECURITY_REGISTER_URL`: Specifies the URL for user registrations. +* :attr:`SECURITY_RESET_URL`: Specifies the URL for password resets. +* :attr:`SECURITY_CONFIRM_URL`: Specifies the URL for account confirmations. +* :attr:`SECURITY_LOGIN_VIEW`: Specifies the URL to redirect to when + authentication is required. +* :attr:`SECURITY_CONFIRM_ERROR_VIEW`: Specifies the URL to redirect to when + an confirmation error occurs. +* :attr:`SECURITY_POST_LOGIN_VIEW`: Specifies the URL to redirect to after a + user logins in. +* :attr:`SECURITY_POST_LOGOUT_VIEW`: Specifies the URL to redirect to after a + user logs out. +* :attr:`SECURITY_POST_FORGOT_VIEW`: Specifies the URL to redirect to after a + user requests password reset instructions. +* :attr:`SECURITY_RESET_PASSWORD_ERROR_VIEW`: Specifies the URL to redirect to + after an error occurs during the password reset process. +* :attr:`SECURITY_POST_REGISTER_VIEW`: Specifies the URL to redirect to after a + user successfully registers. +* :attr:`SECURITY_POST_CONFIRM_VIEW`: Specifies the URL to redirect to after a + user successfully confirms their account. +* :attr:`SECURITY_UNAUTHORIZED_VIEW`: Specifies the URL to redirect to when a + user attempts to access a view they don't have permission to view. +* :attr:`SECURITY_DEFAULT_ROLES`: The default roles any new users should have. +* :attr:`SECURITY_CONFIRMABLE`: Enables confirmation features. Defaults to + `False`. +* :attr:`SECURITY_REGISTERABLE`: Enables user registration features. Defaults to + `False`. +* :attr:`SECURITY_RECOVERABLE`: Enables password reset/recovery features. + Defaults to `False`. +* :attr:`SECURITY_TRACKABLE`: Enables login tracking features. Defaults to + `False`. +* :attr:`SECURITY_CONFIRM_EMAIL_WITHIN`: Specifies the amount of time a user + has to confirm their account/email. Default is `5 days`. +* :attr:`SECURITY_RESET_PASSWORD_WITHIN`: Specifies the amount of time a user + has to reset their password. Default is `5 days`. +* :attr:`SECURITY_LOGIN_WITHOUT_CONFIRMATION`: Specifies if users can login + without first confirming their accounts. Defaults to `False` +* :attr:`SECURITY_EMAIL_SENDER`: Specifies the email address to send emails on + behalf of. Defaults to `no-reply@localhost`. +* :attr:`SECURITY_TOKEN_AUTHENTICATION_KEY`: Specifies the query string argument + to use during token authentication. Defaults to `auth_token`. +* :attr:`SECURITY_TOKEN_AUTHENTICATION_HEADER`: Specifies the header name to use + during token authentication. Defaults to `X-Auth-Token`. +* :attr:`SECURITY_CONFIRM_SALT`: Specifies the salt value to use for account + confirmation tokens. Defaults to `confirm-salt`. +* :attr:`SECURITY_RESET_SALT`: Specifies the salt value to use for password + reset tokens. Defaults to `reset-salt`. +* :attr:`SECURITY_AUTH_SALT`: Specifies the salt value to use for token based + authentication tokens. Defaults to `auth-salt`. +* :attr:`SECURITY_DEFAULT_HTTP_AUTH_REALM`: Specifies the default basic HTTP + authentication realm. Defaults to `Login Required`. \ No newline at end of file diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc new file mode 100644 index 0000000..f0431f1 --- /dev/null +++ b/docs/contents.rst.inc @@ -0,0 +1,13 @@ +Documentation +------------- + +.. toctree:: + :maxdepth: 1 + + overview + features + configuration + quickstart + models + api + changelog \ No newline at end of file diff --git a/docs/features.rst b/docs/features.rst new file mode 100644 index 0000000..aa3b64e --- /dev/null +++ b/docs/features.rst @@ -0,0 +1,130 @@ +Features +======== + +Flask-Security allows you to quickly add common security mechanisms to your +Flask application. They include: + + +.. session-based-auth: + +Session Based Authentication +---------------------------- + +Session based authentication is fulfilled entirely by the `Flask-Login`_ +extension. Flask-Security handles the configuration of Flask-Login automatically +based on a few of its own configuration values and uses Flask-Login's +`alternative token`_ feature for remembering users when their session has +expired. + + +.. role-management: + +Role/Identity Based Access +-------------------------- + +Flask-Security implements very basic role management out of the box. This means +that you can associate a high level role or multiple roles to any user. For +instance, you may assign roles such as `Admin`, `Editor`, `SuperUser`, or a +combination of said roles to a user. Access control is based on the role name +and all roles should be uniquely named. This feature is implemented using the +`Flask-Principal`_ extension. If you'd like to implement more granular access +control you can refer to the Flask-Princpal `documentation on this topic`_. + + +.. password-encryption: + +Password Encryption +------------------- + +Password encryption is enabled with `passlib`_. Passwords are stored in plain +text by default but you can easily configure the encryption algorithm and salt +value in your application configuration. You should **always use an encryption +algorithm** in your production environment. Bcrypt is a popular algorithm as +of writing this documentation. Bear in mind passlib does not assume which +algorithm you will choose and may require additional libraries to be installed. + + +.. basic-http-auth: + +Basic HTTP Authentication +------------------------- + +Basic HTTP authentication is achievable using a simple view method decorator. +This feature expects the incoming authentication information to identify a user +in the system. This means that the username must be equal to their email address. + + +.. token-authentication: + +Token Authentication +-------------------- + +Token based authentication is enabled by retrieving the user auth token by +performing an HTTP POST with the authentication details as JSON data against the +authentication endpoint. A successful call to this endpoint will return the +user's ID and their authentication token. This token can be used in subsequent +requests to protected resources. The auth token is supplied in the request +through an HTTP header or query string parameter. By default the HTTP header +name is `X-Auth-Token` and the default query string parameter name is +`auth_token`. Authentication tokens are generated using the user's password. +Thus if the user changes his or her password their existing authentication token +will become invalid. A new token will need to be retrieved using the user's new +password. + + +.. email-confirmation: + +Email Confirmation +------------------ + +If desired you can require that new users confirm their email address. +Flask-Security will send an email message to any new users with an confirmation +link. Upon navigating to the confirmation link, the user will be automatically +logged in. There is also view for resending a confirmation link to a given email +if the user happens to try to use an expired token or has lost the previous +email. Confirmation links can be configured to expire after a specified amount +of time. + +.. password-recovery: + +Password Reset/Recovery +----------------------- + +Password reset and recovery is available for when a user forgets his or her +password. Flask-Security sends an email to the user with a link to a view which +they can reset their password. Once the password is reset they are automatically +logged in and can use the new password from then on. Password reset links can +be configured to expire after a specified amount of time. + + +.. user-registration: + +User Registration +----------------- + +Flask-Security comes packaged with a basic user registration view. This view is +very simple and new users need only supply an email address and their password. +This view can be overrided if your registration process requires more fields. + + +.. login-tracking: + +Login Tracking +-------------- + +Flask-Security can, if configured, keep track of basic login events and +statistics. They include: + +* Last login date +* Current login date +* Last login IP address +* Current login IP address +* Total login count + + + +.. _Flask-Login: http://packages.python.org/Flask-Login/ +.. _alternative token: http://packages.python.org/Flask-Login/#alternative-tokens +.. _Flask-Principal: http://packages.python.org/Flask-Principal/ +.. _documentation on this topic: http://packages.python.org/Flask-Principal/#granular-resource-protection +.. _passlib: http://packages.python.org/passlib/ diff --git a/docs/index.rst b/docs/index.rst index 6ef0253..9274798 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,369 +1,9 @@ -.. include:: ../README.rst +Flask-Security +============== +.. image:: https://secure.travis-ci.org/mattupstate/flask-security.png?branch=develop -Contents -========= -* :ref:`overview` -* :ref:`installation` -* :ref:`quick-start` -* :ref:`models` -* :ref:`flask-script-commands` -* :ref:`api` -* :doc:`Changelog ` +Flask-Security quickly adds security features to your Flask application. -.. _overview: - -Overview -======== - -Flask-Security allows you to quickly add common user and security mechanisms to -your Flask application. They include: - -1. Session based authentication -2. Role management -3. Password encryption -4. Basic HTTP authentication -5. Token based authentication -6. Token based account activation (optional) -7. Token based password recovery/resetting (optional) -8. User registration (optional) -9. Login tracking (optional) -10. Basic user management commands - -Many of these features are made possible by integrating various Flask extensions -and libraries. They include: - -1. `Flask-Login `_ -2. `Flask-Mail `_ -3. `Flask-Principal `_ -4. `Flask-Script `_ -5. `Flask-WTF `_ -6. `itsdangerous `_ -7. `passlib `_ - -Additionally, it assumes you'll be using a common library for your database -connections and model definitions. Flask-Security thus supports SQLAlchemy and -MongoEngine out of the box and additional libraries can easily be supported. - - -.. _installation: - -Installation -============ - -First, install Flask-Security:: - - $ mkvirtualenv app-name - $ pip install Flask-Security - -Then install your datastore requirement. - -**SQLAlchemy**:: - - $ pip install flask-sqlalchemy - -**MongoEngine**:: - - $ pip install flask-mongoengine - -And lastly install any password encryption library that you may need. For -example:: - - $ pip install py-bcrypt - - -.. _quick-start: - -Quick Start Example -=================== - -The following code sample illustrates how to get started as quickly as possible -using SQLAlchemy.:: - - from flask import Flask, render_template, url_for - from flask.ext.sqlalchemy import SQLAlchemy - from flask.ext.security import Security, UserMixin, RoleMixin, \ - login_required - from flask.ext.security.datastore import SQLAlchemyUserDatastore - from flask.ext.security.forms import LoginForm - - app = Flask(__name__) - app.debug = True - app.config['SECRET_KEY'] = 'secret' - app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///:memory:' - app.config['SECURITY_POST_LOGIN_VIEW'] = '/protected' - - db = SQLAlchemy(app) - - 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()) - roles = db.relationship('Role', secondary=roles_users, - backref=db.backref('users', lazy='dynamic')) - - datastore = SQLAlchemyUserDatastore(db, User, Role) - - Security(app, datastore) - - @app.before_first_request - def add_user(): - db.create_all() - datastore.create_user(email='matt@matt.com', - password='password') - - @app.route('/') - @app.route('/login') - def login(): - return render_template('security/logins/new.html', - login_form=LoginForm()) - - @app.route('/protected') - @login_required - def protected(): - return """

You are logged in

-

Log out""" % ( - url_for('flask_security.logout')) - - if __name__ == '__main__': - app.run() - - -.. _models: - -Models -====== - -Flask-Security assumes you'll be using libraries such as SQLAlchemy or -MongoEngine to define a data model that includes a `User` and `Role` model. The -fields on your models must follow a particular convention depending on the -functionality your app requires. Aside from this, you're free to add any -additional fields to your model(s) if you want. At the bear minimum your `User` -and `Role` model should include the following fields: - -**User** - -* id -* email -* password -* active - -**Role** - -* id -* name -* description - - -Additional Functionality ------------------------- - -Depending on the application's configuration, additional fields may need to be -added to your `User` model. - -Confirmable -^^^^^^^^^^^ - -If you enable account confirmation by setting your application's -`SECURITY_CONFIRMABLE` configuration value to `True` your `User` model will -require the following additional field: - -* confirmed_at - -Trackable -^^^^^^^^^ - -If you enable user tracking by setting your application's `SECURITY_TRACKABLE` -configuration value to `True` your `User` model will require the following -additional fields: - -* last_login_at -* current_login_at -* last_login_ip -* current_login_ip -* login_count - - -.. _flask-script-commands: - -Flask-Script Commands ---------------------- -Flask-Security comes packed with a few Flask-Script commands. They are: - -* :class:`flask_security.script.CreateUserCommand` -* :class:`flask_security.script.CreateRoleCommand` -* :class:`flask_security.script.AddRoleCommand` -* :class:`flask_security.script.RemoveRoleCommand` -* :class:`flask_security.script.DeactivateUserCommand` -* :class:`flask_security.script.ActivateUserCommand` -* :class:`flask_security.script.ActivateUserCommand` -* :class:`flask_security.script.GenerateBlueprintCommand` - -Register these on your script manager for pure convenience. - - -.. _configuration: - -Configuration Values -==================== - -* :attr:`SECURITY_URL_PREFIX`: Specifies the URL prefix for the Security - blueprint. -* :attr:`SECURITY_FLASH_MESSAGES`: Specifies wether or not to flash messages - during security mechanisms. -* :attr:`SECURITY_PASSWORD_HASH`: Specifies the encryption method to use. e.g.: - plaintext, bcrypt, etc. -* :attr:`SECURITY_AUTH_URL`: Specifies the URL to to handle authentication. -* :attr:`SECURITY_LOGOUT_URL`: Specifies the URL to process a logout request. -* :attr:`SECURITY_REGISTER_URL`: Specifies the URL for user registrations. -* :attr:`SECURITY_RESET_URL`: Specifies the URL for password resets. -* :attr:`SECURITY_CONFIRM_URL`: Specifies the URL for account confirmations. -* :attr:`SECURITY_LOGIN_VIEW`: Specifies the URL to redirect to when - authentication is required. -* :attr:`SECURITY_CONFIRM_ERROR_VIEW`: Specifies the URL to redirect to when - an confirmation error occurs. -* :attr:`SECURITY_POST_LOGIN_VIEW`: Specifies the URL to redirect to after a - user logins in. -* :attr:`SECURITY_POST_LOGOUT_VIEW`: Specifies the URL to redirect to after a - user logs out. -* :attr:`SECURITY_POST_FORGOT_VIEW`: Specifies the URL to redirect to after a - user requests password reset instructions. -* :attr:`SECURITY_RESET_PASSWORD_ERROR_VIEW`: Specifies the URL to redirect to - after an error occurs during the password reset process. -* :attr:`SECURITY_POST_REGISTER_VIEW`: Specifies the URL to redirect to after a - user successfully registers. -* :attr:`SECURITY_POST_CONFIRM_VIEW`: Specifies the URL to redirect to after a - user successfully confirms their account. -* :attr:`SECURITY_UNAUTHORIZED_VIEW`: Specifies the URL to redirect to when a - user attempts to access a view they don't have permission to view. -* :attr:`SECURITY_DEFAULT_ROLES`: The default roles any new users should have. -* :attr:`SECURITY_CONFIRMABLE`: Enables confirmation features. Defaults to - `False`. -* :attr:`SECURITY_REGISTERABLE`: Enables user registration features. Defaults to - `False`. -* :attr:`SECURITY_RECOVERABLE`: Enables password reset/recovery features. - Defaults to `False`. -* :attr:`SECURITY_TRACKABLE`: Enables login tracking features. Defaults to - `False`. -* :attr:`SECURITY_CONFIRM_EMAIL_WITHIN`: Specifies the amount of time a user - has to confirm their account/email. Default is `5 days`. -* :attr:`SECURITY_RESET_PASSWORD_WITHIN`: Specifies the amount of time a user - has to reset their password. Default is `5 days`. -* :attr:`SECURITY_LOGIN_WITHOUT_CONFIRMATION`: Specifies if users can login - without first confirming their accounts. Defaults to `False` -* :attr:`SECURITY_EMAIL_SENDER`: Specifies the email address to send emails on - behalf of. Defaults to `no-reply@localhost`. -* :attr:`SECURITY_TOKEN_AUTHENTICATION_KEY`: Specifies the query string argument - to use during token authentication. Defaults to `auth_token`. -* :attr:`SECURITY_TOKEN_AUTHENTICATION_HEADER`: Specifies the header name to use - during token authentication. Defaults to `X-Auth-Token`. -* :attr:`SECURITY_CONFIRM_SALT`: Specifies the salt value to use for account - confirmation tokens. Defaults to `confirm-salt`. -* :attr:`SECURITY_RESET_SALT`: Specifies the salt value to use for password - reset tokens. Defaults to `reset-salt`. -* :attr:`SECURITY_AUTH_SALT`: Specifies the salt value to use for token based - authentication tokens. Defaults to `auth-salt`. -* :attr:`SECURITY_DEFAULT_HTTP_AUTH_REALM`: Specifies the default basic HTTP - authentication realm. Defaults to `Login Required`. - - -.. _api: - -API -=== - -.. autoclass:: flask_security.core.Security - :members: - -.. data:: flask_security.core.current_user - - A proxy for the current user. - - -Protecting Views ----------------- -.. autofunction:: flask_security.decorators.login_required - -.. autofunction:: flask_security.decorators.roles_required - -.. autofunction:: flask_security.decorators.roles_accepted - -.. autofunction:: flask_security.decorators.http_auth_required - -.. autofunction:: flask_security.decorators.auth_token_required - - -User Object Helpers -------------------- -.. autoclass:: flask_security.core.UserMixin - :members: - -.. autoclass:: flask_security.core.RoleMixin - :members: - -.. autoclass:: flask_security.core.AnonymousUser - :members: - - -Datastores ----------- -.. autoclass:: flask_security.datastore.UserDatastore - :members: - -.. autoclass:: flask_security.datastore.SQLAlchemyUserDatastore - :members: - :inherited-members: - -.. autoclass:: flask_security.datastore.MongoEngineUserDatastore - :members: - :inherited-members: - - -Exceptions ----------- -.. autoexception:: flask_security.exceptions.BadCredentialsError - -.. autoexception:: flask_security.exceptions.AuthenticationError - -.. autoexception:: flask_security.exceptions.UserNotFoundError - -.. autoexception:: flask_security.exceptions.RoleNotFoundError - -.. autoexception:: flask_security.exceptions.UserIdNotFoundError - -.. autoexception:: flask_security.exceptions.UserDatastoreError - -.. autoexception:: flask_security.exceptions.UserCreationError - -.. autoexception:: flask_security.exceptions.RoleCreationError - -.. autoexception:: flask_security.exceptions.ConfirmationError - -.. autoexception:: flask_security.exceptions.ResetPasswordError - - -Signals -------- -See the documentation for the signals provided by the Flask-Login and -Flask-Principal extensions. Flask-Security does not provide any additional -signals. - - -Changelog -========= - -.. toctree:: - :maxdepth: 2 - - changelog \ No newline at end of file +.. include:: contents.rst.inc \ No newline at end of file diff --git a/docs/models.rst b/docs/models.rst new file mode 100644 index 0000000..4119c01 --- /dev/null +++ b/docs/models.rst @@ -0,0 +1,51 @@ +Models +====== + +Flask-Security assumes you'll be using libraries such as SQLAlchemy or +MongoEngine to define a data model that includes a `User` and `Role` model. The +fields on your models must follow a particular convention depending on the +functionality your app requires. Aside from this, you're free to add any +additional fields to your model(s) if you want. At the bear minimum your `User` +and `Role` model should include the following fields: + +**User** + +* id +* email +* password +* active + +**Role** + +* id +* name +* description + + +Additional Functionality +------------------------ + +Depending on the application's configuration, additional fields may need to be +added to your `User` model. + +Confirmable +^^^^^^^^^^^ + +If you enable account confirmation by setting your application's +`SECURITY_CONFIRMABLE` configuration value to `True` your `User` model will +require the following additional field: + +* confirmed_at + +Trackable +^^^^^^^^^ + +If you enable user tracking by setting your application's `SECURITY_TRACKABLE` +configuration value to `True` your `User` model will require the following +additional fields: + +* last_login_at +* current_login_at +* last_login_ip +* current_login_ip +* login_count \ No newline at end of file diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..571a9af --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,33 @@ +Overview +======== + +Flask-Security allows you to quickly add common security mechanisms to your +Flask application. They include: + +1. Session based authentication +2. Role management +3. Password encryption +4. Basic HTTP authentication +5. Token based authentication +6. Token based account activation (optional) +7. Token based password recovery/resetting (optional) +8. User registration (optional) +9. Login tracking (optional) + +Many of these features are made possible by integrating various Flask extensions +and libraries. They include: + +1. `Flask-Login `_ +2. `Flask-Mail `_ +3. `Flask-Principal `_ +4. `Flask-Script `_ +5. `Flask-WTF `_ +6. `itsdangerous `_ +7. `passlib `_ + +Additionally, it assumes you'll be using a common library for your database +connections and model definitions. Flask-Security supports the following Flask +extensions out of the box for data persistance: + +1. `Flask-SQLAlchemy `_ +2. `Flask-MongoEngine `_ \ No newline at end of file diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..1aed990 --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,85 @@ +Quick Start +=========== + + +Installation +------------ + +First, install Flask-Security:: + + $ mkvirtualenv + $ pip install flask-security + +Then install your datastore requirement. + +**SQLAlchemy**:: + + $ pip install flask-sqlalchemy + +**MongoEngine**:: + + $ pip install flask-mongoengine + +And lastly install any password encryption library that you may need. For +example:: + + $ pip install py-bcrypt + + +Application Code +---------------- + +The following code sample illustrates how to get started as quickly as possible +using SQLAlchemy.:: + + from flask import Flask, render_template + from flask.ext.sqlalchemy import SQLAlchemy + from flask.ext.security import Security, SQLAlchemyUserDatastore, \ + UserMixin, RoleMixin + + # 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('/') + def home(): + return render_template('index.html') + + if __name__ == '__main__': + app.run()