pallets-eco · TillerBurr · Jun 1, 2016 · May 7, 2019 · May 7, 2019 · May 8, 2019
diff --git a/.gitignore b/.gitignore
@@ -28,6 +28,7 @@ pip-log.txt
 
 #Virtualenv
 env/
+.venv/
 
 #Editor temporaries
 *~
@@ -47,3 +48,6 @@ Session.vim
 
 # Pycharm files
 .idea/
+
+# VScode
+.vscode/
diff --git a/.travis.yml b/.travis.yml
@@ -3,15 +3,19 @@ notifications:
 
 language: python
 
+dist: xenial
+
 python:
   - "2.7"
   - "3.5"
   - "3.6"
-  - "pypy"
+  - "3.7"
+  - "pypy3.5-6.0"
 
 addons:
   apt:
     packages:
+      - gettext
       - libenchant-dev
       - aspell-en
       - aspell-da
@@ -24,7 +28,7 @@ addons:
 
 matrix:
   allow_failures:
-    - python: pypy
+    - python: pypy3.5-6.0
 
 sudo: false
 
@@ -45,7 +49,7 @@ before_install:
   - "requirements-builder -e all --level=min setup.py > .travis-lowest-requirements.txt"
   - "requirements-builder -e all --level=pypi setup.py > .travis-release-requirements.txt"
   - |
-      if [ "$TRAVIS_PYTHON_VERSION" = "pypy" ]; then
+      if [ "$TRAVIS_PYTHON_VERSION" = "pypy3.5-6.0" ]; then
         export PYENV_ROOT="$HOME/.pyenv"
         if [ -f "$PYENV_ROOT/bin/pyenv" ]; then
           cd "$PYENV_ROOT" && git pull

diff --git a/AUTHORS b/AUTHORS
@@ -39,3 +39,6 @@ Tristan Escalada
 Vadim Kotov
 Walt Askew
 John Paraskevopoulos
+Gal Stainfeld
+Ivan Piskunov
+Tyler Baur
diff --git a/docs/api.rst b/docs/api.rst
@@ -81,6 +81,20 @@ Utils
 
 .. autofunction:: flask_security.utils.get_token_status
 
+.. autoclass:: SmsSenderBaseClass
+  ..method:: init(self)
+  ..method:: send_sms(self, from_number, to_number, msg)
+
+.. autoclass:: DummySmsSender
+  ..method:: send_sms(self, from_number, to_number, msg)
+
+.. autoclass:: SmsSenderFactory
+  :members: senders
+
+.. autoclass:: TwilioSmsSender(SmsSenderBaseClass)
+  ..method:: init(self)
+  ..method:: send_sms(self, from_number, to_number, msg)
+
 Signals
 -------
 See the `Flask documentation on signals`_ for information on how to use these
@@ -125,5 +139,14 @@ sends the following signals.
    Sent when a user requests a password reset. In addition to the app (which is
    the sender), it is passed `user` and `token` arguments.
 
+.. data:: user_two_factored
+
+    Sent when a user performs two-factor authentication login on the site. In
+    addition to the app (which is the sender), it is passed `user` argument
+
+.. data:: two_factor_method_changed
+
+  Sent when two-factor is used and user logs in. In addition to the app
+  (which is the sender), it is passed `user` argument.
 
 .. _Flask documentation on signals: http://flask.pocoo.org/docs/signals/
diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -69,6 +69,10 @@ Core
                                          to ``MAIL_DEFAULT_SENDER`` if
                                          Flask-Mail is used otherwise
                                          ``no-reply@localhost``.
+``SECURITY_TWO_FACTOR_RESCUE_MAIL``      Specifies the email address users send
+                                         mail to when they can't complete the
+                                         two-factor authentication login.
+                                         Defaults to ``no-reply@localhost``.
 ``SECURITY_TOKEN_AUTHENTICATION_KEY``    Specifies the query string parameter to
                                          read when using token authentication.
                                          Defaults to ``auth_token``.
@@ -151,31 +155,45 @@ Template Paths
 
 .. tabularcolumns:: |p{6.5cm}|p{8.5cm}|
 
