chore: deprecate unsafe loads & client options, add warnings to risky methods (#2134)

* deprecate unsafe methods, add warnings to risky credential types, and update README instructions

* remove message added in prev commit; it is not strictly required here.

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* fix(docs): update README with secure credential loading example

Updates .readme-partials.yaml with the secure JWT constructor
example for loading credentials from environment variables. This
resolves a Windy Eagle vulnerability mitigation concern and adheres
to the synthtool workflow for documentation.

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* deprecate unsafe client options

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: GautamSharda

.readme-partials.yaml

@@ -253,7 +253,7 @@ body: |-
   The parameters for the JWT auth client including how to use it with a `.pem` file are explained in [samples/jwt.js](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/jwt.js).
 
   #### Loading credentials from environment variables
-  Instead of loading credentials from a key file, you can also provide them using an environment variable and the `GoogleAuth.fromJSON()` method.  This is particularly convenient for systems that deploy directly from source control (Heroku, App Engine, etc).
+  Instead of loading credentials from a key file, you can also provide them using an environment variable.  This is particularly convenient for systems that deploy directly from source control (Heroku, App Engine, etc).
 
   Start by exporting your credentials:
 
@@ -274,7 +274,7 @@ body: |-
   Now you can create a new client from the credentials:
 
   ```js
-  const {auth} = require('google-auth-library');
+  const {JWT} = require('google-auth-library');
 
   // load the environment variable with our keys
   const keysEnvVar = process.env['CREDS'];
@@ -283,9 +283,12 @@ body: |-
   }
   const keys = JSON.parse(keysEnvVar);
 
-  // load the JWT or UserRefreshClient from the keys
-  const client = auth.fromJSON(keys);
-  client.scopes = ['https://www.googleapis.com/auth/cloud-platform'];
+  // create a JWT client
+  const client = new JWT({
+    email: keys.client_email,
+    key: keys.private_key,
+    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+  });
   const url = `https://dns.googleapis.com/dns/v1/projects/${keys.project_id}`;
   const res = await client.fetch(url);
   console.log(res.data);

README.md

@@ -297,7 +297,7 @@ console.log(res.data);
 The parameters for the JWT auth client including how to use it with a `.pem` file are explained in [samples/jwt.js](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/jwt.js).
 
 #### Loading credentials from environment variables
-Instead of loading credentials from a key file, you can also provide them using an environment variable and the `GoogleAuth.fromJSON()` method.  This is particularly convenient for systems that deploy directly from source control (Heroku, App Engine, etc).
+Instead of loading credentials from a key file, you can also provide them using an environment variable.  This is particularly convenient for systems that deploy directly from source control (Heroku, App Engine, etc).
 
 Start by exporting your credentials:
 
@@ -318,7 +318,7 @@ $ export CREDS='{
 Now you can create a new client from the credentials:
 
 ```js
-const {auth} = require('google-auth-library');
+const {JWT} = require('google-auth-library');
 
 // load the environment variable with our keys
 const keysEnvVar = process.env['CREDS'];
@@ -327,9 +327,12 @@ if (!keysEnvVar) {
 }
 const keys = JSON.parse(keysEnvVar);
 
-// load the JWT or UserRefreshClient from the keys
-const client = auth.fromJSON(keys);
-client.scopes = ['https://www.googleapis.com/auth/cloud-platform'];
+// create a JWT client
+const client = new JWT({
+  email: keys.client_email,
+  key: keys.private_key,
+  scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+});
 const url = `https://dns.googleapis.com/dns/v1/projects/${keys.project_id}`;
 const res = await client.fetch(url);
 console.log(res.data);

src/auth/externalclient.ts

@@ -57,6 +57,14 @@ export class ExternalAccountClient {
    * This static method will instantiate the
    * corresponding type of external account credential depending on the
    * underlying credential source.
+   *
+   * **IMPORTANT**: This method does not validate the credential configuration.
+   * A security risk occurs when a credential configuration configured with
+   * malicious URLs is used. When the credential configuration is accepted from
+   * an untrusted source, you should validate it before using it with this
+   * method. For more details, see
+   * https://cloud.google.com/docs/authentication/external/externally-sourced-credentials.
+   *
    * @param options The external account options object typically loaded
    *   from the external account JSON credential file.
    * @return A BaseExternalAccountClient instance or null if the options

src/auth/googleauth.ts

@@ -84,7 +84,33 @@ export interface GoogleAuthOptions<T extends AuthClient = AnyAuthClient> {
    */
   authClient?: T;
   /**
-   * Path to a .json, .pem, or .p12 key file
+   * @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.
+   *
+   * The recommended way to provide credentials is to create an `auth` object
+   * using `google-auth-library` and pass it to the client constructor.
+   * This will ensure that unexpected credential types with potential for
+   * malicious intent are not loaded unintentionally. For example:
+   * ```
+   * const {GoogleAuth} = require('google-auth-library');
+   * const auth = new GoogleAuth({
+   *   // Scopes can be specified either as an array or as a single, space-delimited string.
+   *   scopes: 'https://www.googleapis.com/auth/cloud-platform'
+   * });
+   * const client = new MyClient({ auth: auth });
+   * ```
+   *
+   * 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.
+   *
+   * For more details, see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials.
    */
   keyFilename?: string;
 
@@ -94,13 +120,33 @@ export interface GoogleAuthOptions<T extends AuthClient = AnyAuthClient> {
   keyFile?: string;
 
   /**
-   * Object containing client_email and private_key properties, or the
-   * external account client options.
-   * Cannot be used with {@link GoogleAuthOptions.apiKey `apiKey`}.
+   * @deprecated This option is being deprecated because of a potential security risk.
    *
-   * @remarks
+   * 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.
    *
-   * **Important**: If you accept a credential configuration (credential JSON/File/Stream) from an external source for authentication to Google Cloud, 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, refer to {@link https://cloud.google.com/docs/authentication/external/externally-sourced-credentials Validate credential configurations from external sources}.
+   * The recommended way to provide credentials is to create an `auth` object
+   * using `google-auth-library` and pass it to the client constructor.
+   * This will ensure that unexpected credential types with potential for
+   * malicious intent are not loaded unintentionally. For example:
+   * ```
+   * const {GoogleAuth} = require('google-auth-library');
+   * const auth = new GoogleAuth({
+   *   // Scopes can be specified either as an array or as a single, space-delimited string.
+   *   scopes: 'https://www.googleapis.com/auth/cloud-platform'
+   * });
+   * const client = new MyClient({ auth: auth });
+   * ```
+   *
+   * 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.
+   *
+   * For more details, see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials.
    */
   credentials?: JWTInput | ExternalAccountClientOptions;
 
@@ -654,6 +700,38 @@ export class GoogleAuth<T extends AuthClient = AuthClient> {
    *
    * **Important**: If you accept a credential configuration (credential JSON/File/Stream) from an external source for authentication to Google Cloud, 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, refer to {@link https://cloud.google.com/docs/authentication/external/externally-sourced-credentials Validate credential configurations from external sources}.
    *
+   * @deprecated This method is being deprecated because of a potential security risk.
+   *
+   * This method 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 use a credential-type-specific
+   * constructor. 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. Please follow
+   * the recommendation for that method. For example, if you want to load only
+   * service accounts, you can use the `JWT` constructor:
+   * ```
+   * const {JWT} = require('google-auth-library');
+   * const keys = require('/path/to/key.json');
+   * const client = new JWT({
+   *   email: keys.client_email,
+   *   key: keys.private_key,
+   *   scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+   * });
+   * ```
+   *
+   * 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.
+   *
+   * For more details, see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials.
+   *
    * @param json The input object.
    * @param options The JWT or UserRefresh options for the client
    * @returns JWT or UserRefresh Client with data
@@ -719,6 +797,46 @@ export class GoogleAuth<T extends AuthClient = AuthClient> {
 
   /**
    * Create a credentials instance using the given input stream.
+   *
+   * @deprecated This method is being deprecated because of a potential security risk.
+   *
+   * This method 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 read and parse the stream, and then
+   * use a credential-type-specific constructor. 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. Please follow the recommendation for that method. For
+   * example, if you want to load only service accounts, you can do:
+   * ```
+   * const {JWT} = require('google-auth-library');
+   * const fs = require('fs');
+   *
+   * const stream = fs.createReadStream('path/to/key.json');
+   * const chunks = [];
+   * stream.on('data', (chunk) => chunks.push(chunk));
+   * stream.on('end', () => {
+   *   const keys = JSON.parse(Buffer.concat(chunks).toString());
+   *   const client = new JWT({
+   *     email: keys.client_email,
+   *     key: keys.private_key,
+   *     scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+   *   });
+   *   // use client
+   * });
+   * ```
+   *
+   * 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.
+   *
+   * For more details, see https://cloud.google.com/docs/authentication/external/externally-sourced-credentials.
    * @param inputStream The input stream.
    * @param callback Optional callback.
    */

src/auth/impersonated.ts

@@ -91,6 +91,13 @@ export class Impersonated extends OAuth2Client implements IdTokenProvider {
    * Also, the target service account must grant the orginating principal
    * the "Service Account Token Creator" IAM role.
    *
+   * **IMPORTANT**: This method does not validate the credential configuration.
+   * A security risk occurs when a credential configuration configured with
+   * malicious URLs is used. When the credential configuration is accepted from
+   * an untrusted source, you should validate it before using it with this
+   * method. For more details, see
+   * https://cloud.google.com/docs/authentication/external/externally-sourced-credentials.
+   *
    * @param {object} options - The configuration object.
    * @param {object} [options.sourceClient] the source credential used as to
    * acquire the impersonated credentials.