Skip to main content
Version: 0.7.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.

PROVIDER_GOOGLE​

Constant identifier for Google OAuth provider used in identity resolution and driver configuration.

Type: string

Value: 'google'

Usage:

import { PROVIDER_GOOGLE } from '@nodeblocks/backend-sdk';

// Used for identity queries:
const identity = await identitiesCollection.findOne({
  provider: PROVIDER_GOOGLE,
  providerId: profile.id
});

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 and id from profile, validates both are present, formats profile data with displayName, email, and id fields
  • Output: Calls done callback with formatted profile data ({ displayName, email, id }) or error
  • Errors: AuthenticationBadRequestError when email or id 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.

PROVIDER_TWITTER​

Constant identifier for Twitter OAuth provider used in identity resolution and driver configuration.

Type: string

Value: 'twitter'

Usage:

import { PROVIDER_TWITTER } from '@nodeblocks/backend-sdk';

// Used for identity queries:
const identity = await identitiesCollection.findOne({
  provider: PROVIDER_TWITTER,
  providerId: profile.id
});

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 for callback state management
  • Output: Returns a TwitterOAuthDriver with methods for callback, initialization, and request handling

Key Features:

  • Uses session middleware to maintain OAuth state between request and callback
  • Session middleware is only applied during driver initialization, not to specific routes
  • Provides stateful authentication flow required by Twitter OAuth

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);

LINE OAuth Driver​

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

verifyLineCallback​

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

Parameters:

  • _req: Request — Express request object (unused in this implementation)
  • accessToken: string — LINE OAuth access token for API access
  • refreshToken: string — LINE OAuth refresh token for token renewal
  • profile: LineUserInfoPayload — LINE 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, LINE profile, and verification callback
  • Process: Extracts sub (subject identifier) from profile, validates sub presence, formats profile data for authentication
  • Output: Calls done callback with formatted profile data containing name and sub
  • Errors: AuthenticationOAuthError when sub is missing from LINE profile

Usage:

passport.use(new LineStrategy({
  verify: verifyLineCallback
}));

createLineOAuthDriver​

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

Parameters:

  • clientID: string — LINE channel ID from LINE Developers Console
  • clientSecret: string — LINE channel secret from LINE Developers Console
  • callbackURL: string — URL where LINE will redirect after OAuth completion
  • scope: string[] — Array of OAuth scopes to request (defaults to ['profile', 'openid', 'email'])
  • verify: VerifyFunctionWithRequest — Optional verification function (defaults to verifyLineCallback)

Returns: LineOAuthDriver — LineOAuthDriver object with complete OAuth flow management

Handler Process:

  • Input: LINE OAuth credentials (clientID, clientSecret), callback URL, scope, and optional verification function
  • Process: Configures Passport.js LINE strategy, creates callback and request handlers with Promise wrappers
  • Output: LineOAuthDriver object with callback, initialize, and request functions
  • Errors: Errors from Passport.js authentication, Promise rejections, or AuthenticationOAuthError for authentication failures

Usage:

// Create LINE OAuth driver:
const lineDriver = createLineOAuthDriver(
  'your-channel-id',
  'your-channel-secret',
  'https://app.com/auth/line/callback'
);

// Use in Express app:
app.use('/auth/line', lineDriver.initialize);

🔗 Related Documentation​