API
***

The external (json/form) API is described here


Core
====

class flask_security.Security(app=None, datastore=None, register_blueprint=True, login_form=<class 'flask_security.forms.LoginForm'>, verify_form=<class 'flask_security.forms.VerifyForm'>, confirm_register_form=<class 'flask_security.forms.ConfirmRegisterForm'>, register_form=<class 'flask_security.forms.RegisterForm'>, forgot_password_form=<class 'flask_security.forms.ForgotPasswordForm'>, reset_password_form=<class 'flask_security.forms.ResetPasswordForm'>, change_password_form=<class 'flask_security.forms.ChangePasswordForm'>, send_confirmation_form=<class 'flask_security.forms.SendConfirmationForm'>, passwordless_login_form=<class 'flask_security.forms.PasswordlessLoginForm'>, two_factor_verify_code_form=<class 'flask_security.forms.TwoFactorVerifyCodeForm'>, two_factor_setup_form=<class 'flask_security.forms.TwoFactorSetupForm'>, two_factor_rescue_form=<class 'flask_security.forms.TwoFactorRescueForm'>, us_signin_form=<class 'flask_security.unified_signin.UnifiedSigninForm'>, us_setup_form=<class 'flask_security.unified_signin.UnifiedSigninSetupForm'>, us_setup_validate_form=<class 'flask_security.unified_signin.UnifiedSigninSetupValidateForm'>, us_verify_form=<class 'flask_security.unified_signin.UnifiedVerifyForm'>, anonymous_user=None, login_manager=None, json_encoder_cls=<class 'flask_security.utils.FsJsonEncoder'>, mail_util_cls=<class 'flask_security.mail_util.MailUtil'>, password_util_cls=<class 'flask_security.password_util.PasswordUtil'>, phone_util_cls=<class 'flask_security.phone_util.PhoneUtil'>, render_template=<function default_render_template>, totp_cls=<class 'flask_security.totp.Totp'>, username_util_cls=<class 'flask_security.username_util.UsernameUtil'>, **kwargs)

   The "Security" class initializes the Flask-Security extension.

   Parameters:
      * **app** (*Optional**[**flask.Flask**]*) -- The application.

      * **datastore** (*Optional**[**UserDatastore**]*) -- An instance
        of a user datastore.

      * **register_blueprint** (*bool*) -- to register the Security
        blueprint or not.

      * **login_form** (*Type**[**flask_wtf.form.FlaskForm**]*) -- set
        form for the login view

      * **verify_form** (*Type**[**flask_wtf.form.FlaskForm**]*) --
        set form for re-authentication due to freshness check

      * **register_form** (*Type**[**flask_wtf.form.FlaskForm**]*) --
        set form for the register view when *SECURITY_CONFIRMABLE* is
        false

      * **confirm_register_form**
        (*Type**[**flask_wtf.form.FlaskForm**]*) -- set form for the
        register view when *SECURITY_CONFIRMABLE* is true

      * **forgot_password_form**
        (*Type**[**flask_wtf.form.FlaskForm**]*) -- set form for the
        forgot password view

      * **reset_password_form**
        (*Type**[**flask_wtf.form.FlaskForm**]*) -- set form for the
        reset password view

      * **change_password_form**
        (*Type**[**flask_wtf.form.FlaskForm**]*) -- set form for the
        change password view

      * **send_confirmation_form**
        (*Type**[**flask_wtf.form.FlaskForm**]*) -- set form for the
        send confirmation view

      * **passwordless_login_form**
        (*Type**[**flask_wtf.form.FlaskForm**]*) -- set form for the
        passwordless login view

      * **two_factor_setup_form**
        (*Type**[**flask_wtf.form.FlaskForm**]*) -- set form for the
        2FA setup view

      * **two_factor_verify_code_form**
        (*Type**[**flask_wtf.form.FlaskForm**]*) -- set form the the
        2FA verify code view

      * **two_factor_rescue_form**
        (*Type**[**flask_wtf.form.FlaskForm**]*) -- set form for the
        2FA rescue view

      * **us_signin_form** (*Type**[**flask_wtf.form.FlaskForm**]*) --
        set form for the unified sign in view

      * **us_setup_form** (*Type**[**flask_wtf.form.FlaskForm**]*) --
        set form for the unified sign in setup view

      * **us_setup_validate_form**
        (*Type**[**flask_wtf.form.FlaskForm**]*) -- set form for the
        unified sign in setup validate view

      * **us_verify_form** (*Type**[**flask_wtf.form.FlaskForm**]*) --
        set form for re-authenticating due to freshness check

      * **anonymous_user**
        (*Optional**[**Type**[**flask_login.AnonymousUserMixin**]**]*)
        -- class to use for anonymous user

      * **login_manager** (*Optional**[**flask_login.LoginManager**]*)
        -- An subclass of LoginManager

      * **json_encoder_cls** (*Type**[**flask.json.JSONEncoder**]*) --
        Class to use as blueprint.json_encoder. Defaults to
        "FsJsonEncoder"

      * **mail_util_cls** (*Type**[**MailUtil**]*) -- Class to use for
        sending emails. Defaults to "MailUtil"

      * **password_util_cls** (*Type**[**PasswordUtil**]*) -- Class to
        use for password normalization/validation. Defaults to
        "PasswordUtil"

      * **phone_util_cls** (*Type**[**PhoneUtil**]*) -- Class to use
        for phone number utilities. Defaults to "PhoneUtil"

      * **render_template** (*Callable**[**[**...**]**, **str**]*) --
        function to use to render templates. The default is Flask's
        render_template() function.

      * **totp_cls** (*Type**[**Totp**]*) -- Class to use as TOTP
        factory. Defaults to "Totp"

      * **username_util_cls** (*Type**[**UsernameUtil**]*) -- Class to
        use for normalizing and validating usernames. Defaults to
        "UsernameUtil"

      * **kwargs** (*Any*) --

   Tip:

     Be sure that all your configuration values have been set PRIOR to
     instantiating this class. Some configuration values are set as
     attributes on the instance and therefore won't track any changes.

   New in version 3.4.0: "verify_form" added as part of freshness/re-
   authentication

   New in version 3.4.0: "us_signin_form", "us_setup_form",
   "us_setup_validate_form", and "us_verify_form" added as part of the
   Unified Sign In feature.

   New in version 3.4.0: "totp_cls" added to enable applications to
   implement replay protection - see "Totp".

   New in version 3.4.0: "phone_util_cls" added to allow different
   phone number  parsing implementations - see "PhoneUtil"

   New in version 4.0.0: "mail_util_cls" added to isolate mailing
   handling. "password_util_cls" added to encapsulate password
   validation/normalization.

   New in version 4.1.0: "username_util_cls" added to encapsulate
   username handling.

   Deprecated since version 4.0.0: "send_mail" and "send_mail_task".
   Replaced with "mail_util_cls". "two_factor_verify_password_form"
   removed. "password_validator" removed in favor of the new
   "password_util_cls".

   init_app(app, datastore=None, register_blueprint=None, **kwargs)

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

      Parameters:
         * **app** (*flask.Flask*) -- The application.

         * **datastore** (*Optional**[**UserDatastore**]*) -- An
           instance of a user datastore.

         * **register_blueprint** (*Optional**[**bool**]*) -- to
           register the Security blueprint or not.

         * **kwargs** (*Any*) -- Can be used to override/initialize
           any of the constructor attributes.

      Return type:
         None

      If you create the Security instance with both an 'app' and
      'datastore' you shouldn't call this - it will be called as part
      of the constructor.

   reauthn_handler(cb)

      Callback when endpoint required a fresh authentication. This is
      called by "auth_required()".

      Parameters:
         **cb** (*Callable**[**[**datetime.timedelta**,
         **datetime.timedelta**]**, **ResponseValue**]*) --

         Callback function with signature (within, grace)

         within:
            timedelta that endpoint required fresh authentication
            within.

         grace:
            timedelta of grace period that endpoint allowed.

      Return type:
         None

      Should return a Response or something Flask can create a
      Response from. Can raise an exception if it is handled as part
      of "flask.errorhandler(<exception>)"

      The default implementation will return a 401 response if the
      request was JSON, otherwise will redirect to
      "SECURITY_US_VERIFY_URL" (if "SECURITY_UNIFIED_SIGNIN" is
      enabled) else to "SECURITY_VERIFY_URL". If both of those are
      None it sends an "abort(401)".

      See "flask_security.auth_required()" for details about freshness
      checking.

      New in version 3.4.0.

   render_json(cb)

      Callback to render response payload as JSON.

      Parameters:
         **cb** (*Callable**[**[**Dict**[**str**, **Any**]**, **int**,
         **Optional**[**Dict**[**str**, **str**]**]**,
         **Optional**[**User**]**]**, **ResponseValue**]*) --

         Callback function with signature (payload, code,
         headers=None, user=None)

            payload:
               A dict. Please see the formal API spec for details.

            code:
               Http status code

            headers:
               Headers object

            user:
               the UserDatastore object (or None). Note that this is
               usually the same as current_user - but not always.

      Return type:
         None

      The default implementation simply returns:

         headers["Content-Type"] = "application/json"
         payload = dict(meta=dict(code=code), response=payload)
         return make_response(jsonify(payload), code, headers)

      Important:

        Be aware the Flask's "jsonify" method will first look to see
        if a "json_encoder" has been set on the blueprint
        corresponding to the current request. If not then it looks for
        a "json_encoder" registered on the app; and finally uses
        Flask's default JSONEncoder class. Flask-Security registers
        "FsJsonEncoder()" as its blueprint json_encoder.

      This can be used by applications to unify all their JSON API
      responses. This is called in a request context and should return
      a Response or something Flask can create a Response from.

      New in version 3.3.0.

   unauthn_handler(cb)

      Callback for failed authentication. This is called by
      "auth_required()", "auth_token_required()" or
      "http_auth_required()" if authentication fails.

      Parameters:
         **cb** (*Callable**[**[**List**[**str**]**,
         **Optional**[**Dict**[**str**, **str**]**]**]**,
         **ResponseValue**]*) --

         Callback function with signature (mechanisms, headers=None)

         mechanisms:
            List of which authentication mechanisms were tried

         headers:
            dict of headers to return

      Return type:
         None

      Should return a Response or something Flask can create a
      Response from. Can raise an exception if it is handled as part
      of "flask.errorhandler(<exception>)"

      The default implementation will return a 401 response if the
      request was JSON, otherwise lets
      "flask_login.login_manager.unauthorized()" handle redirects.

      New in version 3.3.0.

   unauthz_handler(cb)

      Callback for failed authorization. This is called by the
      "roles_required()", "roles_accepted()",
      "permissions_required()", or "permissions_accepted()" if a role
      or permission is missing.

      Parameters:
         **cb** (*Callable**[**[**Callable**[**[**Any**]**,
         **Any**]**, **Optional**[**List**[**str**]**]**]**,
         **ResponseValue**]*) --

         Callback function with signature (func, params)

         func:
            the decorator function (e.g. roles_required)

         params:
            list of what (if any) was passed to the decorator.

      Return type:
         None

      Should return a Response or something Flask can create a
      Response from. Can raise an exception if it is handled as part
      of flask.errorhandler(<exception>)

      With the passed parameters the application could deliver a
      concise error message.

      New in version 3.3.0.

   want_json(fn)

      Function that returns True if response should be JSON (based on
      the request)

      Parameters:
         **fn** (*Callable**[**[**flask.Request**]**, **bool**]*) --

         Function with the following signature (request)

         request:
            Werkzueg/Flask request

      Return type:
         None

      The default implementation returns True if either the Content-
      Type is "application/json" or the best Accept header value is
      "application/json".

      New in version 3.3.0.

