Deprecate and Replace v1/password-expired-users API with Scalable, Rule-Aware Version

[PasinduYeshan]

Is your feature request related to a problem? Please describe.

In Identity Server 7.0, we introduced a new API to retrieve users with expired passwords. This was required because in IS 5.6.0, we had the capability of sending email reminders to users whose passwords were about to expire using a DAS-based analytics solution, which was removed in later versions. As a result, we needed to recommend a way for customers to implement this capability in the newer product versions.

However, there are a few limitations with the current API:

• The API does not support pagination, making it not scalable.
• With the introduction of the new Rule-based password expiration feature, we can no longer simply query users based on the lastPasswordUpdateTime. The new rules require evaluating user roles and groups to determine the specific password expiry rule for each user.

Due to these reasons, we need to consider deprecating the existing v1/password-expired-users API and introducing a new v2 version or a completely new API with an updated structure.

Current API Example:

curl --location 'https://localhost:9443/api/server/v1/password-expired-users?expiredAfter=2024-03-01&excludeAfter=2024-03-30' \
-H 'Accept: application/json' \
-H 'Authorization: Basic YWRtaW46YWRtaW4='

Current Response:

[
  {
    "userId": "3c780e73-9ca6-4e49-811e-8e697df22a91",
    "username": "JohnDoe",
    "userStoreDomain": "PRIMARY"
  }
]

Describe the solution you'd like

To address these limitations, we propose the introduction of a new API that supports pagination with a reasonable maximum page size (e.g., 50, to be evaluated). In the service layer, the first 50 users will be retrieved and evaluated against the password expiry rules to determine which rules apply. The response will not return all users with expired passwords; instead, it will return an isPasswordExpired status along with the userId.

New Proposed Response:

[
  "totalResults": 100,
  "startIndex": 1,
  "itemsPerPage": 2,
  "users": [
  {
    "userId": "3c780e73-9ca6-4e49-811e-8e697df22a91",
    "username": "JohnDoe",
    "userStoreDomain": "PRIMARY",
    "isPasswordExpired": true,
  },
  {
    "userId": "3c780e73-9ca6-4e49-811e-8e697df22a22",
    "username": "Jake",
    "userStoreDomain": "PRIMARY",
    "isPasswordExpired": false,
  }
 ]

Describe alternatives you've considered

• An alternative approach could involve displaying a label or alert at the user's login time, indicating the number of days left until their password expires.

[3] - https://is.docs.wso2.com/en/latest/apis/password-expiring-users-identification-rest-api/