Login workflow for the client reference application

[ndegwamartin]

Overview

This discussion thread is focused on the login workflow.

We’re exploring implementation ideas, best practices, and real world use cases. Contributions are welcome—whether it's UX suggestions, security considerations, or technical approaches.

Please share your thoughts clearly and include examples where possible.

The recommended way to implement authentication for mobile applications is by using OAuth2 with the Authorization code Grant Type with PKCE. This grant type ensures that the client does not handle any of the credentials (both user and client credentials) thus limiting the attack surface for a threat actor. Once this flow is triggered, the UI to enter credentials is presented by the Authorization Server in form of a web browser.

The above presents a challenge for CHW mobile apps that are offline first and need to handle Offline login to the device. Offline Login requires that the user log into the app even without an internet connection.

Requirements/Challenges/use cases:

1. Initial login with Auth server
2. Offline login e.g. with Pin or Password(Not recommended)
3. Credentials (e.g. Pin) recovery options when offline
4. Supporting multiple (but curated) users on a shared device.
5. Configurability e.g. we need to support different IAM providers long as they support Oauth2

Ideally we want an approach and design that is practical and balances usability, security, and real-world constraints.

[ndegwamartin]

Requirement 1 - Initial login with Auth server

Here's a possible design for requirement No. 1 above. This workflow requires an internet connection which is (usually) available for the initial set up of devices for a deployment.

After successful authentication, the user is prompted to set a PIN (4 - 6 digits, could be configurable but we could enforce a recommended minimum. Trade off is simplicity and security). This PIN is securely stored on the device e.g. as a salted Hash. Subsequent offline logins to the app can use the pin to unlock.

[qiarie]

@ndegwamartin What does Initial Sync entail? Is this the app manifest and definitions?

[qiarie]

Could we also move the Initial Sync step to come after the Login PIN is saved?

[ndegwamartin]

Yeah that makes total sense.

The initial sync was the the configs needed that could also impact look and feel of following screens which was in the original spec. With the current proposed spec of no runtime configs we could re-order the steps as such.

[qiarie]

@ndegwamartin From a conversation we've had, iteration 1 of the Player app may not require sync. We can implement the sync bit to be pluggable based on approach chosen. The default app may use local configs, but someone implementing it their way can use synced configs.

[ndegwamartin]

Requirement 2: Offline login/app lock

Offline PIN authentication using KDF-based hashing

Overview
To support offline authentication, we store a per-user, salted hash derived from the user’s PIN using a strong key derivation function (preferably Argon2id, or PBKDF2 as a fallback).

When the user enters their PIN:

• The app recomputes the derived value using the stored salt and parameters.
• It compares the result to the stored hash.
• If they match, access is granted.

The same pattern is used for recovery codes (stored as a separate salted hash), allowing PIN reset without requiring server connectivity.

This keeps the design simple with deterministic verification.

Why this approach works well

• Authentication works without any server interaction so offline capable.
• The PIN is never stored, only a salted, KDF-derived hash.
• PINs and recovery codes follow the same structure and logic.
• Argon2id parameters (especially memory cost) can be adjusted to match device capabilities and threat model.
• Good fit for shared devices since each user has an independent record, making multi-user support straightforward.

Things to be aware of / Trade-offs

• If device storage is compromised, an attacker can attempt to brute-force the PIN against the stored hash. This is mitigated by using a strong KDF (Argon2id) with high memory cost.
• Security depends heavily on choosing appropriate KDF parameters (e.g., ~64–128 MB memory on 2 GB devices for Argon2id).
• Recovery codes must be distributed and stored securely, as they function as an alternative authentication method.
• KDF parameters should be versioned and upgradable over time as device capabilities improve.

Attempt limits, lockout, and wipe
To mitigate brute-force attacks, the app should enforce limits on failed PIN attempts:

• Allow up to 10 attempts
• Introduce exponential backoff starting around the 5th failed attempt

After the limit is reached:

• Lock the device until a supervisor-assisted reset, or
• Allow a remote wipe signal delivered via the device manifest

For usability, we can consider resetting the attempt counter after a timeout (e.g., 24 hours), to avoid permanent lockouts due to user error.

[ndegwamartin]

Requirement 3: PIN reset without connectivity

Option A - Supervisor recovery code
At enrollment, we generate a unique recovery code (e.g., a 12-word phrase or alphanumeric string) tied to the user’s account. This code is stored securely on the server, and a human-readable copy is provided to a supervisor – either printed or accessible through the OHS Player web portal.

If a user needs to reset their PIN, the supervisor shares this recovery code (in person or over the phone). The app treats the recovery code as an alternative authentication factor: it derives a hash using the same KDF (Argon2id or PBKDF2) and verifies it against the stored recovery hash. If valid, the user is allowed to set a new PIN.

Why this works well

• Fully offline on the device at verification time
• Supervisors can assist without knowing or resetting the user’s PIN directly
• Same security model as PIN verification (consistent KDF-based design)

