Skip to content

EMAIL_VERIFICATION_GUIDE.md

Latest commit

 

History

History
231 lines (170 loc) · 6.19 KB

EMAIL_VERIFICATION_GUIDE.md

File metadata and controls

231 lines (170 loc) · 6.19 KB
Raw

Email Verification System - Complete Guide

✅ Feature Status: FULLY IMPLEMENTED

The email verification system for student registration is now active and working.

How It Works

1. Student Registration Flow

Student signs up → Account created (verified=false) → Verification email sent → Student clicks link → Account verified → Can login

2. What Happens Behind the Scenes

On Signup:

  • Student enters: firstName, lastName, email (@guc.edu.eg), password, student ID, role
  • Server creates user with verified: false
  • Server generates a JWT token (valid for 24 hours)
  • Server sends email with verification link to student's email
  • Server also stores the email in the database (UserEmail model)

Verification Email Contains:

  • Verification link: http://localhost:5001/api/auth/verify?token=<JWT>
  • When clicked, this link:
    1. Validates the token
    2. Sets user.verified = true
    3. Redirects to: http://localhost:3000/login?verified=1
    4. Login page shows success message

On Login Attempt:

  • If user is NOT verified → Login fails with: "Account not verified. Check your email."
  • If user IS verified → Login succeeds normally

Testing the Feature

Method 1: With Real Email (Recommended)

  1. Start the server and client:

    # Terminal 1 - Server
cd C:\Users\Khaled\VibeCoderz\server
npm run dev

# Terminal 2 - Client  
cd C:\Users\Khaled\VibeCoderz\client
npm run dev

  2. Open browser: http://localhost:3000/signup

  3. Register a new student with your real @guc.edu.eg email

  4. Check your email inbox for verification email from mohamedkhaledvp@gmail.com

  5. Click the verification link in the email

  6. You'll be redirected to login page with success message

  7. Login with your credentials - should work!

Method 2: Without Email (Database Testing)

If you don't want to use real email, you can get the verification link from the database:

cd C:\Users\Khaled\VibeCoderz\server
node scripts/getLastEmail.js student@guc.edu.eg

This will print the stored email including the verification URL. Copy the URL and paste it in your browser.

Email Configuration

Current setup uses Gmail:

The system automatically uses these credentials to send emails.

API Endpoints

POST /api/auth/signup

Creates new user account and sends verification email.

Request:

{
  "firstName": "Ahmed",
  "lastName": "Hassan", 
  "email": "ahmed.hassan@guc.edu.eg",
  "password": "secure123",
  "id": "58-1234",
  "role": "student"
}

Response (Student):

{
  "message": "student signed up successfully",
  "token": "...",
  "user": {
    "email": "ahmed.hassan@guc.edu.eg",
    "verified": false,
    ...
  }
}

GET /api/auth/verify?token=

Verifies user email and redirects to login.

What it does:

  1. Validates JWT token
  2. Finds user by ID from token
  3. Sets user.verified = true
  4. Redirects to: http://localhost:3000/login?verified=1

POST /api/auth/login

Standard login - requires verified account for students.

Error if not verified:

{
  "error": "Account not verified. Check your email."
}

Files Modified

Server

  • ✅ server/controllers/authController.js - Added verification logic
  • ✅ server/routes/auth.js - Added GET /verify route
  • ✅ server/utils/emailService.js - Enabled SMTP email sending

Client

  • ✅ client/src/components/auth/SignupForm.jsx - Shows verification message
  • ✅ client/src/components/auth/LoginForm.jsx - Shows verified success message
  • ✅ client/src/services/authService.js - Uses relative /api paths

Scripts

  • ✅ server/scripts/getLastEmail.js - Helper to fetch stored emails
  • ✅ server/scripts/findUser.js - Helper to check user status

Verification Email Template

The email sent to students looks like this:

Subject: Verify your GUC Events account

Hello Ahmed,

Please verify your email by clicking the link below:

[Verify Email]

This link will expire in 24 hours. If the link does not work, 
copy-paste this URL into your browser:
http://localhost:5001/api/auth/verify?token=eyJhbGc...

After verification you will be redirected to the login page.

Environment Variables Used

# Server Port
PORT=5001

# Database
MONGODB_URI=mongodb+srv://...

# JWT Secret (for verification tokens)
JWT_SECRET=yourSuperSecretKey

# Email Configuration (Gmail)
EMAIL_USER=mohamedkhaledvp@gmail.com
EMAIL_PASSWORD=leos dcrd fzda yaww

# Optional: Override defaults
CLIENT_URL=http://localhost:3000
SERVER_BASE_URL=http://localhost:5001

Security Features

  • ✅ Verification tokens expire in 24 hours
  • ✅ Tokens are signed with JWT_SECRET
  • ✅ Users cannot login until verified
  • ✅ Emails stored in database for audit trail
  • ✅ Password hashed with bcrypt

User States

Role Auto-Verified Requires Email Verification
Student ❌ No ✅ Yes
Staff ❌ No ⚠️ Admin verification required
TA ❌ No ⚠️ Admin verification required
Professor ❌ No ⚠️ Admin verification required
Events Office ✅ Yes ❌ No
Admin ✅ Yes ❌ No

Troubleshooting

Email not received?

  1. Check spam/junk folder
  2. Verify EMAIL_USER and EMAIL_PASSWORD in .env
  3. Check server logs for email sending errors
  4. Use Method 2 to get verification link from database

"Account not verified" error on login?

  • User hasn't clicked verification link yet
  • Check if email was sent (check server logs)
  • Use scripts/getLastEmail.js to get verification link manually

Token expired?

  • Verification links expire after 24 hours
  • User needs to request new verification email (feature can be added if needed)

Next Steps (Optional Enhancements)

Want to add more features? Here are some ideas:

  1. Resend Verification Email - Add endpoint to resend verification
  2. Custom Email Templates - Better HTML email design
  3. Email Notifications - Send emails for other events (password reset, etc.)
  4. Verification Page - Show nice HTML page before redirecting to login

Let me know if you want any of these!