Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Copyright 2016 Google LLC
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
15"""Transport adapter for Requests."""
17from __future__ import absolute_import
19import functools
20import logging
21import numbers
22import time
24try:
25 import requests
26except ImportError as caught_exc: # pragma: NO COVER
27 raise ImportError(
28 "The requests library is not installed from please install the requests package to use the requests transport."
29 ) from caught_exc
30import requests.adapters # pylint: disable=ungrouped-imports
31import requests.exceptions # pylint: disable=ungrouped-imports
32from requests.packages.urllib3.util.ssl_ import ( # type: ignore
33 create_urllib3_context,
34) # pylint: disable=ungrouped-imports
36from google.auth import _helpers
37from google.auth import exceptions
38from google.auth import transport
39import google.auth.transport._mtls_helper
40from google.oauth2 import service_account
42_LOGGER = logging.getLogger(__name__)
44_DEFAULT_TIMEOUT = 120 # in seconds
47class _Response(transport.Response):
48 """Requests transport response adapter.
50 Args:
51 response (requests.Response): The raw Requests response.
52 """
54 def __init__(self, response):
55 self._response = response
57 @property
58 def status(self):
59 return self._response.status_code
61 @property
62 def headers(self):
63 return self._response.headers
65 @property
66 def data(self):
67 return self._response.content
70class TimeoutGuard(object):
71 """A context manager raising an error if the suite execution took too long.
73 Args:
74 timeout (Union[None, Union[float, Tuple[float, float]]]):
75 The maximum number of seconds a suite can run without the context
76 manager raising a timeout exception on exit. If passed as a tuple,
77 the smaller of the values is taken as a timeout. If ``None``, a
78 timeout error is never raised.
79 timeout_error_type (Optional[Exception]):
80 The type of the error to raise on timeout. Defaults to
81 :class:`requests.exceptions.Timeout`.
82 """
84 def __init__(self, timeout, timeout_error_type=requests.exceptions.Timeout):
85 self._timeout = timeout
86 self.remaining_timeout = timeout
87 self._timeout_error_type = timeout_error_type
89 def __enter__(self):
90 self._start = time.time()
91 return self
93 def __exit__(self, exc_type, exc_value, traceback):
94 if exc_value:
95 return # let the error bubble up automatically
97 if self._timeout is None:
98 return # nothing to do, the timeout was not specified
100 elapsed = time.time() - self._start
101 deadline_hit = False
103 if isinstance(self._timeout, numbers.Number):
104 self.remaining_timeout = self._timeout - elapsed
105 deadline_hit = self.remaining_timeout <= 0
106 else:
107 self.remaining_timeout = tuple(x - elapsed for x in self._timeout)
108 deadline_hit = min(self.remaining_timeout) <= 0
110 if deadline_hit:
111 raise self._timeout_error_type()
114class Request(transport.Request):
115 """Requests request adapter.
117 This class is used internally for making requests using various transports
118 in a consistent way. If you use :class:`AuthorizedSession` you do not need
119 to construct or use this class directly.
121 This class can be useful if you want to manually refresh a
122 :class:`~google.auth.credentials.Credentials` instance::
124 import google.auth.transport.requests
125 import requests
127 request = google.auth.transport.requests.Request()
129 credentials.refresh(request)
131 Args:
132 session (requests.Session): An instance :class:`requests.Session` used
133 to make HTTP requests. If not specified, a session will be created.
135 .. automethod:: __call__
136 """
138 def __init__(self, session=None):
139 if not session:
140 session = requests.Session()
142 self.session = session
144 def __del__(self):
145 try:
146 if hasattr(self, "session") and self.session is not None:
147 self.session.close()
148 except TypeError:
149 # NOTE: For certain Python binary built, the queue.Empty exception
150 # might not be considered a normal Python exception causing
151 # TypeError.
152 pass
154 def __call__(
155 self,
156 url,
157 method="GET",
158 body=None,
159 headers=None,
160 timeout=_DEFAULT_TIMEOUT,
161 **kwargs
162 ):
163 """Make an HTTP request using requests.
165 Args:
166 url (str): The URI to be requested.
167 method (str): The HTTP method to use for the request. Defaults
168 to 'GET'.
169 body (bytes): The payload or body in HTTP request.
170 headers (Mapping[str, str]): Request headers.
171 timeout (Optional[int]): The number of seconds to wait for a
172 response from the server. If not specified or if None, the
173 requests default timeout will be used.
174 kwargs: Additional arguments passed through to the underlying
175 requests :meth:`~requests.Session.request` method.
177 Returns:
178 google.auth.transport.Response: The HTTP response.
180 Raises:
181 google.auth.exceptions.TransportError: If any exception occurred.
182 """
183 try:
184 _helpers.request_log(_LOGGER, method, url, body, headers)
185 response = self.session.request(
186 method, url, data=body, headers=headers, timeout=timeout, **kwargs
187 )
188 _helpers.response_log(_LOGGER, response)
189 return _Response(response)
190 except requests.exceptions.RequestException as caught_exc:
191 new_exc = exceptions.TransportError(caught_exc)
192 raise new_exc from caught_exc
195class _MutualTlsAdapter(requests.adapters.HTTPAdapter):
196 """
197 A TransportAdapter that enables mutual TLS.
199 Args:
200 cert (bytes): client certificate in PEM format
201 key (bytes): client private key in PEM format
203 Raises:
204 ImportError: if certifi or pyOpenSSL is not installed
205 OpenSSL.crypto.Error: if client cert or key is invalid
206 """
208 def __init__(self, cert, key):
209 import certifi
210 from OpenSSL import crypto
211 import urllib3.contrib.pyopenssl # type: ignore
213 urllib3.contrib.pyopenssl.inject_into_urllib3()
215 pkey = crypto.load_privatekey(crypto.FILETYPE_PEM, key)
216 x509 = crypto.load_certificate(crypto.FILETYPE_PEM, cert)
218 ctx_poolmanager = create_urllib3_context()
219 ctx_poolmanager.load_verify_locations(cafile=certifi.where())
220 ctx_poolmanager._ctx.use_certificate(x509)
221 ctx_poolmanager._ctx.use_privatekey(pkey)
222 self._ctx_poolmanager = ctx_poolmanager
224 ctx_proxymanager = create_urllib3_context()
225 ctx_proxymanager.load_verify_locations(cafile=certifi.where())
226 ctx_proxymanager._ctx.use_certificate(x509)
227 ctx_proxymanager._ctx.use_privatekey(pkey)
228 self._ctx_proxymanager = ctx_proxymanager
230 super(_MutualTlsAdapter, self).__init__()
232 def init_poolmanager(self, *args, **kwargs):
233 kwargs["ssl_context"] = self._ctx_poolmanager
234 super(_MutualTlsAdapter, self).init_poolmanager(*args, **kwargs)
236 def proxy_manager_for(self, *args, **kwargs):
237 kwargs["ssl_context"] = self._ctx_proxymanager
238 return super(_MutualTlsAdapter, self).proxy_manager_for(*args, **kwargs)
241class _MutualTlsOffloadAdapter(requests.adapters.HTTPAdapter):
242 """
243 A TransportAdapter that enables mutual TLS and offloads the client side
244 signing operation to the signing library.
246 Args:
247 enterprise_cert_file_path (str): the path to a enterprise cert JSON
248 file. The file should contain the following field:
250 {
251 "libs": {
252 "signer_library": "...",
253 "offload_library": "..."
254 }
255 }
257 Raises:
258 ImportError: if certifi or pyOpenSSL is not installed
259 google.auth.exceptions.MutualTLSChannelError: If mutual TLS channel
260 creation failed for any reason.
261 """
263 def __init__(self, enterprise_cert_file_path):
264 import certifi
265 from google.auth.transport import _custom_tls_signer
267 self.signer = _custom_tls_signer.CustomTlsSigner(enterprise_cert_file_path)
268 self.signer.load_libraries()
270 import urllib3.contrib.pyopenssl
272 urllib3.contrib.pyopenssl.inject_into_urllib3()
274 poolmanager = create_urllib3_context()
275 poolmanager.load_verify_locations(cafile=certifi.where())
276 self.signer.attach_to_ssl_context(poolmanager)
277 self._ctx_poolmanager = poolmanager
279 proxymanager = create_urllib3_context()
280 proxymanager.load_verify_locations(cafile=certifi.where())
281 self.signer.attach_to_ssl_context(proxymanager)
282 self._ctx_proxymanager = proxymanager
284 super(_MutualTlsOffloadAdapter, self).__init__()
286 def init_poolmanager(self, *args, **kwargs):
287 kwargs["ssl_context"] = self._ctx_poolmanager
288 super(_MutualTlsOffloadAdapter, self).init_poolmanager(*args, **kwargs)
290 def proxy_manager_for(self, *args, **kwargs):
291 kwargs["ssl_context"] = self._ctx_proxymanager
292 return super(_MutualTlsOffloadAdapter, self).proxy_manager_for(*args, **kwargs)
295class AuthorizedSession(requests.Session):
296 """A Requests Session class with credentials.
298 This class is used to perform requests to API endpoints that require
299 authorization::
301 from google.auth.transport.requests import AuthorizedSession
303 authed_session = AuthorizedSession(credentials)
305 response = authed_session.request(
306 'GET', 'https://www.googleapis.com/storage/v1/b')
309 The underlying :meth:`request` implementation handles adding the
310 credentials' headers to the request and refreshing credentials as needed.
312 This class also supports mutual TLS via :meth:`configure_mtls_channel`
313 method. In order to use this method, the `GOOGLE_API_USE_CLIENT_CERTIFICATE`
314 environment variable must be explicitly set to ``true``, otherwise it does
315 nothing. Assume the environment is set to ``true``, the method behaves in the
316 following manner:
318 If client_cert_callback is provided, client certificate and private
319 key are loaded using the callback; if client_cert_callback is None,
320 application default SSL credentials will be used. Exceptions are raised if
321 there are problems with the certificate, private key, or the loading process,
322 so it should be called within a try/except block.
324 First we set the environment variable to ``true``, then create an :class:`AuthorizedSession`
325 instance and specify the endpoints::
327 regular_endpoint = 'https://pubsub.googleapis.com/v1/projects/{my_project_id}/topics'
328 mtls_endpoint = 'https://pubsub.mtls.googleapis.com/v1/projects/{my_project_id}/topics'
330 authed_session = AuthorizedSession(credentials)
332 Now we can pass a callback to :meth:`configure_mtls_channel`::
334 def my_cert_callback():
335 # some code to load client cert bytes and private key bytes, both in
336 # PEM format.
337 some_code_to_load_client_cert_and_key()
338 if loaded:
339 return cert, key
340 raise MyClientCertFailureException()
342 # Always call configure_mtls_channel within a try/except block.
343 try:
344 authed_session.configure_mtls_channel(my_cert_callback)
345 except:
346 # handle exceptions.
348 if authed_session.is_mtls:
349 response = authed_session.request('GET', mtls_endpoint)
350 else:
351 response = authed_session.request('GET', regular_endpoint)
354 You can alternatively use application default SSL credentials like this::
356 try:
357 authed_session.configure_mtls_channel()
358 except:
359 # handle exceptions.
361 Args:
362 credentials (google.auth.credentials.Credentials): The credentials to
363 add to the request.
364 refresh_status_codes (Sequence[int]): Which HTTP status codes indicate
365 that credentials should be refreshed and the request should be
366 retried.
367 max_refresh_attempts (int): The maximum number of times to attempt to
368 refresh the credentials and retry the request.
369 refresh_timeout (Optional[int]): The timeout value in seconds for
370 credential refresh HTTP requests.
371 auth_request (google.auth.transport.requests.Request):
372 (Optional) An instance of
373 :class:`~google.auth.transport.requests.Request` used when
374 refreshing credentials. If not passed,
375 an instance of :class:`~google.auth.transport.requests.Request`
376 is created.
377 default_host (Optional[str]): A host like "pubsub.googleapis.com".
378 This is used when a self-signed JWT is created from service
379 account credentials.
380 """
382 def __init__(
383 self,
384 credentials,
385 refresh_status_codes=transport.DEFAULT_REFRESH_STATUS_CODES,
386 max_refresh_attempts=transport.DEFAULT_MAX_REFRESH_ATTEMPTS,
387 refresh_timeout=None,
388 auth_request=None,
389 default_host=None,
390 ):
391 super(AuthorizedSession, self).__init__()
392 self.credentials = credentials
393 self._refresh_status_codes = refresh_status_codes
394 self._max_refresh_attempts = max_refresh_attempts
395 self._refresh_timeout = refresh_timeout
396 self._is_mtls = False
397 self._default_host = default_host
399 if auth_request is None:
400 self._auth_request_session = requests.Session()
402 # Using an adapter to make HTTP requests robust to network errors.
403 # This adapter retrys HTTP requests when network errors occur
404 # and the requests seems safely retryable.
405 retry_adapter = requests.adapters.HTTPAdapter(max_retries=3)
406 self._auth_request_session.mount("https://", retry_adapter)
408 # Do not pass `self` as the session here, as it can lead to
409 # infinite recursion.
410 auth_request = Request(self._auth_request_session)
411 else:
412 self._auth_request_session = None
414 # Request instance used by internal methods (for example,
415 # credentials.refresh).
416 self._auth_request = auth_request
418 # https://google.aip.dev/auth/4111
419 # Attempt to use self-signed JWTs when a service account is used.
420 if isinstance(self.credentials, service_account.Credentials):
421 self.credentials._create_self_signed_jwt(
422 "https://{}/".format(self._default_host) if self._default_host else None
423 )
425 def configure_mtls_channel(self, client_cert_callback=None):
426 """Configure the client certificate and key for SSL connection.
428 The function does nothing unless `GOOGLE_API_USE_CLIENT_CERTIFICATE` is
429 explicitly set to `true`. In this case if client certificate and key are
430 successfully obtained (from the given client_cert_callback or from application
431 default SSL credentials), a :class:`_MutualTlsAdapter` instance will be mounted
432 to "https://" prefix.
434 Args:
435 client_cert_callback (Optional[Callable[[], (bytes, bytes)]]):
436 The optional callback returns the client certificate and private
437 key bytes both in PEM format.
438 If the callback is None, application default SSL credentials
439 will be used.
441 Raises:
442 google.auth.exceptions.MutualTLSChannelError: If mutual TLS channel
443 creation failed for any reason.
444 """
445 use_client_cert = google.auth.transport._mtls_helper.check_use_client_cert()
446 if not use_client_cert:
447 self._is_mtls = False
448 return
449 try:
450 import OpenSSL
451 except ImportError as caught_exc:
452 new_exc = exceptions.MutualTLSChannelError(caught_exc)
453 raise new_exc from caught_exc
455 try:
456 (
457 self._is_mtls,
458 cert,
459 key,
460 ) = google.auth.transport._mtls_helper.get_client_cert_and_key(
461 client_cert_callback
462 )
464 if self._is_mtls:
465 mtls_adapter = _MutualTlsAdapter(cert, key)
466 self.mount("https://", mtls_adapter)
467 except (
468 exceptions.ClientCertError,
469 ImportError,
470 OpenSSL.crypto.Error,
471 ) as caught_exc:
472 new_exc = exceptions.MutualTLSChannelError(caught_exc)
473 raise new_exc from caught_exc
475 def request(
476 self,
477 method,
478 url,
479 data=None,
480 headers=None,
481 max_allowed_time=None,
482 timeout=_DEFAULT_TIMEOUT,
483 **kwargs
484 ):
485 """Implementation of Requests' request.
487 Args:
488 timeout (Optional[Union[float, Tuple[float, float]]]):
489 The amount of time in seconds to wait for the server response
490 with each individual request. Can also be passed as a tuple
491 ``(connect_timeout, read_timeout)``. See :meth:`requests.Session.request`
492 documentation for details.
493 max_allowed_time (Optional[float]):
494 If the method runs longer than this, a ``Timeout`` exception is
495 automatically raised. Unlike the ``timeout`` parameter, this
496 value applies to the total method execution time, even if
497 multiple requests are made under the hood.
499 Mind that it is not guaranteed that the timeout error is raised
500 at ``max_allowed_time``. It might take longer, for example, if
501 an underlying request takes a lot of time, but the request
502 itself does not timeout, e.g. if a large file is being
503 transmitted. The timout error will be raised after such
504 request completes.
505 """
506 # pylint: disable=arguments-differ
507 # Requests has a ton of arguments to request, but only two
508 # (method, url) are required. We pass through all of the other
509 # arguments to super, so no need to exhaustively list them here.
511 # Use a kwarg for this instead of an attribute to maintain
512 # thread-safety.
513 _credential_refresh_attempt = kwargs.pop("_credential_refresh_attempt", 0)
515 # Make a copy of the headers. They will be modified by the credentials
516 # and we want to pass the original headers if we recurse.
517 request_headers = headers.copy() if headers is not None else {}
519 # Do not apply the timeout unconditionally in order to not override the
520 # _auth_request's default timeout.
521 auth_request = (
522 self._auth_request
523 if timeout is None
524 else functools.partial(self._auth_request, timeout=timeout)
525 )
527 remaining_time = max_allowed_time
529 with TimeoutGuard(remaining_time) as guard:
530 self.credentials.before_request(auth_request, method, url, request_headers)
531 remaining_time = guard.remaining_timeout
533 with TimeoutGuard(remaining_time) as guard:
534 _helpers.request_log(_LOGGER, method, url, data, headers)
535 response = super(AuthorizedSession, self).request(
536 method,
537 url,
538 data=data,
539 headers=request_headers,
540 timeout=timeout,
541 **kwargs
542 )
543 remaining_time = guard.remaining_timeout
545 # If the response indicated that the credentials needed to be
546 # refreshed, then refresh the credentials and re-attempt the
547 # request.
548 # A stored token may expire between the time it is retrieved and
549 # the time the request is made, so we may need to try twice.
550 if (
551 response.status_code in self._refresh_status_codes
552 and _credential_refresh_attempt < self._max_refresh_attempts
553 ):
555 _LOGGER.info(
556 "Refreshing credentials due to a %s response. Attempt %s/%s.",
557 response.status_code,
558 _credential_refresh_attempt + 1,
559 self._max_refresh_attempts,
560 )
562 # Do not apply the timeout unconditionally in order to not override the
563 # _auth_request's default timeout.
564 auth_request = (
565 self._auth_request
566 if timeout is None
567 else functools.partial(self._auth_request, timeout=timeout)
568 )
570 with TimeoutGuard(remaining_time) as guard:
571 self.credentials.refresh(auth_request)
572 remaining_time = guard.remaining_timeout
574 # Recurse. Pass in the original headers, not our modified set, but
575 # do pass the adjusted max allowed time (i.e. the remaining total time).
576 return self.request(
577 method,
578 url,
579 data=data,
580 headers=headers,
581 max_allowed_time=remaining_time,
582 timeout=timeout,
583 _credential_refresh_attempt=_credential_refresh_attempt + 1,
584 **kwargs
585 )
587 return response
589 @property
590 def is_mtls(self):
591 """Indicates if the created SSL channel is mutual TLS."""
592 return self._is_mtls
594 def close(self):
595 if self._auth_request_session is not None:
596 self._auth_request_session.close()
597 super(AuthorizedSession, self).close()