Password Reset

The IAM service supports two password change flows: self-service password change for authenticated users and admin-initiated password reset for locked or forgotten accounts.

Authenticated users can change their own password by providing their current password and a new one.

Request

curl -X POST http://localhost:8081/api/v1/users/me/password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -H "X-Tenant-ID: 00000000-0000-0000-0000-000000000001" \
  -d '{
    "currentPassword": "OldP@ssw0rd!",
    "newPassword": "NewSecureP@ss123!"
  }'

Request Schema

Response (204 No Content)

Empty response body on success.

Implementation

The PasswordService.changePassword() method:

1. Verifies the current password against the stored hash
2. Validates the new password against the tenant's password policy (minimum length, complexity, history)
3. Checks password history to prevent reuse of recent passwords
4. Hashes the new password with BCrypt and updates the user record
5. Records the password change in PasswordHistory for future reuse checks
6. Updates passwordChangedAt timestamp on the user entity

Administrators can reset any user's password within their tenant. This generates a temporary password that must be changed on first login.

Request

curl -X POST http://localhost:8081/api/v1/users/42/reset-password \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

Response (200 OK)

{
  "temporaryPassword": "Tmp#xK9mQ2pL"
}

Security Considerations

• This endpoint requires ADMIN or PLATFORM_ADMIN role (@PreAuthorize("hasAnyRole('ADMIN', 'PLATFORM_ADMIN')"))
• The temporary password is returned only once in the response -- it is not stored in plain text
• The user's passwordChangedAt is cleared to indicate a forced password change is needed
• An audit log entry is created for compliance tracking

Password Policy Enforcement

The PasswordPolicyService validates passwords against configurable per-tenant rules:

Error Codes