diff --git a/HISTORY.rst b/HISTORY.rst index 1cdcdae..c6e861e 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -1,6 +1,12 @@ History ======= +0.15.0: 2024-06-04 +------------------ + +- Make Channel Binding data per-host +- Added support for explicit passwords using the ``password`` kwarg + 0.14.0: 2021-12-05 ------------------ diff --git a/README.rst b/README.rst index 0d9d962..d38c8ad 100644 --- a/README.rst +++ b/README.rst @@ -21,15 +21,32 @@ The entire ``requests.api`` should be supported. Setup ----- -In order to use this library, there must already be a Kerberos Ticket-Granting -Ticket(TGT) cached in a Kerberos credential cache. Whether a TGT is available -can be easily determined by running the ``klist`` command. If no TGT is -available, then it first must be obtained by running the ``kinit`` command, or -pointing the $KRB5CCNAME to a credential cache with a valid TGT. +Before installing this module, the underlying Kerberos C libraries and Python +development headers need to be installed. An example of how to do this for +some Linux distributions is shown below: -In short, the library will handle the "negotiations" of Kerberos authentication, -but ensuring that an initial TGT is available and valid is the responsibility -of the user. +.. code-block:: bash + + # For Debian based distros + apt-get install gcc python3-dev libkrb5-dev + + # For EL based distros + dnf install gcc python3-devel krb5-devel + +The names of the packages may vary across the distribution so use this as a +general guide. MacOS and Windows users should not need these development +libraries as the underlying Kerberos Python module for those platforms are +provided as a wheel and the C library is already preinstalled. + +While it is possible to use Kerberos authentication with an explicit +``principal`` and ``password`` as an arg to ``HTTPKerberosAuth``, it is +recommended to use an existing credential cache to store the credentials +instead. The credential cache can store a Kerberos Ticket-Granting Ticket +(``TGT``) which is then used for authentication when no ``password`` is given +to ``HTTPKerberosAuth``. The credential cache can store a ``TGT`` by using the +``kinit`` command and ``klist`` can be used to view the contents of the cache. +The environment variable ``KRB5CCNAME`` can be used to specify the location of +a custom credential cache. Authentication Failures ----------------------- @@ -137,9 +154,8 @@ Explicit Principal 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: +This feature depends on OS support for collection-type credential caches. +An explicit principal can be specified with the ``principal`` arg: .. code-block:: python @@ -149,9 +165,27 @@ builds). An explicit principal can be specified with the ``principal`` arg: >>> r = requests.get("http://example.org", auth=kerberos_auth) ... -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``. +Password Authentication +----------------------- + +``HTTPKerberosAuth`` can be used with an explicit principal and password +instead of using a credential stored in the credential cache. An explicit +username and password can be specified with the ``principal`` and ``password`` +arg respectively: + +.. code-block:: python + + >>> import requests + >>> from requests_kerberos import HTTPKerberosAuth, REQUIRED + >>> kerberos_auth = HTTPKerberosAuth( + ... principal="user@REALM", + ... password="SecretPassword", + ...) + >>> r = requests.get("http://example.org", auth=kerberos_auth) + +When specifing a custom principal and password, the underlying Kerberos +library will request a TGT from the KDC before using that TGT to retrieve the +service ticket for authentication. Delegation ---------- diff --git a/requests_kerberos/__init__.py b/requests_kerberos/__init__.py index 54212ee..60407b8 100644 --- a/requests_kerberos/__init__.py +++ b/requests_kerberos/__init__.py @@ -21,4 +21,4 @@ __all__ = ('HTTPKerberosAuth', 'MutualAuthenticationError', 'REQUIRED', 'OPTIONAL', 'DISABLED') -__version__ = '0.14.0' +__version__ = '0.15.0'