flask_security.current_user

   A proxy for the current user.

flask_security.Security.unauthorized_handler()

   If an endpoint fails authentication or authorization from one of
   the decorators described below (except "login_required"), a method
   annotated with this decorator will be called. For "login_required"
   (which is implemented in Flask-Login) use
   **flask_security.login_manager.unauthorized_handler**

   Deprecated since version 3.3.0.


Protecting Views
================

flask_security.anonymous_user_required(f)

   Decorator which requires that caller NOT be logged in. If a logged
   in user accesses an endpoint protected with this decorator they
   will be redirected to the *SECURITY_POST_LOGIN_VIEW*. If the caller
   requests a JSON response, a 400 will be returned.

   Changed in version 3.3.0: Support for JSON response was added.

   Parameters:
      **f** (*Callable**[**[**...**]**, **Any**]*) --

   Return type:
      *Callable*[[...], *Any*]

flask_security.http_auth_required(realm)

   Decorator that protects endpoints using Basic HTTP authentication.

   Parameters:
      **realm** (*Any*) -- optional realm name

   Return type:
      *Callable*[[...], *Any*]

   If authentication fails, then a 401 with the 'WWW-Authenticate'
   header set will be returned.

   Once authenticated, if so configured, CSRF protection will be
   tested.

flask_security.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*

   Once authenticated, if so configured, CSRF protection will be
   tested.

   Parameters:
      **fn** (*Callable**[**[**...**]**, **Any**]*) --

   Return type:
      *Callable*[[...], *Any*]