-======================================== =======================================
-``SECURITY_FORGOT_PASSWORD_TEMPLATE``    Specifies the path to the template for
-                                         the forgot password page. Defaults to
-                                         ``security/forgot_password.html``.
-``SECURITY_LOGIN_USER_TEMPLATE``         Specifies the path to the template for
-                                         the user login page. Defaults to
-                                         ``security/login_user.html``.
-``SECURITY_REGISTER_USER_TEMPLATE``      Specifies the path to the template for
-                                         the user registration page. Defaults to
-                                         ``security/register_user.html``.
-``SECURITY_RESET_PASSWORD_TEMPLATE``     Specifies the path to the template for
-                                         the reset password page. Defaults to
-                                         ``security/reset_password.html``.
-``SECURITY_CHANGE_PASSWORD_TEMPLATE``    Specifies the path to the template for
-                                         the change password page. Defaults to
-                                         ``security/change_password.html``.
-``SECURITY_SEND_CONFIRMATION_TEMPLATE``  Specifies the path to the template for
-                                         the resend confirmation instructions
-                                         page. Defaults to
-                                         ``security/send_confirmation.html``.
-``SECURITY_SEND_LOGIN_TEMPLATE``         Specifies the path to the template for
-                                         the send login instructions page for
-                                         passwordless logins. Defaults to
-                                         ``security/send_login.html``.
-======================================== =======================================
+============================================== =======================================
+``SECURITY_FORGOT_PASSWORD_TEMPLATE``          Specifies the path to the template for
+                                               the forgot password page. Defaults to
+                                               ``security/forgot_password.html``.
+``SECURITY_LOGIN_USER_TEMPLATE``               Specifies the path to the template for
+                                               the user login page. Defaults to
+                                               ``security/login_user.html``.
+``SECURITY_REGISTER_USER_TEMPLATE``            Specifies the path to the template for
+                                               the user registration page. Defaults to
+                                               ``security/register_user.html``.
+``SECURITY_RESET_PASSWORD_TEMPLATE``           Specifies the path to the template for
+                                               the reset password page. Defaults to
+                                               ``security/reset_password.html``.
+``SECURITY_CHANGE_PASSWORD_TEMPLATE``          Specifies the path to the template for
+                                               the change password page. Defaults to
+                                               ``security/change_password.html``.
+``SECURITY_SEND_CONFIRMATION_TEMPLATE``        Specifies the path to the template for
+                                               the resend confirmation instructions
+                                               page. Defaults to
+                                               ``security/send_confirmation.html``.
+``SECURITY_SEND_LOGIN_TEMPLATE``               Specifies the path to the template for
+                                               the send login instructions page for
+                                               passwordless logins. Defaults to
+                                               ``security/send_login.html``.
+``SECURITY_TWO_FACTOR_VERIFY_CODE_TEMPLATE``   Specifies the path to the template for
+                                               the verify code page for the two-factor
+                                               authentication process. Defaults to
+                                               ``security/two_factor_verify_code.html``.
+
+``SECURITY_TWO_FACTOR_CHOOSE_METHOD_TEMPLATE``   Specifies the path to the template for
+                                               the choose method page for the two
+                                               factor authentication process. Defaults
+                                               to ``security/two_factor_choose_method.html``
+``SECURITY_TWO_FACTOR_CHANGE_METHOD_TEMPLATE`` Specifies the path to the template for
+                                               the change method page for the two
+                                               factor authentication process. Defaults
+                                               to ``security/two_factor_change_method_password_confirmation.html``.
+
+============================================== =======================================
 
 
 Feature Flags
@@ -214,6 +232,15 @@ Feature Flags
                           change password endpoint. The URL for this endpoint is
                           specified by the ``SECURITY_CHANGE_URL`` configuration
                           option. Defaults to ``False``.
+``SECURITY_TWO_FACTOR``   Specifies if Flask-Security should enable the
+                          two-factor login feature. If set to ``True``, in
+                          addition to their passwords, users will be required to
+                          enter a code that is sent to them. The added feature
+                          includes the ability to send it either via email, sms
+                          message, or Google Authenticator. Default time of
+                          validity is 30 seconds in Google Authenticator and up
+                          to 60 seconds if sent by mail or sms.
+                          Defaults to ``False``.
 ========================= ======================================================
 
 Email
@@ -249,6 +276,12 @@ Email
 ``SECURITY_EMAIL_HTML``                           Sends email as HTML using
                                                   ``*.html`` template. Defaults
                                                   to ``True``.
