Skip to content
Back to top
View this page

# API Documentation

class flask_httpauth.HTTPBasicAuth(scheme=None, realm=None)

  Create a basic authentication object.

  If the optional `scheme` argument is provided, it will be used instead of the standard “Basic” scheme in the `WWW-Authenticate` response. A fairly common practice is to use a custom scheme to prevent browsers from prompting the user to login.

  The `realm` argument can be used to provide an application defined realm with the `WWW-Authenticate` header.

  current_user()

    The user object returned by the `verify_password` callback on successful authentication. If no user is returned by the callback, this is set to the username passed by the client. Example:

        @app.route('/')
        @auth.login_required
        def index():
            user = auth.current_user()
            return "Hello, {}!".format(user.name)

  error_handler(f)

    Decorator for a function that will be called by the framework when it is necessary to send an authentication error back to the client. The function can take one argument, the status code of the error, which can be 401 (incorrect credentials) or 403 (correct, but insufficient credentials). To preserve compatiiblity with older releases of this package, the function can also be defined without arguments. The return value from this function must by any accepted response type in Flask routes. If this callback isn’t provided a default error response is generated. Example:

        @auth.error_handler
        def auth_error(status):
            return "Access Denied", status

  get_password(f)

    Deprecated Decorator for a function that will be called by the framework to obtain the password for a given user. Example:

        @auth.get_password
        def get_password(username):
            return db.get_user_password(username)

  get_user_roles(f)

    Decorator for a function that will be called by the framework to obtain the roles assigned to a given user. The callback function takes a single argument, the user for which roles are requested. The user object passed to this function will be the one returned by the “verify” callback. If the verify callback returned `True` instead of a user object, then the `Authorization` object provided by Flask will be passed to this function. The function should return the role or list of roles that belong to the user. Example:

        @auth.get_user_roles
        def get_user_roles(user):
            return user.get_roles()

  hash_password(f)

    Deprecated Decorator for a function that will be called by the framework to apply a custom hashing algorithm to the password provided by the client. If this callback isn’t provided the password will be checked unchanged. The callback can take one or two arguments. The one argument version receives the password to hash, while the two argument version receives the username and the password in that order. Example single argument callback:

        @auth.hash_password
        def hash_password(password):
            return md5(password).hexdigest()

    Example two argument callback:

        @auth.hash_password
        def hash_pw(username, password):
            salt = get_salt(username)
            return hash(password, salt)

  login_required(f=None, role=None, optional=None)

    Decorator for a function that will be called when authentication is successful. This will typically be a Flask view function. Example:

        @app.route('/private')
        @auth.login_required
        def private_page():
            return "Only for authorized people!"

    An optional `role` argument can be given to further restrict access by roles. Example:

        @app.route('/private')
        @auth.login_required(role='admin')
        def private_page():
            return "Only for admins!"

    An optional `optional` argument can be set to `True` to allow the route to execute also when authentication is not included with the request, in which case `auth.current_user()` will be set to `None`. Example:

        @app.route('/private')
        @auth.login_required(optional=True)
        def private_page():
            user = auth.current_user()
            return "Hello {}!".format(
                user.name if user is not None else 'anonymous')

  username()

    Deprecated A view function that is protected with this class can access the logged username through this method. Example:

        @app.route('/')
        @auth.login_required
        def index():
            return "Hello, {}!".format(auth.username())

  verify_password(f)

    Decorator for a function that will be called by the framework to verify that the username and password combination provided by the client are valid. The callback function takes two arguments, the username and the password. It must return the user object if credentials are valid, or `True` if a user object is not available. In case of failed authentication, it should return `None` or `False`. Example usage:

        @auth.verify_password
        def verify_password(username, password):
            user = User.query.filter_by(username).first()
            if user and passlib.hash.sha256_crypt.verify(
                    password, user.password_hash):
                return user

    If this callback is defined, it is also invoked when the request does not have the `Authorization` header with user credentials, and in this case both the `username` and `password` arguments are set to empty strings. The application can opt to return `True` in this case and that will allow anonymous users access to the route. The callback function can indicate that the user is anonymous by writing a state variable to `flask.g` or by checking if `auth.current_user()` is `None`.

    Note that when a `verify_password` callback is provided the `get_password` and `hash_password` callbacks are not used.

