{"id":3322,"library":"winkerberos","title":"WinKerberos","description":"WinKerberos is a Python library providing a high-level interface to SSPI (Security Support Provider Interface) for Kerberos client authentication, exclusively for Windows platforms. It is maintained by MongoDB-labs and has a consistent release cadence, frequently updating to support new Python versions.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/mongodb-labs/winkerberos","tags":["kerberos","authentication","windows","sspi","security"],"install":[{"cmd":"pip install winkerberos","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary function for initiating a Kerberos security context on Windows.","symbol":"auth","correct":"import winkerberos\n# ...\ncontext = winkerberos.auth(service_principal, hostname)"}],"quickstart":{"code":"import winkerberos\nimport os\n\n# Example Service Principal Name (SPN) for a hypothetical service.\n# In a real scenario, this would be a valid SPN for the service you want to authenticate with.\n# For example: 'HTTP/webserver.example.com@EXAMPLE.COM'\nSERVICE_PRINCIPAL = os.environ.get('WINKERBEROS_SPN', 'HTTP/localhost@EXAMPLE.COM')\nHOSTNAME = os.environ.get('WINKERBEROS_HOSTNAME', 'localhost')\n\ntry:\n    # winkerberos typically uses the current logged-in user's credentials\n    # on a domain-joined Windows machine, so 'user'/'password' are often not needed.\n    context = winkerberos.auth(SERVICE_PRINCIPAL, HOSTNAME)\n\n    if context:\n        print(f\"Successfully initiated Kerberos context for SPN: {SERVICE_PRINCIPAL}\")\n        print(\"Kerberos authentication context established.\")\n        # In a real application, 'context' would be used to generate tokens\n        # for further communication (e.g., context.step('challenge')).\n    else:\n        print(f\"Failed to initiate Kerberos context for SPN: {SERVICE_PRINCIPAL}\")\n        print(\"Ensure Kerberos is configured, tickets are available, and the SPN is valid.\")\n\nexcept winkerberos.GSSError as e:\n    print(f\"Kerberos GSSAPI Error: {e}\")\n    print(\"This often indicates issues with the Kerberos configuration, \"\n          \"network, or an invalid Service Principal Name (SPN).\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":"0.10.0 and newer"},{"fix":"Use platform-agnostic Kerberos libraries like `python-kerberos` for cross-platform compatibility, or ensure deployment is strictly on Windows where `winkerberos` is needed.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Incorrectly formatted or invalid Service Principal Names (SPNs) for `winkerberos.auth()` will result in `GSSError`s during context initiation.","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"}