+``SECURITY_EMAIL_SUBJECT_TWO_FACTOR``             Sets the subject for the two
+                                                  factor feature. Defaults to
+                                                  ``Two-factor Login``
+``SECURITY_EMAIL_SUBJECT_TWO_FACTOR_RESCUE``      Sets the subject for the two
+                                                  factor help function. Defaults
+                                                  to ``Two-factor Rescue``
 ================================================= ==============================
 
 Miscellaneous
@@ -290,6 +323,28 @@ Miscellaneous
                                               enabled. Always pluralized the
                                               time unit for this value.
                                               Defaults to ``1 days``.
+``SECURITY_TWO_FACTOR_GOOGLE_AUTH_VALIDITY``  Specifies the number of time
+                                              windows user has before the token
+                                              generated for him using google
+                                              authenticator is valid. time
+                                              windows specifies the amount of
+                                              time, which is 30 seconds for each
+                                              window. Default to 0, which is up
+                                              to 30 seconds.
+``SECURITY_TWO_FACTOR_MAIL_VALIDITY``         Specifies the number of time
+                                              windows user has before the token
+                                              sent to him using mail is valid.
+                                              time windows specifies the amount
+                                              of time, which is 30 seconds for
+                                              each window. Default to 1, which
+                                              is up to 60 seconds.
+``SECURITY_TWO_FACTOR_SMS_VALIDITY``         Specifies the number of time
+                                              windows user has before the token
+                                              sent to him using sms is valid.
+                                              time windows specifies the amount
+                                              of time, which is 30 seconds for
+                                              each window. Default to 5, which
+                                              is up to 3 minutes.                                                                                            .
 ``SECURITY_LOGIN_WITHOUT_CONFIRMATION``       Specifies if a user may login
                                               before confirming their email when
                                               the value of
@@ -315,6 +370,24 @@ Miscellaneous
 ``SECURITY_DEFAULT_REMEMBER_ME``              Specifies the default "remember
                                               me" value used when logging in
                                               a user. Defaults to ``False``.
