flask_digest_auth package

Submodules

flask_digest_auth.algo module

The algorithm.

flask_digest_auth.algo.calc_response(method: str, uri: str, password_hash: str, nonce: str, qop: Literal['auth', 'auth-int'] | None = None, algorithm: Literal['MD5', 'MD5-sess'] | None = 'MD5-sess', cnonce: str | None = None, nc: str | None = None, body: bytes | None = None) → str

Calculates the response value of the HTTP digest authentication.

Parameters:

method – The request method.
uri – The request URI.
password_hash – The password hash for the HTTP digest authentication.
nonce – The nonce.
qop – The quality of protection, either auth or auth-int.
algorithm – The algorithm, either MD5 or MD5-sess.
cnonce – The client nonce, which must exists when qop exists or algorithm is MD5-sess.
nc – The request counter, which must exists when qop exists.
body – The request body, which must exists when qop is auth-int.

Returns:

The response value.

Raises:

AssertionError – When cnonce is missing with algorithm is MD5-sess, when body is missing with qop is auth-int, or when cnonce or nc is missing with qop exits.

flask_digest_auth.algo.make_password_hash(realm: str, username: str, password: str) → str

Calculates the password hash for the HTTP digest authentication. Use this function to set the password for the user.

Example:

user.password = make_password_hash(realm, username, password)

Parameters:

realm – The realm.
username – The username.
password – The cleartext password.

Returns:

The password hash for the HTTP digest authentication.

flask_digest_auth.auth module

The HTTP Digest Authentication. See RFC 2617 HTTP Authentication: Basic and Digest Access Authentication

class flask_digest_auth.auth.AuthState

Bases: object

The authentication state. It keeps the status in the earlier authentication stage, so that the latter response stage knows how to response.

opaque: str | None: The opaque value specified by the client, if valid.

stale: bool | None: The stale value, if there is a previous log in attempt.

class flask_digest_auth.auth.BaseOnLogInCallback

Bases: object

The base callback to run when the user logs in, given the logged-in user. The default does nothing.

See flask_digest_auth.auth.DigestAuth.register_on_login()

class flask_digest_auth.auth.BasePasswordHashGetter

Bases: object

The base callback that given the username, returns the password hash, or None if the user does not exist. The default is to raise an UnboundLocalError if the callback is not registered yet.

See flask_digest_auth.auth.DigestAuth.register_get_password()

class flask_digest_auth.auth.BaseUserGetter

Bases: object

The base callback that given the username, returns the user, or None if the user does not exist. The default is to raise an UnboundLocalError if the callback is not registered yet.

See flask_digest_auth.auth.DigestAuth.register_get_user()

class flask_digest_auth.auth.DigestAuth(realm: str | None = None)

Bases: object

The HTTP digest authentication.

algorithm: Literal['MD5', 'MD5-sess'] | None: The algorithm, either None, MD5, or MD5-sess. Default is None.

init_app(app: Flask) → None

Initializes the Flask application. The DigestAuth instance will be stored in app.extensions["digest_auth"].

Example:

app: flask = Flask(__name__)
auth: DigestAuth = DigestAuth()
auth.init_app(app)

Parameters:: app – The Flask application.
Returns:: None.

login_required(view) → Callable

The view decorator for the HTTP digest authentication.

Example:

@app.get("/admin")
@auth.login_required
def admin():
    return f"Hello, {g.user.username}!"

The logged-in user can be retrieved at g.user.

Parameters:: view – The view.
Returns:: The login-protected view.

logout() → None

Logs out the user. This actually causes the next authentication to fail, which forces the browser to ask the user for the username and password again.

Example:

@app.post("/logout")
@auth.login_required
def logout():
    auth.logout()
    return redirect(request.form.get("next"))

Returns:: None.

realm: str: The realm. Default is “Login Required”.

register_get_password(func: Callable[[str], str | None]) → None

The decorator to register the callback to obtain the password hash.

Example:

@auth.register_get_password
def get_password_hash(username: str) -> Optional[str]:
    user = User.query.filter(User.username == username).first()
    return None if user is None else user.password

Parameters:: func – The callback that given the username, returns the password hash, or None if the user does not exist.
Returns:: None.

register_get_user(func: Callable[[str], Any | None]) → None

The decorator to register the callback to obtain the user.

Example:

@auth.register_get_user
def get_user(username: str) -> Optional[User]:
    return User.query.filter(User.username == username).first()

Parameters:: func – The callback that given the username, returns the user, or None if the user does not exist.
Returns:: None.

register_on_login(func: Callable[[Any], None]) → None

The decorator to register the callback to run when the user logs in.

Example:

@auth.register_on_login
def on_login(user: User) -> None:
    user.visits = user.visits + 1

Parameters:: func – The callback given the logged-in user.
Returns:: None.

use_opaque: bool: Whether to use an opaque. Default is True.

exception flask_digest_auth.auth.UnauthorizedException

Bases: Exception

The exception thrown when the authentication fails.

Module contents

The HTTP digest authentication.

flask_digest_auth.VERSION: str = '0.7.0': The package version.