flask_security.auth_required(*auth_methods, within=- 1, grace=None)

   Decorator that protects endpoints through multiple mechanisms
   Example:

      @app.route('/dashboard')
      @auth_required('token', 'session')
      def dashboard():
          return 'Dashboard'

   Parameters:
      * **auth_methods** (*Optional**[**Union**[**str**,
        **Callable**[**[**]**, **List**[**str**]**]**]**]*) --
        Specified mechanisms (token, basic, session). If not specified
        then all current available mechanisms (except "basic") will be
        tried. A callable can also be passed (useful if you need
        app/request context). The callable must return a list.

      * **within** (*Union**[**int**, **float**,
        **Callable**[**[**]**, **datetime.timedelta**]**]*) --

        Add 'freshness' check to authentication. Is either an int
        specifying # of minutes, or a callable that returns a
        timedelta. For timedeltas, timedelta.total_seconds() is used
        for the calculations:

           * If > 0, then the caller must have authenticated within
             the time specified (as measured using the session
             cookie).

           * If 0 and not within the grace period (see below) the
             caller will always be redirected to re-authenticate.

           * If < 0 (the default) no freshness check is performed.

        Note that Basic Auth, by definition, is always 'fresh' and
        will never result in a redirect/error.

      * **grace** (*Optional**[**Union**[**int**, **float**,
        **Callable**[**[**]**, **datetime.timedelta**]**]**]*) -- Add
        a grace period for freshness checks. As above, either an int
        or a callable returning a timedelta. If not specified then
        "SECURITY_FRESHNESS_GRACE_PERIOD" is used. The grace period
        allows callers to complete the required operations w/o being
        prompted again. See
        "flask_security.check_and_update_authn_fresh()" for details.

   Return type:
      *Callable*[[...], *Any*]

   Note that regardless of order specified - they will be tried in the
   following order: token, session, basic.

   The first mechanism that succeeds is used, following that,
   depending on configuration, CSRF protection will be tested.

   On authentication failure *.Security.unauthorized_callback*
   (deprecated) or "Security.unauthn_handler()" will be called.

   As a side effect, upon successful authentication, the request
   global
      "fs_authn_via" will be set to the method ("basic", "token",
      "session")

   Note:

     If "basic" is specified in addition to other methods, then if
     authentication fails, a 401 with the "WWW-Authenticate" header
     will be returned - rather than being redirected to the login
     view.

   Changed in version 3.3.0: If "auth_methods" isn't specified, then
   all will be tried. Authentication mechanisms will always be tried
   in order of "token", "session", "basic" regardless of how they are
   specified in the "auth_methods" parameter.

   Changed in version 3.4.0: Added "within" and "grace" parameters to
   enforce a freshness check.

   Changed in version 3.4.4: If "auth_methods" isn't specified try all
   mechanisms EXCEPT "basic".

   Changed in version 4.0.0: auth_methods can be passed as a callable.

flask_security.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.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:
      **roles** (*str*) -- The required roles.

   Return type:
      *Callable*[[...], *Any*]

flask_security.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:
      **roles** (*str*) -- The possible roles.

   Return type:
      *Callable*[[...], *Any*]

flask_security.permissions_required(*fsperms)

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

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

   The current user must have BOTH permissions (via the roles it has)
   to view the page.

   N.B. Don't confuse these permissions with flask-principle
   Permission()!

   Parameters:
      **fsperms** (*str*) -- The required permissions.

   Return type:
      *Callable*[[...], *Any*]

   New in version 3.3.0.

flask_security.permissions_accepted(*fsperms)

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

      @app.route('/create_post')
      @permissions_accepted('editor-write', 'author-wrote')
      def create_post():
          return 'Create Post'

   The current user must have one of the permissions (via the roles it
   has) to view the page.

   N.B. Don't confuse these permissions with flask-principle
   Permission()!

   Parameters:
      **fsperms** (*str*) -- The possible permissions.

   Return type:
      *Callable*[[...], *Any*]

   New in version 3.3.0.

flask_security.unauth_csrf(fall_through=False)

   Decorator for endpoints that don't need authentication but do want
   CSRF checks (available via Header rather than just form). This is
   required when setting *WTF_CSRF_CHECK_DEFAULT* = **False** since in
   that case, without this decorator, the form validation will attempt
   to do the CSRF check, and that will fail since the csrf-token is in
   the header (for pure JSON requests).

   This decorator does nothing unless Flask-WTF::CSRFProtect has been
   initialized.

   This decorator does nothing if *WTF_CSRF_ENABLED* == **False**.

   This decorator will always require CSRF if the caller is
   authenticated.

   This decorator will suppress CSRF if caller isn't authenticated and
   has set the *SECURITY_CSRF_IGNORE_UNAUTH_ENDPOINTS* config
   variable.

   Parameters:
      **fall_through** (*bool*) -- if set to True, then if CSRF fails
      here - simply keep going. This is appropriate if underlying view
      is form based and once the form is instantiated, the csrf_token
      will be available. Note that this can mask some errors such as
      'The CSRF session token is missing.' meaning that the caller
      didn't send a session cookie and instead the caller might get a
      'The CSRF token is missing.' error.

   Return type:
      *Callable*[[...], *Any*]

   New in version 3.3.0.

flask_security.handle_csrf(method)

   Invoke CSRF protection based on authentication method.

   Usually this is called as part of a decorator, but if that isn't
   appropriate, endpoint code can call this directly.

   If CSRF protection is appropriate, this will call
   flask_wtf::protect() which will raise a ValidationError on CSRF
   failure.

   This routine does nothing if any of these are true:

      1. *WTF_CSRF_ENABLED* is set to False

      2. the Flask-WTF CSRF module hasn't been initialized

      3. csrfProtect already checked and accepted the token

   If the passed in method is not in
   *SECURITY_CSRF_PROTECT_MECHANISMS* then not only will no CSRF code
   be run, but a flag in the current context "fs_ignore_csrf" will be
   set so that downstream code knows to ignore any CSRF checks.

   New in version 3.3.0.

   Parameters:
      **method** (*Optional**[**str**]*) --

   Return type:
      None


User Object Helpers
===================

