RETIRED, further work has moved to Debian project infrastructure
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Cory Benfield 38979f8899 Merge pull request #87 from aowi/master 4 years ago
requests_kerberos v0.11.0 5 years ago
.gitignore Added dist, build and egg dirs to .gitignore. 8 years ago
.travis.yml Test 3.4 also. 6 years ago
AUTHORS Add myself to the authors list 8 years ago
HISTORY.rst v0.11.0 5 years ago
LICENSE add license title 5 years ago Fixed 8 years ago
README.rst add a note on delegation to the README 4 years ago
requirements.txt Require at least WinKerberos 0.5.0. 5 years ago
setup.cfg Use wheel 7 years ago Require at least WinKerberos 0.5.0. 5 years ago Swap kerberos-sspi with winkerberos. 5 years ago


requests Kerberos/GSSAPI authentication library

Requests is an HTTP library, written in Python, for human beings. This library adds optional Kerberos/GSSAPI authentication support and supports mutual authentication. Basic GET usage:

The entire requests.api should be supported.

Authentication Failures

Client authentication failures will be communicated to the caller by returning the 401 response.

Mutual Authentication


By default, HTTPKerberosAuth will require mutual authentication from the server, and if a server emits a non-error response which cannot be authenticated, a requests_kerberos.errors.MutualAuthenticationError will be raised. If a server emits an error which cannot be authenticated, it will be returned to the user but with its contents and headers stripped. If the response content is more important than the need for mutual auth on errors, (eg, for certain WinRM calls) the stripping behavior can be suppressed by setting sanitize_mutual_error_response=False:


If you'd prefer to not require mutual authentication, you can set your preference when constructing your HTTPKerberosAuth object:

This will cause requests_kerberos to attempt mutual authentication if the server advertises that it supports it, and cause a failure if authentication fails, but not if the server does not support it at all.


While we don't recommend it, if you'd prefer to never attempt mutual authentication, you can do that as well:

Preemptive Authentication

HTTPKerberosAuth can be forced to preemptively initiate the Kerberos GSS exchange and present a Kerberos ticket on the initial request (and all subsequent). By default, authentication only occurs after a 401 Unauthorized response containing a Kerberos or Negotiate challenge is received from the origin server. This can cause mutual authentication failures for hosts that use a persistent connection (eg, Windows/WinRM), as no Kerberos challenges are sent after the initial auth handshake. This behavior can be altered by setting force_preemptive=True:

Hostname Override

If communicating with a host whose DNS name doesn't match its kerberos hostname (eg, behind a content switch or load balancer), the hostname used for the Kerberos GSS exchange can be overridden by setting the hostname_override arg:

Explicit Principal

HTTPKerberosAuth normally uses the default principal (ie, the user for whom you last ran kinit or kswitch, or an SSO credential if applicable). However, an explicit principal can be specified, which will cause Kerberos to look for a matching credential cache for the named user. This feature depends on OS support for collection-type credential caches, as well as working principal support in PyKerberos (it is broken in many builds). An explicit principal can be specified with the principal arg:

On Windows, WinKerberos is used instead of PyKerberos. WinKerberos allows the use of arbitrary principals instead of a credential cache. Passwords can be specified by following the form user@realm:password for principal.


requests_kerberos supports credential delegation (GSS_C_DELEG_FLAG). To enable delegation of credentials to a server that requests delegation, pass delegate=True to HTTPKerberosAuth:

Be careful to only allow delegation to servers you trust as they will be able to impersonate you using the delegated credentials.


This library makes extensive use of Python's logging facilities.

Log messages are logged to the requests_kerberos and requests_kerberos.kerberos_ named loggers.

If you are having difficulty we suggest you configure logging. Issues with the underlying kerberos libraries will be made apparent. Additionally, copious debug information is made available which may assist in troubleshooting if you increase your log level all the way up to debug.