🔐 OAuth Module

📖 Overview

The OAuth module implements an OAuth 2.0 Authorization Server, enabling third-party applications to securely access DashClicks platform resources on behalf of users. It provides the complete OAuth 2.0 authorization code flow with refresh tokens, scope-based permissions, and multi-account selection.

File Path: internal/api/v1/oauth/

Key Features

• OAuth 2.0 Compliance: Full authorization code grant flow
• Multi-Account Support: Users can choose which account to authorize
• Scope-Based Permissions: Granular access control per application
• Refresh Tokens: Long-lived tokens for background access
• Web UI: Built-in authorization consent screens (EJS templates)
• Basic Auth: Client authentication via HTTP Basic Auth or body parameters
• State Parameter: CSRF protection via state validation

� Directory Structure

oauth/
├── 📄 index.js              - OAuth endpoints (611 lines)
├── 📄 README.md             - Module documentation
├── 📂 views/                - EJS templates for consent UI
│   ├── signin.ejs           - Login page
│   ├── account-list.ejs     - Account selection
│   ├── scopes.ejs           - Permission consent
│   ├── loading.ejs          - Processing screen
│   ├── error.ejs            - Error display
│   └── css.ejs              - Shared styles
└── 📂 controllers/
    └── (handlers if separated)

Note: Main OAuth logic is in index.js - not separated into controllers/services.

�🗄️ Collections Used

api.apps

• Purpose: Registered third-party applications
• Model: shared/models/api-app.js
• Key Fields:
  • _id (String) - Client ID (public identifier)
  • name (String) - Application name
  • client_secret (String, hashed) - Secret key for authentication
  • redirect_uris (Array[String]) - Whitelisted redirect URIs
  • scopes (Array[ObjectId]) - Allowed permission scopes
  • active (Boolean) - Production vs development mode
  • created_by (ObjectId) - Developer account
  • webhook_url (String) - Event notification endpoint

api.scopes

• Purpose: Define available permission scopes
• Model: shared/models/api-scope.js
• Key Fields:
  • scope (String, unique) - Scope identifier (e.g., 'crm.contacts.read')
  • description (String) - Human-readable explanation
  • category (String) - Grouping (e.g., 'CRM', 'Billing', 'Reports')

Common Scopes:

const SCOPES = [
  'crm.contacts.read',
  'crm.contacts.write',
  'crm.deals.read',
  'crm.deals.write',
  'billing.read',
  'projects.tasks.read',
  'analytics.read',
  'sites.read',
  'sites.write',
];

api.grants

• Purpose: Store authorization codes (short-lived)
• Model: shared/models/api-grant.js
• Key Fields:
  • code (String, unique) - Authorization code (JWT)
  • client_id (String) - Application identifier
  • user_id (ObjectId) - Authorizing user
  • account_id (ObjectId) - Selected account
  • scopes (Array[String]) - Granted permissions
  • redirect_uri (String) - Callback URL
  • expires_at (Date) - Code expiration (10 minutes)
  • used (Boolean) - Prevent code reuse

api.refresh_tokens

• Purpose: Store refresh tokens (long-lived)
• Model: shared/models/api-refresh-token.js
• Key Fields:
  • token (String, unique) - Refresh token (JWT)
  • client_id (String)
  • user_id (ObjectId)
  • account_id (ObjectId)
  • scopes (Array[String])
  • expires_at (Date) - Token expiration (90 days)
  • revoked (Boolean) - Manual revocation

🔄 OAuth 2.0 Authorization Flow

Authorization Code Flow

sequenceDiagram
    participant ThirdParty as Third-Party App
    participant Browser as User Browser
    participant OAuth as OAuth Server
    participant User as User Login
    participant API as DashClicks API

    ThirdParty->>Browser: Redirect to /authorize?client_id=...&redirect_uri=...
    Browser->>OAuth: GET /authorize
    OAuth->>Browser: Show login screen (signin.ejs)

    Browser->>User: Enter credentials
    User->>OAuth: POST /authorize (email, password)
    OAuth->>OAuth: Authenticate user
    OAuth->>Browser: Show account selection (account-list.ejs)

    Browser->>OAuth: Select account
    OAuth->>Browser: Show scope consent (scopes.ejs)

    Browser->>OAuth: Approve scopes
    OAuth->>OAuth: Generate authorization code (JWT)
    OAuth->>Browser: Redirect to redirect_uri?code=xxx&state=xxx

    Browser->>ThirdParty: Deliver authorization code
    ThirdParty->>OAuth: POST /token (code, client_secret)
    OAuth->>OAuth: Validate code & client credentials
    OAuth-->>ThirdParty: { access_token, refresh_token, expires_in }

    ThirdParty->>API: Request with Bearer token
    API->>API: Validate JWT token
    API-->>ThirdParty: Protected resource data

