Skip to main content

Token Storage Do's and Don'ts

Properly storing and transmitting authentication tokens is the foundation of a secure Archibald application.

Web (Browser)​

On the web, Archibald uses the CookieAuthAdapter by default.

Do​

  • Use HttpOnly and Secure cookies: The AuthModule handles this automatically. This prevents JavaScript from accessing the token (mitigating XSS) and ensures it is only sent over HTTPS.
  • Rely on the SameSite=Lax or Strict attribute: This provides built-in CSRF protection by controlling how cookies are sent with cross-site requests.
  • Use JWE (JSON Web Encryption): Always encrypt the session payload. Archibald does this by default using the jose library.

Don't​

  • Store tokens in localStorage: Tokens stored in localStorage are accessible to any script running on the page, making them highly vulnerable to XSS attacks.
  • Manually read cookies for API calls: Let the browser handle cookie transmission. If you need to send the token to an external service, do it from the Archibald backend (server-to-server).

Native (Mobile)​

Native applications use the HeaderAuthAdapter.

Do​

  • Use Secure Storage: Always use a storage adapter that utilizes the device's secure enclave (e.g., Keychain on iOS, Keystore on Android). The CustomNativeStorageAdapter in the Archibald native template is the recommended starting point.
  • Clear tokens on manual Logout: Ensure sessionClient.logOut() is called to wipe tokens from secure storage.

Don't​

  • Store tokens in plain AsyncStorage: Plain AsyncStorage on React Native is unencrypted. If the device is compromised or backup data is accessed, the tokens are exposed.
  • Log the Authorization header: When debugging network requests in native apps, ensure that headers containing tokens are scrubbed from your logs.