1
- requests GSSAPI authentication library
2
- ===============================================
1
+ HTTPX GSSAPI authentication library
2
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
3
4
- Requests is an HTTP library, written in Python, for human beings. This library
5
- adds optional GSSAPI authentication support and supports mutual
6
- authentication.
7
-
8
- It provides a fully backward-compatible shim for the old
9
- python-requests-kerberos library: simply replace ``import requests_kerberos ``
10
- with ``import requests_gssapi ``. A more powerful interface is provided by the
11
- HTTPSPNEGOAuth component, but this is of course not guaranteed to be
12
- compatible. Documentation below is written toward the new interface.
4
+ `HTTPX <https://github.com/encode/httpx >`_ is a full featured Python HTTP library with both sync and async APIs
5
+ designed to be a next generation HTTP client for Python. This library is a port
6
+ of `Requests GSSAPI <https://github.com/pythongssapi/requests-gssapi >`_ to HTTPX which adds optional GSSAPI authentication support and
7
+ supports mutual authentication.
13
8
14
9
Basic GET usage:
15
10
16
-
17
11
.. code-block :: python
18
12
19
- >> > import requests
20
- >> > from requests_gssapi import HTTPSPNEGOAuth
21
- >> > r = requests.get(" http://example.org" , auth = HTTPSPNEGOAuth())
22
- ...
13
+ >> > import httpx
14
+ >> > from httpx_gssapi import HTTPSPNEGOAuth
15
+ >> > r = httpx.get(" http://example.org" , auth = HTTPSPNEGOAuth())
23
16
24
- The entire `` requests.api `` should be supported.
17
+ Both the sync and async HTTPX APIs should be fully supported.
25
18
26
19
Setup
27
20
-----
@@ -49,7 +42,7 @@ Mutual Authentication
49
42
50
43
Mutual authentication is a poorly-named feature of the GSSAPI which doesn't
51
44
provide any additional security benefit to most possible uses of
52
- requests_gssapi . Practically speaking, in most mechanism implementations
45
+ httpx_gssapi . Practically speaking, in most mechanism implementations
53
46
(including krb5), it requires another round-trip between the client and server
54
47
during the authentication handshake. Many clients and servers do not properly
55
48
handle the authentication handshake taking more than one round-trip. If you
@@ -73,14 +66,14 @@ DISABLED
73
66
74
67
By default, there's no need to explicitly disable mutual authentication.
75
68
However, for compatability with older versions of request_gssapi or
76
- requests_kerberos , you can explicitly request it not be attempted:
69
+ httpx_kerberos , you can explicitly request it not be attempted:
77
70
78
71
.. code-block :: python
79
72
80
- >> > import requests
81
- >> > from requests_gssapi import HTTPSPNEGOAuth, DISABLED
73
+ >> > import httpx
74
+ >> > from httpx_gssapi import HTTPSPNEGOAuth, DISABLED
82
75
>> > gssapi_auth = HTTPSPNEGOAuth(mutual_authentication = DISABLED )
83
- >> > r = requests .get(" https://example.org" , auth = gssapi_auth)
76
+ >> > r = httpx .get(" https://example.org" , auth = gssapi_auth)
84
77
...
85
78
86
79
REQUIRED
@@ -89,7 +82,7 @@ REQUIRED
89
82
This was historically the default, but no longer is. If requested,
90
83
``HTTPSPNEGOAuth `` will require mutual authentication from the server, and if
91
84
a server emits a non-error response which cannot be authenticated, a
92
- ``requests_gssapi .errors.MutualAuthenticationError `` will be raised. (See
85
+ ``httpx_gssapi .errors.MutualAuthenticationError `` will be raised. (See
93
86
above for what this means.) If a server emits an error which cannot be
94
87
authenticated, it will be returned to the user but with its contents and
95
88
headers stripped. If the response content is more important than the need for
@@ -98,27 +91,27 @@ can be suppressed by setting ``sanitize_mutual_error_response=False``:
98
91
99
92
.. code-block :: python
100
93
101
- >> > import requests
102
- >> > from requests_gssapi import HTTPSPNEGOAuth, REQUIRED
94
+ >> > import httpx
95
+ >> > from httpx_gssapi import HTTPSPNEGOAuth, REQUIRED
103
96
>> > gssapi_auth = HTTPSPNEGOAuth(mutual_authentication = REQUIRED , sanitize_mutual_error_response = False )
104
- >> > r = requests .get(" https://windows.example.org/wsman" , auth = gssapi_auth)
97
+ >> > r = httpx .get(" https://windows.example.org/wsman" , auth = gssapi_auth)
105
98
...
106
99
107
100
OPTIONAL
108
101
^^^^^^^^
109
102
110
- This will cause ``requests_gssapi `` to attempt mutual authentication if the
103
+ This will cause ``httpx_gssapi `` to attempt mutual authentication if the
111
104
server advertises that it supports it, and cause a failure if authentication
112
105
fails, but not if the server does not support it at all. This is probably not
113
106
what you want: link tampering will either cause hard failures, or silently
114
107
cause it to not happen at all. It is retained for compatability.
115
108
116
109
.. code-block :: python
117
110
118
- >> > import requests
119
- >> > from requests_gssapi import HTTPSPNEGOAuth, OPTIONAL
111
+ >> > import httpx
112
+ >> > from httpx_gssapi import HTTPSPNEGOAuth, OPTIONAL
120
113
>> > gssapi_auth = HTTPSPNEGOAuth(mutual_authentication = OPTIONAL )
121
- >> > r = requests .get(" https://example.org" , auth = gssapi_auth)
114
+ >> > r = httpx .get(" https://example.org" , auth = gssapi_auth)
122
115
...
123
116
124
117
Opportunistic Authentication
@@ -135,10 +128,10 @@ behavior can be altered by setting ``opportunistic_auth=True``:
135
128
136
129
.. code-block :: python
137
130
138
- >> > import requests
139
- >> > from requests_gssapi import HTTPSPNEGOAuth, REQUIRED
131
+ >> > import httpx
132
+ >> > from httpx_gssapi import HTTPSPNEGOAuth, REQUIRED
140
133
>> > gssapi_auth = HTTPSPNEGOAuth(mutual_authentication = REQUIRED , opportunistic_auth = True )
141
- >> > r = requests .get(" https://windows.example.org/wsman" , auth = gssapi_auth)
134
+ >> > r = httpx .get(" https://windows.example.org/wsman" , auth = gssapi_auth)
142
135
...
143
136
144
137
Hostname Override
@@ -151,10 +144,10 @@ passing in a custom name (string or ``gssapi.Name``):
151
144
152
145
.. code-block :: python
153
146
154
- >> > import requests
155
- >> > from requests_gssapi import HTTPSPNEGOAuth, REQUIRED
147
+ >> > import httpx
148
+ >> > from httpx_gssapi import HTTPSPNEGOAuth, REQUIRED
156
149
>> > gssapi_auth = HTTPSPNEGOAuth(target_name = " internalhost.local" )
157
- >> > r = requests .get(" https://externalhost.example.org/" , auth = gssapi_auth)
150
+ >> > r = httpx .get(" https://externalhost.example.org/" , auth = gssapi_auth)
158
151
...
159
152
160
153
Explicit Principal
@@ -167,12 +160,12 @@ applicable). However, an explicit credential can be in instead, if desired.
167
160
.. code-block :: python
168
161
169
162
>> > import gssapi
170
- >> > import requests
171
- >> > from requests_gssapi import HTTPSPNEGOAuth, REQUIRED
163
+ >> > import httpx
164
+ >> > from httpx_gssapi import HTTPSPNEGOAuth, REQUIRED
172
165
>> > name = gssapi.Name(" user@REALM" , gssapi.NameType.hostbased_service)
173
166
>> > creds = gssapi.Credentials(name = name, usage = " initiate" )
174
167
>> > gssapi_auth = HTTPSPNEGOAuth(creds = creds)
175
- >> > r = requests .get(" http://example.org" , auth = gssapi_auth)
168
+ >> > r = httpx .get(" http://example.org" , auth = gssapi_auth)
176
169
...
177
170
178
171
Explicit Mechanism
@@ -186,28 +179,28 @@ without interference. It is expected to be an instance of ``gssapi.mechs.Mechani
186
179
.. code-block :: python
187
180
188
181
>> > import gssapi
189
- >> > import requests
190
- >> > from requests_gssapi import HTTPSPNEGOAuth
182
+ >> > import httpx
183
+ >> > from httpx_gssapi import HTTPSPNEGOAuth
191
184
>> > try :
192
185
... spnego = gssapi,mechs.Mechanism.from_sasl_name(" SPNEGO" )
193
186
... except AttributeError :
194
187
... spnego = gssapi.OID .from_int_seq(" 1.3.6.1.5.5.2" )
195
188
>> > gssapi_auth = HTTPSPNEGOAuth(mech = spnego)
196
- >> > r = requests .get(" http://example.org" , auth = gssapi_auth)
189
+ >> > r = httpx .get(" http://example.org" , auth = gssapi_auth)
197
190
...
198
191
199
192
Delegation
200
193
----------
201
194
202
- ``requests_gssapi `` supports credential delegation (``GSS_C_DELEG_FLAG ``).
195
+ ``httpx_gssapi `` supports credential delegation (``GSS_C_DELEG_FLAG ``).
203
196
To enable delegation of credentials to a server that requests delegation, pass
204
197
``delegate=True `` to ``HTTPSPNEGOAuth ``:
205
198
206
199
.. code-block :: python
207
200
208
- >> > import requests
209
- >> > from requests_gssapi import HTTPSPNEGOAuth
210
- >> > r = requests .get(" http://example.org" , auth = HTTPSPNEGOAuth(delegate = True ))
201
+ >> > import httpx
202
+ >> > from httpx_gssapi import HTTPSPNEGOAuth
203
+ >> > r = httpx .get(" http://example.org" , auth = HTTPSPNEGOAuth(delegate = True ))
211
204
...
212
205
213
206
Be careful to only allow delegation to servers you trust as they will be able
@@ -218,8 +211,8 @@ Logging
218
211
219
212
This library makes extensive use of Python's logging facilities.
220
213
221
- Log messages are logged to the ``requests_gssapi `` and
222
- ``requests_gssapi .gssapi `` named loggers.
214
+ Log messages are logged to the ``httpx_gssapi `` and
215
+ ``httpx_gssapi .gssapi `` named loggers.
223
216
224
217
If you are having difficulty we suggest you configure logging. Issues with the
225
218
underlying GSSAPI libraries will be made apparent. Additionally, copious debug
0 commit comments