Python SPNEGO Authentication Library

Warnings

• breaking Support for Python 3.7 was dropped in version 0.12.0. The minimum required Python version is now 3.9+.
  Fix: Upgrade your Python environment to 3.9 or higher.
• deprecated Direct imports from `spnego.gss`, `spnego.negotiate`, `spnego.ntlm`, and `spnego.sspi` are deprecated. These exports are now private.
  Fix: Use `import spnego.client` for client-side operations and `import spnego.server` for server-side operations.
• deprecated The `username` and `password` properties on authentication context objects are deprecated and will return `None` in future releases.
  Fix: Avoid relying on these properties. The library's `Context` initialization methods still accept `username` and `password` as arguments, but accessing them directly on the context object is discouraged.
• breaking In CredSSP contexts, the `client_credential` property has been removed.
  Fix: Retrieve delegated client credentials using `context.get_extra_info('client_credential')` instead.
• gotcha When using GSSAPI on Linux, particularly with MIT krb5 versions <=1.18.2, channel bindings might fail with pure SPNEGO. This can lead to authentication failures if channel bindings are required by the acceptor.
  Fix: To work around this, set `options=spnego.NegotiateOptions.use_negotiate` when creating the context, or explicitly set `protocol` to either `ntlm` or `kerberos`.
• gotcha When using explicit Kerberos credentials with MIT krb5 versions less than 1.14, the credentials might be stored in the system credential cache, making them accessible to other processes for that user.
  Fix: Upgrade MIT krb5 to at least version 1.14. Alternatively, set the `KRB5CCNAME` environment variable to a process-specific temporary file and delete it after use to ensure credentials are not stored in the default system cache.

Install

• pip install pyspnego Base Installation
• pip install pyspnego[kerberos] With Kerberos support (requires system packages)

Imports

• client

  import spnego.client

  Direct imports from `spnego.gss`, `spnego.negotiate`, `spnego.ntlm`, and `spnego.sspi` are deprecated and will be removed in a future major release. Use `spnego.client` for client-side operations.
• server

  import spnego.server

  Direct imports from `spnego.gss`, `spnego.negotiate`, `spnego.ntlm`, and `spnego.sspi` are deprecated and will be removed in a future major release. Use `spnego.server` for server-side operations.

Quickstart

This quickstart demonstrates how to create a client-side SPNEGO authentication context using `pyspnego`. It initializes a client context with provided (or environment variable sourced) credentials and generates an initial authentication token. In a real-world scenario, this token would be exchanged with a server to complete the authentication handshake.

import spnego
import os

# Example for a client initiating a Negotiate (SPNEGO) context
# Replace with actual credentials or environment variables
username = os.environ.get('SPNEGO_USERNAME', 'testuser')
password = os.environ.get('SPNEGO_PASSWORD', 'testpassword')
service_principal_name = os.environ.get('SPNEGO_SPN', 'HTTP@myservice.example.com')

try:
    # Create a client context. 'negotiate' is the default protocol.
    # For NTLM: protocol='ntlm'
    # For Kerberos: protocol='kerberos' (requires system GSSAPI/Kerberos libs on Linux)
    client_context = spnego.client.Context(
        username=username,
        password=password,
        hostname=service_principal_name.split('@')[1] if '@' in service_principal_name else None,
        service=service_principal_name.split('@')[0] if '@' in service_principal_name else None,
        protocol='negotiate'
    )

    # The client typically sends an initial token
    initial_token = client_context.step()

    print(f"Initial SPNEGO token (base64 encoded): {initial_token.decode('utf-8')}")

    # In a real scenario, this token would be sent to the server,
    # which would then return a response token. The client would then
    # call client_context.step(server_response_token) until complete.

except spnego.exceptions.NegotiateError as e:
    print(f"Authentication error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")