Password Management

Endpoints for changing passwords and resetting forgotten passwords.

POST /api/forgot-password

Send a password reset email to a user.

Authentication: Not required

Request Body:

Field	Type	Required	Description
username	string	Yes	Username to reset password for

Example Request:

{
  "username": "admin"
}

Response:

200 OK (no body)

Pre-blocks:

• User lookup
• Validate user is local domain
• Validate user has email address
• Validate user is enabled
• Check if user is not locked
• Rate limit check (5-minute cooldown between requests)
• Email server validation
• Generate reset token
• Session info extraction

Email Sent:

An email is sent to the user's email address containing:

• Password reset link with code embedded
• Manual verification code
• Browser/OS/IP information for security

Error Responses:

• 400 Bad Request - User account is locked, no email server configured, or email send failed
• 200 OK - User doesn't exist, no email, not local domain, or disabled (silent failure for security)

Rate Limiting

Users can only request a password reset once every 5 minutes. Subsequent requests within this window will silently succeed without sending an email.

Silent Failures

To prevent user enumeration attacks, the endpoint returns 200 OK even if the user doesn't exist, lacks an email, or is not a local user. Errors are logged server-side.

---

POST /api/verify-forgot-password

Verify a password reset code (optional step to validate code before reset).

Authentication: Not required

Request Body:

Field	Type	Required	Description
username	string	Yes	Username
code	string	Yes	Reset code from email

Example Request:

{
  "username": "admin",
  "code": "abc123-reset-code"
}

Response:

200 OK if code is valid

Error Responses:

• 400 Bad Request - Invalid or expired code

Side Effects:

Clears the forgotPasswordRequestTime timestamp on success.

---

POST /api/change-password

Change a user's password using a reset code.

Authentication: Not required

Request Body:

Field	Type	Required	Description
username	string	Yes	Username
password	string	Yes	New password
code	string	Yes	Reset code from email

Example Request:

{
  "username": "admin",
  "password": "NewSecureP@ssw0rd",
  "code": "abc123-reset-code"
}

Pre-blocks:

• User lookup
• Tenant lookup (for password strength requirements)
• Token verification
• Password strength validation

Response:

{
  "username": "admin",
  "displayName": "Administrator",
  "email": "admin@example.com",
  "passwordSetAt": "2024-02-09T10:00:00Z",
  "passwordExpiresAt": "2024-05-09T10:00:00Z"
}

Error Responses:

• 400 Bad Request - Invalid or expired code, password doesn't meet strength requirements

Side Effects:

• Updates user's password (hashed)
• Sets passwordSetAt to current time
• Sets passwordExpiresAt based on tenant's passwordResetTime setting

Password Strength

Password strength requirements are defined at the tenant level (passwordStrength setting). Common requirements include minimum length, character variety, and complexity rules.

---

Password Reset Flow

1. Request Reset

   POST /api/forgot-password
   { "username": "admin" }

2. User Receives Email

   • Email contains reset link and verification code
   • Code expires after configured timeout

3. (Optional) Verify Code

   POST /api/verify-forgot-password
   { "username": "admin", "code": "reset-code" }

4. Change Password

   POST /api/change-password
   {
     "username": "admin",
     "password": "NewPassword123!",
     "code": "reset-code"
   }

5. Login with New Password

   POST /api/login/local
   {
     "username": "admin",
     "password": "NewPassword123!"
   }

---

Security Considerations

Rate Limiting

• Password reset requests are limited to once per 5 minutes per user
• Prevents email flooding attacks

Token Expiration

• Reset tokens have a configurable expiration time
• Tokens are single-use and invalidated after successful password change

Password Strength

• Enforced at tenant level via passwordStrength setting
• Validation occurs before password is accepted

Local Users Only

• Password reset is only available for local domain users
• SSO/SAML users must reset passwords through their identity provider

Account Lockout

• Locked accounts cannot reset passwords
• Admin must unlock the account first

Email Requirement

• Users without an email address cannot use password reset
• Contact admin for manual password reset