2022-11-23 15:08:30 +08:00
|
|
|
================================
|
|
|
|
Flask HTTP Digest Authentication
|
|
|
|
================================
|
2022-11-23 15:07:00 +08:00
|
|
|
|
|
|
|
|
|
|
|
Description
|
|
|
|
===========
|
|
|
|
|
2022-11-24 17:57:25 +08:00
|
|
|
*Flask-Digest-Auth* is an `HTTP Digest Authentication`_ implementation
|
2022-11-23 15:07:00 +08:00
|
|
|
for Flask_ applications. It authenticates the user for the protected
|
2022-11-24 17:57:25 +08:00
|
|
|
views.
|
2022-11-23 15:07:00 +08:00
|
|
|
|
2022-11-24 17:57:25 +08:00
|
|
|
HTTP Digest Authentication is specified in `RFC 2617`_.
|
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
Refer to the full `Flask-Digest-Auth readthedocs documentation`_.
|
|
|
|
|
2022-11-26 19:23:14 +08:00
|
|
|
|
|
|
|
Why HTTP Digest Authentication?
|
|
|
|
-------------------------------
|
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
*HTTP Digest Authentication* has the advantage that it does not send
|
|
|
|
thee 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.
|
2022-11-24 18:25:01 +08:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2022-11-24 17:57:25 +08:00
|
|
|
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.
|
|
|
|
|
2022-11-26 19:23:14 +08:00
|
|
|
|
2022-11-24 04:43:07 +08:00
|
|
|
Installation
|
|
|
|
============
|
|
|
|
|
2022-11-24 17:57:25 +08:00
|
|
|
You can install Flask-Digest-Auth with ``pip``:
|
2022-11-24 04:43:07 +08:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2022-11-24 17:57:25 +08:00
|
|
|
pip install Flask-Digest-Auth
|
2022-11-24 04:43:07 +08:00
|
|
|
|
2022-11-24 05:20:18 +08:00
|
|
|
You may also install the latest source from the
|
2022-11-24 17:57:25 +08:00
|
|
|
`Flask-Digest-Auth GitHub repository`_.
|
2022-11-24 04:43:07 +08:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
pip install git+https://github.com/imacat/flask-digest-auth.git
|
2022-11-24 04:43:07 +08:00
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
|
|
|
|
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.
|
2022-11-24 04:43:07 +08:00
|
|
|
|
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
Flask-Digest-Auth Alone
|
|
|
|
=======================
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
Flask-Digest-Auth can authenticate the users alone.
|
2022-11-23 22:29:44 +08:00
|
|
|
|
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
Simple Applications with Flask-Digest-Auth Alone
|
|
|
|
------------------------------------------------
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
In your ``my_app.py``:
|
|
|
|
|
2022-11-23 22:29:44 +08:00
|
|
|
::
|
|
|
|
|
2022-11-25 05:40:27 +08:00
|
|
|
from flask import Flask, request, redirect
|
2022-11-23 22:29:44 +08:00
|
|
|
from flask_digest_auth import DigestAuth
|
|
|
|
|
|
|
|
app: flask = Flask(__name__)
|
|
|
|
... (Configure the Flask application) ...
|
|
|
|
|
|
|
|
auth: DigestAuth = DigestAuth(realm="Admin")
|
2022-11-25 06:14:57 +08:00
|
|
|
auth.init_app(app)
|
2022-11-23 22:29:44 +08:00
|
|
|
|
|
|
|
@auth.register_get_password
|
|
|
|
def get_password_hash(username: str) -> t.Optional[str]:
|
|
|
|
... (Load the password hash) ...
|
|
|
|
|
|
|
|
@auth.register_get_user
|
|
|
|
def get_user(username: str) -> t.Optional[t.Any]:
|
|
|
|
... (Load the user) ...
|
|
|
|
|
|
|
|
@app.get("/admin")
|
|
|
|
@auth.login_required
|
|
|
|
def admin():
|
2022-11-26 15:59:17 +08:00
|
|
|
return f"Hello, {g.user.username}!"
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-11-25 05:40:27 +08:00
|
|
|
@app.post("/logout")
|
|
|
|
@auth.login_required
|
|
|
|
def logout():
|
|
|
|
auth.logout()
|
|
|
|
return redirect(request.form.get("next"))
|
|
|
|
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
Larger Applications with ``create_app()`` with Flask-Digest-Auth Alone
|
|
|
|
----------------------------------------------------------------------
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
In your ``my_app/__init__.py``:
|
|
|
|
|
2022-11-24 17:57:25 +08:00
|
|
|
::
|
2022-11-23 22:29:44 +08:00
|
|
|
|
|
|
|
from flask import Flask
|
|
|
|
from flask_digest_auth import DigestAuth
|
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
auth: DigestAuth = DigestAuth()
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
def create_app(test_config = None) -> Flask:
|
2022-11-23 22:29:44 +08:00
|
|
|
app: flask = Flask(__name__)
|
|
|
|
... (Configure the Flask application) ...
|
|
|
|
|
|
|
|
auth.realm = app.config["REALM"]
|
2022-11-25 06:14:57 +08:00
|
|
|
auth.init_app(app)
|
2022-11-23 22:29:44 +08:00
|
|
|
|
|
|
|
@auth.register_get_password
|
|
|
|
def get_password_hash(username: str) -> t.Optional[str]:
|
|
|
|
... (Load the password hash) ...
|
|
|
|
|
|
|
|
@auth.register_get_user
|
|
|
|
def get_user(username: str) -> t.Optional[t.Any]:
|
|
|
|
... (Load the user) ...
|
|
|
|
|
|
|
|
return app
|
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
In your ``my_app/views.py``:
|
2022-11-23 22:29:44 +08:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
from my_app import auth
|
2022-11-25 05:40:27 +08:00
|
|
|
from flask import Flask, Blueprint, request, redirect
|
2022-11-23 22:29:44 +08:00
|
|
|
|
|
|
|
bp = Blueprint("admin", __name__, url_prefix="/admin")
|
|
|
|
|
2022-11-25 05:41:30 +08:00
|
|
|
@bp.get("/admin")
|
2022-11-23 22:29:44 +08:00
|
|
|
@auth.login_required
|
|
|
|
def admin():
|
2022-11-26 15:59:17 +08:00
|
|
|
return f"Hello, {g.user.username}!"
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-11-25 05:40:27 +08:00
|
|
|
@app.post("/logout")
|
|
|
|
@auth.login_required
|
|
|
|
def logout():
|
|
|
|
auth.logout()
|
|
|
|
return redirect(request.form.get("next"))
|
|
|
|
|
2022-11-23 22:29:44 +08:00
|
|
|
def init_app(app: Flask) -> None:
|
|
|
|
app.register_blueprint(bp)
|
|
|
|
|
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
|
2022-11-23 22:29:44 +08:00
|
|
|
Flask-Login Integration
|
|
|
|
=======================
|
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
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.
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
To use Flask-Login with Flask-Digest-Auth,
|
2022-11-25 06:14:57 +08:00
|
|
|
``login_manager.init_app(app)`` must be called before
|
|
|
|
``auth.init_app(app)``.
|
|
|
|
|
2022-11-26 15:59:17 +08:00
|
|
|
The currently logged-in user can be retrieved at
|
|
|
|
``flask_login.current_user``, if any.
|
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
The views only depend on Flask-Login, but not the Flask-Digest-Auth.
|
|
|
|
You can change the actual authentication mechanism without changing
|
|
|
|
the views.
|
|
|
|
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
Simple Applications with Flask-Login Integration
|
|
|
|
------------------------------------------------
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
In your ``my_app.py``:
|
|
|
|
|
2022-11-23 22:29:44 +08:00
|
|
|
::
|
|
|
|
|
2022-11-26 15:59:17 +08:00
|
|
|
import flask_login
|
2022-11-25 05:40:27 +08:00
|
|
|
from flask import Flask, request, redirect
|
2022-11-23 22:29:44 +08:00
|
|
|
from flask_digest_auth import DigestAuth
|
|
|
|
|
|
|
|
app: flask = Flask(__name__)
|
|
|
|
... (Configure the Flask application) ...
|
|
|
|
|
2022-11-26 15:59:17 +08:00
|
|
|
login_manager: flask_login.LoginManager = flask_login.LoginManager()
|
2022-11-23 22:29:44 +08:00
|
|
|
login_manager.init_app(app)
|
|
|
|
|
|
|
|
@login_manager.user_loader
|
|
|
|
def load_user(user_id: str) -> t.Optional[User]:
|
|
|
|
... (Load the user with the username) ...
|
|
|
|
|
|
|
|
auth: DigestAuth = DigestAuth(realm="Admin")
|
|
|
|
auth.init_app(app)
|
|
|
|
|
|
|
|
@auth.register_get_password
|
|
|
|
def get_password_hash(username: str) -> t.Optional[str]:
|
|
|
|
... (Load the password hash) ...
|
|
|
|
|
|
|
|
@app.get("/admin")
|
2022-11-26 15:59:17 +08:00
|
|
|
@flask_login.login_required
|
2022-11-23 22:29:44 +08:00
|
|
|
def admin():
|
2022-11-26 15:59:17 +08:00
|
|
|
return f"Hello, {flask_login.current_user.get_id()}!"
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-11-25 05:40:27 +08:00
|
|
|
@app.post("/logout")
|
|
|
|
@flask_login.login_required
|
|
|
|
def logout():
|
|
|
|
auth.logout()
|
|
|
|
# Do not call flask_login.logout_user()
|
|
|
|
return redirect(request.form.get("next"))
|
|
|
|
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
Larger Applications with ``create_app()`` with Flask-Login Integration
|
|
|
|
----------------------------------------------------------------------
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
In your ``my_app/__init__.py``:
|
|
|
|
|
2022-11-24 17:57:25 +08:00
|
|
|
::
|
2022-11-23 22:29:44 +08:00
|
|
|
|
|
|
|
from flask import Flask
|
|
|
|
from flask_digest_auth import DigestAuth
|
|
|
|
from flask_login import LoginManager
|
|
|
|
|
2022-11-25 05:40:27 +08:00
|
|
|
auth: DigestAuth = DigestAuth()
|
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
def create_app(test_config = None) -> Flask:
|
2022-11-23 22:29:44 +08:00
|
|
|
app: flask = Flask(__name__)
|
|
|
|
... (Configure the Flask application) ...
|
|
|
|
|
|
|
|
login_manager: LoginManager = LoginManager()
|
|
|
|
login_manager.init_app(app)
|
|
|
|
|
|
|
|
@login_manager.user_loader
|
|
|
|
def load_user(user_id: str) -> t.Optional[User]:
|
|
|
|
... (Load the user with the username) ...
|
|
|
|
|
2022-11-25 05:40:27 +08:00
|
|
|
auth.realm = app.config["REALM"]
|
2022-11-23 22:29:44 +08:00
|
|
|
auth.init_app(app)
|
|
|
|
|
|
|
|
@auth.register_get_password
|
|
|
|
def get_password_hash(username: str) -> t.Optional[str]:
|
|
|
|
... (Load the password hash) ...
|
|
|
|
|
|
|
|
return app
|
|
|
|
|
2022-11-24 04:35:24 +08:00
|
|
|
In your ``my_app/views.py``:
|
2022-11-23 22:29:44 +08:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
import flask_login
|
2022-11-25 05:40:27 +08:00
|
|
|
from flask import Flask, Blueprint, request, redirect
|
|
|
|
from my_app import auth
|
2022-11-23 22:29:44 +08:00
|
|
|
|
|
|
|
bp = Blueprint("admin", __name__, url_prefix="/admin")
|
|
|
|
|
2022-11-25 05:41:30 +08:00
|
|
|
@bp.get("/admin")
|
2022-11-23 22:29:44 +08:00
|
|
|
@flask_login.login_required
|
|
|
|
def admin():
|
2022-11-26 15:59:17 +08:00
|
|
|
return f"Hello, {flask_login.current_user.get_id()}!"
|
2022-11-23 22:29:44 +08:00
|
|
|
|
2022-11-25 05:40:27 +08:00
|
|
|
@app.post("/logout")
|
|
|
|
@flask_login.login_required
|
|
|
|
def logout():
|
|
|
|
auth.logout()
|
|
|
|
# Do not call flask_login.logout_user()
|
|
|
|
return redirect(request.form.get("next"))
|
|
|
|
|
2022-11-23 22:29:44 +08:00
|
|
|
def init_app(app: Flask) -> None:
|
|
|
|
app.register_blueprint(bp)
|
|
|
|
|
2022-11-24 17:57:25 +08:00
|
|
|
The views only depend on Flask-Login, but not the actual
|
|
|
|
authentication mechanism. You can change the actual authentication
|
|
|
|
mechanism without changing the views.
|
2022-11-23 22:29:44 +08:00
|
|
|
|
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
Session Integration
|
|
|
|
===================
|
2022-11-25 05:40:27 +08:00
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
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.
|
2022-11-25 05:40:27 +08:00
|
|
|
|
|
|
|
|
2022-11-27 03:58:29 +08:00
|
|
|
Log In Bookkeeping
|
2022-11-30 08:31:26 +08:00
|
|
|
==================
|
2022-11-27 03:58:29 +08:00
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
Log Out
|
|
|
|
=======
|
|
|
|
|
|
|
|
Flask-Digest-Auth supports log out. The user will be prompted for the
|
|
|
|
new username and password.
|
|
|
|
|
|
|
|
|
|
|
|
Test Client
|
|
|
|
===========
|
|
|
|
|
|
|
|
Flask-Digest-Auth comes with a test client that supports HTTP digest
|
|
|
|
authentication.
|
2022-11-24 04:31:46 +08:00
|
|
|
|
2022-12-06 07:54:49 +08:00
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
A unittest Test Case
|
|
|
|
--------------------
|
2022-11-24 04:31:46 +08:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2022-12-06 07:54:49 +08:00
|
|
|
from flask import Flask
|
2022-11-24 04:31:46 +08:00
|
|
|
from flask_digest_auth import Client
|
|
|
|
from flask_testing import TestCase
|
|
|
|
from my_app import create_app
|
|
|
|
|
|
|
|
class MyTestCase(TestCase):
|
|
|
|
|
|
|
|
def create_app(self):
|
|
|
|
app: Flask = create_app({
|
|
|
|
"SECRET_KEY": token_urlsafe(32),
|
|
|
|
"TESTING": True
|
|
|
|
})
|
|
|
|
app.test_client_class = Client
|
|
|
|
return app
|
|
|
|
|
|
|
|
def test_admin(self):
|
2022-11-24 04:35:24 +08:00
|
|
|
response = self.client.get("/admin")
|
|
|
|
self.assertEqual(response.status_code, 401)
|
2022-11-24 04:31:46 +08:00
|
|
|
response = self.client.get(
|
|
|
|
"/admin", digest_auth=("my_name", "my_pass"))
|
|
|
|
self.assertEqual(response.status_code, 200)
|
|
|
|
|
|
|
|
|
2022-12-06 21:54:10 +08:00
|
|
|
A pytest Test
|
|
|
|
-------------
|
2022-12-06 07:54:49 +08:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
import pytest
|
|
|
|
from flask import Flask
|
|
|
|
from flask_digest_auth import Client
|
|
|
|
from my_app import create_app
|
|
|
|
|
|
|
|
@pytest.fixture()
|
|
|
|
def app():
|
|
|
|
app: Flask = create_app({
|
|
|
|
"SECRET_KEY": token_urlsafe(32),
|
|
|
|
"TESTING": True
|
|
|
|
})
|
|
|
|
app.test_client_class = Client
|
|
|
|
yield app
|
|
|
|
|
|
|
|
@pytest.fixture()
|
|
|
|
def client(app):
|
|
|
|
return app.test_client()
|
|
|
|
|
|
|
|
def test_admin(app: Flask, client: Client):
|
|
|
|
with app.app_context():
|
2022-12-06 22:46:52 +08:00
|
|
|
response = client.get("/admin")
|
2022-12-06 07:54:49 +08:00
|
|
|
assert response.status_code == 401
|
2022-12-06 22:46:52 +08:00
|
|
|
response = client.get(
|
2022-12-06 07:54:49 +08:00
|
|
|
"/admin", digest_auth=("my_name", "my_pass"))
|
|
|
|
assert response.status_code == 200
|
|
|
|
|
|
|
|
|
2022-11-23 15:07:00 +08:00
|
|
|
Copyright
|
|
|
|
=========
|
|
|
|
|
|
|
|
Copyright (c) 2022 imacat.
|
|
|
|
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
|
|
you may not use this file except in compliance with the License.
|
|
|
|
You may obtain a copy of the License at
|
|
|
|
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
See the License for the specific language governing permissions and
|
|
|
|
limitations under the License.
|
|
|
|
|
2022-11-30 08:31:26 +08:00
|
|
|
|
2022-11-23 15:07:00 +08:00
|
|
|
Authors
|
|
|
|
=======
|
|
|
|
|
|
|
|
| imacat
|
|
|
|
| imacat@mail.imacat.idv.tw
|
|
|
|
| 2022/11/23
|
2022-12-06 21:54:10 +08:00
|
|
|
|
|
|
|
.. _HTTP Digest Authentication: https://en.wikipedia.org/wiki/Digest_access_authentication
|
|
|
|
.. _RFC 2617: https://www.rfc-editor.org/rfc/rfc2617
|
|
|
|
.. _Flask: https://flask.palletsprojects.com
|
|
|
|
.. _Flask-Digest-Auth GitHub repository: https://github.com/imacat/flask-digest-auth
|
|
|
|
.. _Flask-Digest-Auth readthedocs documentation: https://flask-digest-auth.readthedocs.io
|
|
|
|
.. _Flask-Login: https://flask-login.readthedocs.io
|