API¶
Core¶
-
class
IdentityManager
(app=None, db=None, user_model=None, role_model=None, register_blueprint=None, **kwargs)¶ Simple & Customizable User Authentication and Management.
Init IdentityManager with Flask(app), db, user_model and role_model
- Parameters
app – Flask(app) instance
db – An orm database instance.
user_model – The model class of user
role_model – The model class of role
register_blueprint – Register default blueprint
anonymous_user – The class of AnonymousUser based on
AnonymousUserMixin
-
init_app
(app, db=None, user_model=None, role_model=None, register_blueprint=None, **kwargs)¶ Init IdentityManager with Flask(app), db, user_model and role_model
- Parameters
app – Flask(app) instance
db – A database instance
user_model – The model class of user
role_model – The model class of role
register_blueprint – Register default blueprint
anonymous_user – The class of AnonymousUser based on
AnonymousUserMixin
-
unauthenticated_handler
(fn)¶ Register a custom unauthenticated handler. :param fn: Custom unauthenticated function.
Register a custom unauthorized handler. :param fn: Custom unauthorized function.
-
template_render
(fn)¶ Register a custom template render function. :param fn: Custom template render function.
-
get_current_user
()¶ - Try load UserMixin based instance from session,if failed then try load from cookie,if failed then try load from request.Failed return AnonymousUserMixin based instance.
- Returns
UserMixin or AnonymousUserMixin based instance.
-
unauthenticated
(header=None)¶ - If caller wants JSON - return 403Otherwise - assume caller is html and redirect to
IDENTITY_UNAUTHENTICATED_VIEW
or 403
- If caller wants JSON - return 401Otherwise - assume caller is html and redirect to
IDENTITY_UNAUTHORIZED_VIEW
or 401
-
update_request_context_with_user
(user=None)¶ - Parameters
user – User object
- Returns
Store the given user as ctx.user.
-
property
datastore
¶ The datastore of Identity Manager
- Type
return
-
flask_identity.
current_user
¶ A proxy for the current user.
-
flask_identity.
current_identity
¶ A proxy for the current Flask_Identity instance.
DataStore¶
-
class
IdentityStore
(user_model, role_model)¶ Abstracted user identity store.
- Parameters
user_model – A user model class definition
role_model – A role model class definition
Be aware that for mutating operations, the user/role will be added to the store (by calling self.put(<object>). If the datastore is session based (such as for SQLAlchemyDatastore) it is up to caller to actually commit the transaction by calling datastore.commit().
-
find_user
(*args, **kwargs)¶ Returns a user matching the provided parameters.
-
find_role
(*args, **kwargs)¶ Returns a role matching the provided name.
-
add_role_to_user
(user, role)¶ Adds a role to a user.
- Parameters
user – The user to manipulate. Can be an User object or lookup key id with
'IDENTITY_IDENTITY_FIELD'
role – The role to add to the user. Can be a Role object or string role name
-
remove_role_from_user
(user, role)¶ Removes a role from a user.
- Parameters
user – The user to manipulate. Can be an User object or lookup key id with
'IDENTIT_IDENTITY_FIELD'
role – The role to remove from the user. Can be a Role object or string role name
-
toggle_active
(user)¶ Toggles a user’s active status. Always returns True.
-
deactivate_user
(user)¶ Deactivates a specified user. Returns True if a change was made.
This will immediately disallow access to all endpoints that require authentication either via session or tokens. The user will not be able to log in again.
- Parameters
user – The user to deactivate
-
activate_user
(user)¶ Activates a specified user. Returns True if a change was made.
- Parameters
user – The user to activate
-
set_uniquifier
(user, uniquifier=None)¶ Set user’s authentication token uniquifier. This will immediately render outstanding auth tokens invalid.
- Parameters
user – User to modify
uniquifier – Unique value - if none then uuid.uuid4().hex is used
This method is a no-op if the user model doesn’t contain the attribute
uniquifier
-
create_role
(**kwargs)¶ Creates and returns a new role from the given parameters. Supported params (depending on RoleModel):
- Keyword Arguments
name – Role name
-
create_user
(**kwargs)¶ Creates and returns a new user from the given parameters.
- Keyword Arguments
name – required.
password – Hashed password.
roles – list of roles to be added to user. Can be Role objects or strings
Danger
Be aware that whatever password is passed in will be stored directly in the DB. Do NOT pass in a plaintext password! Best practice is to pass in
hash_password(plaintext_password)
.The new user’s
active
property will be set to true.
-
delete_user
(user)¶ Deletes the specified user.
- Parameters
user – The user to delete
-
class
PonyIdentityStore
(db, user_model, role_model)¶ A Pony ORM identity store implementation of IdentityStore for IdentityManager.
-
class
SQLAlchemyIdentityStore
(db, user_model, role_model)¶ A SQLAlchemy identity store implementation of IdentityStore for IdentityManager.
Protecting Views¶
-
auth_required
(*auth_methods)¶ Decorator that protects endpoints through multiple mechanisms.
Example:
@app.route('/dashboard') @auth_required('token', 'session') def dashboard(): return 'Dashboard'
- Parameters
auth_methods – Specified mechanisms (token, session). If not specified then all current available mechanisms will be tried.
Note that regardless of order specified - they will be tried in the following order: token, session.
The first mechanism that succeeds is used, following that, depending on configuration.
On authentication failure
IdentityManager.unauthenticated()
will be called.
-
login_required
(view_function)¶ Ensure that the current user is logged in and authenticated before calling the actual view.
For example:
@app.route('/post') @login_required def post(): pass
Note
Per W3 guidelines for CORS preflight requests, HTTP
OPTIONS
requests are exempt from login checks.- Parameters
view_function (function) – The view function to decorate.
-
roles_required
(*role_names)¶ This decorator ensures that the current user is logged in, and has all of the specified roles (AND operation).
Example:
@route('/escape') @roles_required('Special', 'Agent') def escape_capture(): # User must be 'Special' AND 'Agent' ...
Calls unauthenticated_view() when the user is not logged in or when user is not actived.
Calls unauthorized_view() when the user does not have the required roles.
Calls the decorated view otherwise.
-
roles_accepted
(*role_names)¶ This decorator ensures that the current user is logged in, and has at least one of the specified roles (OR operation).
Example:
@route('/edit_article') @roles_accepted('Writer', 'Editor') def edit_article(): # User must be 'Writer' OR 'Editor' ...
Calls unauthenticated_view() when the user is not logged in or when user is not actived.
Calls unauthorized_view() when the user does not have the required roles.
Calls the decorated view otherwise.
User Object Helpers¶
-
class
UserMixin
¶ This class adds required methods to the User data-model.
Example
- class User(db.Model, UserMixin):
…
-
has_roles
(*requirements)¶ Return True if the user has all of the specified roles. Return False otherwise.
- has_roles() accepts a list of requirements:
has_roles(requirement1, requirement2, requirement3).
- Each requirement is either a role_name, or a tuple_of_role_names.
role_name example: ‘manager’ tuple_of_role_names: (‘funny’, ‘witty’, ‘hilarious’)
A role_name-requirement is accepted when the user has this role. A tuple_of_role_names-requirement is accepted when the user has ONE of these roles.
has_roles() returns true if ALL of the requirements have been accepted.
- For example:
has_roles(‘a’, (‘b’, ‘c’), d)
- Translates to:
User has role ‘a’ AND (role ‘b’ OR role ‘c’) AND role ‘d’
-
get_auth_token
()¶ Constructs the user’s authentication token.
This data MUST be securely signed using the identity token_context
-
get_security_payload
()¶ Serialize user object as response payload.
-
class
RoleMixin
¶ Mixin for Role model definitions
-
class
AnonymousUserMixin
¶ This is the default object for representing an anonymous user.
Utils¶
-
login_user
(user: flask_identity.mixins.UserMixin, uniquifier=None, remember=None, duration=None, fresh=True)¶ Logs a user in. You should pass the actual user object to this. If the user’s is_active property is
False
, they will not be logged in unless force isTrue
.This will return
True
if the log in attempt succeeds, andFalse
if it fails (i.e. because the user is inactive).- Parameters
user (object) – The user object to log in.
uniquifier (str) – The uniquifier for isolate login session. If
None
will use auuid.hex()
as default. Defatuls toNone
.remember (bool) – Whether to remember the user after their session expires. Defaults to
IDENTITY_REMEMBER_ME
.duration (
datetime.timedelta
) – The amount of time before the remember cookie expires. IfNone
the value set in the settings is used. Defaults toNone
.fresh (bool) – setting this to
False
will log in the user with a session marked as not “fresh”. Defaults toTrue
.
-
logout_user
()¶ Logs a user out. (You do not need to pass the actual user.) This will also clean up the remember me cookie if it exists.
-
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)
-
hash_password
(password)¶ Hash the specified plaintext password. :param password: The plaintext password to hash :return: The hashed password
-
url_for_identity
(endpoint, **values)¶ Return a URL for the Flask-Identity blueprint.
This is method is a wrapper of :meth:
Flask.url_for
.- Parameters
endpoint – the endpoint of the URL (name of the function)
values – the variable arguments of the URL rule