Implement Application Default Credentials (ADC) functionality. (#1035)

Author: BenRKarl

README.rst

@@ -28,23 +28,6 @@ Documentation
 Please refer to our `Developer Site`_ for documentation on how to install,
 configure, and use this client library.
 
-Protobuf Messages
------------------
-Version `14.0.0`_ of this library introduced the **required** `use_proto_plus`
-configuration option that specifies which type of protobuf message to use. For
-information on why this flag is important and what the differences are between
-the two message types, see the `Protobuf Messages`_ guide.
-
-Minimum Dependency Versions
----------------------------
-Version `21.2.0`_ of this library *lowered* the minimum version for some
-dependencies in order to improve compatibility with other applications and
-packages that rely on `protobuf`_ version 3.
-
-Note that using protobuf 3 will cause performance degradations in this library,
-so you may experience slower response times. For optimal performance we
-recommend using protobuf versions 4.21.5 or higher.
-
 Miscellaneous
 -------------
 
@@ -73,7 +56,3 @@ Authors
 .. _Andrew Burke: https://github.com/AndrewMBurke
 .. _Laura Chevalier: https://github.com/laurachevalier4
 .. _Bob Hancock: https://github.com/bobhancock
-.. _14.0.0: https://pypi.org/project/google-ads/14.0.0/
-.. _21.2.0: https://pypi.org/project/google-ads/21.2.0/
-.. _Protobuf Messages: https://developers.google.com/google-ads/api/docs/client-libs/python/protobuf-messages
-.. _protobuf: https://pypi.org/project/protobuf/

google-ads.yaml

@@ -81,3 +81,11 @@ login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
 # don't have username and password, just specify host and port.                          #
 # ########################################################################################
 # http_proxy: http://user:password@localhost:8000
+
+# Application default credentials configuration
+##########################################################################################
+# Below you can specify whether to initialize the library using Application Default      #
+# Credentials (ADC). To understand how ADC discovers credentials in a given environment, #
+# see: https://developers.google.com/identity/protocols/application-default-credentials  #
+# ########################################################################################
+# use_application_default_credentials: True

google/ads/googleads/config.py

@@ -34,6 +34,7 @@
     "linked_customer_id",
     "http_proxy",
     "use_cloud_org_for_api_access",
+    "use_application_default_credentials"
 )
 _CONFIG_FILE_PATH_KEY = ("configuration_file_path",)
 _OAUTH2_INSTALLED_APP_KEYS = ("client_id", "client_secret", "refresh_token")
@@ -159,6 +160,16 @@ def parser_wrapper(*args: Any, **kwargs: Any) -> Any:
             value: Union[str, bool] = parsed_config.get("use_proto_plus", False)
             parsed_config["use_proto_plus"]: bool = disambiguate_string_bool(value)
 
+        if "use_application_default_credentials" in config_keys:
+            # When loaded from YAML, YAML string or a dict, this value is
+            # evaluated as a bool. If it's loaded from an environment variable
+            # it's evaluated as a string. If set to "False" as an environment
+            # variable we need to manually change it to the bool False because
+            # the string "False" is truthy and can easily be incorrectly
+            # converted to the boolean True.
+            value: Union[str, bool] = parsed_config.get("use_application_default_credentials", False)
+            parsed_config["use_application_default_credentials"]: bool = disambiguate_string_bool(value)
+
         return parsed_config
 
     return parser_wrapper

google/ads/googleads/oauth2.py

@@ -19,6 +19,8 @@
 
 from google.oauth2.service_account import Credentials as ServiceAccountCreds
 from google.oauth2.credentials import Credentials as InstalledAppCredentials
+from google.auth import default as ApplicationDefaultCredentials
+from google.auth.credentials import Credentials as CredentialsBaseClass
 from google.auth.transport.requests import Request
 
 from google.ads.googleads import config
@@ -109,9 +111,23 @@ def get_service_account_credentials(
     )
 
 
