Skip to main content
Version: 🚧 Canary

🔐 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 Google Passport.js authentication.

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: Express request, access token, refresh token, Google profile, and verification callback
  • Process: Extracts email from profile, validates email presence, formats profile data for authentication
  • Output: Calls done callback with formatted profile data or error
  • Errors: AuthenticationBadRequestError when email is missing from Google profile

Usage:

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

createGoogleOAuthDriver​

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

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: Google OAuth credentials (clientID, clientSecret), callback URL, scope, and optional verification function
  • Process: Configures Passport.js Google strategy, creates callback and request handlers with Promise wrappers
  • Output: GoogleOAuthDriver object with callback, initialize, and request functions
  • Errors: Errors from Passport.js authentication or 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);

Twitter OAuth Driver​

The Twitter OAuth driver integrates Passport.js Twitter strategy and exposes helpers for request and callback handling with session management.

verifyTwitterCallback​

Verifies the Twitter OAuth callback and extracts user information.

Parameters:

  • _req: Request — Express request object (unused)
  • accessToken: string — OAuth access token (unused)
  • refreshToken: string — OAuth refresh token (unused)
  • profile: TwitterUserInfoPayload — Twitter user profile information
  • done: VerifyCallback — Callback function to signal completion

Returns: void — Calls done callback with result or error

Handler Process:

  • Input: Receives OAuth tokens and Twitter user profile
  • Process: Validates the presence of profile, id, and username
  • Output: Returns user information including displayName, id, and username
  • Errors: Returns AuthenticationOAuthError if profile, id, or username is missing

Usage:

passport.use(new TwitterStrategy({
  clientID: TWITTER_CLIENT_ID,
  clientSecret: TWITTER_CLIENT_SECRET,
  callbackURL: "http://www.example.com/auth/twitter/callback"
}, verifyTwitterCallback));

createTwitterOAuthDriver​

Creates a Twitter OAuth driver for handling authentication flows.

Parameters:

  • clientID: string — The client ID for the Twitter application
  • clientSecret: string — The client secret for the Twitter application
  • callbackURL: string — The callback URL for Twitter OAuth
  • sessionSecret: string — The secret for session management
  • verify: VerifyFunctionWithRequest — Optional verification function for handling Twitter OAuth callbacks

Returns: TwitterOAuthDriver — TwitterOAuthDriver object with complete OAuth flow management

Handler Process:

  • Input: Accepts clientID, clientSecret, callbackURL, sessionSecret, and an optional verify function
  • Process: Configures the Twitter strategy with Passport and sets up session middleware
  • Output: Returns a TwitterOAuthDriver with methods for callback, initialization, and request handling

Usage:

const twitterDriver = createTwitterOAuthDriver(
  'your-client-id',
  'your-client-secret',
  'https://yourapp.com/auth/twitter/callback',
  'your-session-secret'
);

// Use in Express app:
app.use('/auth/twitter', twitterDriver.initialize);

🔗 Related Documentation​