Skip to content

README.md

Latest commit

 

History

History
175 lines (139 loc) · 4.24 KB

README.md

File metadata and controls

175 lines (139 loc) · 4.24 KB
Raw

Auth Service

Authentication microservice for user management with JWT-based session handling using HTTP-only cookies.

Role

The Auth Service manages user authentication and authorization for the entire application. It provides user registration, login/logout functionality, JWT token generation and verification, and role-based access control (RBAC). All authentication requests from the API Gateway are processed by this service.

Technologies

  • Runtime: Node.js 18+
  • Framework: Express.js 4.18
  • Database: CouchDB (NoSQL document store)
  • Authentication: JWT (jwt-simple 0.5.0)
  • Password Hashing: bcrypt.js 2.3.0
  • HTTP Client: Axios 1.6.0
  • Testing: Jest 29.7.0, Supertest 6.3.3
  • Containerization: Docker with multi-stage builds

Key Features

  • User Registration & Login: Secure user account creation with bcrypt password hashing (10 salt rounds)
  • JWT Token Management: Token generation, verification, and automatic expiration (configurable, default 2 hours)
  • HTTP-Only Cookies: Secure token storage preventing XSS attacks
  • Role-Based Access Control: Support for user and admin roles
  • Input Validation: Strict username (3-20 alphanumeric chars) and password rules (8+ chars, uppercase, lowercase, number)
  • Default Admin Account: Automatically creates admin user on startup
  • Health Check: Database connectivity monitoring at /health
  • CouchDB Integration: NoSQL document storage for user data

REST API

POST /register

Register a new user account.

Request Body:

{
  "username": "johndoe",
  "password": "SecurePass123"
}

Response (201):

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "username": "johndoe",
    "role": "user"
  }
}

Validation Rules:

  • Username: 3-20 characters, alphanumeric only
  • Password: Minimum 8 characters, must contain uppercase, lowercase, and number

POST /login

Authenticate user and receive JWT token in HTTP-only cookie.

Request Body:

{
  "username": "johndoe",
  "password": "SecurePass123"
}

Response (200):

{
  "success": true,
  "message": "Login successful",
  "data": {
    "username": "johndoe",
    "role": "user"
  }
}

Cookie Set: authToken (HTTP-only, secure in production, 2-hour expiry)

POST /logout

Clear authentication cookie and end user session.

Headers: X-User-Username (set by API Gateway)

Response (200):

{
  "success": true,
  "message": "Logout successful",
  "data": {
    "username": "johndoe"
  }
}

POST /verify

Validate JWT token and retrieve user information.

Request Body (optional):

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Note: Token can be provided in request body (for service-to-service communication) or automatically extracted from authToken cookie (for user sessions).

Response (200):

{
  "success": true,
  "message": "Token is valid",
  "data": {
    "valid": true,
    "username": "johndoe",
    "role": "user",
    "issuedAt": 1700000000,
    "expiresAt": 1700007200
  }
}

GET /health

Health check endpoint for service monitoring.

Response (200):

{
  "status": "healthy",
  "service": "auth-service",
  "timestamp": "2025-11-14T12:00:00.000Z",
  "checks": {
    "database": true
  }
}

Environment Variables

Key configuration variables (see .env.example):

  • PORT: Server port (default: 80)
  • TOKEN_SECRET: JWT signing secret (MUST be changed in production)
  • TOKEN_EXPIRY: Token validity duration in seconds (default: 7200 = 2 hours)
  • DB_NAME: CouchDB database name
  • DB_HOST, DB_PORT: CouchDB connection details
  • ADMIN_NAME, ADMIN_PASSWORD: Default admin credentials

Error Handling

  • 400 Bad Request: Invalid input or missing required fields
  • 401 Unauthorized: Invalid credentials or expired token
  • 409 Conflict: Username already exists
  • 500 Internal Server Error: Database or server errors

Security Notes

  • Passwords are hashed using bcrypt with 10 salt rounds
  • JWT tokens are stored in HTTP-only cookies to prevent XSS
  • Cookies use secure flag in production (HTTPS only)
  • Token expiration is enforced server-side
  • User roles are validated from database on each verification