class flask_security.UserMixin

   Mixin for *User* model definitions

   calc_username()

      Come up with the best 'username' based on how the app is
      configured (via "SECURITY_USER_IDENTITY_ATTRIBUTES"). Returns
      the first non-null match (and converts to string). In theory
      this should NEVER be the empty string unless the user record
      isn't actually valid.

      New in version 3.4.0.

      Return type:
         str

   get_auth_token()

      Constructs the user's authentication token.

      Raises:
         **ValueError** -- If "fs_token_uniquifier" is part of model
         but not set.

      Return type:
         *Union*[str, bytes]

      Optionally use a separate uniquifier so that changing password
      doesn't invalidate auth tokens.

      This data MUST be securely signed using the
      "remember_token_serializer"

      Changed in version 4.0.0: If user model has
      "fs_token_uniquifier" - use that (raise ValueError if not set).
      Otherwise fallback to using "fs_uniqifier".

   get_id()

      Returns the user identification attribute. 'Alternative-token'
      for Flask-Login. This is always "fs_uniquifier".

      New in version 3.4.0.

      Return type:
         str

   get_redirect_qparams(existing=None)

      Return user info that will be added to redirect query params.

      Parameters:
         **existing** (*Optional**[**Dict**[**str**, **Any**]**]*) --
         A dict that will be updated.

      Returns:
         A dict whose keys will be query params and values will be
         query values.

      Return type:
         *Dict*[str, *Any*]

      The returned dict will always have an 'identity' key/value. If
      the User Model contains 'email', an 'email' key/value will
      added. All keys provided in 'existing' will also be merged in.

      New in version 3.2.0.

      Changed in version 4.0.0: Add 'identity' using
      UserMixin.calc_username() - email is optional.

   get_security_payload()

      Serialize user object as response payload. Override this to
      return any/all of the user object in JSON responses. Return a
      dict.

      Return type:
         *Dict*[str, *Any*]

   has_permission(permission)

      Returns *True* if user has this permission (via a role it has).

      Parameters:
         **permission** (*str*) -- permission string name

      Return type:
         bool

      New in version 3.3.0.

   has_role(role)

      Returns *True* if the user identifies with the specified role.

      Parameters:
         **role** (*Union**[**str**, **Role**]*) -- A role name or
         *Role* instance

      Return type:
         bool

   property is_active: bool

      Returns *True* if the user is active.

   tf_send_security_token(method, **kwargs)

      Generate and send the security code for two-factor.

      Parameters:
         * **method** (*str*) -- The method in which the code will be
           sent

         * **kwargs** (*Any*) -- Opaque parameters that are subject to
           change at any time

      Returns:
         None if successful, error message if not.

      Return type:
         *Optional*[str]

      This is a wrapper around "tf_send_security_token()" that can be
      overridden to manage any errors.

      New in version 3.4.0.

   us_send_security_token(method, **kwargs)

      Generate and send the security code for unified sign in.

      Parameters:
         * **method** (*str*) -- The method in which the code will be
           sent

         * **kwargs** (*Any*) -- Opaque parameters that are subject to
           change at any time

      Returns:
         None if successful, error message if not.

      Return type:
         *Optional*[str]

      This is a wrapper around "us_send_security_token()" that can be
      overridden to manage any errors.

      New in version 3.4.0.

   verify_and_update_password(password)

      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.

      N.B. you MUST call DB commit if you are using a session-based
      datastore (such as SqlAlchemy) since the user instance might
      have been altered (i.e. "app.security.datastore.commit()"). This
      is usually handled in the view.

      Parameters:
         **password** (*str*) -- A plaintext password to verify

      Return type:
         bool

      New in version 3.2.0.

   verify_auth_token(data)

      Perform additional verification of contents of auth token. Prior
      to this being called the token has been validated (via signing)
      and has not expired.

      Parameters:
         **data** (*Union**[**str**, **bytes**]*) -- the data as
         formulated by "get_auth_token()"

      Return type:
         bool

      New in version 3.3.0.

      Changed in version 4.0.0: If user model has
      "fs_token_uniquifier" - use that otherwise use "fs_uniquifier".

class flask_security.RoleMixin

   Mixin for *Role* model definitions

   add_permissions(permissions)

      Add one or more permissions to role.

      Parameters:
         **permissions** (*Union**[**set**, **list**, **str**]*) -- a
         set, list, or single string.

      Return type:
         None

      New in version 3.3.0.

      Deprecated since version 3.4.4: Use
      "UserDatastore.add_permissions_to_role()"

   get_permissions()

      Return set of permissions associated with role.

      Supports permissions being a comma separated string, an
      iterable, or a set based on how the underlying DB model was
      built.

      New in version 3.3.0.

      Return type:
         set

   remove_permissions(permissions)

      Remove one or more permissions from role.

      Parameters:
         **permissions** (*Union**[**set**, **list**, **str**]*) -- a
         set, list, or single string.

      Return type:
         None

      New in version 3.3.0.

      Deprecated since version 3.4.4: Use
      "UserDatastore.remove_permissions_from_role()"

class flask_security.AnonymousUser

   AnonymousUser definition

   has_role(*args)

      Returns *False*


Datastores
==========