+``SECURITY_TWO_FACTOR_ENABLED_METHODS``       Specifies the default enabled
+                                              methods for two-factor
+                                              authentication. defaults to
+                                              ``['mail', 'google_authenticator',
+                                              'sms']`` which are the only
+                                              supported method at the moment.
+``SECURITY_TWO_FACTOR_URI_SERVICE_NAME``      Specifies the name of the service
+                                              or application that the user is
+                                              authenticating to. Defaults to
+                                              ``service_name``
+``SECURITY_TWO_FACTOR_SMS_SERVICE``           Specifies the name of the sms
+                                              service provider. Defaults to
+                                              ``Dummy`` which does nothing.
+``SECURITY_TWO_FACTOR_SMS_SERVICE_CONFIG``    Specifies a dictionary of basic
+                                              configurations needed for use of a
+                                              sms service. Defaults to
+                                              ``{'ACCOUNT_ID': NONE, 'AUTH_TOKEN
+                                              ':NONE, 'PHONE_NUMBER': NONE}``
 ``SECURITY_DATETIME_FACTORY``                 Specifies the default datetime
                                               factory. Defaults to
                                               ``datetime.datetime.utcnow``.
@@ -359,5 +432,12 @@ The default messages and error levels can be found in ``core.py``.
 * ``SECURITY_MSG_PASSWORD_RESET_REQUEST``
 * ``SECURITY_MSG_REFRESH``
 * ``SECURITY_MSG_RETYPE_PASSWORD_MISMATCH``
+* ``SECURITY_MSG_TWO_FACTOR_INVALID_TOKEN``
+* ``SECURITY_MSG_TWO_FACTOR_LOGIN_SUCCESSFUL``
+* ``SECURITY_MSG_TWO_FACTOR_CHANGE_METHOD_SUCCESSFUL``
+* ``SECURITY_MSG_TWO_FACTOR_PASSWORD_CONFIRMATION_DONE``
+* ``SECURITY_MSG_TWO_FACTOR_PASSWORD_CONFIRMATION_NEEDED``
+* ``SECURITY_MSG_TWO_FACTOR_PERMISSION_DENIED``
+* ``SECURITY_MSG_TWO_FACTOR_METHOD_NOT_AVAILABLE``
 * ``SECURITY_MSG_UNAUTHORIZED``
 * ``SECURITY_MSG_USER_DOES_NOT_EXIST``
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
@@ -9,6 +9,7 @@ Contents
    quickstart
    models
    customizing
+   two_factor_configurations
    api
    changelog
    authors
diff --git a/docs/customizing.rst b/docs/customizing.rst
@@ -21,6 +21,9 @@ following is a list of view templates:
 * `security/change_password.html`
 * `security/send_confirmation.html`
 * `security/send_login.html`
+* `security/two_factor_change_method_password_confirmation.html`
+* `security/two_factor_choose_method.html`
+* `security/two_factor_verify_code.html`
 
 Overriding these templates is simple:
 
@@ -103,7 +106,10 @@ The following is a list of all the available form overrides:
 * ``change_password_form``: Change password form
 * ``send_confirmation_form``: Send confirmation form
 * ``passwordless_login_form``: Passwordless login form
-
+* ``two_factor_verify_code_form``: Two-factor code form
+* ``two_factor_setup_form``: Two-factor setup form
+* ``two_factor_change_method_verify_password_form``: Two-factor password form
+* ``two_factor_rescue_form``: Two-factor help user form
 
 Emails
 ------
@@ -124,6 +130,10 @@ The following is a list of email templates:
 * `security/email/reset_notice.txt`
 * `security/email/welcome.html`
 * `security/email/welcome.txt`
+* `security/email/two_factor_instructions.html`
+* `security/email/two_factor_instructions.txt`
+* `security/email/two_factor_rescue.html`
+* `security/email/two_factor_rescue.txt`
 
 Overriding these templates is simple:
 

diff --git a/docs/features.rst b/docs/features.rst
@@ -61,6 +61,17 @@ 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.
 
+Two-factor Authentication
+-------------------------
+Two-factor authentication is enabled by generating time-based one time passwords
+(Tokens). The tokens are generated using the users totp secret, which is unique
+per user, and is generated both on first login, and when changing the two-factor
+method.(Doing this causes the previous totp secret to become invalid) The token
+is provided by one of 3 methods - email, sms (service is not provided), or
+Google Authenticator. By default, tokens provided by google authenticator are
+valid for 30 seconds, tokens sent by mail for up to 1 minute and tokens sent by
+sms for up to 3 minutes. The QR code used to supply Google Authenticator with
+the secret is generated using the PyQRCode library.
 
 Email Confirmation
 ------------------
@@ -118,6 +129,8 @@ JSON is supported for the following operations:
 * Confirmation requests
 * Forgot password requests
 * Passwordless login requests
+* Two-factor login requests
+* Change two-factor method requests
 
 
 Command Line Interface
@@ -131,7 +144,10 @@ Run ``flask --help`` and look for users and roles.
 .. _Click: http://click.pocoo.org/
 .. _Flask-Login: https://flask-login.readthedocs.org/en/latest/
 .. _alternative token: https://flask-login.readthedocs.io/en/latest/#alternative-tokens
+.. _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/
-.. _bcrypt: https://en.wikipedia.org/wiki/Bcrypt
+.. _onetimepass: https://pypi.python.org/pypi/onetimepass/
+.. _PyQRCode: https://pypi.python.org/pypi/PyQRCode/
diff --git a/docs/index.rst b/docs/index.rst
@@ -11,9 +11,10 @@ Flask application. They include:
 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. JSON/Ajax Support
+8. Two-factor authentication (optional)
+9. User registration (optional)
+10. Login tracking (optional)
+11. JSON/Ajax Support
 
 Many of these features are made possible by integrating various Flask extensions
 and libraries. They include:
@@ -24,6 +25,8 @@ and libraries. They include:
 4. `Flask-WTF <http://packages.python.org/Flask-WTF/>`_
 5. `itsdangerous <http://packages.python.org/itsdangerous/>`_
 6. `passlib <http://packages.python.org/passlib/>`_
+8. `onetimepass <https://pypi.python.org/pypi/onetimepass/>`_
+9. `PyQRCode <https://pypi.python.org/pypi/PyQRCode/>`_
 
 Additionally, it assumes you'll be using a common library for your database
 connections and model definitions. Flask-Security supports the following Flask