diff --git a/AUTHENTICATION.md b/AUTHENTICATION.md index b9ffcb76f309..cd4c4e66d74f 100644 --- a/AUTHENTICATION.md +++ b/AUTHENTICATION.md @@ -93,30 +93,30 @@ $video = new VideoIntelligenceServiceClient([ ``` #### Note: -Some clients accept the `keyFilePath` and `keyFile` configuration options pointing to the credentials file: +Some clients accept the `keyFilePath` and `keyFile` configuration options pointing to the credentials +file. However, both of these options are deprecated in favor of using the `credentialsFetcher` +option or +[Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). ```php -use Google\Cloud\Storage\StorageClient; +require 'vendor/autoload.php'; -// Authenticate using a keyfile path -$cloud = new StorageClient([ - 'keyFilePath' => 'path/to/keyfile.json' -]); +use Google\Cloud\Storage\StorageClient; +use Google\Auth\Credentials\ServiceAccountCredentials; -// Authenticate using keyfile data -$cloud = new StorageClient([ - 'keyFile' => json_decode(file_get_contents('/path/to/keyfile.json'), true) +// Create the service account credentials and pass them in using the "credentialsFile" option +$keyFile = json_decode(file_get_contents('/path/to/keyfile.json'), true); +$storage = new StorageClient([ + 'credentialsFetcher' => new ServiceAccountCredentials($scopes, $keyFile), ]); ``` A list of clients that accept these parameters are: -- [Bigtable](https://github.com/googleapis/google-cloud-php-bigtable) -- [Spanner](https://github.com/googleapis/google-cloud-php-spanner) -- [Firestore](https://github.com/googleapis/google-cloud-php-firestore) + +- [BigQuery](https://github.com/googleapis/google-cloud-php-bigquery) - [Datastore](https://github.com/googleapis/google-cloud-php-datastore) -- [Pubsub](https://github.com/googleapis/google-cloud-php-pubsub) +- [Firestore](https://github.com/googleapis/google-cloud-php-firestore) - [Logging](https://github.com/googleapis/google-cloud-php-logging) -- [Translate](https://github.com/googleapis/google-cloud-php-translate) -- [Bigquery](https://github.com/googleapis/google-cloud-php-bigquery) +- [Spanner](https://github.com/googleapis/google-cloud-php-spanner) - [Storage](https://github.com/googleapis/google-cloud-php-storage) We recommend to visit the Check the [client documentation][php-ref-docs] for the client library you're using diff --git a/BigQuery/src/BigQueryClient.php b/BigQuery/src/BigQueryClient.php index c266d5daca24..cfc1e8179609 100644 --- a/BigQuery/src/BigQueryClient.php +++ b/BigQuery/src/BigQueryClient.php @@ -93,12 +93,50 @@ class BigQueryClient * fetcher instance. * @type callable $httpHandler A handler used to deliver Psr7 requests. * Only valid for requests sent over REST. - * @type array $keyFile The contents of the service account credentials - * .json file retrieved from the Google Developer's Console. - * Ex: `json_decode(file_get_contents($path), true)`. - * @type string $keyFilePath The full path to your service account - * credentials .json file retrieved from the Google Developers - * Console. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new BigQueryClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new BigQueryClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * @type float $requestTimeout Seconds to wait before timing out the * request. **Defaults to** `0` with REST and `60` with gRPC. * @type int $retries Number of retries for a failed request. **Defaults diff --git a/Bigtable/src/BigtableClient.php b/Bigtable/src/BigtableClient.php index 5cf1747b4fa8..62fa1d032257 100644 --- a/Bigtable/src/BigtableClient.php +++ b/Bigtable/src/BigtableClient.php @@ -91,15 +91,23 @@ class BigtableClient * @type string $apiEndpoint The address of the API remote host. May * optionally include the port, formatted as ":". * **Defaults to** 'bigtable.googleapis.com:443'. - * @type string|array|FetchAuthTokenInterface|CredentialsWrapper $credentials - * The credentials to be used by the client to authorize API calls. - * This option accepts either a path to a credentials file, or a - * decoded credentials file as a PHP array. - * *Advanced usage*: In addition, this option can also accept a - * pre-constructed {@see FetchAuthTokenInterface} object - * or {@see CredentialsWrapper} object. Note that when one of - * these objects are provided, any settings in - * `$config['credentialsConfig']` will be ignored. + * @type FetchAuthTokenInterface|CredentialsWrapper $credentials + * This option should only be used with a pre-constructed + * {@see FetchAuthTokenInterface} or {@see CredentialsWrapper} object. Note that + * when one of these objects are provided, any settings in $credentialsConfig will + * be ignored. + * **Important**: If you are providing a path to a credentials file, or a decoded + * credentials file as a PHP array, this usage is now DEPRECATED. Providing an + * unvalidated credential configuration to Google APIs can compromise the security + * of your systems and data. It is recommended to create the credentials explicitly + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * use Google\Cloud\Bigtable\BigtableClient; + * $creds = new ServiceAccountCredentials($scopes, $json); + * $options = new BigtableClient(['credentials' => $creds]); + * ``` + * {@see + * https://cloud.google.com/docs/authentication/external/externally-sourced-credentials} * @type array $credentialsConfig Options used to configure credentials, * including auth token caching, for the client. For a full list of * supporting configuration options, see {@see CredentialsWrapper}. diff --git a/Core/src/RequestWrapperTrait.php b/Core/src/RequestWrapperTrait.php index 17cf45287bd1..c2ffc9727033 100644 --- a/Core/src/RequestWrapperTrait.php +++ b/Core/src/RequestWrapperTrait.php @@ -84,9 +84,7 @@ trait RequestWrapperTrait * @type array $authCacheOptions Cache configuration options. * @type FetchAuthTokenInterface $credentialsFetcher A credentials * fetcher instance. - * @type array $keyFile The contents of the service account credentials - * .json file retrieved from the Google Developer's Console. - * Ex: `json_decode(file_get_contents($path), true)`. + * @type array $keyFile [DEPRECATED] use `credentialsFetcher` option. * @type float $requestTimeout Seconds to wait before timing out the * request. **Defaults to** `0` with REST and `60` with gRPC. * @type int $retries Number of retries for a failed request. diff --git a/Core/src/ServiceBuilder.php b/Core/src/ServiceBuilder.php index 2de759b76b4e..a2bf67ea4a3f 100644 --- a/Core/src/ServiceBuilder.php +++ b/Core/src/ServiceBuilder.php @@ -88,12 +88,8 @@ class ServiceBuilder * requests specifically for authentication. * @type callable $httpHandler A handler used to deliver Psr7 requests. * Only valid for requests sent over REST. - * @type array $keyFile The contents of the service account credentials - * .json file retrieved from the Google Developer's Console. - * Ex: `json_decode(file_get_contents($path), true)`. - * @type string $keyFilePath The full path to your service account - * credentials .json file retrieved from the Google Developers - * Console. + * @type array $keyFile [DEPRECATED] + * @type string $keyFilePath [DEPRECATED] * @type int $retries Number of retries for a failed request. * **Defaults to** `3`. * @type array $scopes Scopes to be used for the request. diff --git a/Datastore/src/DatastoreClient.php b/Datastore/src/DatastoreClient.php index f1eadc1192ac..0d514dfc4391 100644 --- a/Datastore/src/DatastoreClient.php +++ b/Datastore/src/DatastoreClient.php @@ -130,12 +130,50 @@ class DatastoreClient * fetcher instance. * @type callable $httpHandler A handler used to deliver Psr7 requests. * Only valid for requests sent over REST. - * @type array $keyFile The contents of the service account credentials - * .json file retrieved from the Google Developer's Console. - * Ex: `json_decode(file_get_contents($path), true)`. - * @type string $keyFilePath The full path to your service account - * credentials .json file retrieved from the Google Developers - * Console. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new DatastoreClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new DatastoreClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * @type float $requestTimeout Seconds to wait before timing out the * request. **Defaults to** `0` with REST and `60` with gRPC. * @type int $retries Number of retries for a failed request. **Defaults diff --git a/Firestore/src/FirestoreClient.php b/Firestore/src/FirestoreClient.php index 2c4f97c22b93..1de825379c08 100644 --- a/Firestore/src/FirestoreClient.php +++ b/Firestore/src/FirestoreClient.php @@ -17,6 +17,7 @@ namespace Google\Cloud\Firestore; +use Google\Auth\FetchAuthTokenInterface; use Google\Cloud\Core\Blob; use Google\Cloud\Core\ClientTrait; use Google\Cloud\Core\Exception\AbortedException; @@ -27,7 +28,6 @@ use Google\Cloud\Core\Retry; use Google\Cloud\Core\ValidateTrait; use Google\Cloud\Firestore\Connection\Grpc; -use Psr\Cache\CacheItemPoolInterface; use Psr\Http\Message\StreamInterface; /** @@ -111,7 +111,7 @@ class FirestoreClient * @type string $projectId The project ID from the Google Developer's * Console. * @type string $database The database name to use, if different from - the default. + * the default. * @type CacheItemPoolInterface $authCache A cache for storing access * tokens. **Defaults to** a simple in memory implementation. * @type array $authCacheOptions Cache configuration options. @@ -119,12 +119,52 @@ class FirestoreClient * requests specifically for authentication. * @type callable $httpHandler A handler used to deliver Psr7 requests. * Only valid for requests sent over REST. - * @type array $keyFile The contents of the service account credentials - * .json file retrieved from the Google Developer's Console. - * Ex: `json_decode(file_get_contents($path), true)`. - * @type string $keyFilePath The full path to your service account - * credentials .json file retrieved from the Google Developers - * Console. + * @type FetchAuthTokenInterface $credentialsFetcher A credentials + * fetcher instance. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new FirestoreClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new FirestoreClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * @type int $retries Number of retries for a failed request. **Defaults * to** `3`. * @type array $scopes Scopes to be used for the request. diff --git a/Logging/src/LoggingClient.php b/Logging/src/LoggingClient.php index 8c1de12a2954..753bff80b260 100644 --- a/Logging/src/LoggingClient.php +++ b/Logging/src/LoggingClient.php @@ -167,12 +167,50 @@ public static function psrBatchLogger($name, array $options = []) * fetcher instance. * @type callable $httpHandler A handler used to deliver Psr7 requests. * Only valid for requests sent over REST. - * @type array $keyFile The contents of the service account credentials - * .json file retrieved from the Google Developer's Console. - * Ex: `json_decode(file_get_contents($path), true)`. - * @type string $keyFilePath The full path to your service account - * credentials .json file retrieved from the Google Developers - * Console. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new LoggingClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new LoggingClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * @type float $requestTimeout Seconds to wait before timing out the * request. **Defaults to** `0` with REST and `60` with gRPC. * @type int $retries Number of retries for a failed request. diff --git a/PubSub/src/PubSubClient.php b/PubSub/src/PubSubClient.php index 2d8e8384d558..7bd302f94708 100644 --- a/PubSub/src/PubSubClient.php +++ b/PubSub/src/PubSubClient.php @@ -145,19 +145,22 @@ class PubSubClient * @type string $apiEndpoint The hostname with optional port to use in * place of the default service endpoint. Example: * `foobar.com` or `foobar.com:1234`. - * @type string|array|FetchAuthTokenInterface|CredentialsWrapper $credentials - * The credentials to be used by the client to authorize API calls. This option - * accepts either a path to a credentials file, or a decoded credentials file as a - * PHP array. - * *Advanced usage*: In addition, this option can also accept a pre-constructed - * {@see \Google\Auth\FetchAuthTokenInterface} object or - * {@see \Google\ApiCore\CredentialsWrapper} object. Note that when one of these - * objects are provided, any settings in $credentialsConfig will be ignored. - * *Important*: If you accept a credential configuration (credential - * JSON/File/Stream) from an external source for authentication to Google Cloud - * Platform, you must validate it before providing it to any Google API or library. - * Providing an unvalidated credential configuration to Google APIs can compromise - * the security of your systems and data. For more information {@see + * @type FetchAuthTokenInterface|CredentialsWrapper $credentials + * This option should only be used with a pre-constructed + * {@see FetchAuthTokenInterface} or {@see CredentialsWrapper} object. Note that + * when one of these objects are provided, any settings in $credentialsConfig will + * be ignored. + * **Important**: If you are providing a path to a credentials file, or a decoded + * credentials file as a PHP array, this usage is now DEPRECATED. Providing an + * unvalidated credential configuration to Google APIs can compromise the security + * of your systems and data. It is recommended to create the credentials explicitly + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * use Google\Cloud\PubSub\PubSubClient; + * $creds = new ServiceAccountCredentials($scopes, $json); + * $options = new PubSubClient(['credentials' => $creds]); + * ``` + * {@see * https://cloud.google.com/docs/authentication/external/externally-sourced-credentials} * @type array $credentialsConfig * Options used to configure credentials, including auth token caching, for the diff --git a/Spanner/src/SpannerClient.php b/Spanner/src/SpannerClient.php index 1136889efb72..d252b36ebf2f 100644 --- a/Spanner/src/SpannerClient.php +++ b/Spanner/src/SpannerClient.php @@ -158,12 +158,50 @@ class SpannerClient * fetcher instance. * @type callable $httpHandler A handler used to deliver Psr7 requests. * Only valid for requests sent over REST. - * @type array $keyFile The contents of the service account credentials - * .json file retrieved from the Google Developer's Console. - * Ex: `json_decode(file_get_contents($path), true)`. - * @type string $keyFilePath The full path to your service account - * credentials .json file retrieved from the Google Developers - * Console. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new SpannerClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new SpannerClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * @type float $requestTimeout Seconds to wait before timing out the * request. **Defaults to** `0` with REST and `60` with gRPC. * @type int $retries Number of retries for a failed request. Used only diff --git a/Storage/src/Bucket.php b/Storage/src/Bucket.php index 6abec40c810e..e08884e8fabe 100644 --- a/Storage/src/Bucket.php +++ b/Storage/src/Bucket.php @@ -1519,14 +1519,50 @@ public function lockRetentionPolicy(array $options = []) * space, and line breaks will be replaced by an empty string. * V2 Signed URLs may not provide `x-goog-encryption-key` or * `x-goog-encryption-key-sha256` headers. - * @type array $keyFile Keyfile data to use in place of the keyfile with - * which the client was constructed. If `$options.keyFilePath` is - * set, this option is ignored. - * @type string $keyFilePath A path to a valid keyfile to use in place - * of the keyfile with which the client was constructed. - * @type string|array $scopes One or more authentication scopes to be - * used with a key file. This option is ignored unless - * `$options.keyFile` or `$options.keyFilePath` is set. + * @type FetchAuthTokenInterface $credentialsFetcher A credentials + * fetcher instance. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * @type array $queryParams Additional query parameters to be included * as part of the signed URL query string. For allowed values, * see [Reference Headers](https://cloud.google.com/storage/docs/xml-api/reference-headers#query). @@ -1613,12 +1649,50 @@ public function signedUrl($expires, array $options = []) * `x-ignore` prefix), given as key/value pairs. * @type bool $forceOpenssl If true, OpenSSL will be used regardless of * whether phpseclib is available. **Defaults to** `false`. - * @type array $keyFile Keyfile data to use in place of the keyfile with - * which the client was constructed. If `$options.keyFilePath` is - * set, this option is ignored. - * @type string $keyFilePath A path to a valid Keyfile to use in place - * of the keyfile with which the client was constructed. - * @type string $scheme Either `http` or `https`. Only used if a custom + * @type FetchAuthTokenInterface $credentialsFetcher A credentials + * fetcher instance. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * hostname is provided via `$options.bucketBoundHostname`. If a * custom bucketBoundHostname is provided, **defaults to** `http`. * In all other cases, **defaults to** `https`. diff --git a/Storage/src/SigningHelper.php b/Storage/src/SigningHelper.php index 41acfbaf9ba1..6f4292e722fe 100644 --- a/Storage/src/SigningHelper.php +++ b/Storage/src/SigningHelper.php @@ -628,6 +628,7 @@ private function normalizeOptions(array $options) 'headers' => [], 'keyFile' => null, 'keyFilePath' => null, + 'credentialsFetcher' => null, 'method' => 'GET', 'queryParams' => [], 'responseDisposition' => null, @@ -822,6 +823,8 @@ private function getSigningCredentials(ConnectionInterface $connection, array $o $scopes = $options['scopes'] ?? $rw->scopes(); $credentials = CredentialsLoader::makeCredentials($scopes, $keyFile); + } elseif (isset($options['credentialsFetcher'])) { + $credentials = $options['credentialsFetcher']; } else { $credentials = $rw->getCredentialsFetcher(); } @@ -838,6 +841,7 @@ private function getSigningCredentials(ConnectionInterface $connection, array $o unset( $options['keyFilePath'], $options['keyFile'], + $options['credentialsFetcher'], $options['scopes'] ); diff --git a/Storage/src/StorageClient.php b/Storage/src/StorageClient.php index 97a8850680fb..ea5072600217 100644 --- a/Storage/src/StorageClient.php +++ b/Storage/src/StorageClient.php @@ -97,12 +97,50 @@ class StorageClient * fetcher instance. * @type callable $httpHandler A handler used to deliver Psr7 requests. * Only valid for requests sent over REST. - * @type array $keyFile The contents of the service account credentials - * .json file retrieved from the Google Developer's Console. - * Ex: `json_decode(file_get_contents($path), true)`. - * @type string $keyFilePath The full path to your service account - * credentials .json file retrieved from the Google Developers - * Console. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new StorageClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new StorageClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * @type float $requestTimeout Seconds to wait before timing out the * request. **Defaults to** `0` with REST and `60` with gRPC. * @type int $retries Number of retries for a failed request. diff --git a/Storage/src/StorageObject.php b/Storage/src/StorageObject.php index 5aa1260020eb..824d456d1dd2 100644 --- a/Storage/src/StorageObject.php +++ b/Storage/src/StorageObject.php @@ -925,11 +925,50 @@ public function downloadAsStreamAsync(array $options = []) * space, and line breaks will be replaced by an empty string. * V2 Signed URLs may not provide `x-goog-encryption-key` or * `x-goog-encryption-key-sha256` headers. - * @type array $keyFile Keyfile data to use in place of the keyfile with - * which the client was constructed. If `$options.keyFilePath` is - * set, this option is ignored. - * @type string $keyFilePath A path to a valid Keyfile to use in place - * of the keyfile with which the client was constructed. + * @type FetchAuthTokenInterface $credentialsFetcher A credentials + * fetcher instance. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * @type string $method One of `GET`, `PUT` or `DELETE`. * **Defaults to** `GET`. * @type string $responseDisposition The @@ -1043,11 +1082,50 @@ public function signedUrl($expires, array $options = []) * space, and line breaks will be replaced by an empty string. * V2 Signed URLs may not provide `x-goog-encryption-key` or * `x-goog-encryption-key-sha256` headers. - * @type array $keyFile Keyfile data to use in place of the keyfile with - * which the client was constructed. If `$options.keyFilePath` is - * set, this option is ignored. - * @type string $keyFilePath A path to a valid Keyfile to use in place - * of the keyfile with which the client was constructed. + * @type FetchAuthTokenInterface $credentialsFetcher A credentials + * fetcher instance. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * @type string $responseDisposition The * [`response-content-disposition`](http://www.iana.org/assignments/cont-disp/cont-disp.xhtml) * parameter of the signed url. @@ -1142,12 +1220,50 @@ public function signedUploadUrl($expires, array $options = []) * space, and line breaks will be replaced by an empty string. * V2 Signed URLs may not provide `x-goog-encryption-key` or * `x-goog-encryption-key-sha256` headers. - * @type array $keyFile Keyfile data to use in place of the keyfile with - * which the client was constructed. If `$options.keyFilePath` is - * set, this option is ignored. - * @type string $keyFilePath A path to a valid Keyfile to use in place - * of the keyfile with which the client was constructed. - * @type string $origin Value of CORS header + * @type FetchAuthTokenInterface $credentialsFetcher A credentials + * fetcher instance. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * "Access-Control-Allow-Origin". **Defaults to** `"*"`. * @type string|array $scopes One or more authentication scopes to be * used with a key file. This option is ignored unless diff --git a/Trace/src/TraceClient.php b/Trace/src/TraceClient.php index 1661e7908a97..05da546e8d99 100644 --- a/Trace/src/TraceClient.php +++ b/Trace/src/TraceClient.php @@ -72,14 +72,50 @@ class TraceClient * requests specifically for authentication. * @type FetchAuthTokenInterface $credentialsFetcher A credentials * fetcher instance. - * @type callable $httpHandler A handler used to deliver Psr7 requests. - * Only valid for requests sent over REST. - * @type array $keyFile The contents of the service account credentials - * .json file retrieved from the Google Developer's Console. - * Ex: `json_decode(file_get_contents($path), true)`. - * @type string $keyFilePath The full path to your service account - * credentials .json file retrieved from the Google Developers - * Console. + * @type array $keyFile [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new TraceClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials + * @type string $keyFilePath [DEPRECATED] + * @deprecated This option is being deprecated because of a potential security risk. + * This option does not validate the credential configuration. The security + * risk occurs when a credential configuration is accepted from a source + * that is not under your control and used without validation on your side. + * If you know that you will be loading credential configurations of a + * specific type, it is recommended to create the credentials directly and + * configure them using the `credentialsFetcher` option instead. + * ``` + * use Google\Auth\Credentials\ServiceAccountCredentials; + * $credentialsFetcher = new ServiceAccountCredentials($scopes, $json); + * $creds = new TraceClient(['credentialsFetcher' => $creds]); + * ``` + * This will ensure that an unexpected credential type with potential for + * malicious intent is not loaded unintentionally. You might still have to do + * validation for certain credential types. + * If you are loading your credential configuration from an untrusted source and have + * not mitigated the risks (e.g. by validating the configuration yourself), make + * these changes as soon as possible to prevent security risks to your environment. + * Regardless of the method used, it is always your responsibility to validate + * configurations received from external sources. + * @see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials * @type float $requestTimeout Seconds to wait before timing out the * request. **Defaults to** `0` with REST and `60` with gRPC. * @type int $retries Number of retries for a failed request. diff --git a/dev/tests/fixtures/docfx/ProductNeutralGuides/authentication.md b/dev/tests/fixtures/docfx/ProductNeutralGuides/authentication.md index b9ffcb76f309..cd4c4e66d74f 100644 --- a/dev/tests/fixtures/docfx/ProductNeutralGuides/authentication.md +++ b/dev/tests/fixtures/docfx/ProductNeutralGuides/authentication.md @@ -93,30 +93,30 @@ $video = new VideoIntelligenceServiceClient([ ``` #### Note: -Some clients accept the `keyFilePath` and `keyFile` configuration options pointing to the credentials file: +Some clients accept the `keyFilePath` and `keyFile` configuration options pointing to the credentials +file. However, both of these options are deprecated in favor of using the `credentialsFetcher` +option or +[Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). ```php -use Google\Cloud\Storage\StorageClient; +require 'vendor/autoload.php'; -// Authenticate using a keyfile path -$cloud = new StorageClient([ - 'keyFilePath' => 'path/to/keyfile.json' -]); +use Google\Cloud\Storage\StorageClient; +use Google\Auth\Credentials\ServiceAccountCredentials; -// Authenticate using keyfile data -$cloud = new StorageClient([ - 'keyFile' => json_decode(file_get_contents('/path/to/keyfile.json'), true) +// Create the service account credentials and pass them in using the "credentialsFile" option +$keyFile = json_decode(file_get_contents('/path/to/keyfile.json'), true); +$storage = new StorageClient([ + 'credentialsFetcher' => new ServiceAccountCredentials($scopes, $keyFile), ]); ``` A list of clients that accept these parameters are: -- [Bigtable](https://github.com/googleapis/google-cloud-php-bigtable) -- [Spanner](https://github.com/googleapis/google-cloud-php-spanner) -- [Firestore](https://github.com/googleapis/google-cloud-php-firestore) + +- [BigQuery](https://github.com/googleapis/google-cloud-php-bigquery) - [Datastore](https://github.com/googleapis/google-cloud-php-datastore) -- [Pubsub](https://github.com/googleapis/google-cloud-php-pubsub) +- [Firestore](https://github.com/googleapis/google-cloud-php-firestore) - [Logging](https://github.com/googleapis/google-cloud-php-logging) -- [Translate](https://github.com/googleapis/google-cloud-php-translate) -- [Bigquery](https://github.com/googleapis/google-cloud-php-bigquery) +- [Spanner](https://github.com/googleapis/google-cloud-php-spanner) - [Storage](https://github.com/googleapis/google-cloud-php-storage) We recommend to visit the Check the [client documentation][php-ref-docs] for the client library you're using