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, 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.
-
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.
-
get_security_payload
()¶ Serialize user object as response payload.
-
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
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.
-
-
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 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.
-
-
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 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.
-
class
flask_security.datastore.
PonyUserDatastore
(db, user_model, role_model)¶ A Pony ORM datastore implementation for Flask-Security.
Code primarily from https://github.com/ET-CS but taken over after being abandoned.
-
activate_user
(user)¶ Activates a specified user. Returns True if a change was made.
- Parameters
user – The user to activate
-
add_role_to_user
(**kwargs)¶ 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
(**kwargs)¶ Returns a role matching the provided name.
-
find_user
(**kwargs)¶ Returns a user matching the provided parameters.
-
get_user
(**kwargs)¶ 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, remember=None)¶ 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
remember – Flag specifying if the remember cookie should be set. Defaults to
False
-
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
-
flask_security.utils.
get_token_status
(token, serializer, max_age=None, return_data=False)¶ Get the status of a token.
- Parameters
token – The token to check
serializer – The name of the seriailzer. Can be one of the following:
confirm
,login
,reset
max_age – The name of the max age config option. Can be on of the following:
CONFIRM_EMAIL
,LOGIN
,RESET_PASSWORD
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.