{"id":2977,"library":"kerberos","title":"Kerberos (High-level GSSAPI Interface)","description":"The `kerberos` library provides a high-level Python wrapper for Kerberos (GSSAPI) operations, specifically designed for client/server Kerberos authentication based on RFC 4559. It directly wraps the underlying Kerberos 5 C API, offering a limited set of functions for this purpose. The current version is 1.3.1, and it maintains an active release cadence.","status":"active","version":"1.3.1","language":"en","source_language":"en","source_url":"https://github.com/apple/ccs-pykerberos","tags":["authentication","kerberos","gssapi","security","enterprise"],"install":[{"cmd":"pip install kerberos","lang":"bash","label":"Standard install"},{"cmd":"sudo apt-get install python3-dev libkrb5-dev gcc","lang":"bash","label":"Debian/Ubuntu system dependencies (before pip install)"},{"cmd":"sudo yum install python3-devel krb5-devel gcc","lang":"bash","label":"RHEL/Fedora system dependencies (before pip install)"}],"dependencies":[{"reason":"The library is a C extension wrapper and requires a system-level Kerberos 5 API implementation and its development headers.","package":"Kerberos 5 API (e.g., MIT Kerberos >= 1.17 or Heimdal)","optional":false},{"reason":"Required to compile the C extension during installation.","package":"C Compiler (e.g., GCC)","optional":false}],"imports":[{"note":"The top-level module exposes functions directly.","symbol":"kerberos","correct":"import kerberos"}],"quickstart":{"code":"import kerberos\nimport os\n\n# This is a simplified example. A real Kerberos setup with a KDC, service principal, and active tickets (kinit) is required.\n# Set up a dummy service principal name for illustration.\n# In a real scenario, this would be 'HTTP/your.service.com@REALM'\nservice_principal = os.environ.get('KERBEROS_SPN', 'HTTP/host.example.com@EXAMPLE.COM')\n\nnegotiate_token = None\ntry:\n    # Initialize a Kerberos GSSAPI client context.\n    # `gssflags` can be used to specify options like GSS_C_DELEG_FLAG.\n    # `principal` can specify the client principal, if not using default cache.\n    result, context = kerberos.authGSSClientInit(service_principal)\n\n    # The client sends a 'token' (negotiate_token) to the server.\n    # In a real HTTP exchange, this token would be part of the Authorization header.\n    # This step simulates the client-side generation of the initial token.\n    result = kerberos.authGSSClientStep(context, negotiate_token)\n\n    # If successful, get the token to send to the server.\n    negotiate_token = kerberos.authGSSClientResponse(context)\n    print(f\"Initial GSSAPI token generated: {negotiate_token[:30]}...\")\n\n    # In a real scenario, the server would send back its own token,\n    # which the client would then process in subsequent authGSSClientStep calls.\n    # For this quickstart, we just demonstrate the client init.\n\nexcept kerberos.KerberosError as e:\n    print(f\"Kerberos Error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Always clean up the context to free resources.\n    if 'context' in locals() and context is not None:\n        kerberos.authGSSClientClean(context)\n","lang":"python","description":"This quickstart demonstrates the very basic client-side initialization of a Kerberos GSSAPI context using `kerberos.authGSSClientInit` and `kerberos.authGSSClientStep`. A real Kerberos environment with a Key Distribution Center (KDC), a configured service principal name (SPN), and an active Kerberos ticket (obtained via `kinit`) is required for successful operation. The process typically involves multiple `authGSSClientStep` calls, exchanging tokens with a server."},"warnings":[{"fix":"Ensure your environment is running Python 3.9 or newer. Consider using a virtual environment to manage Python versions.","message":"The library primarily supports Python 3.9+. Older Python 2 installations or versions prior to 3.9 are not officially supported and may lead to installation or runtime issues.","severity":"breaking","affected_versions":"< 1.3.0 (Python < 3.9)"},{"fix":"Install required system packages before `pip install kerberos`. For Debian/Ubuntu, this is typically `python3-dev libkrb5-dev gcc`. For RHEL/Fedora, `python3-devel krb5-devel gcc`. macOS and Windows users installing from wheels might bypass this, but source installs will require it.","message":"Installation often fails without system-level Kerberos development libraries and a C compiler. This is a common pitfall on Linux and some Windows environments.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid `checkPassword` in production. Implement proper GSSAPI-based authentication flows or use higher-level libraries like `requests-kerberos` or `python-gssapi` that handle security correctly.","message":"The `kerberos.checkPassword` method is explicitly for testing purposes only and should NEVER be used in production code due to its lack of protection against KDC spoofing.","severity":"deprecated","affected_versions":"All versions"},{"fix":"For common HTTP Kerberos authentication, consider `pip install requests-kerberos`. For a more comprehensive and Python-friendly GSSAPI interface, explore `pip install gssapi`.","message":"The `kerberos` library is a low-level wrapper around the C GSSAPI. It is complex to use directly for most application-level Kerberos authentication. Higher-level Python libraries like `python-gssapi` or `requests-kerberos` are generally recommended for ease of use and reduced footguns.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify Kerberos configuration (`/etc/krb5.conf`), ensure a valid ticket exists (`klist`), and confirm the SPN matches the service being accessed. Debug with Kerberos logging if available.","message":"Successful Kerberos authentication requires a properly configured Kerberos client, an active Kerberos ticket (e.g., from `kinit`), and correct Service Principal Names (SPNs). Missing tickets, incorrect `krb5.conf` settings, or SPN mismatches are frequent causes of `KerberosError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}