feat: add ExecutableSource credentials

composer.json

@@ -24,7 +24,8 @@
     "sebastian/comparator": ">=1.2.3",
     "phpseclib/phpseclib": "^3.0.35",
     "kelvinmo/simplejwt": "0.7.1",
-    "webmozart/assert": "^1.11"
+    "webmozart/assert": "^1.11",
+    "symfony/process": "^6.0||^7.0"
   },
   "suggest": {
     "phpseclib/phpseclib": "May be used in place of OpenSSL for signing strings or for token management. Please require version ^2."

src/CredentialSource/ExecutableSource.php

@@ -0,0 +1,260 @@
+<?php
+/*
+ * Copyright 2024 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Google\Auth\CredentialSource;
+
+use Google\Auth\ExecutableHandler\ExecutableHandler;
+use Google\Auth\ExecutableHandler\ExecutableResponseError;
+use Google\Auth\ExternalAccountCredentialSourceInterface;
+use RuntimeException;
+
+/**
+ * ExecutableSource enables the exchange of workload identity pool external credentials for
+ * Google access tokens by retrieving 3rd party tokens through a user supplied executable. These
+ * scripts/executables are completely independent of the Google Cloud Auth libraries. These
+ * credentials plug into ADC and will call the specified executable to retrieve the 3rd party token
+ * to be exchanged for a Google access token.
+ *
+ * To use these credentials, the GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES environment variable
+ * must be set to '1'. This is for security reasons.
+ *
+ * Both OIDC and SAML are supported. The executable must adhere to a specific response format
+ * defined below.
+ *
+ * The executable must print out the 3rd party token to STDOUT in JSON format. When an
+ * output_file is specified in the credential configuration, the executable must also handle writing the
+ * JSON response to this file.
+ *
+ * <pre>
+ * OIDC response sample:
+ * {
+ *   "version": 1,
+ *   "success": true,
+ *   "token_type": "urn:ietf:params:oauth:token-type:id_token",
+ *   "id_token": "HEADER.PAYLOAD.SIGNATURE",
+ *   "expiration_time": 1620433341
+ * }
+ *
+ * SAML2 response sample:
+ * {
+ *   "version": 1,
+ *   "success": true,
+ *   "token_type": "urn:ietf:params:oauth:token-type:saml2",
+ *   "saml_response": "...",
+ *   "expiration_time": 1620433341
+ * }
+ *
+ * Error response sample:
+ * {
+ *   "version": 1,
+ *   "success": false,
+ *   "code": "401",
+ *   "message": "Error message."
+ * }
+ * </pre>
+ *
+ * The "expiration_time" field in the JSON response is only required for successful
+ * responses when an output file was specified in the credential configuration
+ *
+ * The auth libraries will populate certain environment variables that will be accessible by the
+ * executable, such as: GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE, GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE,
+ * GOOGLE_EXTERNAL_ACCOUNT_INTERACTIVE, GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL, and
+ * GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE.
+ */
+class ExecutableSource implements ExternalAccountCredentialSourceInterface
+{
+    private const GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES = 'GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES';
+    private const SAML_SUBJECT_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:saml2';
+    private const OIDC_SUBJECT_TOKEN_TYPE1 = 'urn:ietf:params:oauth:token-type:id_token';
+    private const OIDC_SUBJECT_TOKEN_TYPE2 = 'urn:ietf:params:oauth:token-type:jwt';
+
+    private string $command;
+    private ExecutableHandler $executableHandler;
+    private ?string $outputFile;
+
+    /**
+     * @param string $command    The string command to run to get the subject token.
+     * @param string $outputFile
+     */
+    public function __construct(
+        string $command,
+        ?string $outputFile,
+        ExecutableHandler $executableHandler = null,
+    ) {
+        $this->command = $command;
+        $this->outputFile = $outputFile;
+        $this->executableHandler = $executableHandler ?: new ExecutableHandler();
+    }
+
+    /**
+     * @param callable $httpHandler unused.
+     * @return string
+     * @throws RuntimeException if the executable is not allowed to run.
+     * @throws ExecutableResponseError if the executable response is invalid.
+     */
+    public function fetchSubjectToken(callable $httpHandler = null): string
+    {
+        // Check if the executable is allowed to run.
+        if (getenv(self::GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES) !== '1') {
+            throw new RuntimeException(
+                'Pluggable Auth executables need to be explicitly allowed to run by '
+                . 'setting the GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES environment '
+                . 'Variable to 1.'
+            );
+        }
+
+        if (!$executableResponse = $this->getCachedExecutableResponse()) {
+            // Run the executable.
+            $exitCode = ($this->executableHandler)($this->command);
+            $output = $this->executableHandler->getOutput();
+
+            // If the exit code is not 0, throw an exception with the output as the error details
+            if ($exitCode !== 0) {
+                throw new ExecutableResponseError(
+                    'The executable failed to run'
+                    . ($output ? ' with the following error: ' . $output : '.'),
+                    (string) $exitCode
+                );
+            }
+
+            $executableResponse = $this->parseExecutableResponse($output);
+
+            // Validate expiration.
+            if (isset($executableResponse['expiration_time']) && time() >= $executableResponse['expiration_time']) {
+                throw new ExecutableResponseError('Executable response is expired.');
+            }
+        }
+
+        // Throw error when the request was unsuccessful
+        if ($executableResponse['success'] === false) {
+            throw new ExecutableResponseError($executableResponse['message'], (string) $executableResponse['code']);
+        }
+
+        // Return subject token field based on the token type
+        return $executableResponse['token_type'] === self::SAML_SUBJECT_TOKEN_TYPE
+            ? $executableResponse['saml_response']
+            : $executableResponse['id_token'];
+    }
+
+    /**
+     * @return array<string, mixed>|null
+     */
+    private function getCachedExecutableResponse(): ?array
+    {
+        if (
+            $this->outputFile
+            && file_exists($this->outputFile)
+            && !empty(trim($outputFileContents = (string) file_get_contents($this->outputFile)))
+        ) {
+            try {
+                $executableResponse = $this->parseExecutableResponse($outputFileContents);
+            } catch (ExecutableResponseError $e) {
+                throw new ExecutableResponseError(
+                    'Error in output file: ' . $e->getMessage(),
+                    'INVALID_OUTPUT_FILE'
+                );
+            }
+
+            if ($executableResponse['success'] === false) {
+                // If the cached token was unsuccessful, run the executable to get a new one.
+                return null;
+            }
+
+            if (isset($executableResponse['expiration_time']) && time() >= $executableResponse['expiration_time']) {
+                // If the cached token is expired, run the executable to get a new one.
+                return null;
+            }
+
+            return $executableResponse;
+        }
+
+        return null;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function parseExecutableResponse(string $response): array
+    {
+        $executableResponse = json_decode($response, true);
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            throw new ExecutableResponseError(
+                'The executable returned an invalid response: ' . $response,
+                'INVALID_RESPONSE'
+            );
+        }
+        if (!array_key_exists('version', $executableResponse)) {
+            throw new ExecutableResponseError('Executable response must contain a "version" field.');
+        }
+        if (!array_key_exists('success', $executableResponse)) {
+            throw new ExecutableResponseError('Executable response must contain a "success" field.');
+        }
+
+        // Validate required fields for a successful response.
+        if ($executableResponse['success']) {
+            // Validate token type field.
+            $tokenTypes = [self::SAML_SUBJECT_TOKEN_TYPE, self::OIDC_SUBJECT_TOKEN_TYPE1, self::OIDC_SUBJECT_TOKEN_TYPE2];
+            if (!isset($executableResponse['token_type'])) {
+                throw new ExecutableResponseError(
+                    'Executable response must contain a "token_type" field when successful'
+                );
+            }
+            if (!in_array($executableResponse['token_type'], $tokenTypes)) {
+                throw new ExecutableResponseError(sprintf(
+                    'Executable response "token_type" field must be one of %s.',
+                    implode(', ', $tokenTypes)
+                ));
+            }
+
+            // Validate subject token for SAML and OIDC.
+            if ($executableResponse['token_type'] === self::SAML_SUBJECT_TOKEN_TYPE) {
+                if (empty($executableResponse['saml_response'])) {
+                    throw new ExecutableResponseError(sprintf(
+                        'Executable response must contain a "saml_response" field when token_type=%s.',
+                        self::SAML_SUBJECT_TOKEN_TYPE
+                    ));
+                }
+            } elseif (empty($executableResponse['id_token'])) {
+                throw new ExecutableResponseError(sprintf(
+                    'Executable response must contain a "id_token" field when '
+                    . 'token_type=%s.',
+                    $executableResponse['token_type']
+                ));
+            }
+
+            // Validate expiration exists when an output file is specified.
+            if ($this->outputFile) {
+                if (!isset($executableResponse['expiration_time'])) {
+                    throw new ExecutableResponseError(
+                        'The executable response must contain a "expiration_time" field for successful responses ' .
+                        'when an output_file has been specified in the configuration.'
+                    );
+                }
+            }
+        } else {
+            // Both code and message must be provided for unsuccessful responses.
+            if (!array_key_exists('code', $executableResponse)) {
+                throw new ExecutableResponseError('Executable response must contain a "code" field when unsuccessful.');
+            }
+            if (empty($executableResponse['message'])) {
+                throw new ExecutableResponseError('Executable response must contain a "message" field when unsuccessful.');
+            }
+        }
+
+        return $executableResponse;
+    }
+}

src/Credentials/ExternalAccountCredentials.php

@@ -18,8 +18,10 @@
 namespace Google\Auth\Credentials;
 
 use Google\Auth\CredentialSource\AwsNativeSource;
+use Google\Auth\CredentialSource\ExecutableSource;
 use Google\Auth\CredentialSource\FileSource;
 use Google\Auth\CredentialSource\UrlSource;
+use Google\Auth\ExecutableHandler\ExecutableHandler;
 use Google\Auth\ExternalAccountCredentialSourceInterface;
 use Google\Auth\FetchAuthTokenInterface;
 use Google\Auth\GetQuotaProjectInterface;
@@ -150,11 +152,6 @@ private static function buildCredentialSource(array $jsonKey): ExternalAccountCr
                     'The regional_cred_verification_url field is required for aws1 credential source.'
                 );
             }