class flask_security.UserDatastore(user_model, role_model)

   Abstracted user datastore.

   Parameters:
      * **user_model** (*Type**[**User**]*) -- A user model class
        definition

      * **role_model** (*Type**[**Role**]*) -- A role model class
        definition

   Important:

     For mutating operations, the user/role will be added to the
     datastore (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().

   activate_user(user)

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

      Parameters:
         **user** (*User*) -- The user to activate

      Return type:
         bool

   add_permissions_to_role(role, permissions)

      Add one or more permissions to role.

      Parameters:
         * **role** (*Union**[**Role**, **str**]*) -- The role to
           modify. Can be a Role object or string role name

         * **permissions** (*Union**[**set**, **list**, **str**]*) --
           a set, list, or single string.

      Returns:
         True if permissions added, False if role doesn't exist.

      Return type:
         bool

      Caller must commit to DB.

      New in version 4.0.0.

   add_role_to_user(user, role)

      Adds a role to a user.

      Parameters:
         * **user** (*User*) -- The user to manipulate.

         * **role** (*Union**[**Role**, **str**]*) -- The role to add
           to the user. Can be a Role object or string role name

      Returns:
         True is role was added, False if role already existed.

      Return type:
         bool

   create_role(**kwargs)

      Creates and returns a new role from the given parameters.
      Supported params (depending on RoleModel):

      Parameters:
         * **name** -- Role name

         * **permissions** --

           a comma delimited list of permissions, a set or a list.
           These are user-defined strings that correspond to strings
           used with @permissions_required()

           New in version 3.3.0.

         * **kwargs** (*Any*) --

      Return type:
         Role

   create_user(**kwargs)

      Creates and returns a new user from the given parameters.

      Parameters:
         * **email** -- required.

         * **password** -- Hashed password.

         * **roles** -- list of roles to be added to user. Can be Role
           objects or strings

         * **kwargs** (*Any*) --

      Return type:
         User

      Any other element of the User data model may be supplied as
      well.

      Note:

        No normalization is done on email - it is assumed the caller
        has already done that.Best practice is:

           try:
               enorm = app.security._mail_util.validate(email)
           except ValueError:

      Note:

        The roles kwparam is modified as part of the call - it will,
        if necessary be converted from names to role instances.

      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)".Furthermore, no validation
        nor normalization is done on the password (e.g for minimum
        length).Best practice is:

           pbad, pnorm = app.security._password_util.validate(password, True)

        Look for *pbad* being None. Pass the normalized password
        *pnorm* to this method.

      The new user's "active" property will be set to "True" unless
      explicitly set to "False" in *kwargs* (e.g. active = False)

   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** (*User*) -- The user to deactivate

      Return type:
         bool

   delete_user(user)

      Deletes the specified user.

      Parameters:
         **user** (*User*) -- The user to delete

      Return type:
         None

   find_or_create_role(name, **kwargs)

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

      Parameters:
         * **name** (*str*) --

         * **kwargs** (*Any*) --

      Return type:
         Role

   find_role(role)

      Returns a role matching the provided name.

      Parameters:
         **role** (*str*) --

      Return type:
         *Optional*[Role]

   find_user(case_insensitive=False, **kwargs)

      Returns a user matching the provided parameters.

      Parameters:
         * **case_insensitive** (*bool*) --

         * **kwargs** (*Any*) --

      Return type:
         *Optional*[User]

   remove_permissions_from_role(role, permissions)

      Remove one or more permissions from a role.

      Parameters:
         * **role** (*Union**[**Role**, **str**]*) -- The role to
           modify. Can be a Role object or string role name

         * **permissions** (*Union**[**set**, **list**, **str**]*) --
           a set, list, or single string.

      Returns:
         True if permissions removed, False if role doesn't exist.

      Return type:
         bool

      Caller must commit to DB.

      New in version 4.0.0.

   remove_role_from_user(user, role)

      Removes a role from a user.

      Parameters:
         * **user** (*User*) -- The user to manipulate. Can be an User
           object or email

         * **role** (*Union**[**Role**, **str**]*) -- The role to
           remove from the user. Can be a Role object or string role
           name

      Returns:
         True if role was removed, False if role doesn't exist or user
         didn't have role.

      Return type:
         bool

   reset_user_access(user)

      Use this method to reset user authentication methods in the case
      of compromise. This will:

         * reset fs_uniquifier - which causes session cookie, remember
           cookie, auth tokens to be unusable

         * reset fs_token_uniquifier (if present) - cause auth tokens
           to be unusable

         * remove all unified signin TOTP secrets so those can't be
           used

         * remove all two-factor secrets so those can't be used

      Note that if using unified sign in and allow 'email' as a way to
      receive a code; if the email is compromised - login is still
      possible. To handle this - it is better to deactivate the user.

      Note - this method isn't used directly by Flask-Security - it is
      provided as a helper for an application's administrative needs.

      Remember to call commit on DB if needed.

      New in version 3.4.1.

      Parameters:
         **user** (*User*) --

      Return type:
         None

   set_token_uniquifier(user, uniquifier=None)

      Set user's auth token identity key. This will immediately render
      outstanding auth tokens invalid.

      Parameters:
         * **user** (*User*) -- User to modify

         * **uniquifier** (*Optional**[**str**]*) -- Unique value - if
           none then uuid.uuid4().hex is used

      Return type:
         None

      This method is a no-op if the user model doesn't contain the
      attribute "fs_token_uniquifier"

      New in version 4.0.0.

   set_uniquifier(user, uniquifier=None)

      Set user's Flask-Security identity key. This will immediately
      render outstanding auth tokens, session cookies and remember
      cookies invalid.

      Parameters:
         * **user** (*User*) -- User to modify

         * **uniquifier** (*Optional**[**str**]*) -- Unique value - if
           none then uuid.uuid4().hex is used

      Return type:
         None

      New in version 3.3.0.

   tf_reset(user)

      Disable two-factor auth for user

      Parameters:
         **user** (*User*) --

      Return type:
         None

   tf_set(user, primary_method, totp_secret=None, phone=None)

      Set two-factor info into user record. This carefully only
      changes things if different.

      If totp_secret isn't provided - existing one won't be changed.
      If phone isn't provided, the existing phone number won't be
      changed.

      This could be called from an application to apiori setup a user
      for two factor without the user having to go through the setup
      process.

      To get a totp_secret - use
      "app.security._totp_factory.generate_totp_secret()"

      Parameters:
         * **user** (*User*) --

         * **primary_method** (*str*) --

         * **totp_secret** (*Optional**[**str**]*) --

         * **phone** (*Optional**[**str**]*) --

      Return type:
         None

   toggle_active(user)

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

      Parameters:
         **user** (*User*) --

      Return type:
         bool

   us_get_totp_secrets(user)

      Return totp secrets. These are json encoded in the DB.

      Returns a dict with methods as keys and secrets as values.

      New in version 3.4.0.

      Parameters:
         **user** (*User*) --

      Return type:
         *Dict*[str, str]

   us_put_totp_secrets(user, secrets)

      Save secrets. Assume to be a dict (or None) with keys as
      methods, and values as (encrypted) secrets.

      New in version 3.4.0.

      Parameters:
         * **user** (*User*) --

         * **secrets** (*Optional**[**Dict**[**str**, **str**]**]*) --

      Return type:
         None

   us_reset(user)

      Disable unified sign in for user. Be aware that if "email" is an
      allowed way to receive codes, they will still work (as totp
      secrets are generated on the fly). This will disable
      authenticator app and SMS.

      Parameters:
         **user** (*User*) --

      Return type:
         None

   us_set(user, method, totp_secret=None, phone=None)

      Set unified sign in info into user record.

      If totp_secret isn't provided - existing one won't be changed.
      If phone isn't provided, the existing phone number won't be
      changed.

      This could be called from an application to apiori setup a user
      for unified sign in without the user having to go through the
      setup process.

      To get a totp_secret - use
      "app.security._totp_factory.generate_totp_secret()"

      Parameters:
         * **user** (*User*) --

         * **method** (*str*) --

         * **totp_secret** (*Optional**[**str**]*) --

         * **phone** (*Optional**[**str**]*) --

      Return type:
         None

class flask_security.SQLAlchemyUserDatastore(db, user_model, role_model)

   Bases: "flask_security.datastore.SQLAlchemyDatastore",
   "flask_security.datastore.UserDatastore"

   A UserDatastore implementation that assumes the use of Flask-
   SQLAlchemy for datastore transactions.

   Parameters:
      * **db** (*flask_sqlalchemy.SQLAlchemy*) --

      * **user_model** (*Type**[**User**]*) -- See Models.

      * **role_model** (*Type**[**Role**]*) -- See Models.

class flask_security.SQLAlchemySessionUserDatastore(session, user_model, role_model)

   Bases: "flask_security.datastore.SQLAlchemyUserDatastore",
   "flask_security.datastore.SQLAlchemyDatastore"

   A UserDatastore implementation that directly uses SQLAlchemy's
   session API.

   Parameters:
      * **session** (*sqlalchemy.orm.scoping.scoped_session*) --

      * **user_model** (*Type**[**User**]*) -- See Models.

      * **role_model** (*Type**[**Role**]*) -- See Models.

class flask_security.MongoEngineUserDatastore(db, user_model, role_model)

   Bases: "flask_security.datastore.MongoEngineDatastore",
   "flask_security.datastore.UserDatastore"

   A UserDatastore implementation that assumes the use of Flask-
   MongoEngine for datastore transactions.

   Parameters:
      * **db** (*flask_mongoengine.MongoEngine*) --

      * **user_model** (*Type**[**User**]*) -- See Models.

      * **role_model** (*Type**[**Role**]*) -- See Models.

class flask_security.PeeweeUserDatastore(db, user_model, role_model, role_link)

   Bases: "flask_security.datastore.PeeweeDatastore",
   "flask_security.datastore.UserDatastore"

   A UserDatastore implementation that assumes the use of Peewee Flask
   utils for datastore transactions.

   Parameters:
      * **db** --

      * **user_model** -- See Models.

      * **role_model** -- See Models.

      * **role_link** --

class flask_security.PonyUserDatastore(db, user_model, role_model)

   Bases: "flask_security.datastore.PonyDatastore",
   "flask_security.datastore.UserDatastore"

   A UserDatastore implementation that assumes the use of PonyORM for
   datastore transactions.

   Code primarily from https://github.com/ET-CS but taken over after
   being abandoned.

   Parameters:
      * **db** --

      * **user_model** -- See Models.

      * **role_model** -- See Models.

class flask_security.datastore.SQLAlchemyDatastore(db)

   Internal class implementing DataStore interface.

class flask_security.datastore.MongoEngineDatastore(db)

   Internal class implementing DataStore interface.

class flask_security.datastore.PeeweeDatastore(db)

   Internal class implementing DataStore interface.

class flask_security.datastore.PonyDatastore(db)

   Internal class implementing DataStore interface.

class User

   The User model. This must be provided by the application. See
   Models.

class Role

   The Role model. This must be provided by the application. See
   Models.