Refresh Token Flow

sequenceDiagram
    participant ThirdParty as Third-Party App
    participant OAuth as OAuth Server
    participant DB as Database

    Note over ThirdParty: Access token expired

    ThirdParty->>OAuth: POST /token (grant_type=refresh_token, refresh_token=xxx)
    OAuth->>DB: Find refresh token
    DB-->>OAuth: { user_id, account_id, scopes }

    OAuth->>OAuth: Validate token not revoked/expired
    OAuth->>OAuth: Generate new access token
    OAuth->>DB: Update last_used timestamp
    OAuth-->>ThirdParty: { access_token, expires_in }

    ThirdParty->>ThirdParty: Store new access token

🔧 Core Endpoints

GET /authorize

Initiates OAuth authorization flow with user consent.

Query Parameters:

{
  response_type: 'code',          // Required: OAuth flow type
  client_id: String,              // Required: App identifier
  redirect_uri: String,           // Required: Callback URL
  scope: String,                  // Optional: Space-separated scopes
  state: String,                  // Recommended: CSRF token
  user_locale: String             // Optional: UI language
}

Process:

1. Validate Client: Check client_id exists and is active
2. Validate Redirect URI: Must be in app's whitelist
3. Render Login Screen: Show signin.ejs template
4. User Authentication: Verify email/password
5. Account Selection: Show account-list.ejs if user has multiple accounts
6. Scope Consent: Display scopes.ejs with requested permissions
7. Generate Code: Create JWT authorization code
8. Redirect: redirect_uri?code=xxx&state=yyy

Error Responses:

// Invalid client_id
redirect_uri?error=unauthorized_client&error_description=Invalid Client ID

// App not active
redirect_uri?error=unauthorized_client&error_description=App is in dev mode

// Missing response_type
redirect_uri?error=invalid_request&state=xxx

// Unsupported response_type
redirect_uri?error=unsupported_response_type&state=xxx

// User denies access
redirect_uri?error=access_denied&state=xxx

POST /token

Exchanges authorization code for access token or refreshes expired token.

Request Body (Authorization Code Grant):

{
  grant_type: 'authorization_code',
  code: String,                    // From /authorize callback
  redirect_uri: String,            // Must match original
  client_id: String,               // Optional if using Basic Auth
  client_secret: String            // Optional if using Basic Auth
}

Request Body (Refresh Token Grant):

{
  grant_type: 'refresh_token',
  refresh_token: String,
  client_id: String,               // Optional if using Basic Auth
  client_secret: String            // Optional if using Basic Auth
}

Authentication:

• HTTP Basic Auth: Authorization: Basic base64(client_id:client_secret)
• Body Parameters: Include client_id and client_secret in body

Success Response:

{
  access_token: String,            // JWT token (expires in 1 hour)
  token_type: 'Bearer',
  expires_in: 3600,                // Seconds until expiration
  refresh_token: String,           // Long-lived token (90 days)
  scope: String                    // Granted scopes
}

Error Responses:

// Invalid authorization code
{ error: 'invalid_grant', error_description: 'Authorization code not found or expired' }

// Invalid client credentials
{ error: 'invalid_client', error_description: 'Client authentication failed' }

// Redirect URI mismatch
{ error: 'invalid_grant', error_description: 'Redirect URI does not match' }

// Revoked refresh token
{ error: 'invalid_grant', error_description: 'Refresh token has been revoked' }

GET /findUsers

Search for users by email (used in authorization flow).

Query Parameters:

{
  email: String,          // User email to search
  limit: Number,          // Results per page (1-50)
  page: Number            // Page number
}

Response:

{
  success: true,
  data: [
    {
      _id: ObjectId,
      email: 'user@example.com',
      name: 'John Doe',
      accounts: [
        { _id: ObjectId, name: 'Main Account', main: true },
        { _id: ObjectId, name: 'Sub Account', main: false }
      ]
    }
  ]
}

🎨 Authorization UI Templates

EJS Views

