README.rst 2.5 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576
  1. requests Kerberos/GSSAPI authentication library
  2. ===============================================
  3. Requests is an HTTP library, written in Python, for human beings. This library
  4. adds optional Kerberos/GSSAPI authentication support and supports mutual
  5. authentication. Basic GET usage:
  6. .. code-block:: pycon
  7. >>> import requests
  8. >>> from requests_kerberos import HTTPKerberosAuth
  9. >>> r = requests.get("http://example.org", auth=HTTPKerberosAuth())
  10. ...
  11. The entire ``requests.api`` should be supported.
  12. Authentication Failures
  13. -----------------------
  14. Client authentication failures will be communicated to the caller by returning
  15. the 401 response.
  16. Mutual Authentication
  17. ---------------------
  18. By default, ``HTTPKerberosAuth`` will require mutual authentication from the
  19. server, and if a server emits a non-error response which cannot be
  20. authenticated, a ``requests_kerberos.errors.MutualAuthenticationError`` will be
  21. raised. If a server emits an error which cannot be authenticated, it will be
  22. returned to the user but with its contents and headers stripped.
  23. OPTIONAL
  24. ^^^^^^^^
  25. If you'd prefer to not require mutual authentication, you can set your
  26. preference when constructing your ``HTTPKerberosAuth`` object:
  27. .. code-block:: pycon
  28. >>> import requests
  29. >>> from requests_kerberos import HTTPKerberosAuth, OPTIONAL
  30. >>> kerberos_auth = HTTPKerberosAuth(mutual_authentication=OPTIONAL)
  31. >>> r = requests.get("http://example.org", auth=kerberos_auth)
  32. ...
  33. This will cause ``requests_kerberos`` to attempt mutual authentication if the
  34. server advertises that it supports it, and cause a failure if authentication
  35. fails, but not if the server does not support it at all.
  36. DISABLED
  37. ^^^^^^^^
  38. While we don't recommend it, if you'd prefer to never attempt mutual
  39. authentication, you can do that as well:
  40. .. code-block:: pycon
  41. >>> import requests
  42. >>> from requests_kerberos import HTTPKerberosAuth, DISABLED
  43. >>> kerberos_auth = HTTPKerberosAuth(mutual_authentication=DISABLED)
  44. >>> r = requests.get("http://example.org", auth=kerberos_auth)
  45. ...
  46. Logging
  47. -------
  48. This library makes extensive use of Python's logging facilities.
  49. Log messages are logged to the ``requests_kerberos`` and
  50. ``requests_kerberos.kerberos_`` named loggers.
  51. If you are having difficulty we suggest you configure logging. Issues with the
  52. underlying kerberos libraries will be made apparent. Additionally, copious debug
  53. information is made available which may assist in troubleshooting if you
  54. increase your log level all the way up to debug.