feat: add support for Impersonated Service Account Credentials

src/ApplicationDefaultCredentials.php

@@ -20,6 +20,7 @@
 use DomainException;
 use Google\Auth\Credentials\AppIdentityCredentials;
 use Google\Auth\Credentials\GCECredentials;
+use Google\Auth\Credentials\ImpersonatedServiceAccountCredentials;
 use Google\Auth\Credentials\ServiceAccountCredentials;
 use Google\Auth\HttpHandler\HttpClientCache;
 use Google\Auth\HttpHandler\HttpHandlerFactory;
@@ -302,6 +303,10 @@ public static function getIdTokenCredentials(
                 throw new InvalidArgumentException('ID tokens are not supported for end user credentials');
             }
 
+            if ($jsonKey['type'] == 'impersonated_service_account') {
+                return new ImpersonatedServiceAccountCredentials(null, $jsonKey, $targetAudience);
+            }
+
             if ($jsonKey['type'] != 'service_account') {
                 throw new InvalidArgumentException('invalid value in the type field');
             }

src/Credentials/ExternalAccountCredentials.php

@@ -252,6 +252,8 @@ private function getImpersonatedAccessToken(string $stsToken, callable $httpHand
 
     /**
      * @param callable $httpHandler
+     * @param array<mixed> $headers [optional] Metrics headers to be inserted
+     *     into the token endpoint request present.
      *
      * @return array<mixed> {
      *     A set of auth related metadata, containing the following
@@ -263,9 +265,9 @@ private function getImpersonatedAccessToken(string $stsToken, callable $httpHand
      *     @type string $token_type (identity pool only)
      * }
      */
-    public function fetchAuthToken(callable $httpHandler = null)
+    public function fetchAuthToken(callable $httpHandler = null, array $headers = [])
     {
-        $stsToken = $this->auth->fetchAuthToken($httpHandler);
+        $stsToken = $this->auth->fetchAuthToken($httpHandler, $headers);
 
         if (isset($this->serviceAccountImpersonationUrl)) {
             return $this->getImpersonatedAccessToken($stsToken['access_token'], $httpHandler);

src/Credentials/GCECredentials.php

@@ -442,6 +442,9 @@ private static function detectResidencyWindows(string $registryProductKey): bool
      * If $httpHandler is not specified a the default HttpHandler is used.
      *
      * @param callable $httpHandler callback which delivers psr7 request
+     * @param array<mixed> $headers [optional] Headers to be inserted
+     *     into the token endpoint request present.
+     *
      *
      * @return array<mixed> {
      *     A set of auth related metadata, based on the token type.
@@ -453,7 +456,7 @@ private static function detectResidencyWindows(string $registryProductKey): bool
      * }
      * @throws \Exception
      */
-    public function fetchAuthToken(callable $httpHandler = null)
+    public function fetchAuthToken(callable $httpHandler = null, array $headers = [])
     {
         $httpHandler = $httpHandler
             ?: HttpHandlerFactory::build(HttpClientCache::getHttpClient());
@@ -469,7 +472,7 @@ public function fetchAuthToken(callable $httpHandler = null)
         $response = $this->getFromMetadata(
             $httpHandler,
             $this->tokenUri,
-            $this->applyTokenEndpointMetrics([], $this->targetAudience ? 'it' : 'at')
+            $this->applyTokenEndpointMetrics($headers, $this->targetAudience ? 'it' : 'at')
         );
 
         if ($this->targetAudience) {

src/Credentials/ImpersonatedServiceAccountCredentials.php

@@ -18,12 +18,20 @@
 
 namespace Google\Auth\Credentials;
 
+use Google\Auth\CacheTrait;
 use Google\Auth\CredentialsLoader;
+use Google\Auth\FetchAuthTokenInterface;
+use Google\Auth\HttpHandler\HttpClientCache;
+use Google\Auth\HttpHandler\HttpHandlerFactory;
 use Google\Auth\IamSignerTrait;
 use Google\Auth\SignBlobInterface;
+use GuzzleHttp\Psr7\Request;
+use InvalidArgumentException;
+use LogicException;
 
 class ImpersonatedServiceAccountCredentials extends CredentialsLoader implements SignBlobInterface
 {
+    use CacheTrait;
     use IamSignerTrait;
 
     private const CRED_TYPE = 'imp';
@@ -33,50 +41,90 @@ class ImpersonatedServiceAccountCredentials extends CredentialsLoader implements
      */
     protected $impersonatedServiceAccountName;
 
+    protected FetchAuthTokenInterface $sourceCredentials;
+
+    private string $serviceAccountImpersonationUrl;
+
+    /**
+     * @var string[]
+     */
+    private array $delegates;
+
     /**
-     * @var UserRefreshCredentials
+     * @var string|string[]
      */
-    protected $sourceCredentials;
+    private string|array $targetScope;
+
+    private int $lifetime;
 
     /**
      * Instantiate an instance of ImpersonatedServiceAccountCredentials from a credentials file that
-     * has be created with the --impersonated-service-account flag.
+     * has be created with the --impersonate-service-account flag.
      *
-     * @param string|string[]     $scope   The scope of the access request, expressed either as an
-     *                                     array or as a space-delimited string.
-     * @param string|array<mixed> $jsonKey JSON credential file path or JSON credentials
-     *                                     as an associative array.
+     * @param string|string[]|null $scope   The scope of the access request, expressed either as an
+     *                                      array or as a space-delimited string.
+     * @param string|array<mixed>  $jsonKey JSON credential file path or JSON array credentials {
+     *     JSON credentials as an associative array.
+     *
+     *     @type string                         $service_account_impersonation_url The URL to the service account
+     *     @type string|FetchAuthTokenInterface $source_credentials The source credentials to impersonate
+     *     @type int                            $lifetime The lifetime of the impersonated credentials
+     *     @type string[]                       $delegates The delegates to impersonate
+     * }
+     * @param string|null $targetAudience The audience to request an ID token.
      */
     public function __construct(
         $scope,
-        $jsonKey
+        $jsonKey,
+        private ?string $targetAudience = null
     ) {
         if (is_string($jsonKey)) {
             if (!file_exists($jsonKey)) {
-                throw new \InvalidArgumentException('file does not exist');
+                throw new InvalidArgumentException('file does not exist');
             }
             $json = file_get_contents($jsonKey);
             if (!$jsonKey = json_decode((string) $json, true)) {
-                throw new \LogicException('invalid json for auth config');
+                throw new LogicException('invalid json for auth config');
             }
         }
         if (!array_key_exists('service_account_impersonation_url', $jsonKey)) {
-            throw new \LogicException(
+            throw new LogicException(
                 'json key is missing the service_account_impersonation_url field'
             );
         }
         if (!array_key_exists('source_credentials', $jsonKey)) {
-            throw new \LogicException('json key is missing the source_credentials field');
+            throw new LogicException('json key is missing the source_credentials field');
+        }
+        if ($scope && $targetAudience) {
+            throw new InvalidArgumentException(
+                'Scope and targetAudience cannot both be supplied'
+            );
+        }
+        if (is_array($jsonKey['source_credentials'])) {
+            if (!array_key_exists('type', $jsonKey['source_credentials'])) {
+                throw new InvalidArgumentException('json key source credentials are missing the type field');
+            }
+            if (
+                $targetAudience !== null
+                && $jsonKey['source_credentials']['type'] === 'service_account'
+            ) {
+                // Service account tokens MUST request a scope, and as this token is only used to impersonate
+                // an ID token, the narrowest scope we can request is `cloud-platform`.
+                $scope = 'https://www.googleapis.com/auth/cloud-platform';
+            }
+            $jsonKey['source_credentials'] = CredentialsLoader::makeCredentials($scope, $jsonKey['source_credentials']);
         }
 
+        $this->targetScope = $scope ?? [];
+        $this->lifetime = $jsonKey['lifetime'] ?? 3600;
+        $this->delegates = $jsonKey['delegates'] ?? [];
+
+        $this->serviceAccountImpersonationUrl = $jsonKey['service_account_impersonation_url'];
         $this->impersonatedServiceAccountName = $this->getImpersonatedServiceAccountNameFromUrl(
-            $jsonKey['service_account_impersonation_url']
+            $this->serviceAccountImpersonationUrl
         );
 
-        $this->sourceCredentials = new UserRefreshCredentials(
-            $scope,
-            $jsonKey['source_credentials']
-        );
+        $this->sourceCredentials = $jsonKey['source_credentials'];
     }
 
     /**
@@ -123,11 +171,52 @@ public function getClientName(callable $unusedHttpHandler = null)
      */
     public function fetchAuthToken(callable $httpHandler = null)
     {
-        // We don't support id token endpoint requests as of now for Impersonated Cred
-        return $this->sourceCredentials->fetchAuthToken(
+        $httpHandler = $httpHandler ?? HttpHandlerFactory::build(HttpClientCache::getHttpClient());
+
+        // The FetchAuthTokenInterface technically does not have a "headers" argument, but all of
+        // the implementations do. Additionally, passing in more parameters than the function has
+        // defined is allowed in PHP. So we'll just ignore the phpstan error here.
+        // @phpstan-ignore-next-line
+        $authToken = $this->sourceCredentials->fetchAuthToken(
             $httpHandler,
             $this->applyTokenEndpointMetrics([], 'at')
         );
+
+        $headers = $this->applyTokenEndpointMetrics([
+            'Content-Type' => 'application/json',
+            'Cache-Control' => 'no-store',
+            'Authorization' => sprintf('Bearer %s', $authToken['access_token'] ?? $authToken['id_token']),
+        ], $this->isIdTokenRequest() ? 'it' : 'at');
+
+        $body = match ($this->isIdTokenRequest()) {
+            true => [
+                'audience' => $this->targetAudience,
+                'includeEmail' => true,
+            ],
+            false => [
+                'scope' => $this->targetScope,
+                'delegates' => $this->delegates,
+                'lifetime' => sprintf('%ss', $this->lifetime),
+            ]
+        };
+
+        $request = new Request(
+            'POST',
+            $this->serviceAccountImpersonationUrl,
+            $headers,
+            (string) json_encode($body)
+        );
+
+        $response = $httpHandler($request);
+        $body = json_decode((string) $response->getBody(), true);
+
+        return match ($this->isIdTokenRequest()) {
+            true => ['id_token' => $body['token']],
+            false => [
+                'access_token' => $body['accessToken'],
+                'expires_at' => strtotime($body['expireTime']),
+            ]
+        };
     }
 
     /**
@@ -138,7 +227,9 @@ public function fetchAuthToken(callable $httpHandler = null)
      */
     public function getCacheKey()
     {
-        return $this->sourceCredentials->getCacheKey();
+        return $this->getFullCacheKey(
+            $this->serviceAccountImpersonationUrl . $this->sourceCredentials->getCacheKey()
+        );
     }
 
     /**
@@ -153,4 +244,9 @@ protected function getCredType(): string
     {
         return self::CRED_TYPE;
     }
+
+    private function isIdTokenRequest(): bool
+    {
+        return !is_null($this->targetAudience);
+    }
 }

src/Credentials/ServiceAccountCredentials.php

@@ -190,6 +190,8 @@ public function useJwtAccessWithScope()
 
     /**
      * @param callable $httpHandler
+     * @param array<mixed> $headers [optional] Headers to be inserted
+     *     into the token endpoint request present.
      *
      * @return array<mixed> {
      *     A set of auth related metadata, containing the following
@@ -199,7 +201,7 @@ public function useJwtAccessWithScope()
      *     @type string $token_type
      * }
      */
-    public function fetchAuthToken(callable $httpHandler = null)
+    public function fetchAuthToken(callable $httpHandler = null, array $headers = [])
     {
         if ($this->useSelfSignedJwt()) {
             $jwtCreds = $this->createJwtAccessCredentials();
@@ -215,7 +217,10 @@ public function fetchAuthToken(callable $httpHandler = null)
         }
         $authRequestType = empty($this->auth->getAdditionalClaims()['target_audience'])
             ? 'at' : 'it';
-        return $this->auth->fetchAuthToken($httpHandler, $this->applyTokenEndpointMetrics([], $authRequestType));
+        return $this->auth->fetchAuthToken(
+            $httpHandler,
+            $this->applyTokenEndpointMetrics($headers, $authRequestType)
+        );
     }
 
     /**

src/Credentials/UserRefreshCredentials.php

@@ -105,7 +105,7 @@ public function __construct(
 
     /**
      * @param callable $httpHandler
-     * @param array<mixed> $metricsHeader [optional] Metrics headers to be inserted
+     * @param array<mixed> $headers [optional] Metrics headers to be inserted
      *     into the token endpoint request present.
      *     This could be passed from ImersonatedServiceAccountCredentials as it uses
      *     UserRefreshCredentials as source credentials.
@@ -120,12 +120,12 @@ public function __construct(
      *     @type string $id_token
      * }
      */
-    public function fetchAuthToken(callable $httpHandler = null, array $metricsHeader = [])
+    public function fetchAuthToken(callable $httpHandler = null, array $headers = [])
     {
         // We don't support id token endpoint requests as of now for User Cred
         return $this->auth->fetchAuthToken(
             $httpHandler,
-            $this->applyTokenEndpointMetrics($metricsHeader, 'at')
+            $this->applyTokenEndpointMetrics($headers, 'at')
         );
     }
 

src/CredentialsLoader.php

@@ -85,6 +85,7 @@ public static function fromEnv()
             throw new \DomainException(self::unableToReadEnv($cause));
         }
         $jsonKey = file_get_contents($path);
+
         return json_decode((string) $jsonKey, true);
     }
 

src/FetchAuthTokenInterface.php

@@ -26,6 +26,7 @@ interface FetchAuthTokenInterface
      * Fetches the auth tokens based on the current state.
      *
      * @param callable $httpHandler callback which delivers psr7 request
+     *
      * @return array<mixed> a hash of auth tokens
      */
     public function fetchAuthToken(callable $httpHandler = null);

src/OAuth2.php

@@ -586,7 +586,7 @@ public function toJwt(array $config = [])
      *        the token endpoint request.
      * @return RequestInterface the authorization Url.
      */
-    public function generateCredentialsRequest(callable $httpHandler = null, $headers = [])
+    public function generateCredentialsRequest(callable $httpHandler = null, array $headers = [])
     {
         $uri = $this->getTokenCredentialUri();
         if (is_null($uri)) {
@@ -666,7 +666,7 @@ public function generateCredentialsRequest(callable $httpHandler = null, $header
      *        endpoint request.
      * @return array<mixed> the response
      */
-    public function fetchAuthToken(callable $httpHandler = null, $headers = [])
+    public function fetchAuthToken(callable $httpHandler = null, array $headers = [])
     {
         if (is_null($httpHandler)) {
             $httpHandler = HttpHandlerFactory::build(HttpClientCache::getHttpClient());

tests/ApplicationDefaultCredentialsTest.php

@@ -21,6 +21,7 @@
 use Google\Auth\ApplicationDefaultCredentials;
 use Google\Auth\Credentials\ExternalAccountCredentials;
 use Google\Auth\Credentials\GCECredentials;
+use Google\Auth\Credentials\ImpersonatedServiceAccountCredentials;
 use Google\Auth\Credentials\ServiceAccountCredentials;
 use Google\Auth\CredentialsLoader;
 use Google\Auth\CredentialSource;
@@ -509,6 +510,13 @@ public function testGetIdTokenCredentialsFailsIfNotOnGceAndNoDefaultFileFound()
         $this->assertNotNull($creds);
     }
 
+    public function testGetIdTokenCredentialsWithImpersonatedServiceAccountCredentials()
+    {
+        putenv('HOME=' . __DIR__ . '/fixtures5');
+        $creds = ApplicationDefaultCredentials::getIdTokenCredentials('[email protected]');
+        $this->assertInstanceOf(ImpersonatedServiceAccountCredentials::class, $creds);
+    }
+
     public function testGetIdTokenCredentialsWithCacheOptions()
     {
         $keyFile = __DIR__ . '/fixtures' . '/private.json';