Trade-offs

• Recovery code distribution and handling must be tightly controlled
• Loss of recovery code means supervisor-mediated recovery is required again
• Requires secure storage of recovery hashes on the backend

Option B - Supervisor delegation via QR code
In this approach, a supervisor logs into the OHS Player web portal and generates a time-limited, single-use reset token for a specific user and device. The token is cryptographically signed by the server (e.g., JWT or similar signed payload) and encoded as a QR code with an expiry window of 24 - 48 hours.

The supervisor then shares the QR code with the user (in person, or by displaying it on their device). The user scans it with their app, which verifies the token locally using the embedded server public key. If the signature is valid and the token has not expired, the user is allowed to proceed with setting a new PIN.

Why this works well

• No connectivity required on the user’s device at time of reset
• No shared secrets or credentials are exchanged
• Cryptographically signed tokens ensure authenticity and prevent tampering
• Well-suited for field workflows where supervisors have intermittent connectivity

Trade-offs

• Supervisor requires internet access at the time of token generation
• Token lifetime requires careful balancing (shorter improves security, longer improves usability)
• Operational dependency on supervisors having access to a working device for QR generation

PIN change policy
Users should be able to change their PIN at any time, both online and offline.

Technically, this involves recomputing and storing a new KDF-derived hash using the new PIN. Since verification is local, no server interaction is required.

A new recovery code should also be generated and issued whenever the PIN is changed. This part however might need an internet connection if components here need to be synced back to the server.

[ndegwamartin]

Requirement 4: Supporting multiple users on a shared device

We need a reliable way to control which users can access a device, especially in environments where connectivity may be intermittent. Below are two approaches, each with different trade-offs.

Option A - Server-synced device manifest
When the device is set up (or whenever it syncs online), the server provides a signed device_manifest.json. This file has a field which contains the list of users allowed on the device, along with basic metadata like username, display name, role, and data scope.

The app enforces this list locally, meaning only users in the manifest can log in-whether it’s their first login or a subsequent PIN unlock. When the device reconnects, the manifest is refreshed. If access needs to change (e.g., reassigning the device), the server simply updates the manifest-no reinstall required.

Why this works well

• Centralized control over device access.
• Devices can be reassigned or updated remotely without friction.
• Works well offline once the manifest is in place.
• Easy to audit access control.

Trade-offs

• The manifest can become outdated if a device stays offline for a long time.
• This can be mitigated by adding a TTL (e.g., warn if the manifest is older than a certain number of days), but in most field scenarios it’s better to warn rather than block access entirely.

Device retirement and reassignment
When a device is reassigned (e.g., moved to a different jurisdiction), the server pushes an updated device manifest with a new user list and data scope.

On the next sync, the app should:

• Apply the updated manifest
• Remove any locally stored authentication records (e.g., PIN/recovery hashes) for users no longer authorized on the device
• This prevents orphaned credentials from persisting after reassignment.

Handling manifest staleness
Rather than enforcing a hard expiry that blocks access, we can use a tiered approach:

• After the valid_until period, flag the device in the admin system as "needs sync"
• Allow users to continue working without interruption

We can also add stricter controls by introducing a hard lock only after a longer grace period (e.g., 90 days), and ideally only for new login attempts -- not active sessions.

[qiarie]

@ndegwamartin How are the users allowed on a device grouped? This is in line with data segregation in the device. In a case where they represent different subsets, wouldn't that introduce complexities?

Can we constrain multiple users on a device based on their sync strategies and whether they share some key details?

For device_manifest.json, does it mean we will not be using FHIR resources to define an application's manifest as was considered before?

[ndegwamartin]

This was to tackle a use case the ICL team had. I think in line with the sync strategy approach, suppose we have members assigned to same location but their devices are limited to a user group? Or perhaps its an alternative?

@moshonk and team can give some more context here.

[ndegwamartin]

On device_manifest.json this captures the concept of a device manifest. From a FHIR perspective this could be bundled as a Fhir Binary resource.

This is one of those configuration we'd probably want to be syncable over the network.

[ndegwamartin]

Requirement 5: Configurability

We need configurability for these items:

1. Support for different IAM providers
2. Support for different PIN lengths . Maybe we can enforce a hard minimum e.g. 5-6 digits
3. Support for a configuration file that can contain metadata like users allowed on device e.g. device_manifest.json

[ndegwamartin]

Additional design considerations
This section is for edge cases and operational details that help ensure the system behaves reliably in real-world conditions.

Server signing key rotation
The app relies on a server public key to verify manifests and QR reset tokens, so key rotation must be handled safely.

A practical approach:

• Bundle the current public key at build time
• Allow the server to provide a new public key during any online sync
• Verify the new key using the existing trusted key (establishing a chain of trust)

This allows keys to be rotated without breaking existing devices or requiring immediate updates.