Forgot Password

🔐 Overview of Forgot Password Flow in REL-ID SDK

The Forgot Password flow in the REL-ID SDK is designed to securely help users regain access to their accounts when they have forgotten their password. This flow is triggered only under specific conditions and adheres to the security principles set by the SDK.

🎯 Purpose

• 🔄 Account Recovery: Enable users to reset their password without needing to contact support—provided their device is in a valid (active) state.
• 🔐 Security-Compliant: Ensures that only verified users can reset their credentials through pre-configured authentication challenges.
• 💼 Controlled Flexibility: Supports recovery in scenarios like:
  • App reinstallation on the same device.
  • Loss of password on a previously activated device.
  • LDA (Local Device Authentication) changes where user ID is still recognized.

It does not apply to new device activations without access to previously activated devices—in such cases, users must contact support.

📱 UI Guidelines for Displaying the Forgot Password Option

✅ When to Show “Forgot Password?”

Only show the Forgot Password? link on the password input screen if and only if the SDK indicates it's supported in the current context.

🧠 How to Decide? Use the getPassword Event

Listen for the getPassword event, and inspect the following:

🧾 Sample Payload:

{
  "userID": "john_doe",
  "challengeMode": 0,
  "attemptsLeft": 3,
  "challengeResponse": {
    "challengeInfo": [
      {
        "key": "ENABLE_FORGOT_PASSWORD",
        "value": "true"
      }
    ]
  },
  "error": {}
}

✅ Conditions to Check:

If both conditions are true, you may safely render the Forgot Password? link.

🚫 When NOT to Show It

Do not show the option if:

• challengeMode != 0 (i.e., biometric or other non-password challenge)
• ENABLE_FORGOT_PASSWORD is absent or set to "false"
• User is not yet verified (unless using forgotPassword(userId) in React Native)

✅ Forgot Password Flow

1. User initiates Forgot Password via API.
2. SDK triggers challenge event (getActivationCode, getEmailOTP, etc.) as per configuration by REL-ID Admin.
3. App captures input and responds via appropriate API (setActivationCode, etc.).
4. SDK validates and issues getPassword with mode: RDNA_OP_SET_NEW_PASSWORD.
5. User submits new password using:

RdnaClient.setPassword("newSecurePassword123", RDNA_OP_SET_NEW_PASSWORD, (syncResponse) => {})

6. SDK triggers onUserLoggedIn – session and JWT are created.

flowchart TD
    GetPassword[SDK triggers getPassword]
    ShowForgotPasswordLink[App shows Forgot Password option to user]
    StartForgotPassword[App calls forgotPassword]
    TriggerChallengeEvent[SDK triggers challenge event e.g., getActivationCode, getEmailOTP]
    CaptureUserInput[App captures input and calls appropriate API e.g., setActivationCode]
    IssuePasswordChallenge[SDK triggers getPassword with challengeMode: RDNA_OP_SET_NEW_PASSWORD]
    SubmitNewPassword[App calls setPassword with new password and mode RDNA_OP_SET_NEW_PASSWORD]
    UserLoggedIn[SDK triggers onUserLoggedIn and session is created]

    GetPassword -- ENABLE_FORGOT_PASSWORD == true --> ShowForgotPasswordLink
    ShowForgotPasswordLink --> StartForgotPassword
    StartForgotPassword --> TriggerChallengeEvent
    TriggerChallengeEvent --> CaptureUserInput
    CaptureUserInput --> IssuePasswordChallenge
    IssuePasswordChallenge --> SubmitNewPassword
    SubmitNewPassword --> UserLoggedIn

    style GetPassword fill:#d4fdd4,stroke:#228b22,stroke-width:2px
    style TriggerChallengeEvent fill:#d4fdd4,stroke:#228b22,stroke-width:2px
    style IssuePasswordChallenge fill:#d4fdd4,stroke:#228b22,stroke-width:2px
    style UserLoggedIn fill:#d4fdd4,stroke:#228b22,stroke-width:2px

    style CaptureUserInput fill:#ffe4b3,stroke:#ff8c00,stroke-width:2px
    style SubmitNewPassword fill:#ffe4b3,stroke:#ff8c00,stroke-width:2px
    style StartForgotPassword fill:#ffe4b3,stroke:#ff8c00,stroke-width:2px
    

🔧 API Reference

🔁 forgotPassword

📝 Description

Used when the user has forgotten their REL-ID password. This API can only be called after the user is verified and only from an active device.

📲 Pseudocode

RdnaClient.forgotPassword((syncResponse) => {})

rdnaClient.forgotPassword();

com.uniken.rdnaplugin.RdnaClient.forgotPassword(successCallback, errorCallback)

(RDNAError *)forgotPassword;

RDNAError forgotPassword();

🆔 forgotPassword(userId)

📝 Description

Used before user verification. Only available in React Native.

RdnaClient.forgotPassword(userId, (syncResponse) => {})

🚦 Developer Action Guide

⚠️ Error Codes and Handling