API

Core

class flask_security.core.Security(app=None, datastore=None, **kwargs)

The Security class initializes the Flask-Security extension.

Parameters
  • app – The application.

  • datastore – An instance of a user datastore.

init_app(app, datastore=None, register_blueprint=True, login_form=None, confirm_register_form=None, register_form=None, forgot_password_form=None, reset_password_form=None, change_password_form=None, send_confirmation_form=None, anonymous_user=None)

Initializes the Flask-Security extension for the specified application and datastore implentation.

Parameters
  • app – The application.

  • datastore – An instance of a user datastore.

  • register_blueprint – to register the Security blueprint or not.

flask_security.core.current_user

A proxy for the current user.

Protecting Views

flask_security.decorators.login_required(func)

If you decorate a view with this, it will ensure that the current user is logged in and authenticated before calling the actual view. (If they are not, it calls the LoginManager.unauthorized callback.) For example:

@app.route('/post')
@login_required
def post():
    pass

If there are only certain times you need to require that your user is logged in, you can do so with:

if not current_user.is_authenticated:
    return current_app.login_manager.unauthorized()

…which is essentially the code that this function adds to your views.

It can be convenient to globally turn off authentication when unit testing. To enable this, if the application configuration variable LOGIN_DISABLED is set to True, this decorator will be ignored.

Note

Per W3 guidelines for CORS preflight requests, HTTP OPTIONS requests are exempt from login checks.

Parameters

func (function) – The view function to decorate.

flask_security.decorators.roles_required(*roles)

Decorator which specifies that a user must have all the specified roles. Example:

@app.route('/dashboard')
@roles_required('admin', 'editor')
def dashboard():
    return 'Dashboard'

The current user must have both the admin role and editor role in order to view the page.

Parameters

args – The required roles.

flask_security.decorators.roles_accepted(*roles)

Decorator which specifies that a user must have at least one of the specified roles. Example:

@app.route('/create_post')
@roles_accepted('editor', 'author')
def create_post():
    return 'Create Post'

The current user must have either the editor role or author role in order to view the page.

Parameters

args – The possible roles.

User Object Helpers

class flask_security.core.UserMixin

Mixin for User model definitions

has_role(role)

Returns True if the user identifies with the specified role.

Parameters

role – A role name or Role instance

property is_active

Returns True if the user is active.

class flask_security.core.RoleMixin

Mixin for Role model definitions

class flask_security.core.AnonymousUser

AnonymousUser definition

has_role(*args)

Returns False

Datastores

class flask_security.datastore.UserDatastore(user_model, role_model)

Abstracted user datastore.

Parameters
  • user_model – A user model class definition

  • role_model – A role model class definition

activate_user(user)

Activates a specified user. Returns True if a change was made.

Parameters

user – The user to activate

add_role_to_user(user, role)

Adds a role to a user.

Parameters
  • user – The user to manipulate

  • role – The role to add to the user

create_role(**kwargs)

Creates and returns a new role from the given parameters.

create_user(**kwargs)

Creates and returns a new user from the given parameters.

deactivate_user(user)

Deactivates a specified user. Returns True if a change was made.

Parameters

user – The user to deactivate

delete_user(user)

Deletes the specified user.

Parameters

user – The user to delete

find_or_create_role(name, **kwargs)

Returns a role matching the given name or creates it with any additionally provided parameters.

find_role(*args, **kwargs)

Returns a role matching the provided name.

find_user(*args, **kwargs)

Returns a user matching the provided parameters.

get_user(id_or_email)

Returns a user matching the specified ID or email address.

remove_role_from_user(user, role)

Removes a role from a user.

Parameters
  • user – The user to manipulate

  • role – The role to remove from the user

toggle_active(user)

Toggles a user’s active status. Always returns True.

class flask_security.datastore.SQLAlchemyUserDatastore(db, user_model, role_model)

A SQLAlchemy datastore implementation for Flask-Security that assumes the use of the Flask-SQLAlchemy extension.

activate_user(user)

Activates a specified user. Returns True if a change was made.

Parameters

user – The user to activate

add_role_to_user(user, role)

Adds a role to a user.

Parameters
  • user – The user to manipulate

  • role – The role to add to the user

create_role(**kwargs)

