{"id":7668,"library":"requests-gssapi","title":"GSSAPI Authentication Handler for Requests","description":"requests-gssapi is an HTTP library that extends `python-requests` to provide optional GSSAPI authentication support, including mutual authentication. It acts as a fully backward-compatible shim for the older `requests-kerberos` library, allowing for a seamless transition. The current version is 1.4.0 and requires Python >=3.8. It is actively maintained with releases occurring as needed.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/pythongssapi/requests-gssapi","tags":["gssapi","requests","authentication","kerberos","spnego","sso"],"install":[{"cmd":"pip install requests-gssapi","lang":"bash","label":"PyPI"},{"cmd":"conda install requests-gssapi -c conda-forge","lang":"bash","label":"Conda (conda-forge)"}],"dependencies":[{"reason":"Core HTTP library this package extends.","package":"requests"},{"reason":"Underlying Python bindings for GSSAPI C libraries. Required for GSSAPI functionality.","package":"gssapi","optional":false},{"reason":"Required for optional channel binding functionality (e.g., 'tls-server-end-point').","package":"cryptography","optional":true}],"imports":[{"symbol":"HTTPSPNEGOAuth","correct":"from requests_gssapi import HTTPSPNEGOAuth"},{"note":"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.","wrong":"from requests_kerberos import HTTPKerberosAuth","symbol":"HTTPKerberosAuth","correct":"from requests_gssapi import HTTPKerberosAuth"}],"quickstart":{"code":"import requests\nfrom requests_gssapi import HTTPSPNEGOAuth\n\n# Ensure a Kerberos TGT is available (e.g., by running 'kinit' in your shell)\n# For example purposes, hitting a generic domain, replace with your GSSAPI-enabled service\n\ntry:\n    response = requests.get(\"http://example.org/protected\", auth=HTTPSPNEGOAuth())\n    response.raise_for_status()\n    print(f\"Success: {response.status_code}\")\n    print(response.text)\nexcept requests.exceptions.RequestException as e:\n    print(f\"An error occurred: {e}\")\n\n# Example with opportunistic authentication and target name override\n# response_opportunistic = requests.get(\n#     \"https://your-service.example.com/api\", \n#     auth=HTTPSPNEGOAuth(opportunistic_auth=True, target_name=\"service-principal@REALM\")\n# )\n# print(response_opportunistic.status_code)","lang":"python","description":"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."},"warnings":[{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions up to 1.4.0 (known issue in similar library, applicable here)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you intend to use channel bindings, ensure `pip install cryptography` is executed alongside `requests-gssapi`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `kinit` in your shell to obtain a TGT before executing the Python script. Verify with `klist`.","cause":"The Python environment or the user running the script does not have an active Kerberos Ticket-Granting Ticket (TGT) in a credential cache.","error":"No Kerberos credentials available (Mechanism: 'krb5_gss_mech')"},{"fix":"Explicitly specify the SPNEGO mechanism: \n```python\nimport gssapi\nfrom requests_gssapi import HTTPSPNEGOAuth\n\ntry:\n    spnego_mech = gssapi.mechs.Mechanism.from_sasl_name(\"GS2-SPNEGO\")\nexcept AttributeError:\n    # Fallback for older gssapi versions or specific environments\n    spnego_mech = gssapi.OID.from_int_seq(\"1.3.6.1.5.5.2\")\n\nauth = HTTPSPNEGOAuth(mech=spnego_mech)\nresponse = requests.get(\"http://your-spnego-server.com\", auth=auth)\n```","cause":"The GSSAPI negotiation mechanism defaults to Kerberos 5 (KRB5) when the server expects SPNEGO (Simple Protected Negotiation).","error":"Cannot authenticate with requests-gssapi on SPNEGO server, wrong OID selected (KRB5 instead of SPNEGO)."},{"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.","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.","error":"requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response')) OR MutualAuthenticationError"}]}