A robust and secure Node.js Express server providing complete user authentication functionality including registration, login, logout, password reset, and session validation with JWT tokens and OAuth integration.
- 🔐 User Registration - Secure account creation with password hashing
- 🔑 User Login - JWT-based authentication with HTTPOnly cookies
- 🚪 User Logout - Secure session termination with token blacklisting
- ✅ Session Validation - Middleware for protected routes
- 🔄 Password Reset - Email-based password recovery system
- 🌐 OAuth Integration - Google OAuth with Passport.js
- 🛡️ Security Features - Rate limiting, CORS, input validation
- 🐳 Docker Support - Containerized deployment ready
- 🧪 Comprehensive Testing - 87%+ test coverage with Jest
Before you begin, ensure you have met the following requirements:
- Node.js >= 16.0.0 and npm installed
- MongoDB running locally or remotely (MongoDB Atlas recommended)
- Git for version control
- Google OAuth Credentials (optional, for OAuth features)
git clone https://github.com/yunji0387/express-auth-server.git
cd express-auth-servernpm installCreate a .env file in the project root:
# Database
URI=mongodb://localhost:27017/your-database-name
# or for MongoDB Atlas:
# URI=mongodb+srv://username:[email protected]/database-name
# Server Configuration
PORT=5005
NODE_ENV=development
# JWT Configuration
SECRET_ACCESS_TOKEN=your-super-secret-jwt-key-here
# Google OAuth (Optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
# Email Configuration (for password reset)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
[email protected]
EMAIL_PASS=your-app-passwordnpm startThe server will start running on http://localhost:5005
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage-
Build the Docker image:
docker build -t express-auth-server . -
Run with Docker Compose (recommended):
# Create docker-compose.yml with MongoDB service docker-compose up -d -
Or run the container directly:
docker run -p 5005:5005 --env-file .env express-auth-server
Note: Ensure your .env file is properly configured before running with Docker.
http://localhost:5005
- URL:
/auth/register - Method:
POST - Content-Type:
application/json
Request Body:
{
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"password": "SecurePassword123!"
}Success Response: 201 Created
{
"status": "success",
"data": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]"
},
"message": "Your account has been successfully created."
}Error Response: 400 Bad Request
{
"error": {
"status": "failed",
"message": "It seems you already have an account, please log in instead."
}
}- URL:
/auth/login - Method:
POST - Content-Type:
application/json
Request Body:
{
"email": "[email protected]",
"password": "SecurePassword123!"
}Success Response: 200 OK + JWT cookie set
{
"status": "success",
"data": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]"
},
"message": "You have successfully logged in."
}Error Response: 401 Unauthorized
{
"error": {
"status": "failed",
"message": "Invalid email or password. Please try again with the correct credentials."
}
}- URL:
/auth/logout - Method:
GET - Authentication: Required (JWT cookie)
Success Response: 200 OK
{
"status": "success",
"message": "You have successfully logged out."
}- URL:
/auth/verify - Method:
GET - Authentication: Required (JWT cookie)
Success Response: 200 OK
{
"status": "success",
"message": "You are authenticated."
}Error Response: 401 Unauthorized
{
"error": {
"status": "failed",
"message": "Access denied. No valid token provided."
}
}- URL:
/auth/user - Method:
GET - Authentication: Required (JWT cookie)
Success Response: 200 OK
{
"status": "success",
"data": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]"
}
}- Runtime: Node.js (>= 16.0.0)
- Framework: Express.js
- Database: MongoDB with Mongoose
- Authentication: JWT + Passport.js (Google OAuth)
- Security: bcrypt, CORS, cookie-parser
- Testing: Jest with 87%+ coverage
- Container: Docker & Docker Compose
- Environment: dotenv for configuration
├── config/
│ ├── index.js # Passport configuration
│ └── __tests__/ # Config tests
├── controllers/
│ ├── auth.js # Authentication logic
│ └── __tests__/ # Controller tests
├── middleware/
│ ├── validate.js # Input validation
│ ├── verify.js # JWT verification
│ └── __tests__/ # Middleware tests
├── models/
│ ├── User.js # User schema
│ ├── Blacklist.js # Token blacklist
│ └── __tests__/ # Model tests
├── routes/
│ ├── auth.js # Auth routes
│ └── index.js # Route exports
├── views/
│ └── reset-password.ejs # Password reset template
├── public/
│ └── assets/ # Static files
├── .env.example # Environment template
├── server.js # Application entry point
├── Dockerfile # Docker configuration
└── package.json # Dependencies & scripts
This project includes comprehensive test coverage:
# Run all tests
npm test
# Run tests with coverage report
npm run test:coverage
# Run specific test file
npm test -- auth.test.jsCurrent Coverage: Run npm run test:coverage to view the latest coverage report.
We welcome contributions! Please follow these steps:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Ensure tests pass:
npm test - Commit your changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Submit a Pull Request
Please read CONTRIBUTING.md for detailed guidelines.
This project is licensed under the MIT License - see the LICENSE.md file for details.
- Bug Reports: Create an issue
- Feature Requests: Request a feature
- Questions: GitHub Discussions
- Express.js community for the robust framework
- MongoDB team for the excellent database solution
- Passport.js for authentication strategies
- Jest team for the testing framework
⭐ If this project helped you, please consider giving it a star!