treq-kerberos 1.2.0

Kerberos auth for Twisted's treq

Kerberos authentication with Twisted’s treq

treq-kerberos adds Kerberos (SPNEGO/HTTP Negotiate) authentication for treq.

treq is a requests-like library for making HTTP requests asynchronously (non-blocking) using the Twisted framework.

treq-kerberos is inspired by requests-kerberos.

Simple Example: making a request

GET a URL that requires Kerberos authentication:

from treq_kerberos import TreqKerberosAuth
import treq_kerberos
from twisted.internet import defer, reactor


@defer.inlineCallbacks
def example():
    url = 'https://errata.devel.redhat.com/'
    auth = TreqKerberosAuth()
    try:
        response = yield treq_kerberos.get(url, auth=auth)
        content = yield response.content()
        print(content)
    except Exception as e:
        print(e)


if __name__ == '__main__':
    example().addCallback(lambda ign: reactor.stop())
    reactor.run()

(See the full script at examples/get.py.)

Other HTTP methods

treq-kerberos implements the same basic API as treq, so you can call the methods for each of the HTTP verbs:

@defer.inlineCallbacks
def example():
    url = 'https://example.com/'
    auth = TreqKerberosAuth()

    data = {'my': 'parameter'}

    # HTTP GET
    response = yield treq_kerberos.get(url, auth=auth)

    # HTTP PUT
    response = yield treq_kerberos.put(url, data=data, auth=auth)

    # HTTP POST
    response = yield treq_kerberos.post(url, data=data, auth=auth)

    # HTTP PATCH
    response = yield treq_kerberos.patch(url, data=data, auth=auth)

    # HTTP HEAD (note that content() will always be blank)
    response = yield treq_kerberos.head(url, auth=auth)

    # HTTP DELETE
    response = yield treq_kerberos.delete(url, auth=auth)

Alternatively you may also call the general request() method:

# HTTP GET
response = yield treq_kerberos.request('GET', url, auth=auth)

Preemptive authentication

Ordinarily, web clients attempt HTTP Negotiate authentication only after receiving a HTTP 401 response from the web server. The client then retries with the proper Authentication: Negotiate ... header.

If you know your web server will always prompt for HTTP Negotiate authentication, you can skip the first round-trip by setting the force_preemptive=True keyword argument when instantiating TreqKerberosAuth. (This behavior is identical to request-kerberos’s force_preemptive kwarg for HTTPKerberosAuth.)

@defer.inlineCallbacks
def example():
    url = 'https://errata.devel.redhat.com/'
    auth = TreqKerberosAuth(force_preemptive=True)
    response = yield treq_kerberos.get(url, auth=auth)
    # ...

Integration with treq upstream

At the time of this writing, treq supports HTTP Basic authentication by passing a (username, password) tuple via an auth kwarg.

This module borrows that same auth concept. You pass in a TreqNegotiateAuth object instead of the username and password tuple.

Eventually treq may allow more flexible authentication designs that could be suitable to third parties. When this is available in treq upstream, I want treq-kerberos module to support it, ideally minimizing the API changes to support such a future transition.

TODO:

• Rewrite to use python-gssapi instead of python-kerberos (similar to requests-gssapi).

Packages that use this package

• txkoji