Technical Documentation

Executive Summary

This document is a companion technical documentation for the Live Reference Application described in Section 10: Added Value of the Proposal for Consultancy Services — Senior Web Frontend Developer Consultant (TCIS). It details the end-to-end security architecture implemented for the AfDB enterprise portal: MFA-protected authentication flows, SSO-IDP federation with Google Workspace and Azure AD, OWASP Top 10 hardened frontend middleware, and a fully documented API layer — demonstrating the secure, production-ready web applications that the consultancy engagement will deliver.

The AfDB Reference Application is a modern, security-first enterprise web system designed to manage project data, reporting, and operational workflows for the African Development Bank. This live reference application demonstrates in practice the capabilities described in the consultancy proposal — a working, production-deployed system that evaluators can inspect, interact with, and verify.

The system is built as a microservices architecture with a dedicated Authentication Gateway (Beta Backend) that handles all security concerns, and a Data Service (Core Backend) that serves business logic. Both frontends authenticate exclusively through the hardened gateway.

Login Credentials & URLs

Use these credentials to access the live demo portals. Both portals share the same authentication backend (Beta). Login requires email OTP verification — after entering credentials, check the user's Yopmail inbox for the 6-digit code.

Portal URLs

Demo Accounts

System Architecture

2.1 High-Level Architecture

2.2 Authentication Flow

2.3 Microservices Design — Beta & Core

The platform is built as two separate microservices that work together. AfDB Beta handles identity (who you are), and AfDB Core handles business operations (what you do). This separation of concerns ensures that authentication logic is isolated, independently scalable, and reusable across future services.

Service Comparison

Concrete Examples

2.4 Cross-Service Activity Monitoring (Diagnostic Tool)

Building on the microservices design, the platform includes a real-time activity monitoring system that turns Core into a diagnostic tool for tracking every user action performed through the Beta auth portal. Beta emits structured activity events to Core via an internal API, and Core provides a monitoring dashboard for security analysis and operational awareness.

Tracked Auth Events

Activity Event Schema

Each event emitted by Beta and stored in Core includes the following diagnostic fields:

{
  "action":       "auth.login",           // Event type identifier
  "userId":       "66a1b2c3d4e5f6...",  // User who performed the action
  "userName":     "John Doe",             // Display name
  "userEmail":    "john@afdb.org",        // User email address
  "severity":     "info",                 // info | warning | critical
  "status":       "success",              // success | failure
  "ipAddress":    "192.168.1.42",         // Client IP (from x-forwarded-for)
  "userAgent":    "Mozilla/5.0...",       // Browser/device string
  "source":       "beta",                 // Originating service
  "details":      { "role": "admin" },    // Arbitrary extra context
  "createdAt":    "2026-08-29T10:30:00Z"  // Timestamp (auto)
}

Monitoring Dashboard Features

The Core frontend at localhost:3001/monitoring provides a full diagnostic interface:

Activity API Endpoints

Technology Stack

3.1 Frontend

3.2 Backend

3.3 Infrastructure

Security Implementation: MFA-Protected Access

4.1 Overview

Multi-Factor Authentication (MFA) adds a critical second layer of verification beyond passwords. Users must provide both something they know (password) and something they have (authenticator app or backup code).

4.2 TOTP Implementation

4.3 Backup Codes

4.4 MFA API Endpoints

4.5 MFA User Flow

Email OTP Verification

5.1 Overview

The platform implements email-based One-Time Password (OTP) verification across all authentication flows — login, registration, and password reset. Every user who logs in must verify their identity via a 6-digit code sent to their email address, providing a robust second factor that doesn't require a separate authenticator app.

5.2 OTP Architecture

5.3 Authentication Flows with OTP

Login Flow (Email OTP as 2FA)

Registration Flow (Email Verification)

Password Reset Flow

5.4 Professional Email Templates

OTP emails use professional, branded HTML templates with the AfDB logo embedded via CID (Content-ID) attachment. Each purpose has a distinct accent color and messaging:

5.5 Frontend OTP UX

The OTP verification component provides a polished user experience:

• 6 individual input fields — One per digit, auto-focus advancement
• Paste support — Users can paste a full 6-digit code (e.g., from email); digits are distributed across fields automatically
• Countdown timer — 10:00 minute countdown matching the Redis TTL, displayed below the OTP fields
• Color-coded expiry — Gray (normal) → Orange (≤2 min remaining) → Red (expired)
• Auto-disable on expiry — Verify button disabled when code expires; message prompts to resend
• Resend functionality — New code sent, timer resets to 10:00
• Auto-verify — When all 6 digits are entered, verification is submitted automatically

5.6 Retrieving OTP During Testing (Yopmail)

The demo environment uses Yopmail as the email provider for testing. Yopmail is a disposable email service that allows anyone to view the inbox of any @yopmail.com address without a password.

5.7 OTP API Endpoints

5.8 SMTP Configuration

Email delivery is configured via environment variables in the Beta Backend:

SMTP_HOST=smtp.hostinger.com
SMTP_PORT=465
SMTP_USER=no-reply@atradezone.ca
SMTP_PASSWORD=<smtp-password>
SMTP_FROM=no-reply@atradezone.ca

Security Implementation: SSO-IDP Federation

6.1 Overview

Single Sign-On (SSO) federation allows users to authenticate through their organization's existing identity provider without managing separate credentials. This implementation follows the OAuth 2.0 Authorization Code Flow.

