-------------
Released August 27, 2022
**PLEASE READ CHANGE NOTES CAREFULLY - THERE ARE LIKELY REQUIRED CHANGES YOU WILL HAVE TO MAKE.**
Features
++++++++
- (:issue:`475`) Support for WebAuthn.
- (:issue:`479`) Support Two-factor recovery codes.
- (:issue:`585`) Provide option to prevent user enumeration (i.e. Generic Responses).
- (:pr:`532`) Support for Python 3.10.
- (:pr:`657`, :pr:`655`) Support for Flask >= 2.2.
- (:pr:`540`) Improve Templates in support of JS required by WebAuthn.
- (:pr:`608`) Add Icelandic translations. (ofurkusi)
- (:pr:`650`) Update German translations. (sr-verde)
- (:issue:`256`) Add custom HTML attributes to improve user experience.
This changed LoginForm quite a bit - please see backwards compatability concerns
below. The default LoginForm and template should be the same as before.
- (:pr:`638`) The JSON errors response has been unified. Please see backwards
compatibility concerns below.
- Updated all-inclusive data models (fsqla_v3). Add fields necessary for the new WebAuthn and
Two-Factor recovery codes features.
Changed `us_phone_number` to be unique (but not required). Changed `password` to be nullable.
Deprecations
++++++++++++
- (:pr:`568`) Deprecate the old passwordless feature in favor of Unified Signin.
- (:pr:`568`) Deprecate replacing login_manager so we can possibly vendor that in in the future.
- (:pr:`654`) The previously deprecated methods RoleMixin.add_permissions and
RoleMixin.remove_permissions have been removed.
- (:pr:`657`) The ability to pass in a json_encoder_cls as part of initialization has been removed
since Flask 2.2 has deprecated and replaced that functionality.
- (:pr:`655`) Flask has deprecated before_first_request. This was used mostly in examples/quickstart.
These have been changed to use app.app_context() prior to running the app. Flask-Security itself used it in
2 places - to populate `_` in jinja globals if Babel wasn't initialized and to perform
various configuration sanity checks w.r.t. WTF CSRF. All Flask-Security templates have been converted
to use `_fsdomain` rather than ``_`` so Flask-Security no longer sets ``_`` into jinja2 globals.
The configuration checks
have been moved to the end of Security::init_app() - so it is now imperative that `FlaskWTF::CSRFProtect()`
be called PRIOR to initializing Flask-Security.
- encrypt_password method has been removed. It has been deprecated since 2.0.2
- get_token_status has been deprecated.
Fixes
+++++
- (:pr:`591`) Make the required zxcvbn complexity score configurable. (mephi42)
- (:issue:`531`) Get rid of Flask-Mail. Flask-Mailman is now the default preferred email package.
Flask-Mail is still supported so there should be no backwards compatability issues.
- (:issue:`597`) A delete option has been added to us-setup (form and view).
- (:pr:`625`) Improve username support - the LoginForm now has a separate field for username if
``SECURITY_USERNAME_ENABLE`` is True, and properly displays input fields only if the associated
field is an identity attribute (as specified by :py:data:`SECURITY_USER_IDENTITY_ATTRIBUTES`).
- (:pr:`627`) Improve empty password handling. Prior, an unguessable password was set into the user
record when a user registered without a password - now, the DB user model has been changed to
allow nullable passwords. This provides a better user experience since Flask-Security now
knows if a user has an empty password or not. Since registering without a password is not
a mainstream feature, a new configuration variable :py:data:`SECURITY_PASSWORD_REQUIRED`
has been added (defaults to ``True``).
- (:issue:`479`) A new configuration option :py:data:`SECURITY_TWO_FACTOR_RESCUE_EMAIL` has been added
that allows disabling that feature - defaults to backwards compatible ``True``
- (:issue:`658`) us_phone_number needs to be validated to be unique.
Backward Compatibility Concerns
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For unified signin:
- The redirect after a successful us-setup used to redirect to ``SECURITY_US_POST_SETUP_VIEW`` or
``SECURITY_POST_LOGIN_VIEW`` (which would default to '/'). Now it just redirects to
``SECURITY_US_POST_SETUP_VIEW`` which defaults back to the ``/us-setup`` view.
- The ability to authenticate using a one-time email link was automatically setup by the system
for all users.
"email" now behaves like the other unified sign in methods and must be explicitly set up - with the
exception that if a user registers WITHOUT a password, the system will setup the one-time email link
option - since otherwise the user would never be able to authenticate.
- ``/us-signin/send-code`` didn't used to check if the user account required confirmation it just sent a code
and the ``/us-signin`` endpoint did the confirmation check. Now ``send-code`` does the confirmation check and
won't send a code unless the user is confirmed.
- In ``us-verify`` the 'code_methods' item now lists just active/setup methods that generate a code
not ALL possible methods that generate a code.
- ``SECURITY_US_VERIFY_SEND_CODE_URL`` and ``SECURITY_US_SIGNIN_SEND_CODE_URL`` endpoints are now POST only.
- Empty passwords were always permitted when ``SECURITY_UNIFIED_SIGNIN`` was enabled - now an additional configuration
variable ``SECURITY_PASSWORD_REQUIRED`` must be set to False.
- ``SECURITY_US_VERIFY_SEND_CODE_URL`` and ``SECURITY_US_SIGNIN_SEND_CODE_URL`` used to send ``code_sent`` to the template.
Now they flash the ``SECURITY_MSG_CODE_HAS_BEEN_SENT`` message.
- With the addition of being able to delete a previously setup up sign in method, the signal `us_profile_changed` arguments
have changed. `method` is now `methods` and is a list, and a new argument `delete` is True if a sign in option was deleted.
Login:
- Since the beginning of time, the flask-security login form has accepted any input in the
'email' field, and used that to check if it corresponds to any field in ``SECURITY_USER_IDENTITY_ATTRIBUTES``.
This has always been problematic and confusing - and with the addition of HTML attributes for various
form fields - having a field with multiple possible inputs is no longer a viable user experience.
This is no longer supported, and the LoginForm now declares the ``email`` field to be of type ``EmailField``
which requires a valid (after normalization) email address. The most common usage of this legacy feature was to allow
an email or username - Flask-Security now has core support for a ``username`` option - see :py:data:`SECURITY_USERNAME_ENABLE`.
Please see :ref:`custom_login_form` for an example of how to replicate the legacy behavior.
- Some error messages have changed - ``USER_DOES_NOT_EXIST`` is now returned for any identity error including an empty value.
Other:
- A very old piece of code in registrable, would immediately commit to the DB when a new user was created.
It is now consistent with all other views, and has the caller responsible for committing the transaction - usually by
setting up a flask ``after_this_request`` action. This could affect an application that captured the registration signal
and stored the ``user`` object for later use - this user object would likely be invalid after the request is finished.
- Some fields have custom HTML attributes attached to them (e.g. autocomplete, type, etc). These are stored as part of the
form in the ``render_kw`` attribute. This could cause some confusion if an app had its own templates and set different
attributes.
- The keys for "/tf-rescue" select options have changed to be more 'action' oriented:
- `lost_device` -> `email`
- `no_mail_access` -> `help`
- JSON error responses. **THIS IS A BREAKING CHANGE**.
In earlier releases, the JSON error response could have either a `error` key which was for rare cases
where there was a single non-form related error, or an `errors` key which was a a dict as defined by WTForms.
Now, the `errors` key will contain a list of (localized) messages - both non-form related as well as any form related.
The key `field_errors` will contain the dict as specified by WTForms. Please note that starting with WTForms 3.0
form-level errors are supported and show up in the dict with the field name/key of "none". There are no changes to non-error
related JSON responses.
- Permissions **THIS IS A BREAKING CHANGE**. The Role Model now stores permissions as a list, and requires that the underlying DB ORM map that to a supported
DB type. For SQLAlchemy, this is mapped to a comma separated string (as before). For
SQLAlchemy DBs the underlying Column type (UnicodeText) didn't change so no data migration should be required.
However, the ORM Column type did change and requires the following change to your model::
from flask_security import AsaList
from sqlalchemy.ext.mutable import MutableList
class Role(Base, RoleMixin):
...
permissions = Column(MutableList.as_mutable(AsaList()), nullable=True)
...
If your application makes use of Flask-Security's models.fsqla_vX classes - no changes are required.
For Mongo, a ListField can be directly used.
- CSRF - As mentioned above, it is now required that `FlaskWTF::CSRFProtect()`, if used, must be called PRIOR to initializing Flask-Security.
- json_encoder_cls - As mentioned above - Flask-Security initialization no longer accepts overriding the json_encoder class. If this is required,
update to Flask >=2.2 and implement Flask's JSONProvider interface.
For templates:
- Pretty much every template was modified to replace <p> with <div class=xx> to make
styling possible and to make more complex forms more readable.
- Many forms had places where things weren't properly localizable - that has (hopefully) been fixed.
- The ``us_setup.html`` template was modified to add ability to delete an existing set up method.
DB Migration
~~~~~~~~~~~~
To use the new WebAuthn feature a new table and two new columns in the User model are required.
To ease updates - Flask-Security will automatically create a fs_webauthn_user_handle
upon first use for existing users.
If you are using Alembic the schema migration is easy::
op.add_column('user', sa.Column('fs_webauthn_user_handle', sa.String(length=64), nullable=True, unique=True))
If you want to allow for empty passwords as part of registration then set :py:data:`SECURITY_PASSWORD_REQUIRED` to ``False``.
In addition you need to change your DB schema to allow the ``password`` field to be nullable.