Add adc support to php client lib (#1115)

* Add adc support to php client lib

Change-Id: If39acfaed45509eb0301bb585b1e6751fc98092f

* Updated ADC implementation for PHP client lib

Change-Id: I7598112b72fb9f7596e1c719b76f6acc1e65646f

* content cleanup for adc support

Change-Id: I97d2790d46b21e57de59cc263d70133d9af3b7c6

* Add unit tests for ADC support

Change-Id: I86448f9f8e44b206847bd3ce273c93807674d8c7

* Code cleanup

Change-Id: I62e3ecea661b0cf40cd2eeac7cadb776744d8f07

* Refactor scopes

Change-Id: Ibea3b010818553bcc22ab976db8f425215119e65

* refactor ADC implementation and OAuth2 scope handling

Change-Id: I396d276d57b890e110840882cae74a7e6bd341ee

* refactor ADC implementation and update test method

Change-Id: I987a3723ccf5cc57e388c8e39d7a419fcef15fcd

* Additional refactoring and remove changelog edits

Change-Id: Ibdb4f9a450a366fb551a578346907dc0b5360283

* update import statement

Change-Id: I5ea7df214fb295ddd92d3c8ad329d1737014560c

---------

Co-authored-by: Aalap Shastri <aalapshastri@google.com>

Author: ajs424

composer.json

@@ -7,7 +7,8 @@
     "google/gax": "^1.19.1",
     "grpc/grpc": ">=1.36.0 <=1.57.0",
     "google/protobuf": "^3.21.5 || >=4.26 <=4.30.0",
-    "monolog/monolog": "^1.26 || ^2.0 || ^3.0"
+    "monolog/monolog": "^1.26 || ^2.0 || ^3.0",
+    "google/auth": "^1.30 || ^2.0"
   },
   "require-dev": {
     "phpunit/phpunit": "^9.5",

examples/Authentication/google_ads_php.ini

@@ -28,6 +28,14 @@ developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
 ; Required OAuth2 credentials. Uncomment and fill in the values for the
 ; appropriate flow based on your use case.
 
+; Application Default Credentials (ADC)
+; If no explicit credentials (clientId/secret/refreshToken or jsonKeyFilePath)
+; are provided below, the client library will automatically attempt to use ADC
+; to find credentials based on the environment (e.g., GOOGLE_APPLICATION_CREDENTIALS
+; environment variable, 'gcloud auth application-default login', or compute engine service account).
+; Explicitly set credentials take precedence over ADC.
+; See https://cloud.google.com/docs/authentication/application-default-credentials for details.
+
 ; For installed application flow.
 clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
 clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"

src/Google/Ads/GoogleAds/Lib/OAuth2TokenBuilder.php

@@ -18,11 +18,15 @@
 
 namespace Google\Ads\GoogleAds\Lib;
 
+use DomainException;
+use Google\Auth\CredentialsLoaderException;
+use Google\Auth\ApplicationDefaultCredentials;
 use Google\Auth\Credentials\ServiceAccountCredentials;
 use Google\Auth\Credentials\UserRefreshCredentials;
 use Google\Auth\FetchAuthTokenInterface;
 use InvalidArgumentException;
 use UnexpectedValueException;
+use Google\Ads\GoogleAds\Util\EnvironmentalVariables;
 
 /**
  * Builds OAuth2 access token fetchers.
@@ -31,6 +35,8 @@
  */
 final class OAuth2TokenBuilder extends AbstractGoogleAdsBuilder
 {
+    private const DEFAULT_SCOPE = 'https://www.googleapis.com/auth/adwords';
+
     private $jsonKeyFilePath;
     private $scopes;
     private $impersonatedEmail;
@@ -39,6 +45,16 @@ final class OAuth2TokenBuilder extends AbstractGoogleAdsBuilder
     private $clientSecret;
     private $refreshToken;
 
+    private $adcFetcher;
+
+    public function __construct(
+        ConfigurationLoader $configurationLoader = null,
+        ?EnvironmentalVariables $environmentalVariables = null,
+    ) {
+        parent::__construct($configurationLoader, $environmentalVariables);
+        $this->adcFetcher = [ApplicationDefaultCredentials::class, 'getCredentials'];
+    }
+
     /**
      * @see GoogleAdsBuilder::from()
      */
@@ -150,28 +166,84 @@ public function withImpersonatedEmail(?string $impersonatedEmail): self
         return $this;
     }
 
+    /**
+     * Overrides the internal Application Default Credentials fetcher for testing purposes.
+     * @param callable $adcFetcher The mock or custom callable.
+     * @return self
+     */
+    protected function withAdcFetcher(callable $adcFetcher): self
+    {
+        $this->adcFetcher = $adcFetcher;
+        return $this;
+    }
+
     /**
      * @see GoogleAdsBuilder::build()
      *
      * @return FetchAuthTokenInterface the created OAuth2 object that can fetch auth tokens
      */
-    public function build()
+    public function build(): FetchAuthTokenInterface
     {
         $this->defaultOptionals();
-        $this->validate();
 
-        if ($this->jsonKeyFilePath !== null) {
+
+
+        // 1. Check for **EXPLICIT** Service Account Flow
+        if (!empty($this->jsonKeyFilePath)) {
+            if (is_null($this->scopes)) {
+                throw new InvalidArgumentException(
+                    "Both 'jsonKeyFilePath' and 'scopes' must be set when using service account flow."
+                );
+            }
+            if (
+                !is_null($this->clientId)
+                || !is_null($this->clientSecret)
+                || !is_null($this->refreshToken)
+            ) {
+                    throw new InvalidArgumentException(
+                        "Cannot have both service account flow and installed/web "
+                        . "application flow credential values set."
+                    );
+            }
+            // Service Account flow uses the specific configured scope string
             return new ServiceAccountCredentials(
                 $this->scopes,
                 $this->jsonKeyFilePath,
                 $this->impersonatedEmail
             );
-        } else {
-            return new UserRefreshCredentials(null, [
-                'client_id' => $this->clientId,
-                'client_secret' => $this->clientSecret,
-                'refresh_token' => $this->refreshToken
-            ]);
+        }
+
+        // 2. Check for **EXPLICIT** User Refresh Token Flow (Installed/Web App)
+        if (!empty($this->refreshToken)) {
+            if (is_null($this->clientId) || is_null($this->clientSecret)) {
+                throw new UnexpectedValueException(
+                    "Both 'clientId' and 'clientSecret' must be set when using 'refreshToken'."
+                );
+            }
+            return new UserRefreshCredentials(
+                // Use the determined scope array, allowing configuration via $this->scopes
+                $this->scopes,
+                [
+                    'client_id' => $this->clientId,
+                    'client_secret' => $this->clientSecret,
+                    'refresh_token' => $this->refreshToken
+                ]
+            );
+        }
+
+        // 3. FALLBACK: Use Application Default Credentials (ADC)
+        try {
+            // Use the determined scope array, allowing configuration via $this->scopes
+            return call_user_func($this->adcFetcher, $this->scopes);
+        } catch (CredentialsLoaderException $e) {
+            throw new DomainException(
+                "No OAuth2 credentials were provided, and the automatic Application Default "
+                . "Credentials (ADC) search failed. Please ensure you have run "
+                . "'gcloud auth application-default login' or set explicit credentials. "
+                . "Underlying error: " . $e->getMessage(),
+                0,
+                $e
+            );
         }
     }
 
@@ -180,7 +252,12 @@ public function build()
      */
     public function defaultOptionals()
     {
-        // Nothing to default for this builder.
+        // If the user has not set a custom scope via config or withScopes(),
+        // default to the mandatory Google Ads API scope. This is needed for the
+        // User Refresh Token and ADC fallback flows.
+        if (is_null($this->scopes)) {
+            $this->scopes = self::DEFAULT_SCOPE;
+        }
     }
 
     /**
@@ -191,29 +268,32 @@ public function validate()
         if (
             (!is_null($this->jsonKeyFilePath) || !is_null($this->scopes))
             && (!is_null($this->clientId) || !is_null($this->clientSecret)
-                || !is_null($this->refreshToken))
+            || !is_null($this->refreshToken))
         ) {
             throw new InvalidArgumentException(
                 'Cannot have both service account '
                 . 'flow and installed/web application flow credential values set.'
             );
         }
-        if (!is_null($this->jsonKeyFilePath) || !is_null($this->scopes)) {
-            if (is_null($this->jsonKeyFilePath) || is_null($this->scopes)) {
+        if (!is_null($this->jsonKeyFilePath)) {
+            if ($this->scopes === self::DEFAULT_SCOPE) {
                 throw new InvalidArgumentException(
                     "Both 'jsonKeyFilePath' and "
                     . "'scopes' must be set when using service account flow."
                 );
             }
+        // Triggers validation if any part of the Installed/Web flow is set; otherwise, allows the ADC fallback.
         } elseif (
-            is_null($this->clientId)
-            || is_null($this->clientSecret)
-            || is_null($this->refreshToken)
+            !is_null($this->clientId)
+            || !is_null($this->clientSecret)
+            || !is_null($this->refreshToken)
         ) {
-            throw new UnexpectedValueException(
-                "All of 'clientId', 'clientSecret', and 'refreshToken' must be set when using "
-                . "installed/web application flow."
-            );
+            if ((is_null($this->clientId) || is_null($this->clientSecret) || is_null($this->refreshToken))) {
+                throw new UnexpectedValueException(
+                    "All of 'clientId', 'clientSecret', and 'refreshToken' must be set when using "
+                    . "installed/web application flow."
+                );
+            }
         }
     }