OAuth2 Handler Example

This is an example project demonstrating how to use the @blur-effect/oauth2-handler package with Google Calendar API. The example showcases multi-account support, allowing users to connect and manage multiple Google accounts simultaneously.

Setup Instructions

1. Install dependencies:

npm install

2. Create a .env file in the root directory with the following variables:

# Server Configuration
PORT=3000
SESSION_SECRET=your-session-secret

# Google OAuth Configuration
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:3000/oauth2/callback/google

3. Set up a Google Cloud Project and OAuth 2.0 credentials:

   • Go to the Google Cloud Console (https://console.cloud.google.com)
   • Create a new project or select an existing one
   • Enable the Google Calendar API for your project
   • Go to Credentials > Create Credentials > OAuth client ID
   • Choose "Web application" as the application type
   • Set the following:
     • Name: Your app name
     • Authorized JavaScript origins: http://localhost:3000
     • Authorized redirect URIs: http://localhost:3000/oauth2/callback/google
   • Copy the Client ID and Client Secret to your .env file

4. Start the server:

npm start

5. Visit http://localhost:3000 in your browser

Multi-Account Support

This example demonstrates how to implement multi-account support using the OAuth2 handler:

Testing Multiple Accounts

1. Log in with your first Google account
2. Click "Add Another Account" to add additional accounts
3. Use different Google accounts for each login
4. Switch between accounts using the "Switch" button
5. Use "Remove" to delete a specific account
6. Use "Logout All" to clear all accounts

Implementation Details

The multi-account functionality is implemented through:

1. Session Storage:

   • Accounts are stored in an array within the Express session
   • Each account maintains its own authentication state and calendar events

2. Account Management:

   • Active account is tracked via activeAccountIndex in the session
   • Users can switch between accounts without re-authenticating
   • The UI clearly indicates which account is currently active

3. Token Management:

   • Each account has its own OAuth tokens
   • Individual accounts can be deleted via the UI
   • When an account is removed, its OAuth tokens are properly deleted

Key Methods

Token Store Methods

The UniversalTokenStore class provides these key methods for multi-account support:

1. getUserAccounts(agentId, provider):
   • Retrieves all user accounts for a specific agent and provider
   • Returns an array of StoredUserData objects containing user info and tokens
   • Used to display multiple connected accounts in the UI

const userAccounts = await store.getUserAccounts(req.sessionID, 'google');

2. deleteByEmail(agentId, provider, email):
   • Deletes a specific account by its email address
   • Returns a boolean indicating if the deletion was successful
   • Used when removing a specific account

const deleted = await store.deleteByEmail(req.sessionID, 'google', email);

3. save(agentId, provider, tokens):

   • Saves OAuth tokens for a specific user
   • Also fetches and stores user info using the provider's fetcher
   • Called automatically during OAuth callback

4. registerProvider(provider, fetcher):

   • Registers a user info fetcher for a specific provider
   • The fetcher is used to retrieve user data from access tokens
   • Essential for storing user information alongside tokens

store.registerProvider('google', new GoogleUserInfoFetcher());

Route Handler Methods

The Express application implements these route handlers for multi-account management:

1. OAuth Callback Handler - /oauth2/callback/google:

   • Processes OAuth authentication callbacks
   • Retrieves user information and adds to session accounts array
   • Updates existing accounts or adds new ones

2. Switch Account - /switch-account/:index:

   • Changes the active account by updating activeAccountIndex
   • Preserves all connected accounts in the session
   • Allows switching without re-authentication

3. Logout Specific Account - /logout/:index:

   • Removes a specific account from the session
   • Deletes the associated token from the token store
   • Updates the active index if needed

4. Logout All Accounts - /logout-all:

   • Destroys the session entirely
   • Removes all connected accounts at once

Session Management

The application uses Express session middleware to maintain account state:

app.use(async (req, res, next) => {
  // Initialize the accounts array if it doesn't exist
  if (!req.session.accounts) {
    req.session.accounts = [];
  }
  
  // Set the active account if there's at least one and none is active
  if (req.session.accounts.length > 0 && req.session.activeAccountIndex === undefined) {
    req.session.activeAccountIndex = 0;
  }
  
  next();
});

The session stores:

• accounts: Array of connected user accounts
• activeAccountIndex: Index of the currently active account

Account Refresh Method

The application refreshes account data on page load:

// In home route handler
if (req.session.accounts && req.session.accounts.length > 0) {
  const userAccounts = await store.getUserAccounts(req.sessionID, 'google');
  
  // Update accounts data if available
  if (userAccounts && userAccounts.length > 0) {
    // Create an updated accounts array preserving our events data
    const updatedAccounts = [];
    
    // Process all stored accounts from the token store
    for (const userData of userAccounts) {
      // Find if we already have this account in the session
      const existingIndex = req.session.accounts.findIndex(
        acc => acc.email === userData.userInfo.email
      );
      
      // Update existing or add new account
      // ...
    }
  }
}

Key Features

• Google OAuth authentication with multi-account support
• Google Calendar API integration
• Session management for multiple accounts
• Protected routes
• Calendar event display and management
• Token deletion by email
• Account switching interface

Key Implementation Components

• UniversalTokenStore: Stores tokens and user data, supports multiple accounts per session
• Multiple Account UI: Displays all connected accounts with active account indication
• Middleware: Ensures session initialization and account data refreshing

Project Structure

• src/index.js - Main application file with multi-account implementation
• src/views/ - EJS templates with account management UI
• src/public/ - Static assets including CSS for multi-account interface
• .env - Environment variables (not included in git)

Debugging

The application includes debugging information to help understand the multi-account flow:

• Debug info panel shows active account index and total accounts
• Console logs for authentication flow and account management
• Visual indicators for the active account

API Reference

Routes

• / - Home page with account list
• /auth/google - Start Google OAuth flow
• /oauth2/callback/google - OAuth callback handler
• /switch-account/:index - Switch to another connected account
• /logout/:index - Remove a specific account
• /logout-all - Remove all connected accounts
• /calendar - View calendar events for the active account
• /delete-token - API endpoint to delete tokens by email