Security Bundle¶

Integrates Flask Login and Flask Principal with Flask Unchained. Technically speaking, this bundle is actually a heavily refactored fork of the Flask Security project. As of this writing, it is at approximate feature parity with Flask Security, and supports session and token authentication. (We’ve removed support for HTTP Basic Auth, tracking users’ IP addresses and similar, as well as the experimental password-less login support.)

Installation¶

The Security Bundle depends on the SQLAlchemy Bundle, as well as a few third-party libraries:

pip install "flask-unchained[security,sqlalchemy]"

And enable the bundles in your unchained_config.py:

# your_project_root/unchained_config.py

BUNDLES = [
    # ...
    'flask_unchained.bundles.sqlalchemy',
    'flask_unchained.bundles.security',
    'app',
]

Config¶

class flask_unchained.bundles.security.config.AuthenticationConfig[source]

Config options for logging in and out.

SECURITY_LOGIN_FORM: alias of flask_unchained.bundles.security.forms.LoginForm

SECURITY_DEFAULT_REMEMBER_ME = False: Whether or not the login form should default to checking the “Remember me?” option.

SECURITY_REMEMBER_SALT = 'security-remember-salt': Salt used for the remember me cookie token.

SECURITY_USER_IDENTITY_ATTRIBUTES = ['email']: List of attributes on the user model that can used for logging in with. Each must be unique.

SECURITY_POST_LOGIN_REDIRECT_ENDPOINT = '/': The endpoint or url to redirect to after a successful login.

SECURITY_POST_LOGOUT_REDIRECT_ENDPOINT = '/': The endpoint or url to redirect to after a user logs out.

class flask_unchained.bundles.security.config.ChangePasswordConfig[source]

Config options for changing passwords

SECURITY_CHANGEABLE = False: Whether or not to enable change password functionality.

SECURITY_CHANGE_PASSWORD_FORM: alias of flask_unchained.bundles.security.forms.ChangePasswordForm

SECURITY_POST_CHANGE_REDIRECT_ENDPOINT = None: Endpoint or url to redirect to after the user changes their password.

SECURITY_SEND_PASSWORD_CHANGED_EMAIL = False: Whether or not to send the user an email when their password has been changed. Defaults to True, and it’s strongly recommended to leave this option enabled.

class flask_unchained.bundles.security.config.EncryptionConfig[source]

Config options for encryption hashing.

SECURITY_PASSWORD_SALT = 'security-password-salt': Specifies the HMAC salt. This is only used if the password hash type is set to something other than plain text.

SECURITY_PASSWORD_HASH = 'bcrypt': Specifies the password hash algorithm to use when hashing passwords. Recommended values for production systems are argon2, bcrypt, or pbkdf2_sha512. May require extra packages to be installed.

SECURITY_PASSWORD_SINGLE_HASH = False: Specifies that passwords should only be hashed once. By default, passwords are hashed twice, first with SECURITY_PASSWORD_SALT, and then with a random salt. May be useful for integrating with other applications.

SECURITY_PASSWORD_SCHEMES = ['argon2', 'bcrypt', 'pbkdf2_sha512', 'plaintext']: List of algorithms that can be used for hashing passwords.

SECURITY_PASSWORD_HASH_OPTIONS = {}: Specifies additional options to be passed to the hashing method.

SECURITY_DEPRECATED_PASSWORD_SCHEMES = ['auto']: List of deprecated algorithms for hashing passwords.

SECURITY_HASHING_SCHEMES = ['sha512_crypt']: List of algorithms that can be used for creating and validating tokens.

SECURITY_DEPRECATED_HASHING_SCHEMES = []: List of deprecated algorithms for creating and validating tokens.

class flask_unchained.bundles.security.config.ForgotPasswordConfig[source]

Config options for recovering forgotten passwords

SECURITY_RECOVERABLE = False: Whether or not to enable forgot password functionality.

SECURITY_FORGOT_PASSWORD_FORM: alias of flask_unchained.bundles.security.forms.ForgotPasswordForm

SECURITY_RESET_PASSWORD_FORM: alias of flask_unchained.bundles.security.forms.ResetPasswordForm

SECURITY_RESET_SALT = 'security-reset-salt': Salt used for the reset token.

SECURITY_RESET_PASSWORD_WITHIN = '5 days': Specifies the amount of time a user has before their password reset link expires. Always pluralized the time unit for this value. Defaults to 5 days.

SECURITY_POST_RESET_REDIRECT_ENDPOINT = None: Endpoint or url to redirect to after the user resets their password.

SECURITY_INVALID_RESET_TOKEN_REDIRECT = 'security_controller.forgot_password': Endpoint or url to redirect to if the reset token is invalid.

SECURITY_EXPIRED_RESET_TOKEN_REDIRECT = 'security_controller.forgot_password': Endpoint or url to redirect to if the reset token is expired.

SECURITY_API_RESET_PASSWORD_HTTP_GET_REDIRECT = None: Endpoint or url to redirect to if a GET request is made to the reset password view. Defaults to None, meaning no redirect. Useful for single page apps.

SECURITY_SEND_PASSWORD_RESET_NOTICE_EMAIL = False: Whether or not to send the user an email when their password has been reset. Defaults to True, and it’s strongly recommended to leave this option enabled.

