Skip to content

Auth

rn_forge.web.auth

Framework-independent authentication wire contract.

Raw credentials, the Authorization header and the WWW-Authenticate challenge. Verification details must not be exposed in a 401 response.

AUTH_FAILED_DETAIL = 'Authentication failed.' module-attribute

The non-sensitive detail returned for authentication failures.

CSRF_FAILED_DETAIL = 'CSRF verification failed.' module-attribute

The detail returned for a CSRF rejection; it never names the check that failed.

BearerErrorCode = Literal['invalid_request', 'invalid_token', 'insufficient_scope']

The error codes RFC 6750 §3 defines for a Bearer challenge.

Credentials(scheme, token, extras=dict[str, Any]()) dataclass

Raw credentials lifted off the request, before verification.

scheme is the HTTP auth scheme as sent (Bearer, Basic, ...) and token its parameter, verbatim. This is what a framework binding hands an authenticator; nothing here interprets it.

challenge_header(*, scheme='Bearer', realm=None, error=None, error_description=None, scope=None)

Build a WWW-Authenticate challenge.

Parameters follow RFC 6750 for Bearer and RFC 7617 for Basic. None values are omitted.

Parameters:

Name Type Description Default
scheme str

Bearer or Basic.

'Bearer'
realm str | None

The protection space.

None
error BearerErrorCode | None

One of RFC 6750's three codes. Bearer only.

None
error_description str | None

Non-sensitive human-readable text.

None
scope str | None

The scope required, for insufficient_scope.

None

Returns:

Type Description
str

A complete challenge header value.

Example::

challenge_header(realm="example")
# 'Bearer realm="example"'
challenge_header(realm="example", error="insufficient_scope", scope="read")
# 'Bearer realm="example", error="insufficient_scope", scope="read"'

parse_authorization(header, scheme)

Return the scheme credentials in an Authorization header value.

The scheme is matched case-insensitively (RFC 9110 §11.1) and the token is returned verbatim apart from surrounding whitespace — it may be empty.

Parameters:

Name Type Description Default
header str | None

The Authorization header value, or None when absent.

required
scheme str

The expected scheme, e.g. "Bearer".

required

Returns:

Type Description
Credentials | None

Credentials(scheme, token), or None when header is absent or

Credentials | None

names another scheme.