tessl/npm-google-auth-library

Google APIs Authentication Client Library for Node.js providing OAuth2, JWT, and Application Default Credentials

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Application Default Credentials

Name: tessl/npm-google-auth-library
Author: tessl

Application Default Credentials (ADC) provides automatic credential discovery and management across different environments. It's the recommended way to authenticate Google Cloud applications as it follows a standardized credential discovery process.

Capabilities

GoogleAuth Class

The primary authentication factory that automatically discovers credentials based on environment.

/**
 * Primary authentication factory for Google APIs
 * Automatically discovers credentials from environment variables, files, or metadata services
 */
class GoogleAuth {
  constructor(options?: GoogleAuthOptions);
  
  /** Get an authenticated client based on discovered credentials */
  getClient(): Promise<OAuth2Client | JWT | Compute | BaseExternalAccountClient>;
  
  /** Get an access token for the specified scopes */
  getAccessToken(): Promise<string | null>;
  
  /** Get an ID token client for the specified target audience */
  getIdTokenClient(targetAudience: string): Promise<IdTokenClient>;
  
  /** Get the project ID from environment or credentials */
  getProjectId(): Promise<string | null>;
  
  /** Get application default credentials */
  getApplicationDefault(): Promise<AuthClient>;
  
  /** Create client from JSON credentials */
  fromJSON(json: CredentialBody, options?: RefreshOptions): AuthClient;
  
  /** Create client from API key */
  fromAPIKey(apiKey: string, options?: RefreshOptions): AuthClient;
  
  /** Sign a blob using service account credentials */
  sign(blobToSign: string): Promise<string>;
  
  /** Get service account email */
  getCredentials(): Promise<CredentialBody>;
}

interface GoogleAuthOptions {
  /** OAuth2 scopes to request */
  scopes?: string | string[];
  /** Path to service account key file */
  keyFilename?: string;
  /** Service account key file contents */
  keyFile?: string;
  /** Credential object */
  credentials?: CredentialBody;
  /** Additional client options */
  clientOptions?: { [key: string]: any };
  /** Project ID override */
  projectId?: string;
  /** Quota project ID for billing */
  quotaProjectId?: string;
  /** Client email for impersonation */
  clientEmail?: string;
  /** Subject for impersonation */
  subject?: string;
  /** Universe domain */
  universeDomain?: string;
}

Usage Examples:

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

// Basic usage with automatic credential discovery
const auth = new GoogleAuth({
  scopes: ['https://www.googleapis.com/auth/cloud-platform']
});

const client = await auth.getClient();
const projectId = await auth.getProjectId();

// Using specific service account file
const auth = new GoogleAuth({
  keyFilename: '/path/to/service-account.json',
  scopes: ['https://www.googleapis.com/auth/storage-full-control']
});

// Using environment variable GOOGLE_APPLICATION_CREDENTIALS
const auth = new GoogleAuth({
  scopes: ['https://www.googleapis.com/auth/bigquery']
});

// Get access token directly
const accessToken = await auth.getAccessToken();

// Make authenticated request
const response = await client.request({
  url: 'https://storage.googleapis.com/storage/v1/b',
  params: { project: projectId }
});

Credential Discovery Process

GoogleAuth follows this credential discovery order:

GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to service account file
gcloud ADC file in well-known location (~/.config/gcloud/application_default_credentials.json)
Google Cloud metadata service (when running on Google Cloud)
Service account attached to compute resource (GCE, Cloud Run, etc.)

Environment Detection

/**
 * Detect the current Google Cloud environment
 */
enum GCPEnv {
  APP_ENGINE = 'APP_ENGINE',
  KUBERNETES_ENGINE = 'KUBERNETES_ENGINE', 
  COMPUTE_ENGINE = 'COMPUTE_ENGINE',
  CLOUD_FUNCTIONS = 'CLOUD_FUNCTIONS',
  CLOUD_RUN = 'CLOUD_RUN',
  NONE = 'NONE'
}

/**
 * Get the current GCP environment
 */
function getEnv(): GCPEnv;

Project ID Callback

/**
 * Callback function for project ID retrieval
 */
type ProjectIdCallback = (err?: Error | null, projectId?: string | null) => void;

Error Handling

Common authentication errors:

Authentication failed: Invalid credentials or expired tokens
Project ID not found: Unable to determine project ID from environment
Insufficient permissions: Token doesn't have required scopes
Network errors: Unable to reach authentication endpoints

try {
  const auth = new GoogleAuth();
  const client = await auth.getClient();
} catch (error) {
  if (error.message.includes('Could not load the default credentials')) {
    // No credentials found in environment
    console.error('Please set GOOGLE_APPLICATION_CREDENTIALS or run gcloud auth application-default login');
  }
}