1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
.. _authentication:
Authentication
==============
requests supports Basic Authentication and HTTP Digest Authentication by
default. There are also a number of third-party libraries for authentication
with:
- `OAuth <https://requests-oauthlib.readthedocs.io/>`_
- `NTLM <https://github.com/requests/requests-ntlm>`_
- `Kerberos <https://github.com/requests/requests-kerberos>`_
The :mod:`requests_toolbelt.auth` provides extra authentication features in
addition to those. It provides the following authentication classes:
- :class:`requests_toolbelt.auth.guess.GuessAuth`
- :class:`requests_toolbelt.auth.http_proxy_digest.HTTPProxyDigestAuth`
- :class:`requests_toolbelt.auth.handler.AuthHandler`
AuthHandler
-----------
The :class:`~requests_toolbelt.auth.handler.AuthHandler` is a way of using a
single session with multiple websites that require authentication. If you know
what websites require a certain kind of authentication and what your
credentials are.
Take for example a session that needs to authenticate to GitHub's API and
GitLab's API, you would set up and use your
:class:`~requests_toolbelt.auth.handler.AuthHandler` like so:
.. code-block:: python
import requests
from requests_toolbelt.auth.handler import AuthHandler
def gitlab_auth(request):
request.headers['PRIVATE-TOKEN'] = 'asecrettoken'
handler = AuthHandler({
'https://api.github.com': ('sigmavirus24', 'apassword'),
'https://gitlab.com': gitlab_auth,
})
session = requests.Session()
session.auth = handler
r = session.get('https://api.github.com/user')
# assert r.ok
r2 = session.get('https://gitlab.com/api/v3/projects')
# assert r2.ok
.. note::
You **must** provide both the scheme and domain for authentication. The
:class:`~requests_toolbelt.auth.handler.AuthHandler` class will check both
the scheme and host to ensure your data is not accidentally exposed.
.. autoclass:: requests_toolbelt.auth.handler.AuthHandler
:members:
GuessAuth
---------
The :class:`~requests_toolbelt.auth.guess.GuessAuth` authentication class
automatically detects whether to use basic auth or digest auth:
.. code-block:: python
import requests
from requests_toolbelt.auth import GuessAuth
requests.get('http://httpbin.org/basic-auth/user/passwd',
auth=GuessAuth('user', 'passwd'))
requests.get('http://httpbin.org/digest-auth/auth/user/passwd',
auth=GuessAuth('user', 'passwd'))
Detection of the auth type is done via the ``WWW-Authenticate`` header sent by
the server. This requires an additional request in case of basic auth, as
usually basic auth is sent preemptively. If the server didn't explicitly
require authentication, no credentials are sent.
.. autoclass:: requests_toolbelt.auth.guess.GuessAuth
GuessProxyAuth
--------------
The :class:`~requests_toolbelt.auth.guess.GuessProxyAuth` handler will
automatically detect whether to use basic authentication or digest authentication
when authenticating to the provided proxy.
.. code-block:: python
import requests
from requests_toolbelt.auth.guess import GuessProxyAuth
proxies = {
"http": "http://PROXYSERVER:PROXYPORT",
"https": "http://PROXYSERVER:PROXYPORT",
}
requests.get('http://httpbin.org/basic-auth/user/passwd',
auth=GuessProxyAuth('user', 'passwd', 'proxyusr', 'proxypass'),
proxies=proxies)
requests.get('http://httpbin.org/digest-auth/auth/user/passwd',
auth=GuessProxyAuth('user', 'passwd', 'proxyusr', 'proxypass'),
proxies=proxies)
Detection of the auth type is done via the ``Proxy-Authenticate`` header sent by
the server. This requires an additional request in case of basic auth, as
usually basic auth is sent preemptively. If the server didn't explicitly
require authentication, no credentials are sent.
.. autoclass:: requests_toolbelt.auth.guess.GuessProxyAuth
HTTPProxyDigestAuth
-------------------
The ``HTTPProxyDigestAuth`` use digest authentication between the client and
the proxy.
.. code-block:: python
import requests
from requests_toolbelt.auth.http_proxy_digest import HTTPProxyDigestAuth
proxies = {
"http": "http://PROXYSERVER:PROXYPORT",
"https": "https://PROXYSERVER:PROXYPORT",
}
url = "https://toolbelt.readthedocs.io/"
auth = HTTPProxyDigestAuth("USERNAME", "PASSWORD")
requests.get(url, proxies=proxies, auth=auth)
Program would raise error if the username or password is rejected by the proxy.
.. autoclass:: requests_toolbelt.auth.http_proxy_digest.HTTPProxyDigestAuth
|
