1.1 Authentication - FatinaAlTaherr/HopeConnect GitHub Wiki

Overview

The Authentication feature provides secure user registration and login capabilities for the HopeConnect application. It implements JWT (JSON Web Token) based authentication to protect API endpoints and manage user sessions. The system handles user registration with role-based access control and validates credentials during login.

Models

User

Represents a user entity in the system.

  • Attributes:
    • email: Unique identifier and username (Primary Key).
    • userName: Full name of the user (String)
    • email: Unique email address used for login (String)
    • password: Securely hashed password (String)
    • phoneNumber: Contact number (String)
    • role: User role (Enum: Role)
    • location: Physical address (optional)

Role

Enum representing user roles in the system.

  • Attributes: ADMIN, USER, DONOR, SPONSOR, ORPHANAGE_OWNER.

Services

AuthenticationService

Handles core authentication business logic.

  • Methods:
    • register(RegisterPayload request): Creates new user account with encoded password and generates JWT token.
    • authenticate(AuthenticationPayload request): Validates credentials and generates JWT token for valid users.

Repositories

UserRepository

Data access for User entity using Spring Data JPA CRUD operations.

  • Includes custom method findByEmail() for authentication purposes

Controllers

AuthenticationController

Handles authentication-related HTTP requests.

  • Endpoints:
    • POST /HopeConnect/api/auth/register: Registers a new user
    • Request Body: RegisterPayload (email, password, fullName, phoneNumber, role).
    • Response: AuthenticationResponse (JWT token)
    • POST /HopeConnect/api/auth/authenticate: Authenticates an existing user
    • Request Body: AuthenticationPayload (email, password)
    • Response: AuthenticationResponse (JWT token)

UserController

Provides user information endpoints (requires authentication).

  • Endpoints:
    • GET /api/users/{email}/role: Retrieves user's role
    • Response: Role enum.
    • GET /api/users/{email}/location: Retrieves user's geographic coordinates
    • Response: Map<String, Float> with latitude/longitude
    • Note: Uses external geocoding service to convert address

Security Configuration

  • The system uses Spring Security with:
  • Password encoding (BCrypt)
  • JWT token generation and validation
  • Role-based authorization
  • Stateless authentication

Payloads

RegisterPayload

  • Fields:
  • email, password, fullName, phoneNumber, role

AuthenticationPayload

  • Fields:
  • email, password

AuthenticationResponse

  • Fields:
  • token: JWT token for authenticated sessions

Flow

  1. User registers via /register endpoint
  2. System validates input, encodes password, saves user, and returns JWT
  3. For login, user authenticates via /authenticate endpoint
  4. System validates credentials and returns JWT if valid
  5. Client includes JWT in Authorization header for subsequent requests
  6. Protected endpoints verify JWT and check authorities

Error Handling

  • 404 for non-existent users
  • 400 for invalid requests
  • 500 for server/geocoding errors
  • Spring Security handles authentication failures