In this context, it means the OS will force the user to unlock the device (PIN/pattern/password and/or biometrics) before your app can read a secret stored in the Key Store Plugin.

Concretely, in OutSystems 11 with the Key Store Plugin:

1. You store a secret with KeyAuthentication = True
   In the SetValue client action, there is a parameter called KeyAuthentication.

   • If KeyAuthentication = False: the app can read the value directly (no extra prompt).
   • If KeyAuthentication = True: the OS requires the user to authenticate via the device lock screen (PIN/pattern/password) and, if configured, biometrics, before it gives the value back to your app. Key Store Plugin

2. What the user sees when you call GetValue

   • When you later call GetValue for a key that was saved with KeyAuthentication = True, the OS shows its authentication dialog (e.g., fingerprint/Face ID prompt, or PIN screen).
   • Only after the user successfully authenticates will the OS return the secret to GetValue.Value.
   • If the user cancels or fails authentication, GetValue.Success is False and GetValue.Value is empty. Key Store Plugin

3. Why this is important for biometric flows

   • You typically save a token (not a password) to the Key Store with KeyAuthentication = True.
   • When the user taps “Login with biometrics”, you call GetValue, the OS prompts for fingerprint/face/PIN, and only on success you get the token and do your quick login.
   • This way, the token is always protected by the device’s secure lock (and biometrics where configured), and your app never bypasses that. Key Store Plugin

4. Prerequisite: device must be “secure”

   • If the device has no lock screen (no PIN/pattern/password), the keystore is considered not secure, and you can’t use the KeyAuthentication = True flow; you’ll get errors like “DEVICE NOT SECURE” when using SetValue. device not secure

So, “require user authentication before a value can be read” = set KeyAuthentication = True when storing the secret, which makes the OS show its lock/biometric prompt each time you try to read that secret, and only returns it if the user successfully authenticates.

Here’s a practical, step‑by‑step way to use the Touch ID Plugin in an OutSystems 11 mobile app to implement biometric login.

1. Install and reference the plugin

1. Go to Forge and install Touch ID Plugin into your environment.
2. In Service Studio:
   • Open your mobile app module.
   • Use Add/Remove References and reference the plugin:
     • Client actions like CheckTouchIdPlugin and TouchId (names may vary slightly depending on the version).
   • Publish your module.
3. Generate a new mobile app build (Android/iOS) and install it on your device.
   The plugin only becomes available after you rebuild and reinstall the app.Can you give example on how to use this?

2. Understand what the plugin actually does

• The plugin does not create its own fingerprint; it uses the fingerprints already registered on the device.
• When you call the TouchId client action:
  • The OS shows its native fingerprint/biometric dialog (same as when you unlock the device).
  • The action returns:
    • Success = True → fingerprint matches an enrolled finger, user authenticated.
    • Success = False → fingerprint not recognized, user cancelled, or no fingerprint configured.Touch ID Plugin

Make sure the device:

• Supports fingerprint/biometric.
• Has at least one fingerprint configured; otherwise plugin calls will fail.Touch ID Plugin

3. Basic example: “Check Fingerprint” button

Create a simple screen to verify the plugin is working:

1. On a test screen, add a Button: Check Fingerprint.
2. In the button On Click:
   • Call CheckTouchIdPlugin (or equivalent) first to ensure the device supports Touch ID / fingerprint.
   • If supported, call the TouchId client action.
3. Use the output Success to show feedback:
   • If Success=True → show message “Fingerprint OK”.
   • Else → “Authentication failed or cancelled”.

Pseudo‑logic:

OnClick:
  CheckTouchIdPlugin
    If Not IsAvailable
       ShowMessage("Fingerprint not available or not configured.")
       Exit

  TouchId
    If Success
       ShowMessage("Fingerprint authenticated.")
    Else
       ShowMessage("Fingerprint failed or cancelled.")

This is the minimal pattern described in the Forge component examples.Touch ID Plugin

4. Step‑by‑step: Implement login with Touch ID

Typical requirement:

• First login = username + password.
• Next logins = fingerprint only (while still falling back to username/password if needed).fingerprint authentication

4.1 First login (username + password)

On your Login screen:

1. User enters Username and Password.
2. You call your normal login logic (e.g., Login action or REST call to backend).
3. If login succeeds:
   • Ask user: “Enable biometric login on this device?” (e.g., toggle or popup).
   • If user accepts:
     • Call CheckTouchIdPlugin to ensure fingerprint is available.
     • If available:
       • Set a Client Variable / Local Storage flag, e.g. BiometricEnabled = True.
         This tells your app that next time you can offer Touch ID login.
       • Do not store the password locally. Prefer tokens or just the flag.fingerprint authentication

Example data to store

• BiometricEnabled (Boolean) – client variable or local storage.
• Optionally a device‑specific token from your server (if you’re implementing a more advanced flow, see your earlier keystore/biometric discussion).

4.2 Next logins (Touch ID)

On the same Login screen, when the app starts:

1. Check BiometricEnabled:
   • If True, show a “Login with Touch ID” button.
2. When user taps Touch ID login:
   • Call CheckTouchIdPlugin:
     • If fingerprint not available/disabled, show error and fallback to username/password.
   • Call TouchId:
     • If Success=True:
       • Proceed to your “quick login” logic:
         • Either call a backend endpoint that accepts your stored token / device ID, or
         • Log in the user directly if you keep a server‑side association for this device.
       • Navigate to the Home screen.
     • If Success=False:
       • Show a message “Fingerprint failed. Please login with username and password.”

High‑level flow:

OnAppStart or OnLoginScreenInit:
  If BiometricEnabled
     Show "Login with Touch ID" button

OnTouchIdLoginButtonClick:
  CheckTouchIdPlugin
    If Not Available
       ShowMessage("Touch ID not available.")
       Exit

  TouchId
    If Success
         // Quick login logic (e.g., call REST with stored device token)
         NavigateToHome
    Else
         ShowMessage("Fingerprint failed. Use username and password.")

This is essentially what the Touch ID Login Sample Forge component demonstrates.Touch ID Plugin

5. Common pitfalls and fixes

1. “Touch Id is not defined” error

   • Usually happens when:
     • Plugin is not referenced correctly, or
     • You didn’t regenerate and install the mobile app after adding the plugin.
   • Fix:
     • Confirm you added the plugin as a dependency.
     • Publish the app.
     • Regenerate the mobile app build and reinstall.Touch ID Plugin

2. Plugin doesn’t prompt for fingerprint

   • Check:
     • Device has fingerprint configured.
     • You are testing on a real device (Touch ID/fingerprint isn’t available on many emulators).
   • Use CheckTouchIdPlugin before calling TouchId, as recommended.Touch ID Plugin

3. Beginner: login then fingerprint only afterwards

   • Implement using:
     • First login with username/password.
     • Store BiometricEnabled = True plus any device token.
     • On next launches: directly show the Touch ID button and follow the pattern above.fingerprint authentication

6. Where to look for a working example

If you want to see real logic and screens:

• Download the Touch ID Login Sample from Forge and inspect:
  • How it calls TouchId.
  • How it stores the “biometric enabled” state.
  • How the login flow is orchestrated with fingerprints.Touch ID Plugin

If you describe what your current login flow looks like (e.g., OutSystems built‑in login vs REST backend), I can map this Touch ID step‑by‑step onto your exact architecture.