Use Case 009: Password Reset and Recovery

Overview

Property	Value
Use Case ID	UC-009
Use Case Name	Password Reset and Recovery
Module	Identity Management - User Authentication
Priority	High
Status	Implemented
Version	1.0
Last Updated	January 30, 2026

Description

This use case describes the complete process for users to reset their forgotten passwords and recover access to their accounts. The system provides a secure, time-limited password reset mechanism that includes email verification, token validation, password complexity enforcement, and password history checking to prevent reuse. The process also supports admin-initiated password resets and includes security measures such as rate limiting and abuse detection.

Actors

Actor	Description	Role
User	A registered user who has forgotten their password	Primary
Administrator	System admin who can initiate password resets on behalf of users	Primary
System	Application Manager platform	Supporting
Email Service	SMTP or AWS SES for sending reset emails	Supporting
Security Monitor	Automated system monitoring for abuse patterns	Supporting

Preconditions

Application Manager is running and accessible
Email service (SMTP or AWS SES) is configured and operational
User account exists and is not locked or deleted
Password reset token expiration time is configured (default: 1 hour)
Password complexity requirements are defined
Password history tracking is enabled (last 5 passwords)
Rate limiting rules are configured

Postconditions

Success Postconditions

User's password is updated in the Identity database
All existing user sessions are invalidated (forced logout)
Password reset token is marked as used and invalidated
Password history is updated with new hashed password
Confirmation email sent to user
User can authenticate with new password
Activity logged in audit trail with timestamp and IP address

Failure Postconditions

Password not changed if validation fails
Invalid or expired tokens logged as security events
Rate limit violations logged and monitored
Multiple failed attempts trigger account security review
User notified of security events via email

Triggers

User clicks "Forgot Password" link on login page
User requests password reset via API
Administrator initiates password reset for user
User's account is flagged for mandatory password change
Security system detects suspicious activity requiring password reset

Basic Flow (Happy Path)

sequenceDiagram actor User participant Web as Web UI participant API as Application Manager API participant DB as Identity Database participant Email as Email Service participant Cache as Token Cache User->>Web: Click "Forgot Password" Web->>User: Display password reset request form User->>Web: Enter email address Web->>API: POST /api/v1/auth/password-reset/request API->>DB: Find user by email DB->>API: User found API->>API: Check rate limits (email) API->>API: Generate secure reset token (GUID) API->>API: Set token expiration (now + 1 hour) API->>DB: Store PasswordResetToken record DB->>API: Token saved API->>Cache: Store token in cache (1 hour TTL) Cache->>API: Cached API->>Email: Send password reset email with token link Email->>User: Reset email delivered API->>Web: 200 OK (generic success message) Web->>User: "If account exists, reset email sent" Note over User,Email: User checks email User->>Email: Click reset link Email->>Web: GET /reset-password?token=xyz Web->>API: GET /api/v1/auth/password-reset/validate-token?token=xyz API->>Cache: Check token in cache alt Token in cache Cache->>API: Token valid else Token not in cache API->>DB: Query token from database DB->>API: Token found and valid end API->>Web: 200 OK (token valid) Web->>User: Display new password form User->>Web: Enter new password (2x for confirmation) Web->>API: POST /api/v1/auth/password-reset/complete API->>API: Validate password complexity API->>DB: Get user's password history DB->>API: Last 5 password hashes API->>API: Check new password against history API->>API: Hash new password (bcrypt) API->>DB: Update user password API->>DB: Add to password history API->>DB: Mark reset token as used API->>DB: Invalidate all user sessions DB->>API: Password updated successfully API->>Cache: Invalidate token from cache API->>Email: Send password change confirmation Email->>User: Confirmation email delivered API->>Web: 200 OK (password reset complete) Web->>User: "Password reset successful. Please login." Web->>User: Redirect to login page User->>Web: Login with new password Web->>API: POST /api/v1/auth/login API->>DB: Validate credentials DB->>API: Authentication successful API->>Web: Session created Web->>User: Redirect to dashboard

Detailed Steps

