fix: add JSON auth/updatePassword endpoint for expired passwords [DHIS2-21120] (2.43) (#24525)

Author: netroms

dhis-2/dhis-api/src/main/java/org/hisp/dhis/user/UserAccountService.java

@@ -35,6 +35,7 @@
 import org.hisp.dhis.common.auth.UserInviteParams;
 import org.hisp.dhis.common.auth.UserRegistrationParams;
 import org.hisp.dhis.feedback.BadRequestException;
+import org.hisp.dhis.feedback.ForbiddenException;
 
 /**
  * Service that handles user account activities, e.g. create/update account. The Validation can be
@@ -83,4 +84,25 @@ void validateUserRegistration(RegistrationParams params, String remoteIpAddress)
    */
   void validateInvitedUser(RegistrationParams params, String remoteIpAddress)
       throws BadRequestException, IOException;
+
+  /**
+   * Self-service change of an <b>expired</b> password. The caller is not logged in, so the method
+   * is self-guarding: it only proceeds for an expired account whose current password is supplied
+   * correctly. It deliberately does not establish a session; once the password is changed the
+   * account is no longer expired, and the caller logs in through the regular login endpoint.
+   *
+   * <p>The current-password check runs <b>before</b> the expiry check, so "Account is not expired"
+   * can only be observed by a caller who already knows the password (no username enumeration), and
+   * repeated attempts against one account are throttled via the shared account-recovery lockout
+   * (mirrors the forgot-password flow).
+   *
+   * @param username username identifying the account
+   * @param oldPassword the current (expired) password
+   * @param newPassword new password, subject to the password policy
+   * @throws BadRequestException when input is missing, credentials are wrong, the account is not
+   *     expired, or the new password is not acceptable
+   * @throws ForbiddenException when the account is temporarily locked due to too many attempts
+   */
+  void updateExpiredPassword(String username, String oldPassword, String newPassword)
+      throws BadRequestException, ForbiddenException;
 }

dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/user/DefaultUserAccountService.java

@@ -37,12 +37,15 @@
 import java.util.Collection;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
 import org.hisp.dhis.common.auth.RegistrationParams;
 import org.hisp.dhis.common.auth.UserInviteParams;
 import org.hisp.dhis.common.auth.UserRegistrationParams;
 import org.hisp.dhis.configuration.ConfigurationService;
 import org.hisp.dhis.feedback.BadRequestException;
+import org.hisp.dhis.feedback.ForbiddenException;
 import org.hisp.dhis.organisationunit.OrganisationUnit;
+import org.hisp.dhis.security.PasswordManager;
 import org.hisp.dhis.security.spring2fa.TwoFactorAuthenticationProvider;
 import org.hisp.dhis.security.spring2fa.TwoFactorWebAuthenticationDetails;
 import org.hisp.dhis.setting.SystemSettingsProvider;
