13c20d366e
This reverts commitb87f71b90e
, reversing changes made tob86ced24d1
.
147 lines
5.3 KiB
ReStructuredText
147 lines
5.3 KiB
ReStructuredText
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:
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
>>> import requests
|
|
>>> from requests_kerberos import HTTPKerberosAuth
|
|
>>> r = requests.get("http://example.org", auth=HTTPKerberosAuth())
|
|
...
|
|
|
|
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
|
|
---------------------
|
|
|
|
REQUIRED
|
|
^^^^^^^^
|
|
|
|
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``:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> import requests
|
|
>>> from requests_kerberos import HTTPKerberosAuth, REQUIRED
|
|
>>> kerberos_auth = HTTPKerberosAuth(mutual_authentication=REQUIRED, sanitize_mutual_error_response=False)
|
|
>>> r = requests.get("https://windows.example.org/wsman", auth=kerberos_auth)
|
|
...
|
|
|
|
|
|
OPTIONAL
|
|
^^^^^^^^
|
|
|
|
If you'd prefer to not require mutual authentication, you can set your
|
|
preference when constructing your ``HTTPKerberosAuth`` object:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> import requests
|
|
>>> from requests_kerberos import HTTPKerberosAuth, OPTIONAL
|
|
>>> kerberos_auth = HTTPKerberosAuth(mutual_authentication=OPTIONAL)
|
|
>>> r = requests.get("http://example.org", auth=kerberos_auth)
|
|
...
|
|
|
|
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.
|
|
|
|
DISABLED
|
|
^^^^^^^^
|
|
|
|
While we don't recommend it, if you'd prefer to never attempt mutual
|
|
authentication, you can do that as well:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> import requests
|
|
>>> from requests_kerberos import HTTPKerberosAuth, DISABLED
|
|
>>> kerberos_auth = HTTPKerberosAuth(mutual_authentication=DISABLED)
|
|
>>> r = requests.get("http://example.org", auth=kerberos_auth)
|
|
...
|
|
|
|
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``:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> import requests
|
|
>>> from requests_kerberos import HTTPKerberosAuth, REQUIRED
|
|
>>> kerberos_auth = HTTPKerberosAuth(mutual_authentication=REQUIRED, force_preemptive=True)
|
|
>>> r = requests.get("https://windows.example.org/wsman", auth=kerberos_auth)
|
|
...
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> import requests
|
|
>>> from requests_kerberos import HTTPKerberosAuth, REQUIRED
|
|
>>> kerberos_auth = HTTPKerberosAuth(hostname_override="internalhost.local")
|
|
>>> r = requests.get("https://externalhost.example.org/", auth=kerberos_auth)
|
|
...
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> import requests
|
|
>>> from requests_kerberos import HTTPKerberosAuth, REQUIRED
|
|
>>> kerberos_auth = HTTPKerberosAuth(principal="user@REALM")
|
|
>>> r = requests.get("http://example.org", auth=kerberos_auth)
|
|
...
|
|
|
|
Logging
|
|
-------
|
|
|
|
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.
|