Flask-HTTPAuth Documentation

Flask-HTTPAuth provides a role-based system to filter access to routes.

1. Define User Roles: Implement a function that returns a list of roles for a user and decorate it with @auth.get_user_roles.
2. Restrict Routes: Use the role argument in the @auth.login_required decorator.

Role Argument Syntax:

• Single role: role='admin'
• List of roles (OR logic): role=['admin', 'moderator']
• Nested roles (complex logic): role=['user', ['moderator', 'contributor']] (matches if user is a 'user' OR has both 'moderator' and 'contributor' roles).

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

@app.route('/admin')
@auth.login_required(role='admin')
def admins_only():
    return "Hello {}, you are an admin!".format(auth.current_user())

@app.route('/admin')
@auth.login_required(role=['admin', 'moderator'])
def admins_only():
    return "Hello {}, you are an admin or a moderator!".format(auth.current_user())

@app.route('/admin')
@auth.login_required(role=['user', ['moderator', 'contributor']])
def admins_only():
    return "Hello {}, you are a user or a moderator/contributor!".format(auth.current_user())

To use Basic Authentication, instantiate HTTPBasicAuth and use the @auth.verify_password decorator to define how users are validated. The callback should return the username if authentication is successful, or None if it fails. Protect routes using the @auth.login_required decorator. You can retrieve the authenticated user via auth.current_user().

from flask import Flask
from flask_httpauth import HTTPBasicAuth
from werkzeug.security import generate_password_hash, check_password_hash

app = Flask(__name__)
auth = HTTPBasicAuth()

users = {
    "john": generate_password_hash("hello"),
    "susan": generate_password_hash("bye")
}

@auth.verify_password
def verify_password(username, password):
    if username in users and \
            check_password_hash(users.get(username), password):
        return username

@app.route('/')
@auth.login_required
def index():
    return "Hello, %s!" % auth.current_user()

if __name__ == '__main__':
    app.run()

To use Basic authentication, use the HTTPBasicAuth class. You must implement a function decorated with @auth.verify_password which receives the username and password.

• If credentials are valid, return the user object.
• If credentials are invalid, return None or False.
• Use @auth.login_required to protect routes.
• Access the authenticated user via auth.current_user().

from flask import Flask
from flask_httpauth import HTTPBasicAuth
from werkzeug.security import generate_password_hash, check_password_hash

app = Flask(__name__)
auth = HTTPBasicAuth()

users = {
    "john": generate_password_hash("hello"),
    "susan": generate_password_hash("bye")
}

@auth.verify_password
def verify_password(username, password):
    if username in users and \
            check_password_hash(users.get(username), password):
        return username

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

if __name__ == '__main__':
    app.run()

To use Digest authentication, use the HTTPDigestAuth class. You must implement a function decorated with @auth.get_password which receives the username and returns the associated password.

Security Note: Digest authentication requires storing challenge data. By default, Flask-HTTPAuth uses the Flask session. For security, it is recommended to use server-side sessions (e.g., via Flask-Session or Flask-KVSession) rather than default cookie-based sessions to prevent challenge data from being captured in cookies.

from flask import Flask
from flask_httpauth import HTTPDigestAuth

app = Flask(__name__)
app.config['SECRET_KEY'] = 'secret key here'
auth = HTTPDigestAuth()

users = {
    "john": "hello",
    "susan": "bye"
}

@auth.get_password
def get_pw(username):
    if username in users:
        return users.get(username)
    return None
    
@app.route('/')
@auth.login_required
def index():
    return "Hello, {}!".format(auth.username())
        
if __name__ == '__main__':
    app.run()