1- requests Kerberos/ GSSAPI authentication library
1+ requests GSSAPI authentication library
22===============================================
33
44Requests is an HTTP library, written in Python, for human beings. This library
5- adds optional Kerberos/ GSSAPI authentication support and supports mutual
5+ adds optional GSSAPI authentication support and supports mutual
66authentication. Basic GET usage:
77
88
99.. code-block :: python
1010
1111 >> > import requests
12- >> > from requests_kerberos import HTTPKerberosAuth
12+ >> > from requests_gssapi import HTTPKerberosAuth
1313 >> > r = requests.get(" http://example.org" , auth = HTTPKerberosAuth())
1414 ...
1515
@@ -29,7 +29,7 @@ REQUIRED
2929
3030By default, ``HTTPKerberosAuth `` will require mutual authentication from the
3131server, and if a server emits a non-error response which cannot be
32- authenticated, a ``requests_kerberos .errors.MutualAuthenticationError `` will
32+ authenticated, a ``requests_gssapi .errors.MutualAuthenticationError `` will
3333be raised. If a server emits an error which cannot be authenticated, it will
3434be returned to the user but with its contents and headers stripped. If the
3535response content is more important than the need for mutual auth on errors,
@@ -39,9 +39,9 @@ setting ``sanitize_mutual_error_response=False``:
3939.. code-block :: python
4040
4141 >> > import requests
42- >> > from requests_kerberos import HTTPKerberosAuth, REQUIRED
43- >> > kerberos_auth = HTTPKerberosAuth(mutual_authentication = REQUIRED , sanitize_mutual_error_response = False )
44- >> > r = requests.get(" https://windows.example.org/wsman" , auth = kerberos_auth )
42+ >> > from requests_gssapi import HTTPKerberosAuth, REQUIRED
43+ >> > gssapi_auth = HTTPKerberosAuth(mutual_authentication = REQUIRED , sanitize_mutual_error_response = False )
44+ >> > r = requests.get(" https://windows.example.org/wsman" , auth = gssapi_auth )
4545 ...
4646
4747
@@ -54,12 +54,12 @@ preference when constructing your ``HTTPKerberosAuth`` object:
5454.. code-block :: python
5555
5656 >> > import requests
57- >> > from requests_kerberos import HTTPKerberosAuth, OPTIONAL
58- >> > kerberos_auth = HTTPKerberosAuth(mutual_authentication = OPTIONAL )
59- >> > r = requests.get(" http://example.org" , auth = kerberos_auth )
57+ >> > from requests_gssapi import HTTPKerberosAuth, OPTIONAL
58+ >> > gssapi_auth = HTTPKerberosAuth(mutual_authentication = OPTIONAL )
59+ >> > r = requests.get(" http://example.org" , auth = gssapi_auth )
6060 ...
6161
62- This will cause ``requests_kerberos `` to attempt mutual authentication if the
62+ This will cause ``requests_gssapi `` to attempt mutual authentication if the
6363server advertises that it supports it, and cause a failure if authentication
6464fails, but not if the server does not support it at all.
6565
@@ -72,44 +72,44 @@ authentication, you can do that as well:
7272.. code-block :: python
7373
7474 >> > import requests
75- >> > from requests_kerberos import HTTPKerberosAuth, DISABLED
76- >> > kerberos_auth = HTTPKerberosAuth(mutual_authentication = DISABLED )
77- >> > r = requests.get(" http://example.org" , auth = kerberos_auth )
75+ >> > from requests_gssapi import HTTPKerberosAuth, DISABLED
76+ >> > gssapi_auth = HTTPKerberosAuth(mutual_authentication = DISABLED )
77+ >> > r = requests.get(" http://example.org" , auth = gssapi_auth )
7878 ...
7979
8080 Preemptive Authentication
8181-------------------------
8282
83- ``HTTPKerberosAuth `` can be forced to preemptively initiate the Kerberos
84- GSS exchange and present a Kerberos ticket on the initial request (and all
83+ ``HTTPKerberosAuth `` can be forced to preemptively initiate the GSSAPI
84+ exchange and present a token on the initial request (and all
8585subsequent). By default, authentication only occurs after a
86- ``401 Unauthorized `` response containing a Kerberos or Negotiate challenge
86+ ``401 Unauthorized `` response containing a Negotiate challenge
8787is received from the origin server. This can cause mutual authentication
8888failures for hosts that use a persistent connection (eg, Windows/WinRM), as
89- no Kerberos challenges are sent after the initial auth handshake. This
89+ no GSSAPI challenges are sent after the initial auth handshake. This
9090behavior can be altered by setting ``force_preemptive=True ``:
9191
9292.. code-block :: python
9393
9494 >> > import requests
95- >> > from requests_kerberos import HTTPKerberosAuth, REQUIRED
96- >> > kerberos_auth = HTTPKerberosAuth(mutual_authentication = REQUIRED , force_preemptive = True )
97- >> > r = requests.get(" https://windows.example.org/wsman" , auth = kerberos_auth )
95+ >> > from requests_gssapi import HTTPKerberosAuth, REQUIRED
96+ >> > gssapi_auth = HTTPKerberosAuth(mutual_authentication = REQUIRED , force_preemptive = True )
97+ >> > r = requests.get(" https://windows.example.org/wsman" , auth = gssapi_auth )
9898 ...
9999
100100 Hostname Override
101101-----------------
102102
103103If communicating with a host whose DNS name doesn't match its
104- kerberos hostname (eg, behind a content switch or load balancer),
105- the hostname used for the Kerberos GSS exchange can be overridden by
104+ hostname (eg, behind a content switch or load balancer),
105+ the hostname used for the GSSAPI exchange can be overridden by
106106setting the ``hostname_override `` arg:
107107
108108.. code-block :: python
109109
110110 >> > import requests
111- >> > from requests_kerberos import HTTPKerberosAuth, REQUIRED
112- >> > kerberos_auth = HTTPKerberosAuth(hostname_override = " internalhost.local" )
111+ >> > from requests_gssapi import HTTPKerberosAuth, REQUIRED
112+ >> > gssapi_auth = HTTPKerberosAuth(hostname_override = " internalhost.local" )
113113 >> > r = requests.get(" https://externalhost.example.org/" , auth = kerberos_auth)
114114 ...
115115
@@ -119,34 +119,29 @@ Explicit Principal
119119``HTTPKerberosAuth `` normally uses the default principal (ie, the user for
120120whom you last ran ``kinit `` or ``kswitch ``, or an SSO credential if
121121applicable). However, an explicit principal can be specified, which will
122- cause Kerberos to look for a matching credential cache for the named user.
123- This feature depends on OS support for collection-type credential caches,
124- as well as working principal support in PyKerberos (it is broken in many
125- builds). An explicit principal can be specified with the ``principal `` arg:
122+ cause GSSAPI to look for a matching credential cache for the named user.
123+ This feature depends on OS support for collection-type credential caches.
124+ An explicit principal can be specified with the ``principal `` arg:
126125
127126.. code-block :: python
128127
129128 >> > import requests
130- >> > from requests_kerberos import HTTPKerberosAuth, REQUIRED
131- >> > kerberos_auth = HTTPKerberosAuth(principal = " user@REALM" )
132- >> > r = requests.get(" http://example.org" , auth = kerberos_auth )
129+ >> > from requests_gssapi import HTTPKerberosAuth, REQUIRED
130+ >> > gssapi_auth = HTTPKerberosAuth(principal = " user@REALM" )
131+ >> > r = requests.get(" http://example.org" , auth = gssapi_auth )
133132 ...
134133
135- On Windows, WinKerberos is used instead of PyKerberos. WinKerberos allows the
136- use of arbitrary principals instead of a credential cache. Passwords can be
137- specified by following the form ``user@realm:password `` for ``principal ``.
138-
139134 Delegation
140135----------
141136
142- ``requests_kerberos `` supports credential delegation (``GSS_C_DELEG_FLAG ``).
137+ ``requests_gssapi `` supports credential delegation (``GSS_C_DELEG_FLAG ``).
143138To enable delegation of credentials to a server that requests delegation, pass
144139``delegate=True `` to ``HTTPKerberosAuth ``:
145140
146141.. code-block :: python
147142
148143 >> > import requests
149- >> > from requests_kerberos import HTTPKerberosAuth
144+ >> > from requests_gssapi import HTTPKerberosAuth
150145 >> > r = requests.get(" http://example.org" , auth = HTTPKerberosAuth(delegate = True ))
151146 ...
152147
@@ -158,10 +153,10 @@ Logging
158153
159154This library makes extensive use of Python's logging facilities.
160155
161- Log messages are logged to the ``requests_kerberos `` and
162- ``requests_kerberos.kerberos_ `` named loggers.
156+ Log messages are logged to the ``requests_gssapi `` and
157+ ``requests_gssapi.gssapi `` named loggers.
163158
164159If you are having difficulty we suggest you configure logging. Issues with the
165- underlying kerberos libraries will be made apparent. Additionally, copious debug
160+ underlying GSSAPI libraries will be made apparent. Additionally, copious debug
166161information is made available which may assist in troubleshooting if you
167162increase your log level all the way up to debug.
0 commit comments