-            if (!array_key_exists('audience', $jsonKey)) {
-                throw new InvalidArgumentException(
-                    'aws1 credential source requires an audience to be set in the JSON file.'
-                );
-            }
 
             return new AwsNativeSource(
                 $jsonKey['audience'],
@@ -174,6 +171,43 @@ private static function buildCredentialSource(array $jsonKey): ExternalAccountCr
             );
         }
 
+        if (isset($credentialSource['executable'])) {
+            if (!array_key_exists('command', $credentialSource['executable'])) {
+                throw new InvalidArgumentException(
+                    'executable source requires a command to be set in the JSON file.'
+                );
+            }
+
+            // Build command environment variables
+            $env = [
+                'GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE' => $jsonKey['audience'],
+                'GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE' => $jsonKey['subject_token_type'],
+                // Always set to 0 because interactive mode is not supported.
+                'GOOGLE_EXTERNAL_ACCOUNT_INTERACTIVE' => '0',
+            ];
+
+            if ($outputFile = $credentialSource['executable']['output_file'] ?? null) {
+                $env['GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE'] = $outputFile;
+            }
+
+            if ($serviceAccountImpersonationUrl = $jsonKey['service_account_impersonation_url'] ?? null) {
+                // Parse email from URL. The formal looks as follows:
+                // https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/[email protected]:generateAccessToken
+                $regex = '/serviceAccounts\/(?<email>[^:]+):generateAccessToken$/';
+                if (preg_match($regex, $serviceAccountImpersonationUrl, $matches)) {
+                    $env['GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL'] = $matches['email'];
+                }
+            }
+
+            $timeoutMs = $credentialSource['executable']['timeout_millis'] ?? null;
+
+            return new ExecutableSource(
+                $credentialSource['executable']['command'],
+                $outputFile,
+                $timeoutMs ? new ExecutableHandler($env, $timeoutMs) : new ExecutableHandler($env)
+            );
+        }
+
         throw new InvalidArgumentException('Unable to determine credential source from json key.');
     }