Password Reset Feature

Relevant source files

The following files were used as context for generating this wiki page:

• Controllers/Login/UserController.cs
• Service/user/UserService.cs
• Models/ForgotPasswordRequest.cs
• Models/User.cs
• Migrations/20250108150417_AddResetTokenToUser.cs
• Migrations/UserDBContextModelSnapshot.cs
• Configuration/UserConfiguration.cs

The Password Reset feature provides a mechanism for users to securely regain access to their accounts if they have forgotten their password. The process is initiated by the user providing their email address. A unique, time-sensitive reset token is then generated and sent to that email. The user can then use this token to set a new password.

This feature is implemented through a two-step process exposed via the API. The first step handles the request for a password reset token, and the second validates the token and updates the user's password. The User data model is extended with specific fields to manage the reset token and its expiration.

Data Model and Schema

The core of the password reset functionality relies on additions to the User entity. Two nullable fields, ResetToken and ResetTokenExpiration, are added to store the token and its validity period.

Sources: Models/User.cs:11-12, Migrations/20250108150417_AddResetTokenToUser.cs:13-21

User Entity ER Diagram

The following diagram shows the structure of the User table, including the fields for password reset.

User Table Fields

The fields related to the password reset feature are detailed below.

Field	Type	Constraints	Description
ResetToken	string?	Nullable	Stores the unique token for password reset.
ResetTokenExpiration	DateTime?	Nullable	Stores the date and time when the token will expire.

Sources: Models/User.cs:11-12, Migrations/20250108150417_AddResetTokenToUser.cs:13-21

Database Migration

The AddResetTokenToUser migration adds the ResetToken (nvarchar(max), nullable) and ResetTokenExpiration (datetime2, nullable) columns to the User table in the database.

Sources: Migrations/20250108150417_AddResetTokenToUser.cs:11-22

API Endpoints

The feature is exposed through two POST endpoints in the UserController.

Sources: Controllers/Login/UserController.cs:126-198

1. Forgot Password Request

This endpoint initiates the password reset process. It generates a reset token, saves it to the user's record, and sends it to the user's email.

• Endpoint: POST /api/v1/user/forgot-password
• Description: Takes a user's email, generates a reset token valid for 1 hour, and sends it via email.
• Request Body: ForgotPasswordRequest

Parameter	Type	Description
Email	string	The user's email address.

Sources: Controllers/Login/UserController.cs:126-151, Models/ForgotPasswordRequest.cs:3-6

2. Reset Password

This endpoint completes the process. It validates the token and updates the user's password.

• Endpoint: POST /api/v1/user/reset-password
• Description: Resets the user's password if the provided token is valid and not expired. The token is cleared after a successful reset.
• Request Body: ResetPasswordRequest

Parameter	Type	Description
Email	string	The user's email address.
Token	string	The reset token received via email.
NewPassword	string	The user's desired new password.

Sources: Controllers/Login/UserController.cs:153-198, Models/ForgotPasswordRequest.cs:8-13

Workflow and Logic

The password reset logic is orchestrated by UserController and implemented within UserService.

Forgot Password Sequence

This diagram illustrates the flow for requesting a password reset token.

Reset Password Sequence

This diagram shows the flow for setting a new password using the token.

Service Implementation

The UserService class contains the core logic for the password reset feature.

Sources: Service/user/UserService.cs

Key Methods

• GetUserByEmailAsync(string email): Retrieves a user from the database based on their email address.
  Sources: Service/user/UserService.cs:115-118
• UpdateUserAsync(User user): Persists changes to a User entity in the database. This is used to save the reset token and later to update the password and clear the token.
  Sources: Service/user/UserService.cs:100-113
• SendResetPasswordEmailAsync(string email, string resetToken): Sends an email to the user containing the reset token. It uses SmtpClient with Gmail's SMTP server. The credentials and server details are hardcoded.
  Sources: Service/user/UserService.cs:120-144

Token Generation and Expiration

When a user requests a password reset, the following actions occur in UserController:

1. A new Guid is generated and converted to a string to serve as the resetToken.
2. The user's ResetToken property is set to this new value.
3. The ResetTokenExpiration is set to DateTime.UtcNow.AddHours(1), making the token valid for one hour.
4. _userService.UpdateUserAsync(user) is called to save these changes.

Sources: Controllers/Login/UserController.cs:136-141

Password and Token Update

During the final reset step, after successful token validation:

1. The user's Password is updated to the NewPassword from the request.
2. The ResetToken and ResetTokenExpiration fields are set to null to invalidate the token after use.
3. _userService.UpdateUserAsync(user) is called to persist the new password and the cleared token fields.

Sources: Controllers/Login/UserController.cs:178-185