Skip to main content
Version: 0.5.0 (Previous)

🔐 OAuth Drivers

OAuth drivers provide a consistent integration layer for third-party OAuth providers using Passport.js. They encapsulate provider strategy setup and expose simple request and callback helpers you can compose into routes and features.

🎯 Overview​

OAuth drivers in NodeBlocks are thin wrappers around Passport.js strategies that provide:

  • Strategy setup with provider credentials and scopes
  • Promise-based request/callback helpers for composition
  • Pluggable verification callbacks to normalize provider profiles

📋 Available OAuth Drivers​

Google OAuth Driver​

The Google OAuth driver integrates Passport.js Google strategy and exposes helpers for request and callback handling.

verifyGoogleCallback​

Verifies Google OAuth callback and processes user profile data for Passport.js authentication.

Purpose: Extract a normalized profile (email, displayName, accessToken) and pass it to Passport.

Parameters:

  • _req: Request — Express request object (unused in this implementation)
  • accessToken: string — Google OAuth access token for API access
  • refreshToken: string — Google OAuth refresh token for token renewal
  • profile: Profile — Google user profile data from OAuth callback
  • done: VerifyCallback — Passport.js verification callback function

Returns: void — Calls done callback with result or error

Handler Process:

  • Input: Request, access/refresh tokens, Google profile, Passport callback
  • Process: Extracts email from profile, validates presence, formats { accessToken, displayName, email }
  • Output: Calls done(null, formattedProfile) or done(error, false)
  • Errors: Throws AuthenticationBadRequestError when email is missing

Usage:

passport.use(new GoogleStrategy({ verifyGoogleCallback }));

createGoogleOAuthDriver​

Creates Google OAuth driver with Passport.js strategy and authentication helpers.

Purpose: Configure Google strategy and expose initialize, request, and callback helpers.

Parameters:

  • clientID: string — Google OAuth client ID from Google Cloud Console
  • clientSecret: string — Google OAuth client secret from Google Cloud Console
  • callbackURL: string — URL where Google will redirect after OAuth completion
  • scope: string[] — Array of OAuth scopes to request (defaults to ['email', 'profile'])
  • verify: typeof verifyGoogleCallback — Optional verification function (defaults to verifyGoogleCallback)

Returns: GoogleOAuthDriver — GoogleOAuthDriver object with complete OAuth flow management

Handler Process:

  • Input: Client credentials, callback URL, scopes, verification function
  • Process: Configures Passport Google strategy; wraps passport.authenticate in Promises for request/callback
  • Output: Driver object exposing initialize, request, and callback
  • Errors: Propagates Passport/Promise rejections

Usage:

// Create Google OAuth driver:
const googleDriver = createGoogleOAuthDriver(
  'your-client-id',
  'your-client-secret',
  'https://app.com/auth/google/callback'
);

// Use in Express app:
app.use('/auth/google', googleDriver.initialize);

🔗 Related Documentation​