Skip to main content

Authentication and session (React Native)

References: TECHNICAL_REQUIREMENTS.md §3, SPEC.md §2, §5, NFR-PORT-006.

1. Protocol​

  • Use OpenID Connect / OAuth 2.0 Authorization Code flow with PKCE for the mobile app as a public client (TECHNICAL_REQUIREMENTS.md §3).
  • Web and mobile SHALL share the same authorization model—same IdP, same client registration policy (separate client_id for mobile is fine).

Recommended libraries: expo-auth-session + expo-web-browser (Expo), or react-native-app-auth (bare). Prefer IdP-documented redirect URIs: custom URL scheme (e.g. com.ghasi.patient://oauth) or HTTPS universal links.

2. Token storage​

TokenStorage
Access tokenMemory while app foregrounded; optional short secure cache for resume
Refresh tokenExpo SecureStore or Keychain / EncryptedSharedPreferences only—never AsyncStorage for refresh tokens

Rotate and clear on logout. Support remote session revocation by treating 401/403 from API as signal to clear local tokens and show login.

3. Identity claims​

  • tenantId and patient (or proxy) identity SHALL come only from verified tokens—never trust query/body alone (patient-portal-requirements-doc.md §4).
  • Map IdP sub to portal account via backend; the app displays display name from /v1/portal/me when available.

4. Biometric unlock (NFR-PORT-006)​

  • Biometrics (Face ID, fingerprint) are an optional local unlock for returning users after an online login—they replace neither OIDC nor server session policy.
  • After global session expiry or step-up requirement from API, require full OIDC login again.
  • Use expo-local-authentication or native equivalents; fail closed to PIN/password screen if biometrics unavailable.

5. Session timeout and background​

  • Honor tenant idle timeout and absolute session lifetime when communicated by API (e.g., 401 with structured error or config).
  • On app resume from long background, refresh token if valid; if refresh fails, show login. Do not silently extend clinical sessions beyond policy.

6. Proxy / caregiver (FR-PORT-008)​

When enabled, the authenticated user may act in a delegated patient context. The app SHALL:

  • Show which patient is active in the shell header at all times.
  • Require explicit switch patient flow with server-side validation; never accept raw patientId from deep links without authz check.

7. Logout​

  • Clear secure token storage, in-memory cache, and optional biometric “unlocked” flag.
  • Optionally call IdP end-session endpoint if configured (RP-initiated logout).
  • Do not log raw tokens (COMPLIANCE_SECURITY.md).