Utils
=====

flask_security.login_user(user, remember=None, authn_via=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** (*User*) -- The user to login

      * **remember** (*Optional**[**bool**]*) -- Flag specifying if
        the remember cookie should be set. If "None" use value of
        SECURITY_DEFAULT_REMEMBER_ME

      * **authn_via** (*Optional**[**List**[**str**]**]*) -- A list of
        strings denoting which mechanism(s) the user authenticated
        with. These should be one or more of ["password", "sms",
        "authenticator", "email"] or other 'auto-login' mechanisms.

   Returns:
      True if user successfully logged in.

   Return type:
      bool

flask_security.logout_user()

   Logs out the current user.

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

   This sends an "identity_changed" signal to note that the current
   identity is now the *AnonymousIdentity*

   Return type:
      None

flask_security.check_and_update_authn_fresh(within, grace, method=None)

   Check if user authenticated within specified time and update grace
   period.

   Parameters:
      * **within** (*datetime.timedelta*) -- A timedelta specifying
        the maximum time in the past that the caller authenticated
        that is still considered 'fresh'.

      * **grace** (*datetime.timedelta*) -- A timedelta that, if the
        current session is considered 'fresh' will set a grace period
        for which freshness won't be checked. The intent here is that
        the caller shouldn't get part-way though a set of operations
        and suddenly be required to authenticate again.

      * **method** (*Optional**[**str**]*) -- Optional - if set and ==
        "basic" then will always return True. (since basic-auth sends
        username/password on every request)

   Return type:
      bool

   If within.total_seconds() is negative, will always return True
   (always 'fresh'). This effectively just disables this entire
   mechanism.

   If "fs_gexp" is in the session and the current timestamp is less
   than that, return True and extend grace time (i.e. set fs_gexp to
   current time + grace).

   If not within the grace period, and within.total_seconds() is 0,
   return False (not fresh).

   Be aware that for this to work, sessions and therefore session
   cookies must be functioning and being sent as part of the request.
   If the required state isn't in the session cookie then return False
   (not 'fresh').

   Warning:

     Be sure the caller is already authenticated PRIOR to calling this
     method.

   New in version 3.4.0.

   Changed in version 4.0.0: Added *method* parameter.

flask_security.get_hmac(password)

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

   Parameters:
      **password** (*Union**[**str**, **bytes**]*) -- The password to
      sign

   Return type:
      bytes

flask_security.get_request_attr(name)

   Retrieve a request local attribute.

   Currently public attributes are:

   **fs_authn_via**
      will be set to the authentication mechanism (session, token,
      basic) that the current request was authenticated with.

   Returns None if attribute doesn't exist.

   New in version 4.0.0.

   Parameters:
      **name** (*str*) --

   Return type:
      *Any*

flask_security.verify_password(password, password_hash)

   Returns "True" if the password matches the supplied hash.

   Parameters:
      * **password** (*Union**[**str**, **bytes**]*) -- A plaintext
        password to verify

      * **password_hash** (*Union**[**str**, **bytes**]*) -- The
        expected hash value of the password (usually from your
        database)

   Return type:
      bool

   Note:

     Make sure that the password passed in has already been
     normalized.

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

   N.B. you MUST call DB commit if you are using a session-based
   datastore (such as SqlAlchemy) since the user instance might have
   been altered (i.e. "app.security.datastore.commit()"). This is
   usually handled in the view.

   Parameters:
      * **password** (*Union**[**str**, **bytes**]*) -- A plaintext
        password to verify

      * **user** (*User*) -- The user to verify against

   Return type:
      bool

   Tip:

     This should not be called directly - rather use
     "UserMixin.verify_and_update_password()"

flask_security.hash_password(password)

   Hash the specified plaintext password.

   Unless the hash algorithm (as specified by
   *SECURITY_PASSWORD_HASH*) is listed in the configuration variable
   *SECURITY_PASSWORD_SINGLE_HASH*, perform a double hash - first
   create an HMAC from the plaintext password and the value of
   *SECURITY_PASSWORD_SALT*, then use the configured hashing
   algorithm. This satisfies OWASP/ASVS section 2.4.5: 'provide
   additional iteration of a key derivation'.

   New in version 2.0.2.

   Parameters:
      **password** (*Union**[**str**, **bytes**]*) -- The plaintext
      password to hash

   Return type:
      *Any*

flask_security.admin_change_password(user, new_passwd, notify=True)

   Administratively change a user's password. Note that this will
   immediately render the user's existing sessions (and possibly
   authentication tokens) invalid.

   It is up to the caller to inform the user of their new password by
   some out-of-band means.

   Parameters:
      * **user** (*User*) -- The user object to change

      * **new_passwd** (*str*) -- The new plain-text password to
        assign to the user.

      * **notify** (*bool*) -- If True and
        SECURITY_SEND_PASSWORD_CHANGE_EMAIL is True send the
        'change_notice' email to the user.

   Return type:
      None

flask_security.uia_phone_mapper(identity)

   Used to match identity as a phone number. This is a simple proxy to
   "PhoneUtil"

   See "SECURITY_USER_IDENTITY_ATTRIBUTES".

   New in version 3.4.0.

   Parameters:
      **identity** (*str*) --

   Return type:
      *Optional*[str]

flask_security.uia_email_mapper(identity)

   Used to match identity as an email.

   Returns:
      Normalized email or None if not valid email.

   Parameters:
      **identity** (*str*) --

   Return type:
      *Optional*[str]

   See "SECURITY_USER_IDENTITY_ATTRIBUTES".

   New in version 3.4.0.

flask_security.uia_username_mapper(identity)

   Used to match identity as a username. This is a simple proxy to
   "UsernameUtil"

   See "SECURITY_USER_IDENTITY_ATTRIBUTES".

   New in version 4.1.0.

   Parameters:
      **identity** (*str*) --

   Return type:
      *Optional*[str]

flask_security.url_for_security(endpoint, **values)

   Return a URL for the security blueprint

   Parameters:
      * **endpoint** (*str*) -- the endpoint of the URL (name of the
        function)

      * **values** (*Union**[**str**, **bool**]*) -- 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.

   Return type:
      str

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

   Send an email.

   Parameters:
      * **subject** -- Email subject

      * **recipient** -- Email recipient

      * **template** -- The name of the email template

      * **context** -- The context to render the template with

   This formats the email and passes it off to "MailUtil" to actually
   send the message.

flask_security.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 serializer. Can be one of
        the following: "confirm", "login", "reset"

      * **max_age** -- The name of the max age config option. Can be
        one of the following: "CONFIRM_EMAIL", "LOGIN",
        "RESET_PASSWORD"

flask_security.check_and_get_token_status(token, serializer_name, within)

   Get the status of a token and return data.

   Parameters:
      * **token** (*str*) -- The token to check

      * **serializer_name** (*str*) -- The name of the serializer. Can
        be one of the following: "confirm", "login", "reset",
        "us_setup" "remember", "two_factor_validity"

      * **within** (*datetime.timedelta*) -- max age - passed as a
        timedelta

   Returns:
      a tuple of (expired, invalid, data)

   Return type:
      *Tuple*[bool, bool, *Any*]

   New in version 3.4.0.

