Requests Kerberos Authentication

Warnings

• breaking Dropped support for Python 2 and raised the minimum Python version to 3.6.
  Fix: Ensure your project is running on Python 3.6 or newer. Upgrade Python if necessary.
• breaking The underlying Kerberos dependency changed from older libraries to `pyspnego`. Additionally, `wrap_winrm` and `unwrap_winrm` functions were removed.
  Fix: If you relied on `wrap_winrm` or `unwrap_winrm`, these functions are no longer available and require alternative implementations. The change to `pyspnego` is largely internal but may impact specific GSSAPI setups.
• gotcha The `context` attribute on `HTTPKerberosAuth` was renamed to `_context` to indicate it is for internal use only.
  Fix: Avoid directly accessing or relying on the `_context` attribute, as it's not part of the public API and may change without notice.
• gotcha Support for proxying `HTTPS` endpoints with Kerberos authentication is not available due to limitations of the underlying `requests` and `urllib3` libraries.
  Fix: For HTTPS proxying with Kerberos, an alternative approach or a different authentication library might be necessary. This limitation applies specifically to `HTTPS` over `HTTP` proxies that require Kerberos authentication.
• gotcha By default, `HTTPKerberosAuth` requires mutual authentication (`mutual_authentication=REQUIRED`), meaning it will verify the server's identity. If verification fails, a `requests_kerberos.errors.MutualAuthenticationError` is raised. If a server emits an error which cannot be authenticated, the response content/headers might be stripped unless `sanitize_mutual_error_response=False` is set.
  Fix: If mutual authentication is not strictly required or is causing issues with specific services, you can set `mutual_authentication=OPTIONAL` or `mutual_authentication=DISABLED` when initializing `HTTPKerberosAuth`. Consider `sanitize_mutual_error_response=False` if you need to inspect error responses regardless of authentication status.
• gotcha For `requests-kerberos` to function, a Kerberos Ticket-Granting Ticket (TGT) must typically be available in the local credential cache (e.g., obtained via `kinit`). Without an active TGT, authentication attempts will fail.
  Fix: Ensure a valid TGT is present by running `kinit` or configuring your environment for automatic TGT renewal. For programmatic control, `HTTPKerberosAuth` can accept `principal` and `password` arguments, though this is generally less secure than using a credential cache.
• gotcha The implementation of Channel Binding Tokens (CBT) for `send_cbt` is now per-host. This might change behavior if your setup previously relied on a global CBT configuration.
  Fix: Review how `send_cbt` is configured and ensure it aligns with the new per-host behavior, especially in environments with multiple Kerberos-protected services.

Install

• pip install requests-kerberos Install with pip

Imports

• HTTPKerberosAuth

  from requests_kerberos import HTTPKerberosAuth

Quickstart

This quickstart demonstrates how to make a GET request to a Kerberos-protected service. It uses `HTTPKerberosAuth` to handle the authentication handshake. Ensure you have an active Kerberos Ticket-Granting Ticket (TGT) on your system (e.g., by running `kinit`) for the default principal to be used. The `KERBEROS_PROTECTED_URL` environment variable can be used to specify the target URL, otherwise a placeholder is used.

import requests
import os
from requests_kerberos import HTTPKerberosAuth, REQUIRED

# NOTE: This example requires an active Kerberos Ticket-Granting Ticket (TGT)
# obtained via `kinit` or similar, or explicit principal/password (not shown).
# Replace 'http://your-kerberos-protected-service.example.com' with your actual URL.

KERBEROS_URL = os.environ.get('KERBEROS_PROTECTED_URL', 'http://your-kerberos-protected-service.example.com')

try:
    # By default, mutual_authentication=REQUIRED (as explicitly shown here)
    # means the client will verify the server's identity.
    response = requests.get(KERBEROS_URL, auth=HTTPKerberosAuth(mutual_authentication=REQUIRED))
    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)

    print(f"Successfully authenticated to {KERBEROS_URL}")
    print(f"Status Code: {response.status_code}")
    print(f"Response content snippet: {response.text[:200]}...")

except requests.exceptions.RequestException as e:
    print(f"Error accessing Kerberos protected service: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")