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, passwordless_login_form=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(fn)

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).

Parameters:fn – 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.

flask_security.decorators.http_auth_required(realm)

Decorator that protects endpoints using Basic HTTP authentication. The username should be set to the user’s email address.

Parameters:realm – optional realm name

flask_security.decorators.auth_token_required(fn)

Decorator that protects endpoints using token authentication. The token should be added to the request by the client by using a query string variable with a name equal to the configuration value of SECURITY_TOKEN_AUTHENTICATION_KEY or in a request header named that of the configuration value of SECURITY_TOKEN_AUTHENTICATION_HEADER

User Object Helpers

class flask_security.core.UserMixin

Mixin for User model definitions

get_auth_token()

Returns the user’s authentication token.

has_role(role)

Returns True if the user identifies with the specified role.

Parameters:role – A role name or Role instance

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 tp 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)

Delete 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.

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 tp 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)

Delete 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

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.MongoEngineUserDatastore(db, user_model, role_model)

A MongoEngine datastore implementation for Flask-Security that assumes the use of the Flask-MongoEngine 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 tp 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)

Delete 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

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.PeeweeUserDatastore(db, user_model, role_model, role_link)

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

Parameters:

• user_model – A user model class definition
• role_model – A role model class definition
• role_link – A model implementing the many-to-many user-role relation

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 tp 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)

Delete 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

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.

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. It is passed a dict with the user and confirm_token, the user being logged in and the (if so configured) the confirmation token issued.

user_confirmed

Sent when a user is confirmed. It is passed user, which is the user being confirmed.

confirm_instructions_sent

Sent when a user requests confirmation instructions. It is passed the user.

login_instructions_sent

Sent when passwordless login is used and user logs in. It is passed a dict with the user and login_token, the user being logged in and the (if so configured) the login token issued.

password_reset

Sent when a user completes a password reset. It is passed the user.

password_changed

Sent when a user completes a password change. It is passed the user.

reset_password_instructions_sent

Sent when a user requests a password reset. It is passed a dict with the user and token, the user being logged in and the (if so configured) the reset token issued.

All signals are also passed a app keyword argument, which is the current application.