WinKerberos

Warnings

• breaking Upgrading `winkerberos` may require a Python version upgrade. Version 0.11.0 dropped support for Python 3.7. Version 0.10.0 dropped support for Python 2.7, 3.5, and 3.6. Current versions (0.10.0+) require Python >=3.10.
  Fix: Ensure your Python environment meets the `winkerberos` version requirements. For newer `winkerberos` versions, upgrade Python to 3.10 or later. If unable to upgrade Python, pin `winkerberos` to an older compatible version (e.g., `<0.10.0` for Python 3.6, or `<0.11.0` for Python 3.7-3.9).
• gotcha This library is designed exclusively for Windows environments, leveraging the Security Support Provider Interface (SSPI). It will not function on Linux, macOS, or other operating systems.
  Fix: Use platform-agnostic Kerberos libraries like `python-kerberos` for cross-platform compatibility, or ensure deployment is strictly on Windows where `winkerberos` is needed.
• gotcha Successful authentication with `winkerberos` depends on a correctly configured Kerberos environment on the Windows host. This includes domain membership, access to a Key Distribution Center (KDC), valid service principal names (SPNs), and potentially existing Kerberos tickets.
  Fix: Verify the host machine's Kerberos configuration, network connectivity to the KDC, and ensure the target service has a correctly registered SPN. Use tools like `klist` to inspect current tickets and `setspn -L <machine_name>` to list SPNs.
• gotcha Incorrectly formatted or invalid Service Principal Names (SPNs) for `winkerberos.auth()` will result in `GSSError`s during context initiation.
  Fix: Confirm the exact SPN required by your target service (e.g., `service/host@REALM`) and ensure it's registered correctly in Active Directory or your KDC. Double-check case sensitivity and the realm part if explicitly provided.

Install

• pip install winkerberos Install latest version

Imports

• auth

  import winkerberos
  # ...
  context = winkerberos.auth(service_principal, hostname)

  The primary function for initiating a Kerberos security context on Windows.

Quickstart

This quickstart demonstrates how to initiate a Kerberos security context using `winkerberos.auth()`. This function leverages the underlying Windows SSPI to attempt authentication using the current user's Kerberos tickets. Success means a context object is returned, which can then be used for further token exchange in a client-server interaction.

import winkerberos
import os

# Example Service Principal Name (SPN) for a hypothetical service.
# In a real scenario, this would be a valid SPN for the service you want to authenticate with.
# For example: 'HTTP/webserver.example.com@EXAMPLE.COM'
SERVICE_PRINCIPAL = os.environ.get('WINKERBEROS_SPN', 'HTTP/localhost@EXAMPLE.COM')
HOSTNAME = os.environ.get('WINKERBEROS_HOSTNAME', 'localhost')

try:
    # winkerberos typically uses the current logged-in user's credentials
    # on a domain-joined Windows machine, so 'user'/'password' are often not needed.
    context = winkerberos.auth(SERVICE_PRINCIPAL, HOSTNAME)

    if context:
        print(f"Successfully initiated Kerberos context for SPN: {SERVICE_PRINCIPAL}")
        print("Kerberos authentication context established.")
        # In a real application, 'context' would be used to generate tokens
        # for further communication (e.g., context.step('challenge')).
    else:
        print(f"Failed to initiate Kerberos context for SPN: {SERVICE_PRINCIPAL}")
        print("Ensure Kerberos is configured, tickets are available, and the SPN is valid.")

except winkerberos.GSSError as e:
    print(f"Kerberos GSSAPI Error: {e}")
    print("This often indicates issues with the Kerberos configuration, "
          "network, or an invalid Service Principal Name (SPN).")
except Exception as e:
    print(f"An unexpected error occurred: {e}")