API Reference¶

Package¶

Public API for HTTPX2 Kerberos authentication.

The package exposes HTTPKerberosAuth for use with httpx2 request and client calls, plus the public exception types raised by the authentication flow.

Example

>>> from httpx2_kerberos import HTTPKerberosAuth, MutualAuthentication
>>> auth = HTTPKerberosAuth(mutual_authentication=MutualAuthentication.OPTIONAL)
>>> auth.mutual_authentication == MutualAuthentication.OPTIONAL
True

Authentication¶

class httpx2_kerberos.HTTPKerberosAuth(mutual_authentication=MutualAuthentication.REQUIRED, service='HTTP', delegate=False, principal=None, hostname_override=None, sanitize_mutual_error_response=True, send_cbt=True)¶

Bases: Auth

HTTPX2 authentication class for Kerberos/Negotiate challenges.

The object is passed to httpx2 as the auth argument. It sends the original request first, handles a 401 response with a WWW-Authenticate: Negotiate challenge, and then retries the request with an Authorization: Negotiate header.

Parameters:

mutual_authentication (int) – Mutual authentication policy. Values are coerced to MutualAuthentication.
service (str) – Kerberos service name. HTTP services normally use "HTTP".
delegate (bool) – Request credential delegation when the server supports it.
principal (str | None) – Optional client principal. On Windows this may include a password as "user@REALM:password".
hostname_override (str | Mapping[str, str] | None) – Kerberos hostname to use instead of the request hostname, or a mapping from request hostname to Kerberos hostname. A missing mapping key falls back to the request hostname.
sanitize_mutual_error_response (bool) – When mutual authentication is required, strip unauthenticated error responses before returning them.
send_cbt (bool) – Send TLS channel binding data when it can be retrieved.

Example

>>> from httpx2_kerberos import HTTPKerberosAuth, MutualAuthentication
>>> auth = HTTPKerberosAuth(mutual_authentication=MutualAuthentication.OPTIONAL)
>>> auth.mutual_authentication == MutualAuthentication.OPTIONAL
True

Single-host alias example:

>>> auth = HTTPKerberosAuth(hostname_override="internal.example.test")
>>> auth.hostname_override
'internal.example.test'

Multi-host alias example:

>>> auth = HTTPKerberosAuth(
...     hostname_override={
...         "external-a.example.test": "internal-a.example.test",
...         "external-b.example.test": "internal-b.example.test",
...     }
... )
>>> auth.hostname_override["external-a.example.test"]
'internal-a.example.test'

__init__(mutual_authentication=MutualAuthentication.REQUIRED, service='HTTP', delegate=False, principal=None, hostname_override=None, sanitize_mutual_error_response=True, send_cbt=True)¶

Initialize a Kerberos authentication handler.

Parameters:

mutual_authentication (int) – Mutual authentication policy. Integer values are converted to MutualAuthentication.
service (str) – Kerberos service component used when constructing the service principal name. HTTP services normally use "HTTP".
delegate (bool) – Request delegated credentials from the Kerberos backend when the server supports delegation.
principal (str | None) – Optional client principal. A value containing one colon is split into username and password before calling spnego.client.
hostname_override (str | Mapping[str, str] | None) – Kerberos hostname override. A string applies to every request. A mapping applies per request host and falls back to the request host when a key is missing.
sanitize_mutual_error_response (bool) – Strip unauthenticated error responses when mutual authentication is required.
send_cbt (bool) – Attempt TLS channel binding for HTTPS requests.

_kerberos_hostname(host)¶

Resolve the Kerberos target hostname for a request host.

A string hostname_override is returned for every host. A mapping override is looked up by request host and falls back to host when no mapping entry exists.

Parameters:: host (str) – Hostname from the request URL.
Returns:: Hostname to pass to spnego.client.
Return type:: str

auth_flow(request)¶

Execute the HTTPX2 Kerberos authentication flow.

The flow sends the original request first. For a 401 response with a Negotiate challenge, it prepares channel binding data when enabled, adds an Authorization header to the request, and yields the request again. Non-401 responses are passed to handle_other() for optional mutual authentication.

Parameters:

request (Request) – Request being authenticated.

Yields:

The original request and, when Kerberos is supported, the authenticated retry request.

Raises:

