python-gssapi

Python-GSSAPI (imported as gssapi) is a Python interface to RFC 2743/2744, the Generic Security Services API used for authentication, message integrity, and confidentiality across mechanisms like Kerberos. Rather than shelling out to system tools, it exposes GSSAPI as native Python objects — Name, Credentials, SecurityContext, and Mechanism — built on a Cython layer that binds directly to your system’s GSSAPI C library (typically MIT krb5 or Heimdal).

The library ships both a low-level API (gssapi.raw) that mirrors the C GSSAPI calls one-to-one, and a high-level, object-oriented API layered on top that most applications use directly. It’s the security-context negotiation and message wrap/unwrap engine behind SPNEGO/Kerberos support in projects like requests-gssapi, pykerberos-based clients, and SASL/LDAP integrations, and is widely used for single sign-on, mutual authentication between services, and signed or encrypted service-to-service messaging.

What You Get

• High-level Name, Credentials, SecurityContext, and Mechanism classes for everyday GSSAPI usage
• A low-level gssapi.raw module mirroring the RFC 2743/2744 C API one-to-one for advanced control
• Extension support for RFC 4178 SPNEGO negotiation, RFC 5801 SASL naming, and RFC 6680 naming extensions
• Credential import/export and credential-store extensions for passing credentials between processes
• A fully typed Python API with a py.typed marker and mypy-checked stubs for static analysis

Common Use Cases

• Adding Kerberos-based single sign-on to an internal web service or API client
• Implementing SPNEGO negotiation for browser-to-server authentication
• Signing and encrypting messages between services with wrap/unwrap
• Building LDAP or SASL clients that authenticate via GSSAPI mechanisms
• Impersonating a service identity via S4U2Self/S4U2Proxy in constrained-delegation scenarios

Under The Hood

Architecture The library is layered: near-1:1 Cython bindings to the system GSSAPI C library live in gssapi/raw (e.g. creds.pyx, sec_contexts.pyx, message.pyx), cimporting the C API through .pxd declarations against the vendored python_gssapi*.h headers, plus a set of ext_*.pyx modules for optional RFC extensions that are conditionally imported through import_gssapi_extension() in _utils.py so unsupported mechanisms fail with a clear NotImplementedError rather than crashing. The high-level package (gssapi/names.py, creds.py, sec_contexts.py, mechs.py) subclasses these raw Cython types directly — Name extends raw.names.Name, Credentials extends raw.creds.Creds — adding string encoding/decoding, named-tuple results, and deferred-error handling via the CheckLastError metaclass and catch_and_return_token decorator. Because the high-level classes literally inherit from the raw extension types, the raw layer’s mapping to the underlying C ABI is the single point of contact with the system GSSAPI implementation, and changes there propagate straight through to application code.

Tech Stack Built with setuptools and Cython 3.3.0 (declared in pyproject.toml’s build-system), compiling extension modules for CPython 3.9+, including limited-API and free-threading (PEP 703) builds gated by interpreter version checks in setup.py. It links against an external system GSSAPI implementation (MIT krb5 or Heimdal), located at build time via krb5-config (overridable through GSSAPI_KRB5CONFIG), and has no Python runtime dependency beyond the decorator package. Every .pyx module ships a matching .pyi stub, checked under mypy 1.17.1 in strict mode (disallow_untyped_defs, disallow_any_unimported). Test tooling (test-requirements.txt) includes k5test for spinning up an ephemeral MIT Kerberos KDC, parameterized, and flake8; CI is defined in .github/workflows/ci.yml and ci/*.sh.

Code Quality gssapi/tests/test_raw.py and test_high_level.py run against a real ephemeral Kerberos KDC via k5test rather than mocks, exercising credential acquisition, context negotiation, and wrap/unwrap round-trips against an actual GSSAPI mechanism instead of stubbed C calls. Error handling is explicit and typed: GSSAPI major/minor error codes are converted into a hierarchy of specific exceptions (BadNameError, ExpiredCredentialsError, MissingContextError, etc.) defined in exceptions.py, and SecurityContext.step() deliberately defers exceptions via __DEFER_STEP_ERRORS__ so the negotiation partner still receives an error token instead of the connection just dying silently. Naming stays consistent with RFC 2744 terminology throughout, docstrings are extensive and Sphinx-formatted with Args/Returns/Raises on nearly every public method, and the codebase is fully typed with a py.typed marker enforced by strict-mode mypy in CI; flake8 covers style, though there’s no evidence of an autoformatter being enforced.

API Design The defining design choice is that high-level objects are literal subclasses of the low-level Cython types, so a Name, Credentials, or SecurityContext can be passed interchangeably into high-level methods or raw RFC-2744-style functions — there’s no separate wrapper/unwrapper boundary for callers to reason about. Optional RFC extensions (SPNEGO, credential store, S4U, naming) are probed at import time and surface as None when the local system GSSAPI library lacks them, so calling an unsupported feature raises a descriptive NotImplementedError rather than a segfault or a generic AttributeError. Getting started requires only pip install gssapi plus a system Kerberos development package; a caller can go from Credentials() to a working SecurityContext in a handful of lines, with the negotiation loop pattern documented directly in the step() docstring and a runnable tutorial in the docs. This ergonomic honesty about platform and extension support, more than any single novel algorithm, is what sets it apart from ad hoc ctypes-based GSSAPI wrappers.