| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173 |
- requests Kerberos/GSSAPI authentication library
- ===============================================
- .. image:: https://travis-ci.org/requests/requests-kerberos.svg?branch=master
- :target: https://travis-ci.org/requests/requests-kerberos
- .. image:: https://coveralls.io/repos/github/requests/requests-kerberos/badge.svg?branch=master
- :target: https://coveralls.io/github/requests/requests-kerberos?branch=master
- 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)
- ...
- 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``.
- Delegation
- ----------
- ``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``:
- .. code-block:: python
- >>> import requests
- >>> from requests_kerberos import HTTPKerberosAuth
- >>> r = requests.get("http://example.org", auth=HTTPKerberosAuth(delegate=True))
- ...
- Be careful to only allow delegation to servers you trust as they will be able
- to impersonate you using the delegated credentials.
- 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.
|