Authentication

Overview

The Med Agenda API provides role-based authentication for three distinct user types:

Patients - End users scheduling and managing medical appointments
Doctors - Medical professionals managing consultations and diagnoses
Administrators - System administrators with elevated privileges

Each user type has its own authentication endpoint and credential validation system.

How Authentication Works

The authentication system uses email and password credentials with the following security measures:

Password Encryption: All passwords are hashed using BCrypt algorithm before storage
Credential Validation: Email and password are verified against the database
Response Handling: Returns success message or 401 error for invalid credentials

The current implementation uses basic authentication. For production environments, consider implementing JWT tokens or session-based authentication for enhanced security.

Authentication Flow

Patient Authentication

Endpoint: POST /patients/login Source: PatientController.java:24-31 Authenticates a patient user and grants access to patient-specific functionality.

Request

string

required

Patient’s registered email address

password

string

required

Patient’s password (will be verified against BCrypt hash)

Example Request

curl -X POST http://localhost:8080/patients/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123"
  }'

Success Response

Status Code: 200 OK

"Login successful!"

Error Response

Status Code: 401 Unauthorized

"Invalid email or password."

Implementation Details

The patient authentication process:

Receives login request with email and password
Calls PatientService.authenticatePatient(email, password)
Service queries database for patient with matching email
Verifies password using BCrypt password encoder
Returns Optional<Patient> - present if credentials valid, empty otherwise

Doctor Authentication

Endpoint: POST /doctor/login Source: DoctorController.java:29-36 Authenticates a doctor user and grants access to medical professional functionality.

Request

string

required

Doctor’s registered email address

password

string

required

Doctor’s password (will be verified against BCrypt hash)

Example Request

curl -X POST http://localhost:8080/doctor/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "doctorSecure456"
  }'

Success Response

Status Code: 200 OK

"Login successful!"

Error Response

Status Code: 401 Unauthorized

"Invalid email or password."

Implementation Details

The doctor authentication process:

Receives login request with email and password
Calls DoctorService.authenticateDoctor(email, password)
Service queries database for doctor with matching email
Verifies password using BCrypt password encoder
Returns Optional<Doctor> - present if credentials valid, empty otherwise

Administrator Authentication

Endpoint: POST /admin/login Source: AdminController.java:23-30 Authenticates an administrator user and grants access to system administration functionality.

Request

string

required

Administrator’s registered email address

password

string

required

Administrator’s password (will be verified against BCrypt hash)

Example Request

curl -X POST http://localhost:8080/admin/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "adminSecure789"
  }'

Success Response

Status Code: 200 OK

"Login successful!"

Error Response

Status Code: 401 Unauthorized

"Invalid email or password."

Implementation Details

The admin authentication process:

Receives login request with email and password
Calls AdminService.authenticateAdmin(email, password)
Service queries database for admin with matching email
Verifies password using BCrypt password encoder
Returns Optional<Admin> - present if credentials valid, empty otherwise

Session Management

The current implementation does not include session management or token generation. Each request is stateless.

Recommended Enhancements

For production deployments, consider implementing:

JWT Tokens: Issue JSON Web Tokens upon successful authentication
Session Storage: Store active sessions with expiration times
Refresh Tokens: Implement token refresh mechanism for long-lived sessions
Role-Based Access Control: Enforce permissions based on user roles

Example JWT Implementation (Recommended)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "type": "Bearer",
  "expiresIn": 3600,
  "user": {
    "id": "uuid-here",
    "email": "[email protected]",
    "role": "PATIENT"
  }
}

Security Considerations

Password Security

All passwords are encrypted using BCrypt hashing algorithm configured in SecurityConfig.java:27-29:

@Bean
public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
}

Key Features:

One-way hashing (passwords cannot be decrypted)
Salt generation for each password
Adaptive hashing (computational cost increases over time)

HTTPS Requirement

Always use HTTPS in production to encrypt credentials during transmission. The current configuration allows HTTP for local development only.

CORS Configuration

Cross-Origin Resource Sharing is configured in WebConfig.java:12-18 to allow requests from:

http://localhost:5173 (development frontend)
https://final-project-poo2.vercel.app (production frontend)

Allowed methods: GET, POST, PUT, DELETE, OPTIONS

CSRF Protection

CSRF protection is disabled (SecurityConfig.java:16) to support stateless API requests. This is acceptable for token-based authentication but should be reconsidered if implementing session-based authentication.

Error Handling

Common Authentication Errors

Error	Status Code	Description
Invalid credentials	`401 Unauthorized`	Email or password is incorrect
Missing fields	`400 Bad Request`	Email or password not provided
Account not found	`401 Unauthorized`	No user exists with provided email
Server error	`500 Internal Server Error`	Database or service error

Debugging Authentication Issues

Verify email format: Ensure email is correctly formatted
Check password: Passwords are case-sensitive
Confirm user exists: Verify user was created successfully
Database connectivity: Ensure database connection is active
BCrypt configuration: Verify password encoder bean is properly configured

Testing Authentication

Using cURL

Test patient authentication:

# Successful login
curl -v -X POST http://localhost:8080/patients/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"testpass123"}'

# Expected: 200 OK with "Login successful!"

# Failed login
curl -v -X POST http://localhost:8080/patients/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"wrongpassword"}'

# Expected: 401 Unauthorized with "Invalid email or password."

Using JavaScript/Fetch

const login = async (email, password) => {
  try {
    const response = await fetch('http://localhost:8080/patients/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, password }),
    });

    if (response.ok) {
      const message = await response.text();
      console.log(message); // "Login successful!"
      return true;
    } else {
      const error = await response.text();
      console.error(error); // "Invalid email or password."
      return false;
    }
  } catch (error) {
    console.error('Network error:', error);
    return false;
  }
};

Next Steps

After successful authentication, explore these related API endpoints:

Patient Management

Create and manage patient accounts

Doctor Management

Create and manage doctor profiles

Admin Management

Manage administrator accounts

Consultations

Schedule and manage medical appointments

Patients

Doctors

Consultations

Diagnosis

Admin

CID Management

Health News

AI Assistant

​Overview

​How Authentication Works

​Authentication Flow

​Patient Authentication

​Login Endpoint

​Request

​Example Request

​Success Response

​Error Response

​Implementation Details

​Doctor Authentication

​Login Endpoint

​Request

​Example Request

​Success Response

​Error Response

​Implementation Details

​Administrator Authentication

​Login Endpoint

​Request

​Example Request

​Success Response

​Error Response

​Implementation Details

​Session Management

​Recommended Enhancements

​Example JWT Implementation (Recommended)

​Security Considerations

​Password Security

​HTTPS Requirement

​CORS Configuration

​CSRF Protection

​Error Handling

​Common Authentication Errors

​Debugging Authentication Issues

​Testing Authentication

​Using cURL

​Using JavaScript/Fetch

​Next Steps

Patient Management

Doctor Management

Admin Management

Consultations

Build docs developers (and LLMs) love

Overview

How Authentication Works

Authentication Flow

Patient Authentication

Login Endpoint

Request

Example Request

Success Response

Error Response

Implementation Details

Doctor Authentication

Login Endpoint

Request

Example Request

Success Response

Error Response

Implementation Details

Administrator Authentication

Login Endpoint

Request

Example Request

Success Response

Error Response

Implementation Details

Session Management

Recommended Enhancements

Example JWT Implementation (Recommended)

Security Considerations

Password Security

HTTPS Requirement

CORS Configuration

CSRF Protection

Error Handling

Common Authentication Errors

Debugging Authentication Issues

Testing Authentication

Using cURL

Using JavaScript/Fetch

Next Steps