Password

Overview

The password challenge in the REL-ID SDK is one of the core authentication mechanisms. It is invoked when the user must either:

🔐 Authenticate using an existing password (e.g., during login), or

🆕 Set a new password (e.g., during activation or password change flow)

🧩 What is the Password Challenge?

The password challenge is a request from the SDK to the host app to:

1. Display a password prompt to the user.
2. Enforce password rules (if provided).
3. Submit the user’s input securely using the appropriate SDK method.

It is triggered via the getPassword event.

🔄 When Is It Triggered?

💼 Why It Matters

Password authentication remains a foundational method for verifying identity. With REL-ID’s implementation:

• Security is enforced through configurable policies (length, complexity, repetition).
• The experience is standardized across platforms.
• Developers are in control of UI rendering, while the SDK manages validation logic and flow.

🧠 What the App Must Do

When the password authentication method is triggered by the SDK, the app must:

1. Listen for the getPassword event
2. Prompt the user to enter a password
3. Validate it based on the password policy provided
4. Submit it using setPassword()

getPassword Event

📥 Sample Payload – getPassword

{
  "userID": "testuser",
  "challengeMode": 1,
  "attemptsLeft": 3,
  "challengeResponse": {
    "status": {
      "statusCode": 100,
      "statusMessage": "Success"
    },
    "session": {
      "sessionType": 0,
      "sessionID": "1JKMQMQO1X0G9ENL..."
    },
    "additionalInfo": {
      "currentWorkFlow": "FirstTimeUserActivation"
    },
    "challengeInfo": [
      { "key": "Response label", "value": "Password" },
      { "key": "description", "value": "Enter your account password" },
      { "key": "PASSWORD_POLICY", "value": "{{\"minL\": 8,\"maxL\": 16,\"minLc\": 1,\"minDg\":
1,\"minUc\": 1,\"minSc\": 1,\"Repetition\": 2,\"UserIDcheck\":
\"true\",\"msg\": \"Password must contain 8-16 characters, including
atleast 1 uppercase, 1 lowercase, 1 number and special characters\"}}" },
      { "key": "SDK_CHLNG", "value": "YES" },
      { "key": "SDK_CHLNG_MODE", "value": "AUTO" }
    ]
  },
  "error": {
    "shortErrorCode": 0,
    "longErrorCode": 0,
    "errorString": "Success"
  }
}

🧾 Top-Level Fields

🔁 challengeResponse

📘 additionalInfo

📚 challengeInfo[] (Key-Value UI Hints)

🚫 error

🔐 Password Policy Structure

{
  "minL": 8,
  "maxL": 16,
  "minLc": 1,
  "minDg": 1,
  "minUc": 1,
  "minSc": 1,
  "Repetition": 2,
  "UserIDcheck": "true"
}

📤 Submitting the Password - setPassword API

The setPassword API is used in the REL-ID SDK to submit a password entered by the user in response to the getPassword event. This may be for authentication or first-time password setup.

🧭 When to Use

• In response to a getPassword SDK event
• When the user must enter a password as part of the login or onboarding flow
• NOT used for changing passwords (use updatePassword for that)

🧪 Sample Code

RdnaClient.setPassword("MySecure@123", 1, (response) => {
  console.log("Password submitted", response);
});

rdnaClient.setPassword(["MySecure@123", 1]);

com.uniken.rdnaplugin.RdnaClient.setPassword(
  () => console.log("Success"),
  (err) => console.error("Error", err),
  ["MySecure@123", 1]
);

[rdnaInstance setPassword:@"MySecure@123" challengeMode:1];

rdna.setPassword("MySecure@123", RDNAChallengeOpMode.MANUAL);

✅ What Happens If Password Is Correct?

• status.statusCode = 100
• error.shortErrorCode = 0
• The password challenge is completed successfully.
• The SDK moves to the next event in the workflow or completes the session.

❌ Error Handling - Error Codes for getPassword

🔐 Status Codes for getPassword

❌ What Happens If Password Is Incorrect?

• status.statusCode = 102
• The SDK re-triggers getPassword if attemptsLeft > 0
• You should show an error and prompt the user again

🔒 What Happens If Attempts Are Exhausted?

• error.shortErrorCode = 153
• The challenge fails and the SDK determines the next step:
  • Could be fallback authentication
  • Could end the session

🧠 Developer Tips

• Parse and use PASSWORD_POLICY to validate input on the client side.
• Always display the description and attemptsLeft.
• Handle success and error cases cleanly.
• Wait for SDK callbacks to move to the next challenge — do not hardcode flow transitions.
• UsesetPassword() for both verification and setting password in first-time activation (Mode 1).
• UseupdatePassword() for password changes post-login (Mode 2 or 4).
• Always validate inputs against password policy rules when challengeMode is 1, 2, or 4.

🧪 Sample Code Check

// Pseudocode logic
if ([0, 1, 3, 5, 12, 14].includes(challengeMode)) {
    setPassword(userInputPassword);
} else if ([2, 4].includes(challengeMode)) {
    updatePassword(oldPassword, newPassword);
}

📘 Additional Error Codes Related to getPassword

ℹ️ Developer Note:
For all the above error codes:

• If SDK Mode is REL_ID_MANUAL_LDA and RDNAChallengeOpMode is RDNA_CHALLENGE_OP_VERIFY(0):
  • Show error with OK button
  • On OK click → Navigate to password verification screen
• If SDK Mode is AUTO and RDNAChallengeOpMode is RDNA_CHALLENGE_OP_SET(1):
  • Show error with OK button
  • On OK click → Navigate to set password screen

📌 Additional Developer Note (For RDNA_ERR_ENABLED_LDA_NOT_FOUND_ON_DEVICE):
This error is triggered in login flow under the following scenarios:

1. User is activated using device biometric only, and no manual password is set.
2. The prerequisite ACTIVATE_USING_PASS_MANDATORY is configured to FALSE. The user is activated using manual password. Later, biometric authentication is enabled using LDA toggling. During the next login, if all the device biometrics are removed:

👉 Action: Ask user to enroll at least one biometric on the device and try again.