6.2 Supported Identity Providers

6.3 Security Measures

6.4 SSO API Endpoints

6.5 SSO Authentication Sequence

Security Implementation: OWASP Top 10 Compliance

7.1 Compliance by Category

A01: Broken Access Control

A02: Cryptographic Failures

A03: Injection

A04: Insecure Design

A05: Security Misconfiguration

A07: Identification & Authentication

A09: Logging & Monitoring

7.2 Security Middleware Stack

The middleware stack is ordered for defense-in-depth. Each layer processes the request before it reaches the route handler:

Verified HTTP Response Headers

X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'...
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=(), interest-cohort=()
Cache-Control: no-store
X-XSS-Protection: 1; mode=block

API Reference

8.1 Interactive API Documentation (Scalar)

The Beta Backend provides a modern, interactive API documentation powered by Scalar. This allows you to explore, test, and understand all available endpoints directly from your browser.

8.2 System Services & Ports

The AfDB platform consists of four services that work together in a microservices architecture:

8.3 Service Communication Flow

8.4 Authentication Endpoints

8.5 MFA Endpoints

8.6 SSO Endpoints

Testing Scenarios & Results

9.1 Authentication Tests

9.2 MFA Tests

9.3 SSO Tests

9.4 Security Tests

9.5 Frontend UX Tests

Deployment Architecture

10.1 Required Environment Variables

# Server
PORT=4000
NODE_ENV=production
MONGODB_URI=mongodb://host:27018/afdb_beta
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT Secrets (use strong 256-bit random values)
JWT_ACCESS_SECRET=<256-bit-random-secret>
JWT_REFRESH_SECRET=<256-bit-random-secret>
JWT_ACCESS_EXPIRY=30m
JWT_REFRESH_EXPIRY=30d

# CORS
CORS_ORIGINS=https://portal.afdb.org,https://core.afdb.org

# SSO — Google OAuth2
GOOGLE_CLIENT_ID=<google-oauth-client-id>
GOOGLE_CLIENT_SECRET=<google-oauth-client-secret>
GOOGLE_REDIRECT_URI=https://api.afdb.org/api/v1/sso/callback/google

# SSO — Microsoft / Azure AD
MICROSOFT_CLIENT_ID=<azure-ad-client-id>
MICROSOFT_CLIENT_SECRET=<azure-ad-client-secret>
MICROSOFT_TENANT_ID=<azure-tenant-id>
MICROSOFT_REDIRECT_URI=https://api.afdb.org/api/v1/sso/callback/microsoft

# Frontend
FRONTEND_URL=https://portal.afdb.org

# SMTP (Email OTP Delivery)
SMTP_HOST=smtp.afdb.org
SMTP_PORT=465
SMTP_USER=noreply@afdb.org
SMTP_PASSWORD=<smtp-password>
SMTP_FROM=noreply@afdb.org

10.2 Production Readiness Checklist

• Set strong JWT_ACCESS_SECRET and JWT_REFRESH_SECRET (min 256-bit)
• Configure MongoDB with authentication and TLS/SSL
• Enable Redis persistence and authentication
• Set NODE_ENV=production
• Configure TLS/SSL certificates for all endpoints
• Set up Google and/or Microsoft OAuth2 credentials
• Configure CORS_ORIGINS with production domains
• Enable MongoDB audit logging
• Set up log aggregation (Winston → centralized logging platform)
• Configure health check monitoring on /health
• Configure SMTP credentials for email OTP delivery
• Set up alerting for account lockout events
• Run security penetration testing before go-live

Compliance Matrix

11.1 OWASP Top 10 (2021) — Full Coverage

11.2 Password Policy (OWASP-Compliant)

Appendices

Appendix A: User Data Model

{
  email:            String (unique, indexed)
  passwordHash:     String (bcrypt, 12 rounds)
  firstName:        String
  lastName:         String
  role:             Enum ['admin', 'staff', 'viewer']
  mfaEnabled:       Boolean (default: false)
  mfaSecret:        String (TOTP secret)
  mfaBackupCodes:   [{ codeHash: String, used: Boolean }]
  ssoProvider:      String ('google' | 'microsoft')
  ssoId:            String (provider's user ID)
  isActive:         Boolean (default: true)
  loginAttempts:    Number (default: 0)
  lockUntil:        Date
  lastLogin:        Date
  passwordChangedAt: Date
  createdAt:        Date (auto)
  updatedAt:        Date (auto)
}

Appendix B: Token Lifecycle

Appendix C: Security Event Log Examples

INFO  User created: admin@afdb.org
INFO  MFA secret generated for user: 6a91c08b...
INFO  MFA backup codes generated for user: 6a91c08b...
INFO  MFA backup code used for user: 6a91c08b...
WARN  Login attempt on locked account: admin@afdb.org
WARN  Account locked due to 5 failed attempts: admin@afdb.org
INFO  SSO: auto-provisioning user for user@org.com via google
INFO  All tokens revoked for user: 6a91c08b...
INFO  Password changed for user: 6a91c08b...

Appendix D: Demo Credentials

All demo accounts use @yopmail.com email addresses. After logging in with credentials, you will receive a 6-digit OTP via email. Visit https://yopmail.com and enter the username (e.g., afdbadmin) to check the inbox and retrieve the OTP code.