How do you handle authentication and authorization in an offline-first mobile application where the user's session token may expire while the device is offline?

Question

Accepted Answer

Authentication in an offline-first application presents a unique challenge: the user needs to access the application and their data even when the server that validates their credentials is unreachable. At the same time, the application must not compromise security by granting indefinite access without verification.

The standard approach uses a combination of token-based authentication with local session caching. When the user authenticates online, the server issues an access token and a refresh token. The access token has a short expiry, typically 15-60 minutes. The refresh token has a longer expiry, days to weeks. Both are stored securely on the device using the platform's secure storage: Keychain on iOS and EncryptedSharedPreferences or the Android Keystore on Android.

While online, the application uses the access token for API requests and refreshes it using the refresh token before expiry. Standard OAuth2 flow. The offline challenge begins when the device loses connectivity while a valid session exists.

The first decision is whether to allow offline access at all when tokens expire. For many applications, the answer is yes with constraints. The user was authenticated when they went offline, and requiring re-authentication without connectivity would lock them out entirely. The approach is to cache the authentication state locally, including the user's profile and role information, and allow access to local data based on this cached state.

Define an offline grace period. Even after the access token expires, the application continues to allow local access for a configured duration, say 7 days from the last successful online authentication. This grace period acknowledges that the user's identity was recently verified while limiting how long a compromised or revoked account can continue accessing data. Store the timestamp of the last successful authentication in secure storage and check it against the grace period on each app launch.

During the offline grace period, the application operates in a restricted mode. The user can read and modify local data, but all changes are queued for sync. The application prominently indicates that the session needs renewal and will sync pending changes when connectivity returns. If the grace period expires without connectivity, the application can either lock access entirely or restrict it to read-only mode depending on security requirements.

When connectivity returns after token expiry, the application attempts a silent refresh using the refresh token. If the refresh token is still valid, new tokens are issued and the user continues without interruption. If the refresh token has also expired, the user must re-authenticate. Critically, the pending sync queue should not be lost in this case. After re-authentication, the queued changes are synced under the new session.

Token revocation is an edge case that requires careful handling. If the server revokes a user's access, such as an employee being terminated, the device does not learn about the revocation until it reconnects. The offline grace period is the maximum window of continued access after revocation. For high-security applications, this grace period should be shorter. Some enterprises use push notifications through a secondary channel to force immediate session invalidation on managed devices.

Local data encryption ensures that cached data is protected even if the device is compromised. Encrypt the local database with a key derived from the user's authentication, so that logged-out devices cannot access the data. When the user logs out or the session is invalidated, clear the encryption key, effectively making the local data inaccessible without re-authentication.

Biometric authentication can supplement the offline experience. After the initial password-based authentication, allow the user to unlock the application with fingerprint or face recognition during the offline grace period. This adds a layer of security ensuring that a found or stolen device cannot access the application even within the grace period, without requiring network access.

Authorization decisions must also work offline. If the user's permissions are role-based, cache the role assignments and permission rules locally. If permissions change on the server while the device is offline, the device operates on stale permissions until it syncs. Design your permission model so that the risk of stale permissions is bounded, and enforce server-side authorization for all synced operations regardless of what the client claims.