class flask_httpauth.HTTPDigestAuth(scheme=None, realm=None, use_ha1_pw=False, qop='auth', algorithm='MD5')

  Create a digest authentication object.

  If the optional `scheme` argument is provided, it will be used instead of the “Digest” scheme in the `WWW-Authenticate` response. A fairly common practice is to use a custom scheme to prevent browsers from prompting the user to login.

  The `realm` argument can be used to provide an application defined realm with the `WWW-Authenticate` header.

  If `use_ha1_pw` is False, then the `get_password` callback needs to return the plain text password for the given user. If `use_ha1_pw` is True, the `get_password` callback needs to return the HA1 value for the given user. The advantage of setting `use_ha1_pw` to `True` is that it allows the application to store the HA1 hash of the password in the user database.

  The `qop` option configures a list of accepted quality of protection extensions. This argument can be given as a comma-separated string, a list of strings, or `None` to disable. The default is `auth`. The `auth-int` option is currently not implemented.

  The `algorithm` option configures the hash generation algorithm to use. The default is `MD5`. The two algorithms that are implemented are `MD5` and `MD5-Sess`.

  current_user()

    The user object returned by the `verify_password` callback on successful authentication. If no user is returned by the callback, this is set to the username passed by the client. Example:

        @app.route('/')
        @auth.login_required
        def index():
            user = auth.current_user()
            return "Hello, {}!".format(user.name)

  error_handler(f)

    Decorator for a function that will be called by the framework when it is necessary to send an authentication error back to the client. The function can take one argument, the status code of the error, which can be 401 (incorrect credentials) or 403 (correct, but insufficient credentials). To preserve compatiiblity with older releases of this package, the function can also be defined without arguments. The return value from this function must by any accepted response type in Flask routes. If this callback isn’t provided a default error response is generated. Example:

        @auth.error_handler
        def auth_error(status):
            return "Access Denied", status

  generate_ha1(username, password)

    Generate the HA1 hash that can be stored in the user database when `use_ha1_pw` is set to True in the constructor.

  generate_nonce(f)

    If defined, this callback function will be called by the framework to generate a nonce. If this is defined, `verify_nonce` should also be defined.

    This can be used to use a state storage mechanism other than the session.

  generate_opaque(f)

    Decorator for a function that will be called by the framework to generate an opaque value. If this is defined, `verify_opaque` should also be defined.

    This can be used to use a state storage mechanism other than the session.

  get_password(f)

    Deprecated Decorator for a function that will be called by the framework to obtain the password for a given user. Example:

        @auth.get_password
        def get_password(username):
            return db.get_user_password(username)

  get_user_roles(f)

    Decorator for a function that will be called by the framework to obtain the roles assigned to a given user. The callback function takes a single argument, the user for which roles are requested. The user object passed to this function will be the one returned by the “verify” callback. If the verify callback returned `True` instead of a user object, then the `Authorization` object provided by Flask will be passed to this function. The function should return the role or list of roles that belong to the user. Example:

        @auth.get_user_roles
        def get_user_roles(user):
            return user.get_roles()

  login_required(f=None, role=None, optional=None)

    Decorator for a function that will be called when authentication is successful. This will typically be a Flask view function. Example:

        @app.route('/private')
        @auth.login_required
        def private_page():
            return "Only for authorized people!"

    An optional `role` argument can be given to further restrict access by roles. Example:

        @app.route('/private')
        @auth.login_required(role='admin')
        def private_page():
            return "Only for admins!"

    An optional `optional` argument can be set to `True` to allow the route to execute also when authentication is not included with the request, in which case `auth.current_user()` will be set to `None`. Example:

        @app.route('/private')
        @auth.login_required(optional=True)
        def private_page():
            user = auth.current_user()
            return "Hello {}!".format(
                user.name if user is not None else 'anonymous')

  username()

    Deprecated A view function that is protected with this class can access the logged username through this method. Example:

        @app.route('/')
        @auth.login_required
        def index():
            return "Hello, {}!".format(auth.username())

  verify_nonce(f)

    Decorator for a function that will be called by the framework to verify that a nonce is valid. It will be called with a single argument: the nonce to be verified.

    This can be used to use a state storage mechanism other than the session.

  verify_opaque(f)

    Decorator for a function that will be called by the framework to verify that an opaque value is valid. It will be called with a single argument: the opaque value to be verified.

    This can be used to use a state storage mechanism other than the session.