flask_security.get_url(endpoint_or_url, qparams=None)

   Returns a URL if a valid endpoint is found. Otherwise, returns the
   provided value.

   Parameters:
      * **endpoint_or_url** (*Optional**[**str**]*) -- The endpoint
        name or URL to default to

      * **qparams** (*Optional**[**Dict**[**str**, **str**]**]*) --
        additional query params to add to end of url

   Returns:
      URL

   Return type:
      *Optional*[str]

flask_security.password_length_validator(password)

   Test password for length.

   Parameters:
      **password** (*str*) -- Plain text password to check

   Returns:
      "None" if password conforms to length requirements, a list of
      error/suggestions if not.

   Return type:
      *Optional*[*List*[str]]

   New in version 3.4.0.

flask_security.password_complexity_validator(password, is_register, **kwargs)

   Test password for complexity.

   Currently just supports 'zxcvbn'.

   Parameters:
      * **password** (*str*) -- Plain text password to check

      * **is_register** (*bool*) -- if True then kwargs are arbitrary
        additional info. (e.g. info from a registration form). If
        False, must be a SINGLE key "user" that corresponds to the
        current_user. All string values will be extracted and sent to
        the complexity checker.

      * **kwargs** (*Any*) --

   Returns:
      "None" if password is complex enough, a list of
      error/suggestions if not. Be aware that zxcvbn does not (easily)
      provide a way to localize messages.

   Return type:
      *Optional*[*List*[str]]

   New in version 3.4.0.

flask_security.password_breached_validator(password)

   Check if password on breached list. Does nothing unless
   "SECURITY_PASSWORD_CHECK_BREACHED" is set. If password is found on
   the breached list, return an error if the count is greater than or
   equal to "SECURITY_PASSWORD_BREACHED_COUNT". Uses "pwned()".

   Parameters:
      **password** (*str*) -- Plain text password to check

   Returns:
      "None" if password passes breached tests, else a list of error
      messages.

   Return type:
      *Optional*[*List*[str]]

   New in version 3.4.0.

