PyKerberos

Warnings

• breaking Older versions (pre-1.2.4) experienced C API incompatibility issues with Python 3.10+ and pointer alignment problems on M1 Macs. Users on these platforms should upgrade to v1.2.4 or newer to avoid errors.
  Fix: Upgrade to `pykerberos==1.2.4` or a newer version using `pip install --upgrade pykerberos`.
• gotcha PyKerberos is a C extension and requires system-level Kerberos development libraries (e.g., `krb5-devel` on RHEL/CentOS/Fedora, `libkrb5-dev` on Debian/Ubuntu, or Homebrew `krb5` with Xcode Command Line Tools on macOS) to be installed *before* `pip install pykerberos`. Installation will fail without them.
  Fix: Install the appropriate Kerberos development package for your OS before installing pykerberos. Example: `sudo yum install krb5-devel` or `sudo apt-get install libkrb5-dev`.
• gotcha Versions prior to 1.1.9 had known memory leaks in GSS code and less robust Python 3 compatibility. It's strongly recommended to use v1.1.9 or newer for improved stability and Python 3 support.
  Fix: Upgrade to `pykerberos==1.1.9` or a newer version using `pip install --upgrade pykerberos`.
• gotcha Common errors (e.g., `kerberos.GSSError`) arise from incorrect Kerberos setup: missing `kinit` tickets, incorrect service principal, or KDC unreachability. Ensure your Kerberos environment is properly configured.
  Fix: Verify Kerberos tickets (`klist`), service principal format, and network connectivity to your KDC. Consult Kerberos documentation for your specific environment and use `KRB5_TRACE=/dev/stderr` for detailed debugging.

Install

• pip install pykerberos Install PyKerberos

Imports

• kerberos

  import kerberos

Quickstart

This quickstart demonstrates how to initialize a Kerberos client context and generate the first authentication token using `pykerberos`. It simulates the client-side of a GSSAPI negotiation flow. To run this, you'll typically need an active Kerberos ticket (e.g., obtained via `kinit`) and the correct service principal for your target service. Remember to install system Kerberos development libraries before installing pykerberos.

import kerberos
import os

try:
    # Service principal for the target service (e.g., HTTP service on a host)
    # Replace 'HTTP/server.example.com@REALM.COM' with your actual service principal.
    # For a runnable example, we use an environment variable.
    service_principal = os.environ.get('KERBEROS_SERVICE_PRINCIPAL', 'HTTP/fakeserver.example.com@FAKE.REALM')

    # Initialize a Kerberos client context
    # rc: return code (0 for success, non-zero for error)
    # vc: client context handle (opaque object)
    rc, vc = kerberos.authGSSClientInit(service_principal)

    if rc == kerberos.AUTH_GSS_COMPLETE:
        print(f"Successfully initialized Kerberos client context for {service_principal}")

        # Perform the first step of GSS-API negotiation
        # This generates a token to send to the server.
        # The input 'challenge' is empty for the first step.
        rc_step, client_token = kerberos.authGSSClientStep(vc, "")

        if rc_step == kerberos.AUTH_GSS_COMPLETE:
            print(f"Generated client token (to send to server): {client_token[:60]}...")
            print("Kerberos client authentication flow started.")
            print("Next, send this token to your server and process its response with authGSSClientStep.")
        else:
            print(f"Kerberos client step failed with return code: {rc_step}")

        # Clean up the client context when done
        kerberos.authGSSClientClean(vc)
        print("Kerberos client context cleaned up.")

    else:
        print(f"Failed to initialize Kerberos client context for {service_principal}. Return code: {rc}")
        print("Possible reasons: missing kinit ticket, incorrect service principal, or system Kerberos setup issues.")

except kerberos.GSSError as e:
    print(f"Kerberos GSSAPI Error: {e}")
    print("Make sure you have Kerberos development libraries (e.g., krb5-devel) installed and KDC is reachable.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")