GSSAPI Authentication Handler for Requests

Common errors

• No Kerberos credentials available (Mechanism: 'krb5_gss_mech')

  cause The Python environment or the user running the script does not have an active Kerberos Ticket-Granting Ticket (TGT) in a credential cache.
  fix Run `kinit` in your shell to obtain a TGT before executing the Python script. Verify with `klist`.

• Cannot authenticate with requests-gssapi on SPNEGO server, wrong OID selected (KRB5 instead of SPNEGO).

  cause The GSSAPI negotiation mechanism defaults to Kerberos 5 (KRB5) when the server expects SPNEGO (Simple Protected Negotiation).
  fix Explicitly specify the SPNEGO mechanism: ```python import gssapi from requests_gssapi import HTTPSPNEGOAuth try: spnego_mech = gssapi.mechs.Mechanism.from_sasl_name("GS2-SPNEGO") except AttributeError: # Fallback for older gssapi versions or specific environments spnego_mech = gssapi.OID.from_int_seq("1.3.6.1.5.5.2") auth = HTTPSPNEGOAuth(mech=spnego_mech) response = requests.get("http://your-spnego-server.com", auth=auth) ```

• requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response')) OR MutualAuthenticationError

  cause The server closed the connection prematurely, often related to mutual authentication issues where the server does not correctly handle the multiple round-trip authentication handshake, or `requests-gssapi` was configured to require mutual authentication which the server failed to provide.
  fix If mutual authentication is not strictly required for your security model, disable it: `auth=HTTPSPNEGOAuth(mutual_authentication=requests_gssapi.DISABLED)`. Ensure your server is correctly configured for GSSAPI/SPNEGO without requiring additional mutual authentication rounds if that's the desired behavior.

Warnings

• gotcha Mutual Authentication can cause handshake failures with some servers. While historically defaulted to REQUIRED in `requests-kerberos`, `requests-gssapi` has evolved to handle it more flexibly (often `OPTIONAL` or implicitly not required). If you encounter `MutualAuthenticationError`, the server might not be prepared for the extra round-trip, or `REQUIRED` was inadvertently set.
  Fix: Set `mutual_authentication` explicitly to `requests_gssapi.DISABLED` (or `gssapi.C_NO_FLAG`) in `HTTPSPNEGOAuth` if not needed and issues occur: `auth=HTTPSPNEGOAuth(mutual_authentication=requests_gssapi.DISABLED)`.
• breaking Sharing `HTTPSPNEGOAuth` objects across multiple threads can lead to concurrency issues and authentication failures. The library caches `gssapi.SecurityContext` objects per hostname, which can be overwritten by concurrent requests to the same host.
  Fix: Instantiate a new `HTTPSPNEGOAuth` object for each thread or request, or ensure `HTTPSPNEGOAuth` instances are not shared concurrently across requests to the same target hostname.
• gotcha Requests with a body (e.g., POST requests) might fail with a 401 Unauthorized on the initial attempt due to `httplib` not supporting the `Expect-Continue` header. This can lead to additional overhead for request retransmission and failure for non-repeatable bodies.
  Fix: Be aware of this limitation for requests with bodies. If possible, design the server to tolerate retransmitted requests or consider alternative authentication flows for such operations if issues persist.
• gotcha Using channel bindings (e.g., `tls-server-end-point`) requires the `cryptography` Python package to be installed, as `requests-gssapi` attempts to import its `x509` module to process peer certificates.
  Fix: If you intend to use channel bindings, ensure `pip install cryptography` is executed alongside `requests-gssapi`.

Install

• pip install requests-gssapi PyPI
• conda install requests-gssapi -c conda-forge Conda (conda-forge)

Imports

• HTTPSPNEGOAuth

  from requests_gssapi import HTTPSPNEGOAuth

• HTTPKerberosAuth
  wrong:

  from requests_kerberos import HTTPKerberosAuth

  correct:

  from requests_gssapi import HTTPKerberosAuth

  requests-gssapi provides a backward-compatible shim, so the old import still works, but directly importing from requests_gssapi is preferred for clarity and consistency with the new API.

Quickstart

Demonstrates a basic GET request using `HTTPSPNEGOAuth` to an GSSAPI-protected endpoint. It's crucial to have a valid Kerberos Ticket-Granting Ticket (TGT) obtained via `kinit` or similar methods before running. Optional parameters like `opportunistic_auth` and `target_name` are available for more advanced scenarios.

import requests
from requests_gssapi import HTTPSPNEGOAuth

# Ensure a Kerberos TGT is available (e.g., by running 'kinit' in your shell)
# For example purposes, hitting a generic domain, replace with your GSSAPI-enabled service

try:
    response = requests.get("http://example.org/protected", auth=HTTPSPNEGOAuth())
    response.raise_for_status()
    print(f"Success: {response.status_code}")
    print(response.text)
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

# Example with opportunistic authentication and target name override
# response_opportunistic = requests.get(
#     "https://your-service.example.com/api", 
#     auth=HTTPSPNEGOAuth(opportunistic_auth=True, target_name="service-principal@REALM")
# )
# print(response_opportunistic.status_code)