User Story - 1 : Multi-Factor Authentication (MFA) Support in eSignet <WIP>

[rachik1709]

1. Purpose

As a developer, I want to implement multi-factor authentication (MFA) in eSignet, so that users can authenticate using two or more factors across different categories (knowledge, possession, inherence), ensuring higher security and compliance with identity assurance standards.

2. Pre-requisite:

1. The relying party portal (OIDC client) should be onboarded to eSignet. Please follow the guide here for more details on relying party onboarding.

2. eSignet sign in plugin is integrated on the relying party portal.

3. Basic Flow

1. User navigate to the the relying party portal for login (Health portal reference implementation - Collab)

2. User clicks on the 'Sign in with eSignet' button on the relying party portal.

3. User is redirected to the eSignet UI to proceed with Login

4. User is displayed multiple auth factors to choose from with a new auth factor added by Label “Login with MFA“

5. User chooses “Login with MFA“ and enters the UIN/National ID to initiate the authentication.

6. Based on the configuration in the backend for the new auth factor, eSignet UI prompts the user to authenticate using 1st factor (Password for example)

7. User enters password and clicks on “Verify Password“.

8. Upon successful verification the user is navigate to the screen for the 2nd auth factor.(OTP for example)

9. User clicks on the “Send OTP“ button, and OTP is sent to the registered mobile number.

10. User enters the OTP and clicks “Verify OTP”.

11. Upon Successful authentication the user is authenticated successfully and is redirected to the Consent screen.

12. Once user provides consent the user is able to login and land on the relying party landing page with user info displayed in the profile section.

4. Alternate Flows <WIP>:

5. Acceptance Criteria

1. A new authentication factor: <MFA> is added in the eSignet backend.

2. A new acr value should be supported to reflect the same.

3. Configurable acr_values define MFA requirements (e.g., acr:mfa:pwd+otp)

4. The combinations of the factors that are included in the new auth factor - MFA should be configurable. For example:

   1. It should support the combination of any 2 or more auth factors like password, OTP and biometrics, or only password or OTP as per the requirement.

   2. It should be possible to configure the order in which these factors are prompted to the user.

      1. For ex, user is asked to enter the password first and then OTP or vice versa as per requirement.

   3. Example amr-acr-mapping.json file:

      1. The existing amr-acr mapping can be referred here.

      2. The amr-acr-mapping file a new acr value can be added. Refer the example below:

         1. {
              "amr" : {
                "MFA" : [{"type": "OTP"},{"type": "PWD"}]
              },
              "acr_amr" : {
                "mosip:idp:acr:mfa" : ["MFA"]"
              }
            }
            

5. The national ID/UIN/Individual ID that user enters at the start for the transaction will be contained and re-used through out the transaction.

6. The authenticate endpoint will be call each time the user chooses to verify the challenge entered for the auth factor. For ex

   1. If user first enters a password, an eSignet service will initiate an authenticate endpoint call to verify the challenge (password) and return the response.

   2. Similarly if once the password is verified and user enters OTP as next step of multi factor auth, eSignet service will again initiate a authenticate endpoint call to verify the challenge (OTP) and return response.

   3. So there will be sequential authenticate calls as per the number of auth factors configured.

   4. New version of the existing authenticate endpoint is to be created.

7. The auth factors configured in for multi factor authentication should be displayed in the UI as well.

8. The order in which the auth factors are displayed should be as per configuration in the backend.

9. At least two different factor categories (knowledge, possession, inherence) must be used when MFA is configured.

10. Retry policies are configurable (per factor)

    1. The default retry for each auth actor is 3

    2. After 3rd time the user will be redirected to the Relying party home page and user will be locked for some time.

    3. The period for which the user will be locked after 3 failed attempts should be configurable

    4. The default lock time period for the user will be 10 mins after 3 failed attempts

11. If any factor fails, flow terminates immediately (no further factors prompted) and the whole transaction is failed

    1. User is redirected to the relying party home page to restart the process

12. For each auth factor, once a challenge is validated a new authTransactionID will be generated and returned in the response of the authenticate endpoint. More details are added in later sections

13. On the UI user will be shown the the next auth factor UI screen until:

    1. authTransactionId and next factor is null

    2. no errors are returned in the response

14. User should not be able to go back the the already verified auth factor in the multi factor auth

    1. If user has already successfully verified the password as 1st auth factor, and is on the OTP verification screen, then is user tries to go back the then the transaction will fail.

    2. The page will refresh and user will start again from the “Sign in with eSignet“ button.

15. Once all the auth factors are validated then the user will be prompted to provide consent on the consent screen.

    1. Essential and voluntary claims are listed on the consent screen as per the relying party requirements.

16. In cases of the network disconnection, proper network disconnection UI page should be displayed to the user

    1. Once the connection is back user should be able to proceed from the same page.

6. Technical Details

6.1 Frontend (eSignet UI)

1. Dynamically interpret acr_values returned from backend.