class flask_httpauth.HTTPTokenAuth(scheme='Bearer', realm=None, header=None)
  current_user()

    The user object returned by the `verify_password` callback on successful authentication. If no user is returned by the callback, this is set to the username passed by the client. Example:

        @app.route('/')
        @auth.login_required
        def index():
            user = auth.current_user()
            return "Hello, {}!".format(user.name)

  error_handler(f)

    Decorator for a function that will be called by the framework when it is necessary to send an authentication error back to the client. The function can take one argument, the status code of the error, which can be 401 (incorrect credentials) or 403 (correct, but insufficient credentials). To preserve compatiiblity with older releases of this package, the function can also be defined without arguments. The return value from this function must by any accepted response type in Flask routes. If this callback isn’t provided a default error response is generated. Example:

        @auth.error_handler
        def auth_error(status):
            return "Access Denied", status

  get_password(f)

    Deprecated Decorator for a function that will be called by the framework to obtain the password for a given user. Example:

        @auth.get_password
        def get_password(username):
            return db.get_user_password(username)

  get_user_roles(f)

    Decorator for a function that will be called by the framework to obtain the roles assigned to a given user. The callback function takes a single argument, the user for which roles are requested. The user object passed to this function will be the one returned by the “verify” callback. If the verify callback returned `True` instead of a user object, then the `Authorization` object provided by Flask will be passed to this function. The function should return the role or list of roles that belong to the user. Example:

        @auth.get_user_roles
        def get_user_roles(user):
            return user.get_roles()

  login_required(f=None, role=None, optional=None)

    Decorator for a function that will be called when authentication is successful. This will typically be a Flask view function. Example:

        @app.route('/private')
        @auth.login_required
        def private_page():
            return "Only for authorized people!"

    An optional `role` argument can be given to further restrict access by roles. Example:

        @app.route('/private')
        @auth.login_required(role='admin')
        def private_page():
            return "Only for admins!"

    An optional `optional` argument can be set to `True` to allow the route to execute also when authentication is not included with the request, in which case `auth.current_user()` will be set to `None`. Example:

        @app.route('/private')
        @auth.login_required(optional=True)
        def private_page():
            user = auth.current_user()
            return "Hello {}!".format(
                user.name if user is not None else 'anonymous')

  username()

    Deprecated A view function that is protected with this class can access the logged username through this method. Example:

        @app.route('/')
        @auth.login_required
        def index():
            return "Hello, {}!".format(auth.username())

  verify_token(f)

    Decorator for a function that will be called by the framework to verify that the credentials sent by the client with the `Authorization` header are valid. The callback function takes one argument, the token provided by the client. The function must return the user object if the token is valid, or `True` if a user object is not available. In case of a failed authentication, the function should return `None` or `False`. Example usage:

        @auth.verify_token
        def verify_token(token):
            return User.query.filter_by(token=token).first()

    Note that a `verify_token` callback is required when using this class.

class flask_httpauth.MultiAuth(main_auth, *additional_auths)

  Create a multiple authentication object.

  The arguments are one or more instances of `HTTPBasicAuth`, `HTTPDigestAuth` or `HTTPTokenAuth`. A route protected with this authentication method will try all the given authentication objects until one succeeds.

  current_user()

    The authenticated user.

  login_required(f=None, role=None, optional=None)

    Decorator for a function that will be called when authentication is successful. This will typically be a Flask view function.