flask_security.pwned(password)

   Check password against pwnedpasswords API using k-Anonymity.
   https://haveibeenpwned.com/API/v3

   Returns:
      Count of password in DB (0 means hasn't been compromised)

   Parameters:
      **password** (*str*) --

   Return type:
      int

   Can raise HTTPError

   New in version 3.4.0.

flask_security.transform_url(url, qparams=None, **kwargs)

   Modify url

   Parameters:
      * **url** (*Optional**[**str**]*) -- url to transform (can be
        relative)

      * **qparams** (*Optional**[**Dict**[**str**, **str**]**]*) --
        additional query params to add to end of url

      * **kwargs** (*str*) -- pieces of URL to modify - e.g.
        netloc=localhost:8000

   Returns:
      Modified URL

   Return type:
      *Optional*[str]

   New in version 3.2.0.

flask_security.unique_identity_attribute(form, field)

   A validator that checks the field data against all configured
   SECURITY_USER_IDENTITY_ATTRIBUTES. This can be used as part of
   registration.

   Be aware that the "mapper" function likely also normalizes the
   input in addition to validating it.

   Parameters:
      * **form** --

      * **field** --

   Returns:
      Nothing; if field data corresponds to an existing User,
      ValidationError is raised.

flask_security.us_send_security_token(user, method, totp_secret, phone_number, send_magic_link=False)

   Generate and send the security code.

   Parameters:
      * **user** -- The user to send the code to

      * **method** -- The method in which the code will be sent

      * **totp_secret** -- the unique shared secret of the user

      * **phone_number** -- If 'sms' phone number to send to

      * **send_magic_link** -- If true a magic link that can be
        clicked on will be sent. This shouldn't be sent during a
        setup.

   There is no return value - it is assumed that exceptions are thrown
   by underlying methods that callers can catch.

   Flask-Security code should NOT call this directly - call
   "UserMixin.us_send_security_token()"

   New in version 3.4.0.

flask_security.tf_send_security_token(user, method, totp_secret, phone_number)

   Sends the security token via email/sms for the specified user.

   Parameters:
      * **user** -- The user to send the code to

      * **method** -- The method in which the code will be sent
        ('email' or 'sms', or 'authenticator') at the moment

      * **totp_secret** -- a unique shared secret of the user

      * **phone_number** -- If 'sms' phone number to send to

   There is no return value - it is assumed that exceptions are thrown
   by underlying methods that callers can catch.

   Flask-Security code should NOT call this directly - call
   "UserMixin.tf_send_security_token()"

class flask_security.FsJsonEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

   Flask-Security JSON encoder. Extends Flask's JSONencoder to handle
   lazy-text.

   New in version 3.3.0.

class flask_security.Totp(secrets, issuer)

   Encapsulate usage of Passlib TOTP functionality.

   Flask-Security doesn't implement any replay-attack protection out
   of the box as suggested by:
   https://passlib.readthedocs.io/en/stable/narr/totp-tutorial.html
   #match-verify

   Subclass this and implement the get/set last_counter methods. Your
   subclass can be registered at Flask-Security
   creation/initialization time.

   New in version 3.4.0.

   Parameters:
      * **secrets** (*Dict**[**Union**[**str**, **int**]**, **str**]*)
        --

      * **issuer** (*str*) --

   generate_qrcode(username, totp)

      Generate QRcode
         Using username, totp, generate the actual QRcode image. This
         method can be overridden to fine-tune how the image is
         created - such as size, color etc.

         It must return a string suitable for use in an <img src=xx>
         tag.

      New in version 4.0.0.

      Parameters:
         * **username** (*str*) --

         * **totp** (*str*) --

      Return type:
         str

   get_last_counter(user)

      Implement this to fetch stored last_counter from cache.

      Parameters:
         **user** (*User*) -- User model

      Returns:
         last_counter as stored in set_last_counter()

      Return type:
         *Optional*[passlib.totp.TotpMatch]

   set_last_counter(user, tmatch)

      Implement this to cache last_counter.

      Parameters:
         * **user** (*User*) -- User model

         * **tmatch** (*passlib.totp.TotpMatch*) -- a TotpMatch as
           returned from totp.verify()

      Return type:
         None

class flask_security.PhoneUtil(app)

   Provide parsing and validation for user inputted phone numbers.
   Subclass this to use a different underlying phone number parsing
   library.

   To provide your own implementation, pass in the class as
   "phone_util_cls" at init time. Your class will be instantiated once
   as part of Flask-Security initialization.

   New in version 3.4.0.

   Changed in version 4.0.0: __init__ takes app argument, and is
   instantiated at Flask-Security initialization time rather than at
   first request.

   Parameters:
      **app** (*flask.Flask*) --

   __init__(app)

      Instantiate class.

      Parameters:
         **app** (*flask.Flask*) -- The Flask application being
         initialized.

   get_canonical_form(input_data)

      Validate and return a canonical form to be stored in DB and
      compared against. Returns "None" if input isn't a valid phone
      number.

      Parameters:
         **input_data** (*str*) --

      Return type:
         *Optional*[str]

   validate_phone_number(input_data)

      Return "None" if a valid phone number else the "PHONE_INVALID"
      error message.

      Parameters:
         **input_data** (*str*) --

      Return type:
         *Optional*[str]

class flask_security.MailUtil(app)

   Utility class providing methods for validating, normalizing and
   sending emails.

   This default class uses the email_validator package to handle
   validation and normalization, and the flask_mail package to send
   emails.

   To provide your own implementation, pass in the class as
   "mail_util_cls" at init time.  Your class will be instantiated once
   as part of app initialization.

   New in version 4.0.0.

   Parameters:
      **app** (*flask.Flask*) --

   __init__(app)

      Instantiate class.

      Parameters:
         **app** (*flask.Flask*) -- The Flask application being
         initialized.

   normalize(email)

      Given an input email - return a normalized version. Must be
      called in app context and uses "SECURITY_EMAIL_VALIDATOR_ARGS"
      config variable to pass any relevant arguments to
      email_validator.validate_email() method.

      Will throw email_validator.EmailNotValidError if email isn't
      even valid.

      Parameters:
         **email** (*str*) --

      Return type:
         str

   send_mail(template, subject, recipient, sender, body, html, user, **kwargs)

      Send an email via the Flask-Mail extension.

      Parameters:
         * **template** (*str*) -- the Template name. The message has
           already been rendered however this might be useful to
           differentiate why the email is being sent.

         * **subject** (*str*) -- Email subject

         * **recipient** (*str*) -- Email recipient

         * **sender** (*Union**[**str**, **tuple**]*) -- who to send
           email as (see "SECURITY_EMAIL_SENDER")

         * **body** (*str*) -- the rendered body (text)

         * **html** (*str*) -- the rendered body (html)

         * **user** (*User*) -- the user model

         * **kwargs** (*Any*) --

      Return type:
         None

   validate(email)

      Validate the given email. If valid, the normalized version is
      returned.

      ValueError is thrown if not valid.

      Parameters:
         **email** (*str*) --

      Return type:
         str

class flask_security.PasswordUtil(app)

   Utility class providing methods for validating and normalizing
   passwords.

   To provide your own implementation, pass in the class as
   "password_util_cls" at init time.  Your class will be instantiated
   once as part of app initialization.

   New in version 4.0.0.

   Parameters:
      **app** (*flask.Flask*) --

   __init__(app)

      Instantiate class.

      Parameters:
         **app** (*flask.Flask*) -- The Flask application being
         initialized.

   normalize(password)

      Given an input password - return a normalized version (using
      Python's unicodedata.normalize()). Must be called in app context
      and uses "SECURITY_PASSWORD_NORMALIZE_FORM" config variable.

      Parameters:
         **password** (*str*) --

      Return type:
         str

   validate(password, is_register, **kwargs)

      Password validation. Called in app/request context.

      If is_register is True then kwargs will be the contents of the
      register form. If is_register is False, then there is a single
      kwarg "user" which has the current user data model.

      The password is first normalized then validated. Return value is
      a tuple ([msgs], normalized_password)

      Parameters:
         * **password** (*str*) --

         * **is_register** (*bool*) --

         * **kwargs** (*Any*) --

      Return type:
         *Tuple*[*Optional*[*List*], str]

class flask_security.UsernameUtil(app)

   Utility class providing methods for validating and normalizing
   usernames.

   To provide your own implementation, pass in the class as
   "username_util_cls" at init time.  Your class will be instantiated
   once as part of app initialization.

   New in version 4.1.0.

   Parameters:
      **app** (*flask.Flask*) --

   __init__(app)

      Instantiate class.

      Parameters:
         **app** (*flask.Flask*) -- The Flask application being
         initialized.

   check_username(username)

      Given a username - check for allowable character categories.
      This is broken out so applications can easily override this
      method only.

      By default allow letters and numbers (using
      unicodedata.category).

      Returns None if allowed, error message if not allowed.

      Parameters:
         **username** (*str*) --

      Return type:
         *Optional*[str]

   normalize(username)

      Given an input username - return a clean (using bleach) and
      normalized (using Python's unicodedata.normalize()) version.
      Must be called in app context and uses
      "SECURITY_USERNAME_NORMALIZE_FORM" config variable.

      Parameters:
         **username** (*str*) --

      Return type:
         str

   validate(username)

      Username validation. Called in app/request context.

      The username is first validated then normalized. Input is
      restricted/validated via a call to check_username. Return value
      is a tuple (msg, normalized_username). msg will be None if
      properly validated.

      Parameters:
         **username** (*str*) --

      Return type:
         *Tuple*[*Optional*[str], *Optional*[str]]

class flask_security.SmsSenderBaseClass(*args, **kwargs)

   abstract send_sms(from_number, to_number, msg)

      Abstract method for sending sms messages

      New in version 3.2.0.

      Parameters:
         * **from_number** (*str*) --

         * **to_number** (*str*) --

         * **msg** (*str*) --

      Return type:
         None

class flask_security.SmsSenderFactory

   classmethod createSender(name, *args, **kwargs)

      Initialize an SMS sender.

      Parameters:
         **name** -- Name as registered in SmsSenderFactory:senders
         (e.g. 'Twilio')

      New in version 3.2.0.


Signals
=======

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

Tip:

  Remember to add "**extra_args" to your signature so that if we add
  additional parameters in the future your code doesn't break.

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_authenticated

   Sent when a user successfully authenticates. In addition to the app
   (which is the sender), it is passed *user*, and *authn_via*
   arguments. The *authn_via* argument specifies how the user
   authenticated - it will be a list with possible values of
   "password", "sms", "authenticator", "email", "confirm", "reset",
   "register".

   New in version 3.4.0.

user_registered

   Sent when a user registers on the site. In addition to the app
   (which is the sender), it is passed *user*, *confirm_token*
   (deprecated), *confirmation_token* and *form_data* arguments.
   *form_data* is a dictionary representation of registration form's
   content received with the registration request.

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* and
   *confirmation_token* arguments.

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*, *token* (deprecated),
   and *reset_token* arguments.

tf_code_confirmed

   Sent when a user performs two-factor authentication login on the
   site. In addition to the app (which is the sender), it is passed
   *user* and *method* arguments.

   New in version 3.3.0.

tf_profile_changed

   Sent when two-factor is used and user logs in. In addition to the
   app (which is the sender), it is passed *user* and *method*
   arguments.

   New in version 3.3.0.

tf_disabled

   Sent when two-factor is disabled. In addition to the app (which is
   the sender), it is passed *user* argument.

   New in version 3.3.0.

tf_security_token_sent

   Sent when a two factor security/access code is sent. In addition to
   the app (which is the sender), it is passed *user*, *method*, and
   *token* arguments.

   New in version 3.3.0.

us_security_token_sent

   Sent when a unified sign in access code is sent. In addition to the
   app (which is the sender), it is passed *user*, *method*, *token*
   (deprecated), *login_token*, *phone_number*, and *send_magic_link*
   arguments.

   New in version 3.4.0.

us_profile_changed

   Sent when user completes changing their unified sign in profile. In
   addition to the app (which is the sender), it is passed *user* and
   *method* arguments.

   New in version 3.4.0.