-def get_credentials(
-    config_data: dict[str, Any]
-) -> Union[InstalledAppCredentials, ServiceAccountCreds]:
+@_initialize_credentials_decorator
+def get_application_default_credentials(
+    scopes: list[str] = _SERVICE_ACCOUNT_SCOPES
+) -> CredentialsBaseClass:
+    """Loads Application Default Credentials as returns them.
+
+    Args:
+        scopes: A list of additional scopes.
+
+    Returns:
+        An instance of auth.credentials.Credentials
+    """
+    (credentials, _) = ApplicationDefaultCredentials(scopes=scopes)
+    return credentials
+
+
+def get_credentials(config_data: dict[str, Any]) -> CredentialsBaseClass:
     """Decides which type of credentials to return based on the given config.
 
     Args:
@@ -127,20 +143,23 @@ def get_credentials(
         str, ...
     ] = config.get_oauth2_required_service_account_keys()
 
+    if config_data.get("use_application_default_credentials"):
+        # Using Application Default Credentials
+        return get_application_default_credentials()
     if all(key in config_data for key in required_installed_app_keys):
         # Using the Installed App Flow
         return get_installed_app_credentials(
-            config_data.get("client_id"),  # type: ignore[arg-type]
-            config_data.get("client_secret"),  # type: ignore[arg-type]
-            config_data.get("refresh_token"),  # type: ignore[arg-type]
-            http_proxy=config_data.get("http_proxy"),  # type: ignore[arg-type]
+            config_data.get("client_id"),
+            config_data.get("client_secret"),
+            config_data.get("refresh_token"),
+            http_proxy=config_data.get("http_proxy"),
         )
     elif all(key in config_data for key in required_service_account_keys):
         # Using the Service Account Flow
         return get_service_account_credentials(
-            config_data.get("json_key_file_path"),  # type: ignore[arg-type]
-            config_data.get("impersonated_email"),  # type: ignore[arg-type]
-            http_proxy=config_data.get("http_proxy"),  # type: ignore[arg-type]
+            config_data.get("json_key_file_path"),
+            config_data.get("impersonated_email"),
+            http_proxy=config_data.get("http_proxy"),
         )
     else:
         raise ValueError(

tests/config_test.py

@@ -38,6 +38,7 @@ def setUp(self):
         self.impersonated_email = "[email protected]"
         self.use_proto_plus = False
         self.use_cloud_org_for_api_access = False
+        self.use_application_default_credentials = True
         # The below fields are defaults that include required keys.
         # They are merged with other keys in individual tests, and isolated
         # here so that new required keys don't need to be added to each test.
@@ -355,6 +356,7 @@ def test_load_from_env(self, config_spy):
                 "GOOGLE_ADS_LINKED_CUSTOMER_ID": self.linked_customer_id,
                 "GOOGLE_ADS_JSON_KEY_FILE_PATH": self.json_key_file_path,
                 "GOOGLE_ADS_IMPERSONATED_EMAIL": self.impersonated_email,
+                "GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS": self.use_application_default_credentials,
             },
         }
 
@@ -374,6 +376,7 @@ def test_load_from_env(self, config_spy):
                     "linked_customer_id": self.linked_customer_id,
                     "json_key_file_path": self.json_key_file_path,
                     "impersonated_email": self.impersonated_email,
+                    "use_application_default_credentials": self.use_application_default_credentials
                 },
             )
             config_spy.assert_called_once()
@@ -689,3 +692,16 @@ def test_load_from_yaml_file_use_cloud_org_for_api_access_not_set(self):
         self._create_mock_yaml({})
         result = config.load_from_yaml_file()
         self.assertEqual(result.get("use_cloud_org_for_api_access"), None)
+
+    def test_load_from_yaml_file_use_account_default_credentials(self):
+        """Should load "use_account_default_credentials" config from a yaml."""
+        self._create_mock_yaml({"use_account_default_credentials": True})
+
+        result = config.load_from_yaml_file()
+        self.assertEqual(result["use_account_default_credentials"], True)
+
+    def test_load_from_yaml_file_use_account_default_credentials_not_set(self):
+        """Should set "use_account_default_credentials" as None when not set."""
+        self._create_mock_yaml({})
+        result = config.load_from_yaml_file()
+        self.assertEqual(result.get("use_account_default_credentials"), None)

tests/oauth2_test.py

@@ -173,3 +173,28 @@ def test_get_installed_app_credentials_without_proxy(self):
                 self.client_id, self.client_secret, self.refresh_token
             )
             mock_request_class.assert_called_once_with()
+
+    def test_get_application_default_credentials(self):
+        mock_credentials = mock.Mock()
+        mock_request = mock.Mock()
+        with mock.patch.object(
+            oauth2, "ApplicationDefaultCredentials", return_value=(mock_credentials, None)
+        ) as mock_initializer, mock.patch.object(
+            oauth2, "Request", return_value=mock_request
+        ) as mock_request_class:
+            result = oauth2.get_application_default_credentials(self.scopes)
+
+            mock_initializer.assert_called_once_with(scopes=self.scopes)
+            mock_request_class.assert_called_once()
+            result.refresh.assert_called_once_with(mock_request)
+
+    def test_get_credentials_application_default(self):
+        mock_config = {
+            "use_application_default_credentials": True
+        }
+
+        with mock.patch.object(
+            oauth2, "get_application_default_credentials", return_value=None
+        ) as mock_initializer:
+            oauth2.get_credentials(mock_config)
+            mock_initializer.assert_called_once()