Google Auth Library for Node.js

Common errors

• Error: Node.js v16.x.x is not supported.

  cause The installed version of `google-auth-library` requires Node.js v18 or newer.
  fix Upgrade your Node.js runtime to version 18 or higher. For example, using nvm: `nvm install 18 && nvm use 18`.

• TypeError: require is not a function

  cause Attempting to use CommonJS `require()` syntax within an ES Module (ESM) context, or a general module import mismatch.
  fix If your project is ESM, ensure `"type": "module"` is set in `package.json` and use `import` statements. If CommonJS, verify no conflicting ESM configurations.

• Error: Could not load the default credentials. Browse to https://cloud.google.com/docs/authentication/getting-started for more information.

  cause Application Default Credentials (ADC) could not be automatically located or configured in the current environment.
  fix Authenticate using `gcloud auth application-default login`, set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file path, or ensure your application runs within a Google Cloud environment with associated service accounts.

Warnings

• breaking The library explicitly requires Node.js v18 or newer. Running on older versions will result in runtime errors or unexpected behavior.
  Fix: Upgrade your Node.js environment to version 18 or a more recent LTS release (e.g., using nvm: `nvm install 18 && nvm use 18`).
• gotcha While the library supports CommonJS, it is primarily designed for ES Modules. Using incorrect import syntax (e.g., `require` in an ES Module context) can lead to 'require is not defined' or `undefined` module exports.
  Fix: For new projects or modern Node.js environments, use ES Module `import` syntax (e.g., `import { Class } from 'pkg';`). Ensure your `package.json` specifies `"type": "module"` for ESM projects.
• breaking The `gtoken` dependency, previously exposed in some internal contexts, was internalized within the `google-auth-library` since v10.6.0. Direct access or manipulation of `gtoken` objects is no longer officially supported and may break.
  Fix: Rely solely on the public API of `google-auth-library` for token management and generation. Avoid direct interaction with internal `gtoken` implementations.
• gotcha Application Default Credentials (ADC) require proper environment configuration (e.g., `GOOGLE_APPLICATION_CREDENTIALS` environment variable, `gcloud` login, or running on GCP/GKE) to function automatically. Without it, authentication calls will fail.
  Fix: Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file, run `gcloud auth application-default login`, or ensure your application is deployed on a Google Cloud environment that provides default credentials.
• gotcha Updates to underlying HTTP proxy agents (e.g., `http-proxy-agent` updated to v7 in `teeny-request`, which is used by this library) may require adjustments if custom proxy configurations are used, potentially causing connection issues.
  Fix: Review and update custom proxy agent configurations to be compatible with the latest `http-proxy-agent` versions. Ensure any custom agent factories are correctly exporting constructors or objects as expected by updated dependencies.

Install

• npm install google-auth-library npm
• yarn add google-auth-library yarn
• pnpm add google-auth-library pnpm

Imports

• GoogleAuth
  wrong:

  const GoogleAuth = require('google-auth-library').GoogleAuth;

  correct:

  import { GoogleAuth } from 'google-auth-library';

  The primary entry point for Application Default Credentials (ADC) and general credential management. The library is primarily ESM-first, so 'require' can lead to issues in mixed environments.
• OAuth2Client
  wrong:

  import OAuth2Client from 'google-auth-library';

  correct:

  import { OAuth2Client } from 'google-auth-library';

  Used for user-based OAuth 2.0 flows. This is a named export, not a default export.
• JWT
  wrong:

  const JWT = require('google-auth-library').JWT;

  correct:

  import { JWT } from 'google-auth-library';

  For authentication using JSON Web Tokens (JWTs), typically with service accounts. Like other main exports, it's a named export in an ESM-preferred package.

Quickstart

Installs the library and authenticates using Application Default Credentials (ADC) to obtain and verify an access token.

import { GoogleAuth } from 'google-auth-library';

async function authenticateWithADC() {
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
  });

  // Get the credentials for the default project
  const client = await auth.getClient();
  const accessToken = await client.getAccessToken();

  console.log('Successfully obtained access token using Application Default Credentials.');
  console.log('Access Token:', accessToken.token);

  // Example: Use the token to make an authenticated request
  // (This is illustrative; actual API calls would use a client library or fetch with Authorization header)
  if (accessToken.token) {
    const url = 'https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=' + accessToken.token;
    try {
      const response = await fetch(url);
      const data = await response.json();
      console.log('Token Info:', data);
    } catch (fetchError) {
      console.error('Failed to verify token:', fetchError);
    }
  } else {
    console.warn("No access token found. Ensure ADC is configured correctly (e.g., GOOGLE_APPLICATION_CREDENTIALS set or running on GCP).");
  }
}

authenticateWithADC().catch(console.error);