MutualAuthenticationError – If a response cannot be mutually authenticated when required.
KerberosExchangeError – If the Kerberos backend fails while generating an authorization token.

Return type:

Generator[Request, Response, None]

handle_auth_error(request, response)¶

Handle a 401 response and attempt Kerberos authentication.

Parameters:

request (Request) – Request that will receive the Authorization header.
response (Response) – 401 response containing a possible Negotiate challenge.

Raises:

KerberosUnsupported – If the response does not include a WWW-Authenticate: Negotiate token.
KerberosExchangeError – If token generation fails.

Return type:

None

handle_other(response)¶

Handle non-401 responses and enforce mutual authentication.

Successful responses must include a valid server authentication token when mutual authentication is required. Error responses may be returned as-is, sanitized, or allowed depending on mutual_authentication and sanitize_mutual_error_response.

Parameters:: response (Response) – Response returned after the initial request or authenticated retry.
Raises:: MutualAuthenticationError – If mutual authentication is required and the response cannot be authenticated.
Return type:: None

authenticate_user(request, response)¶

Add a Kerberos Authorization header to a request.

The request is mutated in place because HTTPX2 auth flows retry the same request object after the 401 challenge.

Parameters:

request (Request) – Request to update with an authorization header.
response (Response) – Challenge response used to continue the SPNEGO exchange.

Raises:

KerberosExchangeError – If the Kerberos backend fails while generating the request token.

Return type:

None

authenticate_server(response)¶

Authenticate a server response token with the stored context.

Parameters:: response (Response) – Response containing a WWW-Authenticate: Negotiate server token.
Returns:: True when the server token is accepted, otherwise False.
Return type:: bool

generate_request_header(response, host)¶

Generate the value for an Authorization header.

This creates a new spnego.client context for host, performs one context step using the server token from response, stores the context for later mutual authentication, and returns a header value in the form "Negotiate <base64-token>".

Parameters:

response (Response) – Challenge response containing the server token.
host (str) – Request host used to key the authentication context and channel binding cache.

Returns:

Complete Authorization header value.

Raises:

KerberosExchangeError – If context initialization or stepping fails in the Kerberos backend.

Return type:

str

class httpx2_kerberos.MutualAuthentication(*values)¶

Mutual authentication policy for HTTPKerberosAuth.

REQUIRED verifies successful responses by default. OPTIONAL accepts responses from servers that do not advertise mutual authentication. DISABLED skips server authentication entirely.

Example

>>> MutualAuthentication.REQUIRED.value
1
>>> MutualAuthentication(MutualAuthentication.DISABLED) == MutualAuthentication.DISABLED
True

Exceptions and Warnings¶

Exceptions and warnings emitted by httpx2_kerberos.

Authentication errors keep the original httpx2.Response on the exception so callers can inspect the status code, headers, or request that failed.

Example

>>> from httpx2 import Request, Response
>>> from httpx2_kerberos.exceptions import KerberosExchangeError
>>> response = Response(401, request=Request("GET", "https://example.test/"))
>>> error = KerberosExchangeError("ctx step failed", response=response)
>>> error.response is response
True

exception httpx2_kerberos.exceptions.NegotiationStepFailedWarning¶: Warning emitted when SPNEGO returns no negotiation token.

exception httpx2_kerberos.exceptions.NoCertificateRetrievedWarning¶: Warning emitted when TLS channel binding data cannot be retrieved.

exception httpx2_kerberos.exceptions.UnknownSignatureAlgorithmOID¶: Warning emitted when a certificate signature algorithm is unsupported.

exception httpx2_kerberos.exceptions.MutualAuthenticationError(message, *, response)¶

Unable to verify the server during mutual authentication.

Parameters:

message (str) – Human-readable failure detail.
response (Response) – Response that could not be authenticated.

Return type:

None

exception httpx2_kerberos.exceptions.KerberosExchangeError(message, *, response)¶

Kerberos token exchange failed.

Parameters:

message (str) – Human-readable failure detail from the Kerberos backend.
response (Response) – Response that triggered the failed exchange.

Return type:

None

exception httpx2_kerberos.exceptions.KerberosUnsupported¶: Internal signal used when a server does not advertise Negotiate auth.

API Reference¶

Package¶

Authentication¶

Exceptions and Warnings¶

httpx2_kerberos

Navigation

Related Topics