Situation Description & Motivation

Ghana Health Service (GHS) requested that SORMAS users should be able to generate their own password. According to GHS, the default password generated by the SORMAS application is not easy to easily remember.

The feature allows user to enter current password, New password and verify new password.

Use case (SORMAS Default Authentication)

1. User clicks on the user settings on the main menu.
   
2. The user setting form comes as seen below. User then clicks on the "Create new password"
   
3. The Change password form comes up and user update the available fields with current password, new password and confirm new password.
   

NB: The form has two ways of generating password.
3a1. This option allows user to key in current password, new password and confirm new password.
3a2. After the save button is clicked, a message pops up on the screen to alert password changed successful. See image below:

3b1. Another option is to click on the "Generate new password".
3b2. If an email is set for the current user, the SORMAS application sends the password to the user's email address. See image below:

3b3. If current user is without email address, a pop up with new password is shown to the user as indicated in the below image:

4. Type the required values in the fields and click on the "Save" button. When successful, a message prompt (as seen below) comes on the screen.
   

5. If password does not match, an alert message pops up as seen in the image below:
   

Use case (Keycloak Authentication)

1. For current password validation to be successful on keycloak there is the need for admin to turn on the "Direct Access Grant" on the "sormas-backend" client on the keycloak admin console as seen in the below image:
   

Alternatively, the configuration could permanently be added to the sormas.json file for keycloak to automatically pick at the point of running.

2. User clicks on the user settings on the main menu.
   
3. The user setting form pops up as seen below. User then clicks on the "Create new password"
   
4. Upon clicking the "Create New Password" link, the user is directed to the SORMAS Keycloak authentication form, displaying the "Forgot Your Password" prompt. The user is then required to:

a. Enter their username in the designated field.
b. Select the "Submit" button.

Once submitted, the system will initiate further steps, typically providing the user with additional instructions via email to complete the password reset process. This workflow leverages Keycloak’s secure identity management for credential recovery.

5. Type the required values in the fields and click on the "Save" button. When successful, a message prompt (as seen below) comes on the screen.
   

6. If password does not match, an alert message pops up as seen in the image below:
   

NB:
If at the point of validating a password, user gets feedback of wrong current password even though the password is correct, there are three things to check:

1. The admin checking the direct access grant on the sormas-backend client on the keycloak console.
2. Check whether the keycloak server is up
3. Check if the current user has date password as part of required user actions or his password is set with a temporal status especially when current user password is changed from the keycloak admin console. NB: This doesn't when password is set from the SORMAS interface using the self password reset.

Use Case (Mobile)

1. User clicks on the user settings on the main menu and this brings up the settings form. User then clicks on "Change Password".
   

2. After clicking on the "Change Password" button, the change password form pops up on the screen as seen in the below image.
   

There are two ways of changing the password (Either by typing the previous and new password or letting the application generate password in accordance with rules around password generation)
2a1. Type password

User is required to type in previous, current and confirm current password in the designated fields. User then click on the "Change Password" button and this will save the new password in the system which will pop up a message prompt with the inscription "User's password was changed successfully".

NB: A password strength status will indicate to the user whether password is weak or strong.

2a2. Generate Password
This section allows password to be generated automatically based on password rules and policies.

Here, user simply clicks on the "Generate Password" link and this automatically generate password in the New password and confirm new password fields. The user then types the previous password in the previous password field before clicking on the "Change Password" button. This action pops up a message prompt with the inscription "Change Password".

NB: Click on the password on the message prompt to copy the password to the clipboard for further use.

High-Level Explanation

Timeline

Tasks

• #1091

• #1092

• #3702

• #6

• ePareto: Creates the Epic for Password reset on SORMAS GitHub Repository from ePareto GitHub account(Until 10th January 2024).

• ePareto: Create a feature branch/fork (with EPIC #) from the development branch and inform SF(Until 11th January 2024).

• ePareto: Import or integrate the code into the feature branch/fork (Until 17th January 2024).

• ePareto: Start QA by checking the code (Until 22nd January 2024).

• ePareto: Perform final commit into feature branch/fork and inform SF (Until 23rd January 2024)

• SORMAS Foundation: Take the feature branch/fork, test code locally and when everything is fine ePareto will do a Pull Request to merge with the development branch (Until 29th January 2024).

• SORMAS Foundation: Approve the request to the development branch (Until 31st January 2024).

• SORMAS Foundation: Merge the Development branch into the master branch when the new version of SORMAS is released(The date is not defined yet).

Alternatives

Risks

Additional Information