User Requests Password Reset
- User navigates to login page
- User clicks "Forgot Password" link
- System displays password reset request form with email input
User Provides Email Address
- User enters email address associated with account
- User submits form
- Web UI sends request to API
System Validates Request
- Check email format is valid
- Check rate limits for this email address (max 5 requests per hour)
- Check rate limits for requesting IP (max 10 requests per hour)
- If rate limited, return generic success message (don't reveal rate limit to attacker)
System Looks Up User
- Query database for user by email address
- If user not found, return generic success message (don't reveal user existence)
- If user found, proceed to token generation
System Generates Reset Token
- Generate cryptographically secure token (GUID/UUID v4)
- Calculate expiration timestamp: now + 1 hour
- Ensure token is unique (check against existing active tokens)
System Stores Reset Token
- Create PasswordResetToken record with:
  - Token value (hashed for storage)
  - User ID
  - Expiration timestamp
  - Created timestamp
  - IsUsed = false
  - IP address of requester
- Store in database
- Cache token for fast validation (1 hour TTL)
System Sends Reset Email
- Compose email with:
  - Password reset link containing token
  - Token expiration time (1 hour)
  - Security notice about not sharing the link
  - Link to contact support if not requested
- Send via configured email provider
- Log email delivery attempt
System Returns Success Response
- Return 200 OK with generic message
- Message: "If an account exists with that email, a password reset link has been sent."
- This prevents email enumeration attacks
User Receives Reset Email
- User checks email inbox (and spam folder if needed)
- User reviews reset email and security notice
- User clicks password reset link within 1 hour
System Validates Reset Token
- Extract token from URL query parameter
- Check token in cache for fast validation
- If not in cache, query database
- Verify token is not expired
- Verify token is not already used
- Verify token matches stored hash
- If valid, display password reset form
- If invalid/expired, display error and offer to request new token
User Enters New Password
- User enters new password
- User confirms new password (must match)
- User submits form
System Validates New Password
- Check password meets complexity requirements:
  - Minimum 12 characters
  - At least 1 uppercase letter
  - At least 1 lowercase letter
  - At least 1 number
  - At least 1 special character
- Verify password confirmation matches
- Retrieve user's password history (last 5 hashes)
- Hash new password using bcrypt
- Compare against password history
- If password was used recently, reject with error message
System Updates Password
- Hash new password using bcrypt (work factor 12)
- Update user's PasswordHash field
- Add new hash to password history
- Mark reset token as used (IsUsed = true)
- Set TokenUsedAt timestamp
- Invalidate all existing user sessions (force logout all devices)
- Clear any cached authentication data
System Sends Confirmation Email
- Compose confirmation email:
  - Notify password was changed successfully
  - Include timestamp and IP address
  - Provide instructions if user didn't initiate change
  - Include link to contact support

Send via email service

System Returns Success Response
- Return 200 OK
- Message: "Password reset successful. Please login with your new password."
- Web UI redirects to login page after 3 seconds
User Logs In with New Password
- User enters email and new password
- System validates credentials
- User gains access to account

Alternative Flows

Alt Flow 1: Reset Token Expired

sequenceDiagram actor User participant Web as Web UI participant API as Application Manager API participant DB as Identity Database User->>Web: Click expired reset link Web->>API: GET /api/v1/auth/password-reset/validate-token?token=xyz API->>DB: Query token DB->>API: Token found but expired API->>Web: 400 Bad Request (token expired) Web->>User: Display error message Web->>User: Show "Request New Reset Link" button User->>Web: Click "Request New Reset Link" Web->>User: Redirect to password reset request form Note over User,Web: User starts over (Basic Flow)

Steps:

User clicks reset link after 1 hour has passed
System validates token and detects expiration
System returns 400 Bad Request with error: "This password reset link has expired. Please request a new one."
Web UI displays error message with option to request new reset
User can click button to return to reset request form
Process restarts from Basic Flow step 1

Alt Flow 2: Invalid or Already Used Token

sequenceDiagram actor User participant Web as Web UI participant API as Application Manager API participant DB as Identity Database participant Security as Security Monitor User->>Web: Click reset link Web->>API: GET /api/v1/auth/password-reset/validate-token?token=invalid API->>DB: Query token alt Token not found DB->>API: No matching token API->>Security: Log potential security event else Token already used DB->>API: Token found, IsUsed=true API->>Security: Log duplicate use attempt end Security->>Security: Check for abuse patterns API->>Web: 400 Bad Request (invalid/used token) Web->>User: Display error message Web->>User: Offer to request new reset link

Steps:

User clicks invalid, tampered, or already-used token link
System attempts to validate token
System detects token is invalid or already used
System logs security event (potential attack)
System returns 400 Bad Request with generic error: "This password reset link is invalid or has already been used."
System checks for patterns of abuse from IP address
User is offered option to request new reset link
Security team is alerted if abuse pattern detected

Alt Flow 3: Password Fails Complexity Validation

flowchart TD A[User submits new password] --> B{Validate complexity} B -->|Too short| C[Return 400: Minimum 12 characters] B -->|No uppercase| D[Return 400: Must contain uppercase letter] B -->|No lowercase| E[Return 400: Must contain lowercase letter] B -->|No number| F[Return 400: Must contain number] B -->|No special char| G[Return 400: Must contain special character] B -->|Same as username| H[Return 400: Cannot contain username] B -->|Common password| I[Return 400: Password too common] B -->|Passwords don't match| J[Return 400: Passwords must match] B -->|Valid| K[Check password history] C --> L[User revises password] D --> L E --> L F --> L G --> L H --> L I --> L J --> L L --> A K --> M{In recent history?} M -->|Yes| N[Return 400: Cannot reuse recent password] M -->|No| O[Proceed with password update] N --> L

Steps:

User submits new password during Basic Flow step 11
System validates password complexity during step 12
System identifies specific validation failure
System returns 400 Bad Request with descriptive error
Web UI displays error message with password requirements
User corrects password and resubmits
Process continues from step 11

Alt Flow 4: Password in History (Reuse Prevention)

sequenceDiagram actor User participant API as Application Manager API participant DB as Identity Database User->>API: POST /api/v1/auth/password-reset/complete (new password) API->>API: Validate password complexity ✓ API->>DB: Get user's password history DB->>API: Return last 5 password hashes API->>API: Hash new password with bcrypt API->>API: Compare against history hashes loop For each historical hash API->>API: bcrypt.compare(newPassword, historicalHash) alt Match found API->>API: Password reuse detected! end end API->>User: 400 Bad Request Note over User,API: "Password was recently used.<br/>Choose a different password." User->>API: Submit different password API->>API: Check against history again API->>User: Password accepted ✓

Steps:

User submits new password that passes complexity validation
System retrieves user's last 5 password hashes from database
System hashes the new password using bcrypt
System compares new hash against each historical hash using bcrypt.compare()
If match found, system rejects password
System returns 400 Bad Request: "This password was recently used. Please choose a different password."
User enters different password
System validates again and proceeds if unique

Alt Flow 5: Rate Limiting Exceeded

sequenceDiagram actor User participant API as Application Manager API participant Cache as Rate Limit Cache participant Security as Security Monitor User->>API: POST /api/v1/auth/password-reset/request (6th attempt in 1 hour) API->>Cache: Check rate limit for email Cache->>API: 5 requests already made in last hour API->>API: Rate limit exceeded API->>Security: Log rate limit violation Security->>Security: Check for attack patterns alt Suspicious pattern detected Security->>Security: Flag IP address for review Security->>Security: Send alert to security team end API->>User: 200 OK (generic success message) Note over User,API: Don't reveal rate limiting<br/>to prevent information disclosure Note over Cache: Reset counter after 1 hour

Steps:

User (or attacker) makes 6th password reset request within 1 hour
System checks rate limit counter in cache
System detects rate limit exceeded
System logs security event with IP address and email
System still returns 200 OK with generic success message (prevents revealing rate limit)
No email is actually sent
Security monitor checks for attack patterns
If suspicious, IP address is flagged and admin is alerted
User must wait 1 hour before next valid request

Alt Flow 6: Admin-Initiated Password Reset

sequenceDiagram actor Admin participant AdminUI as Admin Panel participant API as Application Manager API participant DB as Identity Database participant Email as Email Service actor User Admin->>AdminUI: Search for user account AdminUI->>API: GET /api/v1/admin/users?email=user@example.com API->>DB: Query user DB->>API: User found API->>AdminUI: Display user details Admin->>AdminUI: Click "Reset User Password" AdminUI->>Admin: Confirm action dialog Admin->>AdminUI: Confirm reset AdminUI->>API: POST /api/v1/admin/users/{userId}/password-reset API->>API: Verify admin permissions API->>API: Generate reset token API->>DB: Store reset token API->>DB: Set RequirePasswordChange flag alt Send reset email API->>Email: Send admin-initiated reset email Email->>User: Reset email delivered else Generate temporary password API->>API: Generate temporary password API->>DB: Update user password (temporary) API->>AdminUI: Return temporary password AdminUI->>Admin: Display temporary password Admin->>User: Provide temporary password via secure channel end API->>DB: Log admin action in audit trail API->>AdminUI: 200 OK (reset initiated) AdminUI->>Admin: Display success confirmation Note over User: User must change password on next login

Steps:

Administrator logs into admin panel
Administrator searches for user by email
System displays user account details
Administrator clicks "Reset User Password" button
System prompts for confirmation and reset method
Administrator selects method:
- Option A: Send reset email (preferred)
- Option B: Generate temporary password
If reset email:
- System generates reset token (same as user-initiated)
- Email sent to user with special note about admin reset
- User follows normal reset process
If temporary password:
- System generates strong temporary password
- System updates user's password (marked as temporary)
- System sets RequirePasswordChange = true
- Temporary password displayed to admin once
- Admin provides password to user through secure channel
- User must change password on next login
System logs admin action with timestamp, admin ID, and reason
User receives notification of password reset

Alt Flow 7: Account Locked Due to Security

sequenceDiagram actor User participant API as Application Manager API participant DB as Identity Database participant Security as Security Monitor User->>API: POST /api/v1/auth/password-reset/request API->>DB: Find user by email DB->>API: User found API->>DB: Check account status DB->>API: Account locked (IsLocked=true) API->>Security: Log reset attempt for locked account Security->>Security: Evaluate security context API->>User: 200 OK (generic message) Note over User,API: Don't reveal account is locked Note over User: No email sent Security->>Security: Alert security team if suspicious

Steps:

User requests password reset for locked account
System finds user record but detects IsLocked = true
System logs security event (reset attempt on locked account)
System returns generic success message (don't reveal account status)
No email is sent to user
Security team is notified of locked account access attempt
User must contact support to unlock account
Support verifies identity before unlocking

Business Rules

Rule ID	Description	Enforcement
BR-001	Password reset tokens expire after 1 hour	Token validation logic + database check
BR-002	Password reset tokens can only be used once	Database flag `IsUsed` + validation
BR-003	New passwords must be at least 12 characters long	Password validation
BR-004	Passwords must contain uppercase, lowercase, number, and special character	Regex validation
BR-005	Passwords cannot be reused from last 5 passwords	Password history check with bcrypt
BR-006	Maximum 5 reset requests per email per hour	Rate limiting (cache + database)
BR-007	Maximum 10 reset requests per IP per hour	Rate limiting (cache + database)
BR-008	All existing sessions invalidated when password changes	Session cleanup on password update
BR-009	Password change confirmation email must be sent	Email notification requirement
BR-010	Admin password resets logged in audit trail with admin ID	Audit logging requirement
BR-011	Generic success messages prevent email enumeration	Security requirement
BR-012	Reset tokens must be cryptographically secure (GUID/UUID v4)	Token generation requirement
BR-013	Passwords cannot contain username or email	Password validation
BR-014	Common/breached passwords rejected using dictionary check	Optional validation against common password list
BR-015	Account locked after 10 failed reset attempts in 24 hours	Security lockout mechanism

Data Requirements

PasswordResetToken Schema

{
  "Id": "uuid-v4",
  "UserId": "uuid-v4 (foreign key to Users table)",
  "TokenHash": "string (SHA-256 hash of token)",
  "ExpiresAt": "datetime (UTC, created + 1 hour)",
  "CreatedAt": "datetime (UTC)",
  "IsUsed": "boolean (default: false)",
  "UsedAt": "datetime (UTC, nullable)",
  "RequestIpAddress": "string (IPv4 or IPv6)",
  "UseIpAddress": "string (IPv4 or IPv6, nullable)",
  "UserAgent": "string (optional, browser/device info)"
}

User Password Fields (Updated)

{
  "UserId": "uuid-v4",
  "PasswordHash": "string (bcrypt hash, work factor 12)",
  "PasswordChangedAt": "datetime (UTC)",
  "RequirePasswordChange": "boolean (default: false)",
  "FailedPasswordResetAttempts": "integer (default: 0)",
  "LastPasswordResetRequestAt": "datetime (UTC, nullable)",
  "IsLocked": "boolean (default: false)",
  "LockedAt": "datetime (UTC, nullable)",
  "LockReason": "string (nullable)"
}

PasswordHistory Schema

{
  "Id": "uuid-v4",
  "UserId": "uuid-v4 (foreign key)",
  "PasswordHash": "string (bcrypt hash)",
  "CreatedAt": "datetime (UTC)",
  "ChangedBy": "string (enum: User, Admin, System)"
}

Rate Limit Cache Entry

{
  "Key": "password-reset:{email-or-ip}",
  "RequestCount": "integer",
  "WindowStart": "datetime (UTC)",
  "ExpiresAt": "datetime (UTC, windowStart + 1 hour)"
}

User Interface

Password Reset Request Form

┌─────────────────────────────────────────────────────┐
│  Forgot Your Password?                              │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Enter your email address and we'll send you a     │
│  link to reset your password.                      │
│                                                     │
│  Email Address                                      │
│  ┌─────────────────────────────────────────────┐   │
│  │ your.email@example.com                      │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ┌─────────────────────┐                           │
│  │  Send Reset Link     │                          │
│  └─────────────────────┘                           │
│                                                     │
│  [← Back to Login]                                  │
│                                                     │
└─────────────────────────────────────────────────────┘

Reset Email Sent Confirmation

┌─────────────────────────────────────────────────────┐
│  ✉️  Check Your Email                               │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  If an account exists with that email address,     │
│  we've sent a password reset link.                 │
│                                                     │
│  📧 Check your inbox for an email from:             │
│     noreply@riptide.example.com                    │
│                                                     │
│  ⏰ The reset link expires in 1 hour                │
│                                                     │
│  Didn't receive the email?                          │
│  • Check your spam/junk folder                      │
│  • Wait a few minutes and check again               │
│  • Make sure you entered the correct email          │
│                                                     │
│  [Request Another Reset Link]                       │
│                                                     │
│  [← Back to Login]                                  │
│                                                     │
└─────────────────────────────────────────────────────┘

New Password Entry Form

┌─────────────────────────────────────────────────────┐
│  Reset Your Password                                │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Create a strong password for your account.        │
│                                                     │
│  New Password                                       │
│  ┌─────────────────────────────────────────────┐   │
│  │ ••••••••••••••••                            │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Password Strength: [████████░░] Strong            │
│                                                     │
│  Confirm New Password                               │
│  ┌─────────────────────────────────────────────┐   │
│  │ ••••••••••••••••                            │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ✓ At least 12 characters                          │
│  ✓ Contains uppercase letter                       │
│  ✓ Contains lowercase letter                       │
│  ✓ Contains number                                 │
│  ✓ Contains special character                      │
│  ✗ Not recently used                               │
│                                                     │
│  ┌─────────────────────┐                           │
│  │  Reset Password      │                          │
│  └─────────────────────┘                           │
│                                                     │
│  [Cancel]                                           │
│                                                     │
└─────────────────────────────────────────────────────┘

Password Reset Success

┌─────────────────────────────────────────────────────┐
│  ✅ Password Reset Successful!                      │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Your password has been changed successfully.      │
│                                                     │
│  🔒 For security, all devices have been logged out. │
│                                                     │
│  You can now login with your new password.         │
│                                                     │
│  ┌─────────────────────┐                           │
│  │   Go to Login        │                          │
│  └─────────────────────┘                           │
│                                                     │
│  Redirecting in 3 seconds...                       │
│                                                     │
└─────────────────────────────────────────────────────┘

Token Expired Error

┌─────────────────────────────────────────────────────┐
│  ⚠️  Reset Link Expired                             │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  This password reset link has expired.             │
│                                                     │
│  ⏰ Reset links are valid for 1 hour only           │
│                                                     │
│  For security reasons, you'll need to request      │
│  a new password reset link.                        │
│                                                     │
│  ┌─────────────────────────┐                       │
│  │  Request New Reset Link  │                      │
│  └─────────────────────────┘                       │
│                                                     │
│  [← Back to Login]                                  │
│                                                     │
└─────────────────────────────────────────────────────┘

Admin Password Reset Panel

┌─────────────────────────────────────────────────────┐
│  Admin: Reset User Password                        │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  User: john.doe@example.com                        │
│  User ID: 550e8400-e29b-41d4-a716-446655440000     │
│  Status: Active                                     │
│                                                     │
│  Reset Method:                                      │
│  ○ Send password reset email (Recommended)         │
│  ○ Generate temporary password                     │
│                                                     │
│  Reason for Reset:                                  │
│  ┌─────────────────────────────────────────────┐   │
│  │ User requested password reset via support   │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Options:                                           │
│  ☑ Require password change on next login           │
│  ☑ Invalidate all existing sessions                │
│  ☐ Send notification email to user                 │
│                                                     │
│  ⚠️  This action will be logged in the audit trail │
│                                                     │
│  ┌─────────────────────┐  [Cancel]                 │
│  │  Reset Password      │                          │
│  └─────────────────────┘                           │
│                                                     │
└─────────────────────────────────────────────────────┘

Email Templates

Password Reset Request Email

Subject: Reset Your Riptide Password

From: Riptide Support <noreply@riptide.example.com>
To: {{userEmail}}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Password Reset Request

Hello {{userName}},

We received a request to reset the password for your Riptide account.

To reset your password, click the link below:

┌─────────────────────────────────────────────────────┐
│  RESET MY PASSWORD                                  │
│  {{resetUrl}}?token={{resetToken}}                  │
└─────────────────────────────────────────────────────┘

⏰ This link expires in 1 hour (at {{expirationTime}})

🔒 Security Tips:
• Never share this link with anyone
• We will never ask for your password via email
• If you didn't request this reset, please ignore this email

If the button doesn't work, copy and paste this URL into your browser:
{{resetUrl}}?token={{resetToken}}

Need Help?
If you didn't request this password reset or need assistance,
please contact our support team:
📧 support@riptide.example.com
📞 1-800-RIPTIDE

Best regards,
The Riptide Team

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This is an automated message. Please do not reply to this email.

Request Details:
• Time: {{requestTime}} UTC
• IP Address: {{requestIp}}
• Browser: {{userAgent}}

Password Reset Confirmation Email

Subject: Your Riptide Password Was Changed

From: Riptide Security <security@riptide.example.com>
To: {{userEmail}}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Password Changed Successfully

Hello {{userName}},

This email confirms that your Riptide account password was changed 
successfully.

Change Details:
• Time: {{changeTime}} UTC
• IP Address: {{changeIp}}
• Location: {{geoLocation}}
• Device: {{deviceInfo}}

🔒 All existing sessions have been logged out for security.

⚠️  DIDN'T MAKE THIS CHANGE?

If you did not authorize this password change, your account may 
have been compromised. Take these steps immediately:

1. Click here to secure your account:
   {{securityUrl}}

2. Contact our security team:
   📧 security@riptide.example.com
   📞 1-800-RIPTIDE (24/7)

Security Recommendations:
✓ Use a unique password for Riptide
✓ Enable two-factor authentication
✓ Regularly review account activity
✓ Never share your password with anyone

Best regards,
The Riptide Security Team

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This is an automated security notification. Please do not reply.

Admin-Initiated Reset Email

Subject: Administrator Reset Your Riptide Password

From: Riptide Admin <admin@riptide.example.com>
To: {{userEmail}}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Admin Password Reset

Hello {{userName}},

A system administrator has initiated a password reset for your 
Riptide account.

Reason: {{resetReason}}

To set your new password, click the link below:

┌─────────────────────────────────────────────────────┐
│  RESET MY PASSWORD                                  │
│  {{resetUrl}}?token={{resetToken}}                  │
└─────────────────────────────────────────────────────┘

⏰ This link expires in 1 hour (at {{expirationTime}})

🔒 For security, all existing sessions have been logged out.

Admin Details:
• Admin: {{adminName}} ({{adminEmail}})
• Time: {{resetTime}} UTC
• Ticket: {{ticketNumber}}

If you have questions about this password reset, please contact
the administrator or our support team.

📧 support@riptide.example.com
📞 1-800-RIPTIDE

Best regards,
The Riptide Team

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Request ID: {{requestId}}

API Endpoints

Request Password Reset

Endpoint: POST /api/v1/auth/password-reset/request

Authentication: None (public endpoint)

Rate Limiting: 5 requests per email per hour, 10 requests per IP per hour

Request Body:

{
  "email": "user@example.com"
}

Success Response: 200 OK

{
  "message": "If an account exists with that email, a password reset link has been sent.",
  "requestId": "req-12345"
}

Notes:

Always returns 200 OK even if email not found (prevents enumeration)
No details about whether email exists in system
No indication if rate limit was hit

Error Response: 400 Bad Request (invalid input only)

{
  "error": "ValidationError",
  "message": "Invalid email format",
  "field": "email"
}

Validate Reset Token

Endpoint: GET /api/v1/auth/password-reset/validate-token

Authentication: None (public endpoint)

Query Parameters:

token (required): The reset token from email link

Success Response: 200 OK

{
  "valid": true,
  "expiresAt": "2026-01-30T12:30:00Z",
  "timeRemaining": "45 minutes"
}

Error Responses:

400 Bad Request - Token expired

{
  "error": "TokenExpired",
  "message": "This password reset link has expired. Please request a new one.",
  "valid": false
}

400 Bad Request - Token invalid or used

{
  "error": "InvalidToken",
  "message": "This password reset link is invalid or has already been used.",
  "valid": false
}

Complete Password Reset

Endpoint: POST /api/v1/auth/password-reset/complete

Authentication: None (token provides authentication)

Request Body:

{
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "newPassword": "MySecureP@ssw0rd2026",
  "confirmPassword": "MySecureP@ssw0rd2026"
}

Success Response: 200 OK

{
  "success": true,
  "message": "Password reset successful. You can now login with your new password.",
  "sessionsInvalidated": 3
}

Error Responses:

400 Bad Request - Validation error

{
  "error": "ValidationError",
  "message": "Password does not meet complexity requirements",
  "errors": {
    "newPassword": [
      "Password must be at least 12 characters",
      "Password must contain at least one special character"
    ]
  }
}

400 Bad Request - Password confirmation mismatch

{
  "error": "ValidationError",
  "message": "Passwords do not match",
  "field": "confirmPassword"
}

400 Bad Request - Password in history

{
  "error": "PasswordReuseError",
  "message": "This password was recently used. Please choose a different password.",
  "hint": "You cannot reuse any of your last 5 passwords"
}

400 Bad Request - Token expired or invalid

{
  "error": "InvalidToken",
  "message": "This password reset link is invalid or has expired."
}

Admin: Initiate User Password Reset

Endpoint: POST /api/v1/admin/users/{userId}/password-reset

Authentication: Required (Admin role)

Authorization: AdminRole required

Path Parameters:

userId: UUID of user to reset password for

Request Body:

{
  "method": "email",
  "reason": "User requested password reset via support ticket #12345",
  "requirePasswordChange": true,
  "invalidateSessions": true,
  "sendNotification": true
}

Method Options:

email: Send password reset email (preferred)
temporary: Generate temporary password

Success Response: 200 OK

For method: email:

{
  "success": true,
  "method": "email",
  "message": "Password reset email sent to user",
  "emailSentTo": "user@example.com",
  "resetTokenExpiresAt": "2026-01-30T12:30:00Z",
  "auditLogId": "audit-550e8400"
}

For method: temporary:

{
  "success": true,
  "method": "temporary",
  "message": "Temporary password generated",
  "temporaryPassword": "Temp-P@ssw0rd-2026-XyZ",
  "requirePasswordChange": true,
  "note": "This password is shown once. User must change on next login.",
  "auditLogId": "audit-550e8401"
}

Error Responses:

403 Forbidden - Insufficient permissions

{
  "error": "Forbidden",
  "message": "Admin role required to reset user passwords"
}

404 Not Found - User not found

{
  "error": "NotFound",
  "message": "User not found",
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Get Password Reset History (Admin)

Endpoint: GET /api/v1/admin/users/{userId}/password-reset-history

Authentication: Required (Admin role)

Authorization: AdminRole required

Query Parameters:

limit (optional): Max records to return (default: 50, max: 100)
offset (optional): Pagination offset (default: 0)

Success Response: 200 OK

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "totalResets": 5,
  "resets": [
    {
      "id": "reset-001",
      "requestedAt": "2026-01-30T10:00:00Z",
      "requestIpAddress": "192.168.1.100",
      "completedAt": "2026-01-30T10:15:00Z",
      "useIpAddress": "192.168.1.100",
      "method": "user_initiated",
      "status": "completed"
    },
    {
      "id": "reset-002",
      "requestedAt": "2026-01-25T14:30:00Z",
      "requestIpAddress": "192.168.1.50",
      "completedAt": null,
      "method": "user_initiated",
      "status": "expired"
    },
    {
      "id": "reset-003",
      "requestedAt": "2026-01-20T09:00:00Z",
      "requestIpAddress": "10.0.0.1",
      "completedAt": "2026-01-20T09:05:00Z",
      "method": "admin_initiated",
      "adminId": "admin-123",
      "adminEmail": "admin@riptide.example.com",
      "reason": "User locked out",
      "status": "completed"
    }
  ]
}

Performance Requirements

Metric	Target	Critical Threshold
Password reset request processing	< 500ms	< 2 seconds
Token validation (cache hit)	< 50ms	< 200ms
Token validation (cache miss)	< 300ms	< 1 second
Password update transaction	< 1 second	< 3 seconds
Email delivery time	< 30 seconds	< 2 minutes
Password complexity validation	< 100ms	< 500ms
Password history check	< 200ms	< 1 second
Concurrent reset requests supported	200/minute	100/minute
Rate limit check (cache)	< 10ms	< 50ms

Security Considerations

Token Security

Reset tokens must be cryptographically secure (GUID/UUID v4 using CSPRNG)
Tokens stored as SHA-256 hashes in database (never plain text)
Tokens are single-use only (marked as used after successful reset)
Tokens expire after 1 hour (configurable, minimum 15 minutes, maximum 24 hours)
Token generation includes uniqueness check to prevent collisions
Tokens invalidated immediately when used, even if validation fails afterward
Cache tokens with short TTL for performance (1 hour max)

Password Security

Passwords hashed using bcrypt with work factor 12 (minimum 10, recommended 12-14)
Password history maintained for last 5 passwords (configurable 3-10)
Password history uses same hash algorithm (bcrypt) for comparison
Password complexity requirements enforced on client and server
Common/breached password check against known password databases (optional)
Password strength meter displayed in real-time on UI

Rate Limiting

Per-email rate limit: 5 requests per hour (prevents brute force against specific account)
Per-IP rate limit: 10 requests per hour (prevents distributed attacks)
Global rate limit: 1000 requests per minute (prevents DoS)
Rate limit counters stored in Redis/cache for fast access
Rate limit violations logged for security monitoring
Progressive delays: First violation = no delay, subsequent = exponential backoff

Session Management

All user sessions invalidated immediately upon password change
Session tokens stored with password version/timestamp
Old sessions rejected even if technically valid tokens
Force logout across all devices (mobile, web, API clients)
Clear any cached authentication data

Information Disclosure Prevention

Generic success messages (don't reveal if email exists)
Same response time whether email exists or not
Don't reveal account locked status
Don't reveal rate limiting to potential attackers
Error messages don't leak sensitive information

Email Security

Use TLS/SSL for SMTP connections
SPF, DKIM, and DMARC configured for email authentication
Reset links use HTTPS only
Include security warnings in all emails
Email content doesn't include sensitive data
Unsubscribe link included for compliance

Audit Logging

Log all password reset requests (email, IP, timestamp, user-agent)
Log all token validations (success and failure)
Log all password changes (timestamp, IP, method)
Log all admin-initiated resets (admin ID, reason, method)
Log all rate limit violations
Log all token expiration and reuse attempts
Retain logs for minimum 90 days (configurable by compliance requirements)

Abuse Detection

Monitor for patterns:
- Multiple resets from single IP
- Multiple resets for single email
- Token validation without use
- Expired token access patterns
- Abnormal geographic access patterns
Automatic alerts for suspicious activity
Account lockout after 10 failed reset attempts in 24 hours
IP blocking for severe abuse patterns
CAPTCHA challenge after multiple failed attempts (optional)

Admin Security

Admin password resets require MFA verification
Admin actions logged with full audit trail
Temporary passwords are strongly generated (20+ chars, high entropy)
Temporary passwords expire after first use or 24 hours
Admin panel access restricted to specific IP ranges (optional)
Admin actions require reason/justification

Testing Scenarios

Test Case 1: Successful Password Reset Flow

Given: Valid user account with email user@example.com
When: User requests reset, receives email, clicks link, enters valid new password
Then: Password updated, sessions invalidated, confirmation email sent
Verify:

Reset token created in database with 1-hour expiration
Email delivered with valid token link
Token validation returns success
New password passes all complexity checks
New password not in password history
Old password hash added to history
All user sessions deleted
Confirmation email received
User can login with new password
Old password rejected

Test Case 2: Expired Token Handling

Given: Password reset token created more than 1 hour ago
When: User clicks reset link with expired token
Then: Token validation fails with expiration error
Verify:

Token marked as expired in database
Error message displayed: "Reset link has expired"
Option to request new reset link shown
Security event logged
No password change allowed

Test Case 3: Token Reuse Prevention

Given: Password reset token already used successfully
When: User attempts to use same token again
Then: Token validation fails with "already used" error
Verify:

Token marked as IsUsed = true in database
UsedAt timestamp recorded
Error message displayed
Security event logged
Password cannot be changed again

Test Case 4: Password Complexity Validation

Given: User on password reset form
When: User enters password that fails complexity requirements
Then: Specific validation errors displayed
Test Scenarios:

Password too short (< 12 chars): "Minimum 12 characters required"
No uppercase: "Must contain uppercase letter"
No lowercase: "Must contain lowercase letter"
No number: "Must contain number"
No special character: "Must contain special character"
Contains username: "Cannot contain username" Verify:
Each validation rule tested independently
Multiple violations shown together
Password not updated
User remains on form with errors

Test Case 5: Password History Check

Given: User with 5 passwords in history
When: User attempts to reuse any of last 5 passwords
Then: Password rejected with history error
Verify:

New password hashed with bcrypt
Compared against all 5 historical hashes using bcrypt.compare()
Match detected correctly
Error message: "Password recently used"
Suggestion to choose different password
Password not updated
User can submit different password successfully

Test Case 6: Rate Limiting - Email Based

Given: User email user@example.com
When: User requests password reset 6 times in 1 hour
Then: 6th request silently rate limited
Verify:

First 5 requests succeed and send emails
6th request returns success message (generic)
No email sent for 6th request
Rate limit counter incremented in cache
Security event logged
After 1 hour, user can request again

Test Case 7: Rate Limiting - IP Based

Given: IP address 192.168.1.100
When: 11 reset requests from same IP for different emails
Then: 11th request silently rate limited
Verify:

First 10 requests processed normally
11th request returns success but doesn't process
IP rate limit counter in cache
Security monitor alerted
Potential abuse flagged

Test Case 8: Invalid/Tampered Token

Given: User receives reset email
When: User modifies token in URL before clicking
Then: Token validation fails
Verify:

Token not found in database
Error: "Invalid or expired token"
Security event logged
Potential attack flagged
User offered option to request new token

Test Case 9: Email Not Found (Enumeration Prevention)

Given: Email address not registered in system
When: User requests password reset for non-existent email
Then: Generic success message returned
Verify:

Same response as successful request
Same response time (no timing attack)
No email sent
No database record created
Request logged for security monitoring

Test Case 10: Admin-Initiated Reset with Email

Given: Admin logged in with proper permissions
When: Admin initiates password reset for user via email method
Then: Reset email sent to user with admin context
Verify:

Admin permissions validated
Reset token generated
Email sent to user
Email indicates admin-initiated reset
Reason included in email
Admin action logged in audit trail
User receives email and can reset password
RequirePasswordChange flag set if selected

Test Case 11: Admin-Initiated Reset with Temporary Password

Given: Admin logged in with proper permissions
When: Admin generates temporary password for user
Then: Strong temporary password created and displayed once
Verify:

Temporary password is strong (20+ chars, mixed case, numbers, symbols)
Password displayed to admin in UI
User's password updated in database
RequirePasswordChange = true set
All user sessions invalidated
Temporary password works for login
User forced to change password on next login
Admin action logged

Test Case 12: Locked Account Reset Attempt

Given: User account with IsLocked = true
When: User requests password reset
Then: Generic success message, no email sent
Verify:

Account lock status checked
Generic success message returned
No email sent to user
Security event logged
Security team notified
User must contact support to unlock

Test Case 13: Password Reset During Active Session

Given: User currently logged in with active session
When: User completes password reset successfully
Then: All sessions invalidated including current one
Verify:

Password updated
All session records deleted or marked invalid
User's current session terminated
User redirected to login page
User must login with new password
Confirmation email sent

Test Case 14: Email Delivery Failure

Given: SMTP server unavailable
When: User requests password reset
Then: Error handled gracefully
Verify:

Reset token created successfully
Email send attempt fails
Failure logged with details
Generic success message still shown to user
Admin notified of email failure
User can request resend
System retries email delivery (optional)

Test Case 15: Concurrent Password Reset Requests

Given: User submits multiple reset requests rapidly
When: Multiple requests processed concurrently
Then: All requests handled correctly
Verify:

Each request gets unique token
No token collisions
Rate limiting applied correctly
All requests logged
Latest token is valid
Previous tokens remain valid until expiration

Test Case 16: Security Questions (Alternative Flow)

Given: Security questions enabled for account
When: User requests password reset
Then: Security questions presented before reset
Verify:

User must answer security questions
Correct answers required to proceed
Incorrect answers limit (3 attempts)
Account locked after failed attempts
Success allows password reset
Failure logged and monitored

Test Case 17: Mobile Device Reset Flow

Given: User on mobile device
When: User completes password reset
Then: Mobile-optimized experience provided
Verify:

Forms responsive and mobile-friendly
Password visibility toggle works
Password strength meter displays correctly
Success/error messages readable
Redirects work on mobile browsers
Deep links work (if native app)

Test Case 18: Password Confirmation Mismatch

Given: User entering new password
When: Password and confirmation don't match
Then: Validation error displayed
Verify:

Error shown immediately (client-side)
Error confirmed on server-side
Specific message: "Passwords do not match"
User can correct without losing progress
Password requirements still visible

Monitoring and Analytics

Key Metrics to Track

Volume Metrics:

Password Reset Requests: Total requests per day/week/month
Successful Resets: Completed password changes
Failed Resets: Failed attempts by reason (expired, invalid, complexity)
Admin-Initiated Resets: Count and method distribution

Performance Metrics:

Request Processing Time: P50, P95, P99 latencies
Token Validation Time: Cache hits vs misses
Email Delivery Time: Time from request to delivery
Password Update Time: Database transaction duration

Security Metrics:

Rate Limit Violations: By email and by IP
Token Reuse Attempts: Potential security events
Expired Token Access: Users clicking old links
Password Complexity Failures: Most common violations
Password History Violations: Reuse attempts
Suspicious Patterns: Multiple resets, geographic anomalies

User Experience Metrics:

Time to Reset: From request to completion
Email Open Rate: Percentage of reset emails opened
Link Click Rate: Percentage who click reset link
Completion Rate: Requests that result in successful reset
Abandonment Points: Where users drop off in process
Mobile vs Desktop: Device-specific success rates

Business Metrics:

Support Tickets Related to Resets: Volume and resolution time
Account Lockouts: Due to reset abuse
Fraud Indicators: Suspicious reset patterns

Alerts and Thresholds

Critical Alerts (Immediate Action Required):

Password reset success rate < 70% for 15 minutes
Email delivery failure rate > 20% for 5 minutes
Database errors during password update
Rate limiting system failure
Mass password reset attempts (> 100/minute from single IP)

Warning Alerts (Review Required):

Password reset request spike (> 300% above baseline)
Email delivery rate < 90% for 1 hour
Token validation failure rate > 15%
Password complexity failure rate > 40%
Abandoned resets > 50% for 1 hour

Security Alerts (Investigation Required):

10+ rate limit violations from single IP in 1 hour
5+ token reuse attempts for single user
20+ password history violations in 1 hour
Geographic anomalies (reset from unusual country)
Admin reset spike (> 50 in 1 hour)
Account lockouts due to reset abuse

Dashboards

Operations Dashboard:

Real-time reset request volume (line chart)
Success vs failure rate (pie chart)
Average completion time (gauge)
Email delivery status (success/failure/pending)
Top failure reasons (bar chart)
Geographic distribution (map)

Security Dashboard:

Rate limit violations (time series)
Suspicious activity alerts (list)
Token reuse attempts (count)
Account lockouts (count)
Failed complexity checks (breakdown)
Admin-initiated resets (audit trail)

User Experience Dashboard:

Funnel visualization (request → email → reset → complete)
Abandonment points (drop-off analysis)
Average time per step
Mobile vs desktop success rates
Browser/device breakdown
User feedback/satisfaction scores

UC-001: Trial User Self-Registration and Access
UC-002: User Login and Session Management
UC-003: User Profile and Settings Management
UC-004: Account Security and Two-Factor Authentication
UC-005: Admin User Management
UC-006: Email Verification and Notification
UC-007: Account Lockout and Security Response
UC-008: Audit Logging and Compliance Reporting
UC-010: Security Questions and Identity Verification

Notes and Assumptions

Email as Primary Channel: Password resets rely entirely on email delivery; alternative channels (SMS, authenticator apps) not currently supported
Single Active Token: Only one reset token active per user at a time; new request invalidates previous token
Session Invalidation: All sessions forcibly terminated on password change for security
No Password Recovery: Old passwords cannot be recovered; only reset to new password
Rate Limiting Philosophy: Prefer silent rate limiting over explicit errors to avoid information disclosure
Token Entropy: UUIDs provide sufficient entropy (122 bits) for security without need for longer tokens
Password History Storage: Bcrypt hashes stored directly; no need for separate salt storage (bcrypt includes salt)
Cache Dependency: Redis or similar required for performant rate limiting; fallback to database acceptable but slower
Email Template Customization: Templates should be customizable per deployment for branding
Compliance: GDPR, CCPA, SOC2 considerations addressed through audit logging and data retention policies
MFA Integration: If 2FA enabled, password reset may require additional verification (future enhancement)
Password Strength Meter: Client-side library (e.g., zxcvbn) used for real-time feedback
Localization: Currently English-only; internationalization planned for future releases
Mobile App Deep Links: Reset links should support deep linking to native mobile apps
Admin Permissions: Password reset capability requires specific admin permission; not all admins have access

Revision History

Version	Date	Author	Changes
1.0	2026-01-30	System Analyst	Initial use case documentation

Document Owner: Platform Security Team
Stakeholders: Product Management, Engineering, Security, Customer Success
Review Cycle: Quarterly or as needed for security updates

Use Case 009: Password Reset and Recovery

Overview

Description

Actors

Preconditions

Postconditions

Success Postconditions

Failure Postconditions

Triggers

Basic Flow (Happy Path)

Detailed Steps

Alternative Flows

Alt Flow 1: Reset Token Expired

Alt Flow 2: Invalid or Already Used Token

Alt Flow 3: Password Fails Complexity Validation

Alt Flow 4: Password in History (Reuse Prevention)

Alt Flow 5: Rate Limiting Exceeded

Alt Flow 6: Admin-Initiated Password Reset

Alt Flow 7: Account Locked Due to Security

Business Rules

Data Requirements

PasswordResetToken Schema

User Password Fields (Updated)

PasswordHistory Schema

Rate Limit Cache Entry

User Interface

Password Reset Request Form

Reset Email Sent Confirmation

New Password Entry Form

Password Reset Success

Token Expired Error

Admin Password Reset Panel

Email Templates

Password Reset Request Email

Password Reset Confirmation Email

Admin-Initiated Reset Email

API Endpoints

Request Password Reset

Validate Reset Token

Complete Password Reset

Admin: Initiate User Password Reset

Get Password Reset History (Admin)

Performance Requirements

Security Considerations

Token Security

Password Security

Rate Limiting

Session Management

Information Disclosure Prevention

Email Security

Audit Logging

Abuse Detection

Admin Security

Testing Scenarios

Test Case 1: Successful Password Reset Flow

Test Case 2: Expired Token Handling

Test Case 3: Token Reuse Prevention

Test Case 4: Password Complexity Validation

Test Case 5: Password History Check

Test Case 6: Rate Limiting - Email Based

Test Case 7: Rate Limiting - IP Based

Test Case 8: Invalid/Tampered Token

Test Case 9: Email Not Found (Enumeration Prevention)

Test Case 10: Admin-Initiated Reset with Email

Test Case 11: Admin-Initiated Reset with Temporary Password

Test Case 12: Locked Account Reset Attempt

Test Case 13: Password Reset During Active Session

Test Case 14: Email Delivery Failure

Test Case 15: Concurrent Password Reset Requests

Test Case 16: Security Questions (Alternative Flow)

Test Case 17: Mobile Device Reset Flow

Test Case 18: Password Confirmation Mismatch

Monitoring and Analytics

Key Metrics to Track

Alerts and Thresholds

Dashboards

Related Use Cases

Notes and Assumptions

Revision History