mbkauthe 3.1.0 → 3.2.1

package/README.md

@@ -1,4 +1,4 @@
-# MBKAuthe v3.0 - Authentication System for Node.js
+# MBKAuthe v3.2 - Authentication System for Node.js
 
 [![Version](https://img.shields.io/npm/v/mbkauthe.svg)](https://www.npmjs.com/package/mbkauthe)
 [![License](https://img.shields.io/badge/License-GPL--2.0-blue.svg)](LICENSE)
@@ -16,19 +16,20 @@
   <img height="48px" src="https://handlebarsjs.com/handlebars-icon.svg" alt="Handlebars" />
 </p>
 
-**MBKAuth v3.0** is a production-ready authentication system for Node.js applications. Built with Express and PostgreSQL, it provides secure authentication, 2FA, role-based access, and GitHub OAuth out of the box.
+**MBKAuth v3.2** is a production-ready authentication system for Node.js applications. Built with Express and PostgreSQL, it provides secure authentication, 2FA, role-based access, and OAuth integration (GitHub & Google) out of the box.
 
 ## ✨ Key Features
 
 - 🔐 Secure password authentication with PBKDF2 hashing
 - 🔑 PostgreSQL session management with cross-subdomain support
 - 📱 Optional TOTP-based 2FA with trusted device memory
-- 🔄 GitHub OAuth integration
+- 🔄 OAuth integration (GitHub & Google)
 - 👥 Role-based access control (SuperAdmin, NormalUser, Guest)
 - 🎯 Multi-application user management
-- 🛡️ CSRF protection & rate limiting
+- 🛡️ CSRF protection & advanced rate limiting
 - 🚀 Easy Express.js integration
 - 🎨 Customizable Handlebars templates
+- 🔒 Enhanced security with session fixation prevention
 
 ## 📦 Installation
 
@@ -48,10 +49,18 @@ IS_DEPLOYED=false
 DOMAIN=localhost
 LOGIN_DB=postgresql://user:pass@localhost:5432/db
 
-# Optional
+# Optional Features
 MBKAUTH_TWO_FA_ENABLE=false
 COOKIE_EXPIRE_TIME=2
+
+# OAuth Configuration (Optional)
 GITHUB_LOGIN_ENABLED=false
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+
+GOOGLE_LOGIN_ENABLED=false
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
 ```
 
 **2. Set Up Database**
@@ -110,24 +119,44 @@ app.get('/admin', validateSession, checkRolePermission(['SuperAdmin']), (req, re
 app.listen(3000);
 ```
 
-## 🧪 Testing
 
-MBKAuthe includes comprehensive test coverage for all authentication features:
+## 🧪 Testing & Git Hooks
+
+MBKAuthe includes comprehensive test coverage for all authentication features. **A pre-commit hook is provided to ensure code quality:**
+
+### Pre-commit Hook (Automatic Test Runner)
+
+- Located at `scripts/pre-commit` and `scripts/pre-commit` (Node.js, cross-platform)
+- Starts the dev server, runs all tests, and blocks commits if any test fails
+- The dev server is automatically stopped after tests complete
+- Ensures you never commit code that breaks tests
+
+### Git Hook Setup
+
+Hooks are auto-configured every time you run `npm run dev`, `npm test`, or `npm run test:watch` (see `scripts/setup-hooks.js`).
+
+If you ever need to manually set up hooks:
 
 ```bash
-# Run all tests
+node scripts/setup-hooks.js
+```
+
+### Running Tests
+
+```bash
+# Run all tests (auto-configures hooks)
 npm test
 
-# Run tests in watch mode (auto-rerun on changes)
+# Run tests in watch mode (auto-configures hooks)
 npm run test:watch
 
-# Run with development flags
+# Run with development flags (auto-configures hooks)
 npm run dev
 ```
 
 **Test Coverage:**
 - ✅ Authentication flows (login, 2FA, logout)
-- ✅ OAuth integration (GitHub)  
+- ✅ OAuth integration (GitHub)
 - ✅ Session management and security
 - ✅ Role-based access control
 - ✅ API endpoints and error handling
@@ -183,6 +212,8 @@ app.post('/api/data', authenticate(process.env.API_TOKEN), handler);
 **OAuth Routes:**
 - `GET /mbkauthe/api/github/login` - GitHub OAuth initiation (10/5min rate limit)
 - `GET /mbkauthe/api/github/login/callback` - GitHub OAuth callback
+- `GET /mbkauthe/api/google/login` - Google OAuth initiation (10/5min rate limit)
+- `GET /mbkauthe/api/google/login/callback` - Google OAuth callback
 
 **Information & Utility Routes:**
 - `GET /mbkauthe/info`, `/mbkauthe/i` - Version & config info (8/min rate limit)
@@ -200,11 +231,12 @@ app.post('/api/data', authenticate(process.env.API_TOKEN), handler);
 
 ## 🔐 Security Features
 
-- **Rate Limiting**: Login (8/min), Logout (10/min), 2FA (5/min), OAuth (10/5min)
-- **CSRF Protection**: All POST routes protected
+- **Rate Limiting**: Login (8/min), Logout (10/min), 2FA (5/min), OAuth (10/5min), Admin (3/5min)
+- **CSRF Protection**: All state-changing routes protected with token validation
 - **Secure Cookies**: httpOnly, sameSite, secure in production
 - **Password Hashing**: PBKDF2 with 100k iterations
-- **Session Security**: PostgreSQL-backed, automatic cleanup
+- **Session Security**: PostgreSQL-backed, automatic cleanup, session fixation prevention
+- **OAuth Security**: State validation, token expiry handling, secure callback validation
 
 ## 📱 Two-Factor Authentication
 
@@ -220,7 +252,9 @@ CREATE TABLE "TwoFA" (
 
 Users can mark devices as trusted to skip 2FA for configurable duration.
 
-## 🔄 GitHub OAuth
+## 🔄 OAuth Integration
+
+### GitHub OAuth
 
 **Setup:**
 
@@ -243,6 +277,32 @@ CREATE TABLE user_github (
 );
 ```
 
+### Google OAuth
+
+**Setup:**
+
+1. Create Google OAuth 2.0 Client in [Google Cloud Console](https://console.cloud.google.com/)
+2. Add authorized redirect URI: `https://yourdomain.com/mbkauthe/api/google/login/callback`
+3. Configure environment:
+```env
+GOOGLE_LOGIN_ENABLED=true
+GOOGLE_CLIENT_ID=your_client_id
+GOOGLE_CLIENT_SECRET=your_client_secret
+```
+4. Create table:
+```sql
+CREATE TABLE user_google (
+    id SERIAL PRIMARY KEY,
+    user_name VARCHAR(50) REFERENCES "Users"("UserName"),
+    google_id VARCHAR(255) UNIQUE,
+    google_email VARCHAR(255),
+    access_token VARCHAR(255),
+    created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+**Note:** Users must link their OAuth accounts before they can use OAuth login.
+
 ## 🎨 Customization
 
 **Redirect URL:**

package/docs/api.md

@@ -108,6 +108,7 @@ Renders the main login page.
 
 **Template Variables:**
 - `githubLoginEnabled` - Whether GitHub OAuth is enabled
+- `googleLoginEnabled` - Whether Google OAuth is enabled
 - `customURL` - Redirect URL after login
 - `userLoggedIn` - Whether user is already authenticated
 - `username` - Current username if logged in
@@ -328,7 +329,7 @@ Terminates all active sessions across all users (admin only).
 
 **Authentication:** API token required (via `authenticate` middleware)
 
-**Rate Limit:** No explicit rate limiting applied
+**Rate Limit:** 3 requests per 5 minutes
 
 **Headers:**
 ```
@@ -354,11 +355,12 @@ Authorization: your-main-secret-token
 | 500 | Internal Server Error |
 
 **Implementation Details:**
-- Clears all user session IDs in the database (`Users` table)
-- Deletes all session records from the `session` table  
+- Clears all user session IDs in the database (`Users` table) where sessions exist
+- Deletes all active session records from the `session` table  
 - Destroys the current request session
 - Clears session cookies
 - Runs database operations in parallel for better performance
+- Uses optimized queries with WHERE clauses to avoid unnecessary updates
 
 **Example Request:**
 ```javascript
@@ -557,12 +559,16 @@ GET /mbkauthe/test
 
 ### OAuth Endpoints
 
-#### `GET /mbkauthe/api/github/login`
+#### GitHub OAuth
+
+##### `GET /mbkauthe/api/github/login`
 
 Initiates the GitHub OAuth authentication flow.
 
 **Rate Limit:** 10 requests per 5 minutes
 
+**CSRF Protection:** Required (state parameter used for validation)
+
 **Query Parameters:**
 - `redirect` (optional) - Relative URL to redirect after successful authentication (must start with `/` to prevent open redirect attacks)
 
@@ -580,15 +586,16 @@ GET /mbkauthe/api/github/login?redirect=/dashboard
 
 **Workflow:**
 1. User clicks "Login with GitHub"
-2. Redirects to GitHub for authorization
-3. GitHub redirects back to callback URL
-4. System verifies GitHub account is linked
-5. If 2FA enabled, prompts for 2FA
-6. Creates session and redirects to specified URL
+2. CSRF token generated and stored in session
+3. Redirects to GitHub for authorization
+4. GitHub redirects back to callback URL
+5. System verifies GitHub account is linked
+6. If 2FA enabled, prompts for 2FA
+7. Creates session and redirects to specified URL
 
 ---
 
-#### `GET /mbkauthe/api/github/login/callback`
+##### `GET /mbkauthe/api/github/login/callback`
 
 Handles the OAuth callback from GitHub after user authorization.
 
@@ -628,6 +635,104 @@ WHERE ug.github_id = $1
 
 ---
 
+#### Google OAuth
+
+##### `GET /mbkauthe/api/google/login`
+
+Initiates the Google OAuth 2.0 authentication flow.
+
+**Rate Limit:** 10 requests per 5 minutes
+
+**CSRF Protection:** Required (state parameter used for validation)
+
+**Query Parameters:**
+- `redirect` (optional) - Relative URL to redirect after successful authentication (must start with `/` to prevent open redirect attacks)
+
+**Response:** Redirects to Google OAuth authorization page
+
+**Prerequisites:**
+- `GOOGLE_LOGIN_ENABLED=true` in environment
+- Valid `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` configured
+- User's Google account must be linked to an MBKAuth account in `user_google` table
+
+**Example:**
+```
+GET /mbkauthe/api/google/login?redirect=/dashboard
+```
+
+**Workflow:**
+1. User clicks "Login with Google"
+2. CSRF token generated and stored in session
+3. Redirects to Google for authorization
+4. Google redirects back to callback URL
+5. System verifies Google account is linked
+6. If 2FA enabled, prompts for 2FA
+7. Creates session and redirects to specified URL
+
+**Error Responses:**
+- **Configuration Error**: Returns 500 if Google OAuth credentials are not properly configured
+- **Disabled**: Returns 403 if `GOOGLE_LOGIN_ENABLED` is false
+
+---
+
+##### `GET /mbkauthe/api/google/login/callback`
+
+Handles the OAuth callback from Google after user authorization.
+
+**Rate Limit:** Inherited from OAuth rate limiter (10 requests per 5 minutes)
+
+**Query Parameters:**
+- `code` - Authorization code from Google (automatically provided)
+- `state` - State parameter for CSRF protection (automatically provided)
+
+**Response:** 
+- Redirects to 2FA page if 2FA is enabled for the user
+- Redirects to `loginRedirectURL` or stored redirect URL if 2FA is not required
+- Renders error page if authentication fails
+
+**Error Handling:**
+- **Google Not Linked**: Returns error if Google account is not in `user_google` table
+- **Account Inactive**: Returns error if user account is deactivated
+- **Not Authorized**: Returns error if user is not allowed to access the application
+- **Google Auth Error**: Returns error for any OAuth-related failures
+- **Token Error**: Handles expired or invalid OAuth tokens with user-friendly message
+- **CSRF Validation Failed**: Returns 403 if state parameter doesn't match
+
+**Success Flow:**
+```
+Google → /api/google/login/callback 
+  → (CSRF Validation)
+  → (If 2FA enabled) → /mbkauthe/2fa 
+  → (If no 2FA) → loginRedirectURL or stored redirect
+```
+
+**Database Query:**
+```sql
+SELECT ug.*, u."UserName", u."Role", u."Active", u."AllowedApps", u."id" 
+FROM user_google ug 
+JOIN "Users" u ON ug.user_name = u."UserName" 
+WHERE ug.google_id = $1
+```
+
+**Note:** This endpoint is automatically called by Google and should not be accessed directly by users.
+
+---
+
+#### OAuth Security Features
+
+Both GitHub and Google OAuth implementations include:
+
+- **CSRF Protection**: State parameter validation to prevent cross-site request forgery
+- **Session Security**: OAuth state tokens stored in session and validated on callback
+- **Rate Limiting**: 10 requests per 5 minutes to prevent abuse
+- **Token Validation**: Proper handling of expired or invalid OAuth tokens
+- **Redirect Validation**: Only allows relative URLs to prevent open redirect attacks
+- **Account Linking**: Users must pre-link OAuth accounts before login
+- **2FA Integration**: Respects 2FA settings and trusted device configuration
+- **Comprehensive Error Handling**: User-friendly error messages for all failure scenarios
+
+---
+
 ## Middleware Reference
 
 ### `validateSession`

package/docs/db.md

@@ -1,7 +1,7 @@
-# GitHub Login Setup Guide
+# OAuth Login Setup Guide
 
 ## Overview
-This GitHub login feature allows users to authenticate using their GitHub account if it's already linked to their account in the system. Users must first connect their GitHub account through the regular account linking process, then they can use GitHub to log in directly.
+This OAuth login feature allows users to authenticate using their GitHub or Google account if it's already linked to their account in the system. Users must first connect their OAuth account through the regular account linking process, then they can use it to log in directly.
 
 ## Setup Instructions
 
@@ -12,6 +12,10 @@ Add these to your `.env` file:
 # GitHub OAuth App Configuration
 GITHUB_CLIENT_ID=your_github_client_id
 GITHUB_CLIENT_SECRET=your_github_client_secret
+
+# Google OAuth App Configuration
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
 ```
 
 ### 2. GitHub OAuth App Setup
@@ -20,16 +24,26 @@ GITHUB_CLIENT_SECRET=your_github_client_secret
 3. Set the Authorization callback URL to: `https://yourdomain.com/mbkauthe/api/github/login/callback`
 4. Copy the Client ID and Client Secret to your `.env` file
 
-### 3. Database Schema
-Ensure your `user_github` table exists with these columns:
+### 3. Google OAuth App Setup
+1. Go to Google Cloud Console (https://console.cloud.google.com/)
+2. Create a new project or select an existing one
+3. Enable the Google+ API
+4. Go to Credentials > Create Credentials > OAuth 2.0 Client ID
+5. Set the application type to "Web application"
+6. Add authorized redirect URI: `https://yourdomain.com/mbkauthe/api/google/login/callback`
+7. Copy the Client ID and Client Secret to your `.env` file
+
+### 4. Database Schema
+Ensure your OAuth tables exist with these columns:
 
 ```sql
+-- GitHub users table
 CREATE TABLE user_github (
     id SERIAL PRIMARY KEY,
     user_name VARCHAR(50) REFERENCES "Users"("UserName"),
     github_id VARCHAR(255) UNIQUE,
     github_username VARCHAR(255),
-    access_token VARCHAR(255),
+    access_token TEXT,
     created_at TimeStamp WITH TIME ZONE DEFAULT NOW(),
     updated_at TimeStamp WITH TIME ZONE DEFAULT NOW()
 );
@@ -37,57 +51,98 @@ CREATE TABLE user_github (
 -- Add indexes for performance optimization
 CREATE INDEX IF NOT EXISTS idx_user_github_github_id ON user_github (github_id);
 CREATE INDEX IF NOT EXISTS idx_user_github_user_name ON user_github (user_name);
+
+-- Google users table
+CREATE TABLE user_google (
+    id SERIAL PRIMARY KEY,
+    user_name VARCHAR(50) REFERENCES "Users"("UserName"),
+    google_id VARCHAR(255) UNIQUE,
+    google_email VARCHAR(255),
+    access_token TEXT,
+    created_at TimeStamp WITH TIME ZONE DEFAULT NOW(),
+    updated_at TimeStamp WITH TIME ZONE DEFAULT NOW()
+);
+
+-- Add indexes for performance optimization
+CREATE INDEX IF NOT EXISTS idx_user_google_google_id ON user_google (google_id);
+CREATE INDEX IF NOT EXISTS idx_user_google_user_name ON user_google (user_name);
 ```
 
 ## How It Works
 
-### Login Flow
-1. User clicks "Login with GitHub" on the login page
-2. User is redirected to GitHub for authentication
-3. GitHub redirects back to `/mbkauthe/api/github/login/callback`
-4. System checks if the GitHub ID exists in `user_github` table
+### Login Flow (GitHub/Google)
+1. User clicks "Login with GitHub" or "Login with Google" on the login page
+2. User is redirected to the OAuth provider for authentication
+3. Provider redirects back to `/mbkauthe/api/{provider}/login/callback`
+4. System checks if the OAuth ID exists in the respective `user_{provider}` table
 5. If found and user is active/authorized:
    - If 2FA is enabled, redirect to 2FA page
    - If no 2FA, complete login and redirect to home
 6. If not found, redirect to login page with error
 
 ### Account Linking
-Users must first link their GitHub account through your existing GitHub connection system (likely in user settings) before they can use GitHub login.
+Users must first link their OAuth account through your existing connection system (likely in user settings) before they can use OAuth login.
 
 ## API Routes Added
 
-### `/mbkauthe/api/github/login`
+### GitHub Routes
+
+#### `/mbkauthe/api/github/login`
 - **Method**: GET
 - **Description**: Initiates GitHub OAuth flow
 - **Redirects to**: GitHub authorization page
 
-### `/mbkauthe/api/github/login/callback`
+#### `/mbkauthe/api/github/login/callback`
 - **Method**: GET
 - **Description**: Handles GitHub OAuth callback
 - **Parameters**: `code` (from GitHub), `state` (optional)
 - **Success**: Redirects to home page or configured redirect URL
 - **Error**: Redirects to login page with error parameter
 
+### Google Routes
+
+#### `/mbkauthe/api/google/login`
+- **Method**: GET
+- **Description**: Initiates Google OAuth flow
+- **Redirects to**: Google authorization page
+
+#### `/mbkauthe/api/google/login/callback`
+- **Method**: GET
+- **Description**: Handles Google OAuth callback
+- **Parameters**: `code` (from Google), `state` (optional)
+- **Success**: Redirects to home page or configured redirect URL
+- **Error**: Redirects to login page with error parameter
+
 ## Error Handling
 
 The system handles various error cases:
-- `github_auth_failed`: GitHub OAuth failed
-- `user_not_found`: GitHub account not linked to any user
+- `github_auth_failed` / `google_auth_failed`: OAuth authentication failed
+- `user_not_found`: OAuth account not linked to any user
+- `account_inactive`: User account is deactivated
+- `not_authorized`: User not authorized for this app
 - `session_error`: Session save failed
 - `internal_error`: General server error
 
 ## Testing
 
+### GitHub Login
 1. Create a test user in your `Users` table
 2. Link a GitHub account to that user using your existing connection system
 3. Try logging in with GitHub using the new login button
 4. Check console logs for debugging information
 
+### Google Login
+1. Create a test user in your `Users` table
+2. Link a Google account to that user using your existing connection system
+3. Try logging in with Google using the new login button
+4. Check console logs for debugging information
+
 ## Login Page Updates
 
 The login page now includes:
 - A "Continue with GitHub" button
-- A divider ("or") between regular and GitHub login
+- A "Continue with Google" button
+- A divider ("or") between regular and OAuth login
 - Proper styling that matches your existing design
 
 ## Security Notes
@@ -96,7 +151,7 @@ The login page now includes:
 - App authorization is checked (same as regular login)
 - 2FA is respected if enabled
 - Session management is handled the same way as regular login
-- GitHub access tokens are stored securely
+- OAuth access tokens are stored securely
 
 ## Troubleshooting
 

package/docs/env.md

@@ -230,16 +230,18 @@ DEVICE_TRUST_DURATION_DAYS=30  # 30 days (convenience)
 
 ---
 
-## 🐙 GitHub OAuth Authentication
+## 🔐 OAuth Authentication
 
-### GitHub Login Configuration
+### GitHub OAuth Authentication
+
+#### GitHub Login Configuration
 ```env
 GITHUB_LOGIN_ENABLED=false
 GITHUB_CLIENT_ID=your-github-client-id
 GITHUB_CLIENT_SECRET=your-github-client-secret
 ```
 
-#### GITHUB_LOGIN_ENABLED
+##### GITHUB_LOGIN_ENABLED
 **Description:** Enables or disables GitHub OAuth login functionality.
 
 **Values:**
@@ -248,7 +250,7 @@ GITHUB_CLIENT_SECRET=your-github-client-secret
 
 **Required:** Yes (if using GitHub authentication)
 
-#### GITHUB_CLIENT_ID
+##### GITHUB_CLIENT_ID
 **Description:** OAuth application client ID from GitHub.
 
 - **Purpose:** Identifies your application to GitHub's OAuth service
@@ -258,7 +260,7 @@ GITHUB_CLIENT_SECRET=your-github-client-secret
 
 **Example:** `GITHUB_CLIENT_ID=Iv1.a1b2c3d4e5f6g7h8`
 
-#### GITHUB_CLIENT_SECRET
+##### GITHUB_CLIENT_SECRET
 **Description:** OAuth application client secret from GitHub.
 
 - **Purpose:** Authenticates your application with GitHub's OAuth service
@@ -269,7 +271,7 @@ GITHUB_CLIENT_SECRET=your-github-client-secret
 
 **Example:** `GITHUB_CLIENT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0`
 
-### Setting Up GitHub OAuth
+#### Setting Up GitHub OAuth
 
 1. **Create GitHub OAuth App:**
    - Go to [GitHub Developer Settings](https://github.com/settings/developers)
@@ -277,7 +279,7 @@ GITHUB_CLIENT_SECRET=your-github-client-secret
    - Fill in application details:
      - **Application name:** Your app name
      - **Homepage URL:** `https://yourdomain.com` (or `http://localhost:3000` for dev)
-     - **Authorization callback URL:** `https://yourdomain.com/auth/github/callback`
+     - **Authorization callback URL:** `https://yourdomain.com/mbkauthe/api/github/login/callback`
    - Click "Register application"
 
 2. **Copy Credentials:**
@@ -291,10 +293,91 @@ GITHUB_CLIENT_SECRET=your-github-client-secret
    GITHUB_CLIENT_SECRET=your-copied-client-secret
    ```
 
-**Security Notes:**
+---
+
+### Google OAuth Authentication
+
+#### Google Login Configuration
+```env
+GOOGLE_LOGIN_ENABLED=false
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+```
+
+##### GOOGLE_LOGIN_ENABLED
+**Description:** Enables or disables Google OAuth login functionality.
+
+**Values:**
+- `true` - Enable Google login (users can authenticate via Google)
+- `false` - Disable Google login (default)
+
+**Required:** Yes (if using Google authentication)
+
+##### GOOGLE_CLIENT_ID
+**Description:** OAuth 2.0 client ID from Google Cloud Console.
+
+- **Purpose:** Identifies your application to Google's OAuth service
+- **Format:** String ending in `.apps.googleusercontent.com`
+- **Setup:** Obtain from [Google Cloud Console](https://console.cloud.google.com/)
+- **Required:** Yes (when `GOOGLE_LOGIN_ENABLED=true`)
+
+**Example:** `GOOGLE_CLIENT_ID=123456789-abc123def456.apps.googleusercontent.com`
+
+##### GOOGLE_CLIENT_SECRET
+**Description:** OAuth 2.0 client secret from Google Cloud Console.
+
+- **Purpose:** Authenticates your application with Google's OAuth service
+- **Security:** Keep this secret secure and never commit to version control
+- **Format:** Alphanumeric string provided by Google
+- **Setup:** Generated when creating OAuth credentials in Google Cloud Console
+- **Required:** Yes (when `GOOGLE_LOGIN_ENABLED=true`)
+
+**Example:** `GOOGLE_CLIENT_SECRET=GOCSPX-abc123def456ghi789jkl012mno`
+
+#### Setting Up Google OAuth
+
+1. **Create Google Cloud Project:**
+   - Go to [Google Cloud Console](https://console.cloud.google.com/)
+   - Create a new project or select an existing one
+   - Enable the Google+ API (or People API)
+
+2. **Configure OAuth Consent Screen:**
+   - Navigate to "OAuth consent screen" in the sidebar
+   - Choose "External" user type (or "Internal" for Google Workspace)
+   - Fill in required app information
+   - Add your domain to authorized domains
+   - Save and continue
+
+3. **Create OAuth Credentials:**
+   - Navigate to "Credentials" in the sidebar
+   - Click "Create Credentials" > "OAuth 2.0 Client ID"
+   - Choose "Web application" as application type
+   - Add authorized JavaScript origins:
+     - `https://yourdomain.com`
+     - `http://localhost:3000` (for development)
+   - Add authorized redirect URIs:
+     - `https://yourdomain.com/mbkauthe/api/google/login/callback`
+     - `http://localhost:3000/mbkauthe/api/google/login/callback` (for development)
+   - Click "Create"
+
+4. **Copy Credentials:**
+   - Copy the **Client ID**
+   - Copy the **Client Secret**
+
+5. **Configure Environment:**
+   ```env
+   GOOGLE_LOGIN_ENABLED=true
+   GOOGLE_CLIENT_ID=your-copied-client-id
+   GOOGLE_CLIENT_SECRET=your-copied-client-secret
+   ```
+
+### OAuth Security Notes
+
 - Use separate OAuth apps for development and production environments
 - Rotate client secrets periodically
 - Never expose client secrets in client-side code
+- Ensure callback URLs match exactly with OAuth provider configuration
+- Users must link their OAuth accounts before they can use OAuth login
 
 ---