Creates and returns a new role from the given parameters.

create_user(**kwargs)

Creates and returns a new user from the given parameters.

deactivate_user(user)

Deactivates a specified user. Returns True if a change was made.

Parameters

user – The user to deactivate

delete_user(user)

Deletes the specified user.

Parameters

user – The user to delete

find_or_create_role(name, **kwargs)

Returns a role matching the given name or creates it with any additionally provided parameters.

find_role(role)

Returns a role matching the provided name.

find_user(**kwargs)

Returns a user matching the provided parameters.

get_user(identifier)

Returns a user matching the specified ID or email address.

remove_role_from_user(user, role)

Removes a role from a user.

Parameters
  • user – The user to manipulate

  • role – The role to remove from the user

toggle_active(user)

Toggles a user’s active status. Always returns True.

Utils

flask_security.utils.login_user(user, **kwargs)

Perform the login routine.

If SECURITY_TRACKABLE is used, make sure you commit changes after this request (i.e. app.security.datastore.commit()).

Parameters

user – The user to login

flask_security.utils.logout_user()

Logs out the current.

This will also clean up the remember me cookie if it exists.

flask_security.utils.get_hmac(password)

Returns a Base64 encoded HMAC+SHA512 of the password signed with the salt specified by SECURITY_PASSWORD_SALT.

Parameters

password – The password to sign

flask_security.utils.verify_password(password, password_hash)

Returns True if the password matches the supplied hash.

Parameters
  • password – A plaintext password to verify

  • password_hash – The expected hash value of the password (usually from your database)

flask_security.utils.verify_and_update_password(password, user)

Returns True if the password is valid for the specified user.

Additionally, the hashed password in the database is updated if the hashing algorithm happens to have changed.

Parameters
  • password – A plaintext password to verify

  • user – The user to verify against

flask_security.utils.encrypt_password(password)

Encrypt the specified plaintext password.

It uses the configured encryption options.

Deprecated since version 2.0.2: Use hash_password() instead.

Parameters

password – The plaintext password to encrypt

flask_security.utils.hash_password(password)

Hash the specified plaintext password.

It uses the configured hashing options.

New in version 2.0.2.

Parameters

password – The plaintext password to hash

flask_security.utils.url_for_security(endpoint, **values)

Return a URL for the security blueprint

Parameters
  • endpoint – the endpoint of the URL (name of the function)

  • values – the variable arguments of the URL rule

  • _external – if set to True, an absolute URL is generated. Server address can be changed via SERVER_NAME configuration variable which defaults to localhost.

  • _anchor – if provided this is added as anchor to the URL.

  • _method – if provided this explicitly specifies an HTTP method.

flask_security.utils.get_within_delta(key, app=None)

Get a timedelta object from the application configuration following the internal convention of:

<Amount of Units> <Type of Units>

Examples of valid config values:

5 days
10 minutes
Parameters
  • key – The config value key without the SECURITY_ prefix

  • app – Optional application to inspect. Defaults to Flask’s current_app

flask_security.utils.send_mail(subject, recipient, template, **context)

Send an email via the Flask-Mail extension.

Parameters
  • subject – Email subject

  • recipient – Email recipient

  • template – The name of the email template

  • context – The context to render the template with

Signals

See the Flask documentation on signals for information on how to use these signals in your code.

See the documentation for the signals provided by the Flask-Login and Flask-Principal extensions. In addition to those signals, Flask-Security sends the following signals.

user_registered

Sent when a user registers on the site. In addition to the app (which is the sender), it is passed user and confirm_token arguments.

user_confirmed

Sent when a user is confirmed. In addition to the app (which is the sender), it is passed a user argument.

confirm_instructions_sent

Sent when a user requests confirmation instructions. In addition to the app (which is the sender), it is passed a user argument.

login_instructions_sent

Sent when passwordless login is used and user logs in. In addition to the app (which is the sender), it is passed user and login_token arguments.

password_reset

Sent when a user completes a password reset. In addition to the app (which is the sender), it is passed a user argument.

password_changed

Sent when a user completes a password change. In addition to the app (which is the sender), it is passed a user argument.

reset_password_instructions_sent

Sent when a user requests a password reset. In addition to the app (which is the sender), it is passed user and token arguments.