@@ -62,11 +65,20 @@
 @RequiredArgsConstructor
 public class DefaultUserAccountService implements UserAccountService {
 
+  /**
+   * Valid bcrypt hash (of a random string, same cost as the configured encoder) used to spend one
+   * password verification on the unknown-username path of {@link #updateExpiredPassword}, so that
+   * unknown and known usernames respond in similar time (no enumeration via timing).
+   */
+  private static final String TIMING_EQUALIZATION_HASH =
+      "$2a$10$4TXauPu06PhCTK8Up3oHi.0Y7SXLeu8ISJ6jq1GYpaaQOsSL5FOxG"; // NOSONAR not a secret
+
   private final UserService userService;
   private final ConfigurationService configService;
   private final TwoFactorAuthenticationProvider twoFactorAuthProvider;
   private final SystemSettingsProvider settingsProvider;
   private final PasswordValidationService passwordValidationService;
+  private final PasswordManager passwordManager;
 
   @Override
   public void validateUserRegistration(RegistrationParams params, String remoteAddress)
@@ -134,6 +146,85 @@ public void confirmUserInvite(UserInviteParams params, HttpServletRequest reques
     authenticate(user.getUsername(), params.getPassword(), user.getAuthorities(), request);
   }
 
+  @Override
+  @Transactional
+  public void updateExpiredPassword(String username, String oldPassword, String newPassword)
+      throws BadRequestException, ForbiddenException {
+    if (StringUtils.isBlank(username)
+        || StringUtils.isBlank(oldPassword)
+        || StringUtils.isBlank(newPassword)) {
+      throw new BadRequestException("Username, old password and new password are required");
+    }
+
+    User user = userService.getUserByUsername(username);
+    if (user == null) {
+      // Generic message on purpose: do not reveal whether the username exists. Spend one password
+      // verification (result deliberately ignored) so this path takes as long as the known-user
+      // path below and the timing does not reveal it either.
+      passwordManager.matches(oldPassword, TIMING_EQUALIZATION_HASH);
+      throw new BadRequestException("Invalid username or password");
+    }
+
+    // Throttle repeated attempts against a single account (brute-force protection), reusing the
+    // account-recovery lockout. Registers an attempt and rejects once the threshold is exceeded.
+    checkRecoveryLock(user.getUsername());
+
+    // Caller must know the current (expired) password. Checked before the expiry guard below so
+    // that "Account is not expired" can only be observed by someone who knows the password.
+    if (!passwordManager.matches(oldPassword, user.getPassword())) {
+      throw new BadRequestException("Invalid username or password");
+    }
+
+    // This self-service path is ONLY for expired accounts.
+    if (userService.userNonExpired(user)) {
+      throw new BadRequestException("Account is not expired");
+    }
+
+    // The old password was verified against the stored hash above, so plain equality is enough.
+    if (newPassword.equals(oldPassword)) {
+      throw new BadRequestException("New password must be different from the old password");
+    }
+
+    validateNewPassword(user, newPassword);
+
+    userService.encodeAndSetPassword(user, newPassword);
+    userService.updateUser(user, new SystemUser());
+
+    log.info("Expired password updated for user: {}", user.getUsername());
+  }
+
+  /** Rejects a new password that is equal to the username or fails the password policy. */
+  private void validateNewPassword(User user, String newPassword) throws BadRequestException {
+    if (newPassword.trim().equals(user.getUsername().trim())) {
+      throw new BadRequestException("Password cannot be equal to username");
+    }
+
+    PasswordValidationResult result =
+        passwordValidationService.validate(
+            CredentialsInfo.builder()
+                .username(user.getUsername())
+                .password(newPassword)
+                .email(StringUtils.trimToEmpty(user.getEmail()))
+                .newUser(false)
+                .build());
+    if (!result.isValid()) {
+      throw new BadRequestException(result.getErrorMessage());
+    }
+  }
+
+  /** Registers a recovery attempt and rejects once the account has exceeded the allowed rate. */
+  private void checkRecoveryLock(String username) throws ForbiddenException {
+    if (userService.isRecoveryLocked(username)) {
+      throw new ForbiddenException(
+          "The account recovery operation for the given user is temporarily locked due to too "
+              + "many calls to this endpoint in the last '"
+              + UserConstants.RECOVERY_LOCKOUT_MINS
+              + "' minutes. Username:"
+              + username);
+    }
+    userService.registerRecoveryAttempt(username);
+  }
+
   private User validateRestoreLinkAndToken(UserInviteParams params) throws BadRequestException {
     String[] idAndRestoreToken = userService.decodeEncodedTokens(params.getToken());
     String idToken = idAndRestoreToken[0];

dhis-2/dhis-services/dhis-service-core/src/test/java/org/hisp/dhis/user/UserAccountServiceTest.java

@@ -31,6 +31,11 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
 import java.io.IOException;
@@ -40,6 +45,8 @@
 import org.hisp.dhis.common.auth.UserRegistrationParams;
 import org.hisp.dhis.configuration.ConfigurationService;
 import org.hisp.dhis.feedback.BadRequestException;
+import org.hisp.dhis.feedback.ForbiddenException;
+import org.hisp.dhis.security.PasswordManager;
 import org.hisp.dhis.security.spring2fa.TwoFactorAuthenticationProvider;
 import org.hisp.dhis.setting.SystemSettings;
 import org.hisp.dhis.setting.SystemSettingsService;
@@ -59,6 +66,7 @@ class UserAccountServiceTest {
   @Mock private TwoFactorAuthenticationProvider twoFactorAuthProvider;
   @Mock private SystemSettingsService settingsService;
   @Mock private PasswordValidationService passwordValidationService;
+  @Mock private PasswordManager passwordManager;
 
   @BeforeEach
   public void init() {
@@ -68,7 +76,8 @@ public void init() {
             configService,
             twoFactorAuthProvider,
             settingsService,
-            passwordValidationService);
+            passwordValidationService,
+            passwordManager);
   }
 
   @Test
@@ -95,6 +104,116 @@ void failedRecaptchaResponseUserRegTest() throws IOException {
         "Recaptcha validation failed: [invalid challenge received]", exception.getMessage());
   }
 
+  @Test
+  @DisplayName("updateExpiredPassword with unknown username is generic and burns one verification")
+  void updateExpiredPasswordUnknownUserTest() {
+    when(userService.getUserByUsername("ghost")).thenReturn(null);
+
+    BadRequestException exception =
+        assertThrows(
+            BadRequestException.class,
+            () -> userAccountService.updateExpiredPassword("ghost", "Old_pw1!", "New_pw1!"));
+
+    assertEquals("Invalid username or password", exception.getMessage());
+    // The timing-equalization verification must run, so unknown and known usernames respond in
+    // similar time; no recovery attempt is registered for a nonexistent account.
+    verify(passwordManager).matches(eq("Old_pw1!"), anyString());
+    verify(userService, never()).registerRecoveryAttempt(anyString());
+  }
+
+  @Test
+  @DisplayName("updateExpiredPassword rejects a recovery-locked account before checking passwords")
+  void updateExpiredPasswordLockedTest() {
+    User user = expiredPasswordUser();
+    when(userService.getUserByUsername("mia")).thenReturn(user);
+    when(userService.isRecoveryLocked("mia")).thenReturn(true);
+
+    assertThrows(
+        ForbiddenException.class,
+        () -> userAccountService.updateExpiredPassword("mia", "Old_pw1!", "New_pw1!"));
+
+    verify(userService, never()).registerRecoveryAttempt(anyString());
+    verify(passwordManager, never()).matches(anyString(), anyString());
+  }
+
+  @Test
+  @DisplayName("updateExpiredPassword with wrong old password is generic and registers an attempt")
+  void updateExpiredPasswordWrongOldPasswordTest() {
+    User user = expiredPasswordUser();
+    when(userService.getUserByUsername("mia")).thenReturn(user);
+    when(userService.isRecoveryLocked("mia")).thenReturn(false);
+    when(passwordManager.matches("Wrong_pw1!", "encoded-old")).thenReturn(false);
+
+    BadRequestException exception =
+        assertThrows(
+            BadRequestException.class,
+            () -> userAccountService.updateExpiredPassword("mia", "Wrong_pw1!", "New_pw1!"));
+
+    assertEquals("Invalid username or password", exception.getMessage());
+    verify(userService).registerRecoveryAttempt("mia");
+    // Guard order: expiry state must not be consulted before the password is verified, so
+    // "Account is not expired" is only observable by a caller who knows the password.
+    verify(userService, never()).userNonExpired(any(User.class));
+  }
+
+  @Test
+  @DisplayName("updateExpiredPassword rejects a non-expired account")
+  void updateExpiredPasswordNonExpiredTest() {
+    User user = expiredPasswordUser();
+    when(userService.getUserByUsername("mia")).thenReturn(user);
+    when(userService.isRecoveryLocked("mia")).thenReturn(false);
+    when(passwordManager.matches("Old_pw1!", "encoded-old")).thenReturn(true);
+    when(userService.userNonExpired(user)).thenReturn(true);
+
+    BadRequestException exception =
+        assertThrows(
+            BadRequestException.class,
+            () -> userAccountService.updateExpiredPassword("mia", "Old_pw1!", "New_pw1!"));
+
+    assertEquals("Account is not expired", exception.getMessage());
+  }
+
+  @Test
+  @DisplayName("updateExpiredPassword rejects a new password equal to the old one")
+  void updateExpiredPasswordSameAsOldTest() {
+    User user = expiredPasswordUser();
+    when(userService.getUserByUsername("mia")).thenReturn(user);
+    when(userService.isRecoveryLocked("mia")).thenReturn(false);
+    when(passwordManager.matches("Old_pw1!", "encoded-old")).thenReturn(true);
+    when(userService.userNonExpired(user)).thenReturn(false);
+
+    BadRequestException exception =
+        assertThrows(
+            BadRequestException.class,
+            () -> userAccountService.updateExpiredPassword("mia", "Old_pw1!", "Old_pw1!"));
+
+    assertEquals("New password must be different from the old password", exception.getMessage());
+  }
+
+  @Test
+  @DisplayName("updateExpiredPassword sets and persists a valid new password")
+  void updateExpiredPasswordOkTest() throws BadRequestException, ForbiddenException {
+    User user = expiredPasswordUser();
+    when(userService.getUserByUsername("mia")).thenReturn(user);
+    when(userService.isRecoveryLocked("mia")).thenReturn(false);
+    when(passwordManager.matches("Old_pw1!", "encoded-old")).thenReturn(true);
+    when(userService.userNonExpired(user)).thenReturn(false);
+    when(passwordValidationService.validate(any(CredentialsInfo.class)))
+        .thenReturn(PasswordValidationResult.VALID);
+
+    userAccountService.updateExpiredPassword("mia", "Old_pw1!", "New_pw1!");
+
+    verify(userService).encodeAndSetPassword(user, "New_pw1!");
+    verify(userService).updateUser(eq(user), any(SystemUser.class));
+  }
+
+  private User expiredPasswordUser() {
+    User user = new User();
+    user.setUsername("mia");
+    user.setPassword("encoded-old");
+    return user;
+  }
+
   @Test
   @DisplayName("Failed recaptcha response during user invite throws an exception")
   void failedRecaptchaResponseUserInviteTest() throws IOException {