class flask_unchained.bundles.security.config.RegistrationConfig[source]

Config options for user registration

SECURITY_REGISTERABLE = False: Whether or not to enable registration.

SECURITY_REGISTER_FORM: alias of flask_unchained.bundles.security.forms.RegisterForm

SECURITY_POST_REGISTER_REDIRECT_ENDPOINT = None: The endpoint or url to redirect to after a user completes the registration form.

SECURITY_SEND_REGISTER_EMAIL = False: Whether or not send a welcome email after a user completes the registration form.

SECURITY_CONFIRMABLE = False: Whether or not to enable required email confirmation for new users.

SECURITY_SEND_CONFIRMATION_FORM: alias of flask_unchained.bundles.security.forms.SendConfirmationForm

SECURITY_CONFIRM_SALT = 'security-confirm-salt': Salt used for the confirmation token.

SECURITY_LOGIN_WITHOUT_CONFIRMATION = False: Allow users to login without confirming their email first. (This option only applies when SECURITY_CONFIRMABLE is True.)

SECURITY_CONFIRM_EMAIL_WITHIN = '5 days': How long to wait until considering the token in confirmation emails to be expired.

SECURITY_POST_CONFIRM_REDIRECT_ENDPOINT = None: Endpoint or url to redirect to after the user confirms their email. Defaults to SECURITY_POST_LOGIN_REDIRECT_ENDPOINT.

SECURITY_CONFIRM_ERROR_REDIRECT_ENDPOINT = None: Endpoint to redirect to if there’s an error confirming the user’s email.

class flask_unchained.bundles.security.config.TokenConfig[source]

Config options for token authentication.

SECURITY_TOKEN_AUTHENTICATION_KEY = 'auth_token': Specifies the query string parameter to read when using token authentication.

SECURITY_TOKEN_AUTHENTICATION_HEADER = 'Authentication-Token': Specifies the HTTP header to read when using token authentication.

SECURITY_TOKEN_MAX_AGE = None: Specifies the number of seconds before an authentication token expires. Defaults to None, meaning the token never expires.

class flask_unchained.bundles.security.config.Config[source]

Config options for the Security Bundle.

SECURITY_ANONYMOUS_USER: alias of flask_unchained.bundles.security.models.anonymous_user.AnonymousUser

SECURITY_UNAUTHORIZED_CALLBACK(): This callback gets called when authorization fails. By default we abort with an HTTP status code of 401 (UNAUTHORIZED).

SECURITY_DATETIME_FACTORY(): Factory function to use when creating new dates. By default we use datetime.now(timezone.utc) to create a timezone-aware datetime.

class flask_unchained.bundles.security.config.TestConfig[source]

Default test settings for the Security Bundle.

SECURITY_PASSWORD_HASH = 'plaintext': Disable password-hashing in tests (shaves about 30% off the test-run time)

Commands¶

flask users¶

User model commands.

flask users COMMAND [<args>...] [OPTIONS]

activate¶

Activate a user.

flask users activate <query> [OPTIONS]

Arguments

QUERY¶: Required argument

add-role¶

Add a role to a user.

flask users add-role [OPTIONS]

Options

-u, --user <user>¶: The query to search for a user by. For example, id=5, email=a@a.com or first_name=A,last_name=B.

-r, --role <role>¶: The query to search for a role by. For example, id=5 or name=ROLE_USER.

confirm¶

Confirm a user account.

flask users confirm <query> [OPTIONS]

Arguments

QUERY¶: Required argument

create¶

Create a new user.

flask users create [OPTIONS]

Options

--email <email>¶: The user’s email address.

--password <password>¶: The user’s password.

--active, --inactive¶

Whether or not the new user should be active.

Default: False

--confirmed-at <confirmed_at>¶: The date stamp the user was confirmed at (or enter “now”) [default: None]

--send-email, --no-email¶

Whether or not to send the user a welcome email.

Default: False

deactivate¶

Deactivate a user.

flask users deactivate <query> [OPTIONS]

Arguments

QUERY¶: Required argument

delete¶

Delete a user.

flask users delete <query> [OPTIONS]

Arguments

QUERY¶: Required argument

list¶

List users.

flask users list [OPTIONS]

remove-role¶

Remove a role from a user.

flask users remove-role [OPTIONS]

Options

-u, --user <user>¶: The query to search for a user by. For example, id=5, email=a@a.com or first_name=A,last_name=B.

-r, --role <role>¶: The query to search for a role by. For example, id=5 or name=ROLE_USER.

set-password¶

Set a user’s password.

flask users set-password <query> [OPTIONS]

Options

--password <password>¶: The new password to assign to the user.

--send-email, --no-email¶

Whether or not to send the user a notification email.

Default: False

Arguments

QUERY¶: Required argument

flask roles¶

Role commands.

flask roles COMMAND [<args>...] [OPTIONS]

create¶

Create a new role.

flask roles create [OPTIONS]

Options

--name <name>¶: The name of the role to create, eg ROLE_USER.

delete¶

Delete a role.

flask roles delete <query> [OPTIONS]

Arguments

QUERY¶: Required argument

list¶

List roles.

flask roles list [OPTIONS]

API Docs¶

See Security Bundle API