Location: views/*.ejs

Templates:

1. signin.ejs - Login form

   • Email/password fields
   • Client app name display
   • Branding customization

2. account-list.ejs - Account selection

   • Lists user's accounts
   • Radio button selection
   • Main/sub-account indicators

3. scopes.ejs - Permission consent

   • Requested scope descriptions
   • Approve/deny buttons
   • Privacy policy link

4. loading.ejs - Processing screen

   • Loading animation
   • Status messages

5. error.ejs - Error display

   • Error messages
   • Return to app link

6. css.ejs - Shared styles

Template Variables

res.locals = {
  client_name: 'Third-Party App Name',
  userscope: 'crm.contacts.read crm.deals.read',
  redirect_uri: 'https://app.example.com/callback',
  token: 'jwt_token_for_state',
  base_url: process.env.API_PUBLIC_BASE_URL,
  error: 'Error message if applicable',
};

🔀 Integration Points

API Authentication

Third-party apps use OAuth access tokens to authenticate API requests:

// HTTP Header
Authorization: Bearer <
  access_token >
  // Decoded JWT payload
  {
    type: 'access_token',
    uid: 'user_id',
    account_id: 'account_id',
    parent_account: 'parent_account_id',
    client_id: 'app_client_id',
    scope: 'crm.contacts.read crm.deals.read',
    exp: timestamp,
    iat: timestamp,
  };

Webhook Notifications

Apps can register webhook URLs to receive real-time event notifications:

// api.apps.webhook_url configuration
POST https://app.example.com/webhooks
{
  event: 'contact.created',
  data: { ... },
  account_id: 'xxx',
  timestamp: Date
}

Rate Limiting

OAuth apps subject to rate limits:

• Authorization Requests: 10 per minute per IP
• Token Requests: 100 per hour per client_id
• API Requests: Based on account tier (1000-10000 per hour)

🔐 Security Features

Client Authentication

Basic Auth:

curl -X POST https://api.dashclicks.com/v1/auth/oauth/token \
  -u "client_id:client_secret" \
  -d "grant_type=authorization_code&code=xxx&redirect_uri=..."

Body Parameters:

curl -X POST https://api.dashclicks.com/v1/auth/oauth/token \
  -d "client_id=xxx&client_secret=yyy&grant_type=authorization_code&code=zzz&redirect_uri=..."

Secret Hashing

Client secrets stored as bcrypt hashes:

const { newHash, verifyHash } = require('../utilities/auth');

// On app creation
const hashed_secret = await newHash(client_secret);

// On authentication
const valid = await verifyHash(provided_secret, stored_hash);

State Parameter

CSRF protection via state validation:

// App generates random state
const state = crypto.randomBytes(16).toString('hex');

// Pass to /authorize
const authUrl = `${baseUrl}/authorize?client_id=...&state=${state}`;

// Validate in callback
if (req.query.state !== storedState) {
  throw new Error('State mismatch - possible CSRF attack');
}

Token Expiration

• Authorization Codes: 10 minutes
• Access Tokens: 1 hour
• Refresh Tokens: 90 days

Redirect URI Validation

// Whitelist enforcement
if (!app.redirect_uris.includes(req.query.redirect_uri)) {
  throw new Error('Redirect URI not authorized');
}

// Exact match required (no wildcards)

⚠️ Important Notes

• 🔒 HTTPS Required: All OAuth endpoints require HTTPS in production
• 🔄 Code Single-Use: Authorization codes can only be exchanged once
• 📊 Audit Logging: All token issuance and revocation events logged
• 🌐 CORS Enabled: Cross-origin requests allowed for /token endpoint
• ⏰ Clock Skew: 5-minute tolerance for JWT expiration validation
• 🚫 No Implicit Flow: Only authorization code grant supported
• 🔑 Secret Rotation: Client secrets can be rotated without downtime

🧪 Edge Cases & Special Handling

Case: User Has Multiple Accounts

Handling: Display account selection screen before scope consent

Case: App Requests Unknown Scope

Handling: Filter to intersection of requested and allowed scopes

Case: User Changes Accounts Mid-Flow

Handling: State token includes account_id to prevent switching

Case: Refresh Token Reuse

Handling: Track last_used timestamp, allow reuse within grace period

---

Last Updated: 2025-10-08
Module Path: internal/api/v1/oauth/
Primary File: index.js (611 lines)
OAuth Version: 2.0 (RFC 6749)