OAuth refresh token storage

For OAuth refresh token storage, the key goal is: treat refresh tokens like passwords. They can usually be used to mint new access tokens, so protect them accordingly.

Best practices

1) Store server-side if possible

If you have a backend, keep refresh tokens only on the server, not in the browser or mobile app storage unless necessary.

2) Encrypt at rest

If stored in a database or secret store, encrypt them using a strong, managed key system:

• KMS/HSM-backed encryption preferred
• Rotate encryption keys when possible

3) Never log them

Make sure refresh tokens are:

• excluded from application logs
• excluded from analytics/events
• masked in traces and error reporting

4) Use secure storage appropriate to the platform

• Web apps: prefer HttpOnly, Secure cookies for refresh-token sessions
• Mobile apps: use Keychain (iOS) / Keystore (Android)
• Backend services: store in a secrets manager or encrypted DB field

5) Rotate refresh tokens

Use refresh token rotation:

• each refresh returns a new refresh token
• invalidate the old one
• detect reuse to identify theft

6) Scope and expire them

Limit exposure by:

• short refresh-token lifetime where feasible
• least-privilege scopes
• separate tokens per device/session

7) Bind tokens to context when possible

Depending on your authorization server:

• device/session binding
• sender-constrained tokens (e.g., DPoP, mTLS)
• token family tracking

8) Provide revocation

Support:

• logout revocation
• admin revocation
• compromise response

Common patterns

Web app

• Access token stored in memory
• Refresh token stored in Secure + HttpOnly cookie
• Backend uses refresh token to get new access token

SPA-only app

Avoid localStorage for refresh tokens if you can. If unavoidable, understand XSS risk is much higher. Prefer a backend-for-frontend (BFF) pattern.

Mobile app

• Store refresh token in OS secure storage
• Use biometric gating if needed for sensitive actions, but don’t rely on biometrics alone for token security

Avoid

• localStorage / sessionStorage for refresh tokens in browsers
• plaintext database storage
• sharing refresh tokens across users/devices
• long-lived tokens without revocation or rotation
• embedding tokens in code or config files

If you want, I can give you a recommended architecture for:

• web app
• SPA
• mobile app
• backend service