4.1 KiB
Introduction
Flask-Digest-Auth is an HTTP Digest Authentication implementation for Flask applications. It authenticates the user for the protected views.
HTTP Digest Authentication is specified in RFC 2617.
Why HTTP Digest Authentication?
HTTP Digest Authentication has the advantage that it does not send the actual password to the server, which greatly enhances the security. It uses the challenge-response authentication scheme. The client returns the response calculated from the challenge and the password, but not the original password.
Log in forms has the advantage of freedom, in the senses of both the visual design and the actual implementation. You may implement your own challenge-response log in form, but then you are reinventing the wheels. If a pretty log in form is not critical to your project, HTTP Digest Authentication should be a good choice.
Flask-Digest-Auth works with Flask-Login. Log in protection can be separated with the authentication mechanism. You can create protected Flask modules without knowing the actual authentication mechanisms.
Installation
You can install Flask-Digest-Auth with pip:
pip install Flask-Digest-Auth
You may also install the latest source from the Flask-Digest-Auth GitHub repository.
pip install git+https://github.com/imacat/flask-digest-auth.git
Setting the Password
The password hash of the HTTP Digest Authentication is composed of the realm, the username, and the password. Example for setting the password:
from flask_digest_auth import make_password_hash user.password = make_password_hash(realm, username, password)
The username is part of the hash. If the user changes their username, you need to ask their password, to generate and store the new password hash.
See :func:`flask_digest_auth.algo.make_password_hash`.
System Message: ERROR/3 (<stdin>, line 66); backlink
Unknown interpreted text role "func".Flask-Digest-Auth Alone
Flask-Digest-Auth can authenticate the users alone.
See :ref:`example-alone-simple` and :ref:`example-alone-large`.
System Message: ERROR/3 (<stdin>, line 74); backlink
Unknown interpreted text role "ref".System Message: ERROR/3 (<stdin>, line 74); backlink
Unknown interpreted text role "ref".Flask-Login Integration
Flask-Digest-Auth works with Flask-Login. You can write a Flask module that requires log in, without specifying how to log in. The application can use either HTTP Digest Authentication, or the log in forms, as needed.
To use Flask-Login with Flask-Digest-Auth, login_manager.init_app(app) must be called before auth.init_app(app).
The currently logged-in user can be retrieved at flask_login.current_user, if any.
See :ref:`example-flask-login-simple` and :ref:`example-flask-login-large`.
System Message: ERROR/3 (<stdin>, line 92); backlink
Unknown interpreted text role "ref".System Message: ERROR/3 (<stdin>, line 92); backlink
Unknown interpreted text role "ref".The views only depend on Flask-Login, but not the Flask-Digest-Auth. You can change the actual authentication mechanism without changing the views.
Session Integration
Flask-Digest-Auth features session integration. The user log in is remembered in the session. The authentication information is not requested again. This is different to the practice of the HTTP Digest Authentication, but is convenient for the log in accounting.
Log In Bookkeeping
You can register a callback to run when the user logs in, for ex., logging the log in event, adding the log in counter, etc.
@auth.register_on_login
def on_login(user: User) -> None:
user.visits = user.visits + 1
See :meth:`flask_digest_auth.auth.DigestAuth.register_on_login`.
System Message: ERROR/3 (<stdin>, line 121); backlink
Unknown interpreted text role "meth".Log Out
Flask-Digest-Auth supports log out. The user will be prompted for the new username and password.
See :meth:`flask_digest_auth.auth.DigestAuth.logout`.
System Message: ERROR/3 (<stdin>, line 130); backlink
Unknown interpreted text role "meth".Test Client
Flask-Digest-Auth comes with a test client that supports HTTP digest authentication.
See :class:`flask_digest_auth.test.Client`.
System Message: ERROR/3 (<stdin>, line 139); backlink
Unknown interpreted text role "class".Also see :ref:`example-unittest` and :ref:`example-pytest`.
System Message: ERROR/3 (<stdin>, line 141); backlink
Unknown interpreted text role "ref".System Message: ERROR/3 (<stdin>, line 141); backlink
Unknown interpreted text role "ref".