README.rst 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173
  1. requests Kerberos/GSSAPI authentication library
  2. ===============================================
  3. .. image:: https://travis-ci.org/requests/requests-kerberos.svg?branch=master
  4. :target: https://travis-ci.org/requests/requests-kerberos
  5. .. image:: https://coveralls.io/repos/github/requests/requests-kerberos/badge.svg?branch=master
  6. :target: https://coveralls.io/github/requests/requests-kerberos?branch=master
  7. Requests is an HTTP library, written in Python, for human beings. This library
  8. adds optional Kerberos/GSSAPI authentication support and supports mutual
  9. authentication. Basic GET usage:
  10. .. code-block:: python
  11. >>> import requests
  12. >>> from requests_kerberos import HTTPKerberosAuth
  13. >>> r = requests.get("http://example.org", auth=HTTPKerberosAuth())
  14. ...
  15. The entire ``requests.api`` should be supported.
  16. Authentication Failures
  17. -----------------------
  18. Client authentication failures will be communicated to the caller by returning
  19. the 401 response.
  20. Mutual Authentication
  21. ---------------------
  22. REQUIRED
  23. ^^^^^^^^
  24. By default, ``HTTPKerberosAuth`` will require mutual authentication from the
  25. server, and if a server emits a non-error response which cannot be
  26. authenticated, a ``requests_kerberos.errors.MutualAuthenticationError`` will
  27. be raised. If a server emits an error which cannot be authenticated, it will
  28. be returned to the user but with its contents and headers stripped. If the
  29. response content is more important than the need for mutual auth on errors,
  30. (eg, for certain WinRM calls) the stripping behavior can be suppressed by
  31. setting ``sanitize_mutual_error_response=False``:
  32. .. code-block:: python
  33. >>> import requests
  34. >>> from requests_kerberos import HTTPKerberosAuth, REQUIRED
  35. >>> kerberos_auth = HTTPKerberosAuth(mutual_authentication=REQUIRED, sanitize_mutual_error_response=False)
  36. >>> r = requests.get("https://windows.example.org/wsman", auth=kerberos_auth)
  37. ...
  38. OPTIONAL
  39. ^^^^^^^^
  40. If you'd prefer to not require mutual authentication, you can set your
  41. preference when constructing your ``HTTPKerberosAuth`` object:
  42. .. code-block:: python
  43. >>> import requests
  44. >>> from requests_kerberos import HTTPKerberosAuth, OPTIONAL
  45. >>> kerberos_auth = HTTPKerberosAuth(mutual_authentication=OPTIONAL)
  46. >>> r = requests.get("http://example.org", auth=kerberos_auth)
  47. ...
  48. This will cause ``requests_kerberos`` to attempt mutual authentication if the
  49. server advertises that it supports it, and cause a failure if authentication
  50. fails, but not if the server does not support it at all.
  51. DISABLED
  52. ^^^^^^^^
  53. While we don't recommend it, if you'd prefer to never attempt mutual
  54. authentication, you can do that as well:
  55. .. code-block:: python
  56. >>> import requests
  57. >>> from requests_kerberos import HTTPKerberosAuth, DISABLED
  58. >>> kerberos_auth = HTTPKerberosAuth(mutual_authentication=DISABLED)
  59. >>> r = requests.get("http://example.org", auth=kerberos_auth)
  60. ...
  61. Preemptive Authentication
  62. -------------------------
  63. ``HTTPKerberosAuth`` can be forced to preemptively initiate the Kerberos
  64. GSS exchange and present a Kerberos ticket on the initial request (and all
  65. subsequent). By default, authentication only occurs after a
  66. ``401 Unauthorized`` response containing a Kerberos or Negotiate challenge
  67. is received from the origin server. This can cause mutual authentication
  68. failures for hosts that use a persistent connection (eg, Windows/WinRM), as
  69. no Kerberos challenges are sent after the initial auth handshake. This
  70. behavior can be altered by setting ``force_preemptive=True``:
  71. .. code-block:: python
  72. >>> import requests
  73. >>> from requests_kerberos import HTTPKerberosAuth, REQUIRED
  74. >>> kerberos_auth = HTTPKerberosAuth(mutual_authentication=REQUIRED, force_preemptive=True)
  75. >>> r = requests.get("https://windows.example.org/wsman", auth=kerberos_auth)
  76. ...
  77. Hostname Override
  78. -----------------
  79. If communicating with a host whose DNS name doesn't match its
  80. kerberos hostname (eg, behind a content switch or load balancer),
  81. the hostname used for the Kerberos GSS exchange can be overridden by
  82. setting the ``hostname_override`` arg:
  83. .. code-block:: python
  84. >>> import requests
  85. >>> from requests_kerberos import HTTPKerberosAuth, REQUIRED
  86. >>> kerberos_auth = HTTPKerberosAuth(hostname_override="internalhost.local")
  87. >>> r = requests.get("https://externalhost.example.org/", auth=kerberos_auth)
  88. ...
  89. Explicit Principal
  90. ------------------
  91. ``HTTPKerberosAuth`` normally uses the default principal (ie, the user for
  92. whom you last ran ``kinit`` or ``kswitch``, or an SSO credential if
  93. applicable). However, an explicit principal can be specified, which will
  94. cause Kerberos to look for a matching credential cache for the named user.
  95. This feature depends on OS support for collection-type credential caches,
  96. as well as working principal support in PyKerberos (it is broken in many
  97. builds). An explicit principal can be specified with the ``principal`` arg:
  98. .. code-block:: python
  99. >>> import requests
  100. >>> from requests_kerberos import HTTPKerberosAuth, REQUIRED
  101. >>> kerberos_auth = HTTPKerberosAuth(principal="user@REALM")
  102. >>> r = requests.get("http://example.org", auth=kerberos_auth)
  103. ...
  104. On Windows, WinKerberos is used instead of PyKerberos. WinKerberos allows the
  105. use of arbitrary principals instead of a credential cache. Passwords can be
  106. specified by following the form ``user@realm:password`` for ``principal``.
  107. Delegation
  108. ----------
  109. ``requests_kerberos`` supports credential delegation (``GSS_C_DELEG_FLAG``).
  110. To enable delegation of credentials to a server that requests delegation, pass
  111. ``delegate=True`` to ``HTTPKerberosAuth``:
  112. .. code-block:: python
  113. >>> import requests
  114. >>> from requests_kerberos import HTTPKerberosAuth
  115. >>> r = requests.get("http://example.org", auth=HTTPKerberosAuth(delegate=True))
  116. ...
  117. Be careful to only allow delegation to servers you trust as they will be able
  118. to impersonate you using the delegated credentials.
  119. Logging
  120. -------
  121. This library makes extensive use of Python's logging facilities.
  122. Log messages are logged to the ``requests_kerberos`` and
  123. ``requests_kerberos.kerberos_`` named loggers.
  124. If you are having difficulty we suggest you configure logging. Issues with the
  125. underlying kerberos libraries will be made apparent. Additionally, copious debug
  126. information is made available which may assist in troubleshooting if you
  127. increase your log level all the way up to debug.