2. Prompt user for factors sequentially (UI widgets).

   1. On the UI user will be shown the the next auth factor UI screen until:

      1. authTransactionId and next factor is null

      2. no errors are returned in the response

3. Handle retries

   1. Password attempts

      1. By default it is set to 3

   2. OTP resend

      1. It should be possible to configure the number of time user can resent OTP

      2. By default it is set to 3

   3. Biometric retry

      1. By default it is set to 3

Note - There already an existing config to handle above retries , which can be referred here.

4. Validations for the input fields should be added to display the user proper error messages. Please refer the error handling section for more details:

   1. Regex validations should be added for each UI challenge verification screen.

   2. Inline error messages displayed for the incorrect challenge entered by the user.

5. UI should be able to retain the UIN/National ID/Individual ID that user enters at the start of the authentication , so it can be reused for all auth factors.

6. Create a new UI component for the new auth factor - MFA
   

6.2 Backend (eSignet Core)

1. Create new v4/authenticate endpoint:

1. New version of the existing authenticate endpoint is to be created with the addition of the below parameters in the request structure.

2. Added Request Parameters:

1. authTransactionId - Identifier for the specific authentication transaction once login with MFA is selected.

3. Processing Logic

1. Determine whether the user-selected acr corresponds to Multi-Factor Authentication (MFA).

2. One the transaction is initiated the authfactortype is part of the challangelist in the request of the authenticate endpoint.

3. The authfactortype will be matched with the acr values in the amr-acr-mapping.json which is stored in the server (eSignet) for the first authentication call.

4. If the challenge is successfully validated:

   1. Generate a new authTransactionId for the next factor in the authentication sequence.

   2. For each auth factor once a challenge is validated a new authTransactionID will be generated and returned in the response of the authenticate endpoint.

   3. The authfactortype is stored in the cache to be referred to in the subsequent authentication cals.

5. For the subsequent authentication calls, authfactortype will matched with the array arc having array of auth factors.

6. If the MFA acr does not have a auth factor configured as the next step and the authenitcate call is made, the authentication will fail with inavild_acr value.

7. If the acr is configured to support MFA and user selects MFA then:

   1. Validate the provided challenge for each auth factor.

8. Once the authentication is completed, the rest of the flow to get auth_code, access token and user info will remain same.

   1. Please refer here for the existing authentication flow.

4. Response

The API returns the following information along with the existing parameters in the response existing authenticate endpoint.

1. new authTransactionId — Identifier for the next authentication factor.

7. Error handling

S.No | Scenario | UI Error message - Inline -- | -- | -- 1 | User enters invalid/wrong individual ID | Please try again with valid {fieldname}. For example , in case of UIN the message will be - Please try again with valid UIN. 2 | User enters a wrong password | Please try again with the Valid Password. 3 | Caps lock is on when password is being entered | inline message to highligh the caps lock on - “Caps lock is enabled“ 4 | User enters a invalid OTP | Please try again with a valid OTP. 5 | The biometrics given by user is not valid | Unable to verify the biometrics. Please try again, 6 | if PIN is configured as. 1 of the auth factors, and user enters wrong PIN. | Please try again with a valid PIN. 7 | User click on the back button to go back to the previously verified auth factor UI screen. | user is redirected to the relying party home page with error:“Transaction failed. Please try again.“ 8 | If the user enters incorrect password more that the configured number of retries | The transaction is failed and user is redirected to the relying party home page with error:”Transaction failed. Please try again.” 9 | If user tries to login again after the maximum number of attempts limit is breached. | Error message will be displayed to user once user selects auth factor and enters the UIN/National ID/Individual ID:”Too many failed attempts! Your account is temporarily locked. Please try again after ” 10 | If user chooses to close the tab on any UI screen during authentication. | Browser level pop up is displayed to confirm if user wants to close the tab. 11 | If the network is disconnected during the authentication flow: | Network disconnected UI screen is displayed with message. “Network Disconnected. Please check your network connection and try again.

8. Sequence Diagram:

9. UI/UX user flow:

Please refer below for the UI designs for the MFA.

MFA UI Designs - (WIP)

10. Environment (QA, Dev, Collab)

• Dev

• QA

• Collab

11. Resources:

1. eSignet Github - https://github.com/mosip/esignet/tree/v1.4.2

2. eSignet-mock-services - https://github.com/mosip/esignet-mock-services/tree/master/mock-relying-party-ui

3. eSignet docs - https://docs.esignet.io/

4. eSignet in Collab - https://esignet-mosipid.collab.mosip.net/

5. Demo portal for self exp- https://healthservices-mosipid.collab.mosip.net/

6. Workshop for integration with eSignet - https://docs.esignet.io/general/resources#esignet-workshop-2024

7. User guide to set up INJI wallet for Wallet based login - https://docs.inji.io/inji-wallet/inji-mobile/functional-overview/end-user-guide

8. Self registration Portal - https://self-register.collab.mosip.net/