or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

adc.mdcrypto.mdexternal-identity.mdindex.mdoauth2.mdservice-accounts.mdtoken-management.md
tile.json

tessl/npm-google-auth-library

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/google-auth-library@10.3.x

To install, run

npx @tessl/cli install tessl/npm-google-auth-library@10.3.0

index.mddocs/

Google Auth Library

Google Auth Library is Google's officially supported Node.js client library for OAuth 2.0 authorization and authentication with Google APIs. It provides comprehensive authentication methods including Application Default Credentials (ADC), Service Account credentials, JWT tokens, OAuth2 flows, and workload identity federation for accessing Google Cloud resources from various environments.

Package Information

  • Package Name: google-auth-library
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install google-auth-library

Core Imports

import { GoogleAuth, OAuth2Client, JWT } from "google-auth-library";

For CommonJS:

const { GoogleAuth, OAuth2Client, JWT } = require("google-auth-library");

Basic Usage

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

// Application Default Credentials (ADC) - automatic credential discovery
const auth = new GoogleAuth({
  scopes: ['https://www.googleapis.com/auth/cloud-platform']
});

// Get authenticated client
const authClient = await auth.getClient();

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

// Make authenticated request
const response = await authClient.request({
  url: 'https://www.googleapis.com/oauth2/v1/userinfo'
});

Architecture

Google Auth Library is built around several key components:

  • Application Default Credentials (ADC): Automatic credential discovery from environment variables, service account files, or metadata services
  • OAuth2 Flow: Standard OAuth2 authorization code flow for user authentication
  • Service Account Authentication: JWT-based authentication for server-to-server communication
  • Workload Identity Federation: Support for external identity providers (AWS, Azure, OIDC) to access Google Cloud
  • Token Management: Automatic token refresh, caching, and validation
  • Multi-Environment Support: Works in Node.js, browsers, Google Cloud environments, and external clouds

Capabilities

Application Default Credentials

Primary authentication factory that automatically discovers and manages credentials based on the environment. Supports service accounts, user credentials, and workload identity federation.

class GoogleAuth {
  constructor(options?: GoogleAuthOptions);
  
  getClient(): Promise<OAuth2Client | JWT | Compute | BaseExternalAccountClient>;
  getAccessToken(): Promise<string | null>;
  getIdTokenClient(targetAudience: string): Promise<IdTokenClient>;
  getProjectId(): Promise<string | null>;
}

interface GoogleAuthOptions {
  scopes?: string | string[];
  keyFilename?: string;
  keyFile?: string;
  credentials?: CredentialBody;
  clientOptions?: { [key: string]: any };
  projectId?: string;
}

Application Default Credentials

OAuth2 Authentication

OAuth2 client for implementing authorization code flows, managing user tokens, and verifying ID tokens. Essential for applications requiring user consent and authentication.

class OAuth2Client {
  constructor(clientId?: string, clientSecret?: string, redirectUrl?: string);
  
  generateAuthUrl(opts: GenerateAuthUrlOpts): string;
  getToken(code: string, callback?: GetTokenCallback): Promise<GetTokenResponse>;
  setCredentials(credentials: Credentials): void;
  refreshAccessToken(): Promise<RefreshAccessTokenResponse>;
  verifyIdToken(options: VerifyIdTokenOptions): Promise<LoginTicket>;
}

interface GenerateAuthUrlOpts {
  access_type?: string;
  scope?: string | string[];
  response_type?: string;
  state?: string;
  code_challenge_method?: CodeChallengeMethod;
  code_challenge?: string;
  prompt?: string;
}

OAuth2 Authentication

Service Account Authentication

JWT-based authentication for server-to-server communication using service account credentials. Ideal for backend services and automation.

class JWT {
  constructor(options?: JWTOptions);
  
  authorize(): Promise<string>;
  createSignedJWT(payload: JWTInput): string;
  getAccessToken(): Promise<string | null>;
}

interface JWTOptions {
  email?: string;
  keyFile?: string;
  key?: string;
  keyId?: string;
  scopes?: string | string[];
  subject?: string;
  additionalClaims?: { [key: string]: any };
}

Service Account Authentication

External Identity Federation

Support for workload identity federation allowing authentication from external identity providers (AWS, Azure, OIDC) to access Google Cloud resources without storing service account keys.

class BaseExternalAccountClient {
  constructor(options: BaseExternalAccountClientOptions);
  
  getAccessToken(): Promise<{ token?: string | null; res?: GaxiosResponse }>;
  retrieveSubjectToken(): Promise<string>;
}

class AwsClient extends BaseExternalAccountClient {
  constructor(options: AwsClientOptions);
}

class IdentityPoolClient extends BaseExternalAccountClient {
  constructor(options: IdentityPoolClientOptions);
}

External Identity Federation

Token Management

Utilities for token refresh, validation, and credential management. Includes downscoped tokens and service account impersonation.

class UserRefreshClient {
  constructor(options?: UserRefreshClientOptions);
  
  refreshAccessToken(): Promise<RefreshAccessTokenResponse>;
}

class Impersonated {
  constructor(options: ImpersonatedOptions);
  
  getAccessToken(): Promise<{ token?: string | null; res?: GaxiosResponse }>;
}

class DownscopedClient {
  constructor(options: DownscopedClientOptions);
  
  getAccessToken(): Promise<{ token?: string | null; res?: GaxiosResponse }>;
}

Token Management

Cryptographic Operations

Cryptographic utilities for signing, verification, and hashing operations. Provides both Node.js and browser-compatible implementations.

function createCrypto(): Crypto;
function hasBrowserCrypto(): boolean;

interface Crypto {
  sha256DigestBase64(str: string): Promise<string>;
  randomBytesBase64(count: number): string;
  verify(pubkey: string, data: string, signature: string): Promise<boolean>;
  sign(privateKey: string, data: string): Promise<string>;
}

Cryptographic Operations

Common Types

interface Credentials {
  access_token?: string | null;
  refresh_token?: string | null;
  scope?: string;
  token_type?: string;
  id_token?: string | null;
  expiry_date?: number | null;
}

interface CredentialBody {
  client_email?: string;
  client_id?: string;
  client_secret?: string;
  private_key?: string;
  private_key_id?: string;
  project_id?: string;
  quota_project_id?: string;
  refresh_token?: string;
  type?: string;
}

interface TokenPayload {
  iss?: string;
  azp?: string;
  aud?: string | string[];
  sub?: string;
  hd?: string;
  email?: string;
  email_verified?: boolean;
  at_hash?: string;
  nonce?: string;
  name?: string;
  picture?: string;
  given_name?: string;
  family_name?: string;
  locale?: string;
  iat?: number;
  exp?: number;
  jti?: string;
}

interface RequestMetadata {
  [key: string]: string | string[];
}

type GCPEnv = 'APP_ENGINE' | 'KUBERNETES_ENGINE' | 'COMPUTE_ENGINE' | 'CLOUD_FUNCTIONS' | 'CLOUD_RUN' | 'NONE';

enum CodeChallengeMethod {
  Plain = 'plain',
  S256 = 'S256'
}