Document token storage mechanism in MSAL Android

[Copilot]

Problem

No documentation exists for the token storage flow in MSAL Android—where tokens are persisted, what data structures are saved, cache key generation patterns, or storage security mechanisms.

Changes

Documentation Added

/docs/TOKEN_STORAGE_DOCUMENTATION.md (700 lines)

• Complete flow: BaseController.saveTokens() → MsalOAuth2TokenCache → SharedPreferencesAccountCredentialCache → SharedPreferencesFileManager → Android SharedPreferences XML
• Token types: AccountRecord, AccessTokenRecord, RefreshTokenRecord, IdTokenRecord with all fields documented
• Storage: /data/data/{package}/shared_prefs/com.microsoft.identity.client.account_credential_cache.xml
• Cache keys: Composite format {homeAccountId}-{environment}-{credentialType}-{clientId}-{realm}-{target}[optional-components]
• Security: Android KeyStore encryption, MODE_PRIVATE access, UID-sequestration in broker mode
• Architecture diagrams and code references with file paths

/docs/TOKEN_STORAGE_QUICKREF.md (76 lines)

• Quick reference: storage paths, key formats, security checklist

Cache Key Examples

Account:
  a1b2c3d4...890-login.microsoftonline.com-12345678...def0

Access Token:
  a1b2c3d4...890-login.microsoftonline.com-accesstoken-12345678...cdef-12345678...def0-user.read mail.read

Refresh Token (MRRT):
  a1b2c3d4...890-login.microsoftonline.com-refreshtoken-12345678...cdef--

Refresh Token (FOCI):
  a1b2c3d4...890-login.microsoftonline.com-refreshtoken-1--

Special Behaviors Documented

• MRRT: Single refresh token for all resources (AAD v1/v2)
• FOCI: Family of Client IDs share refresh tokens across first-party apps
• Automatic cleanup: Old refresh tokens removed when saving new ones
• In-memory LRU cache: 256 entries for performance

Original prompt

Hey, can you check where the tokens are finally saved when this method is triggered? I want you to create a document on what gets saved, where it gets saved, what is the cach structure etc;

TITLE: Token Storage Documentation Request

USER INTENT: The user wants to understand and document the token storage mechanism - specifically where tokens are saved when a particular method is triggered, including details about what data gets saved, the storage location, and cache structure.

TASK DESCRIPTION:

• Investigate and trace the token storage flow when a specific method is triggered
• Create documentation covering:
  • What token data gets saved
  • Where the tokens are stored (storage location/mechanism)
  • The cache structure used for token storage

EXISTING:

• No prior context provided about the specific method or codebase
• No files or code have been shared yet

PENDING:

• User needs to provide the specific method they're referring to
• Need to identify the codebase/files to investigate
• Trace the token storage flow
• Document the findings including:
  • Token data structure
  • Storage location
  • Cache structure

CODE STATE:

• No files or code snippets have been shared yet

RELEVANT CODE/DOCUMENTATION SNIPPETS:

• None provided yet - awaiting user to share the method or codebase reference

OTHER NOTES:

• This appears to be the beginning of a conversation
• The user references "this method" but hasn't specified which method they're referring to
• Need clarification on:
  • Which method triggers the token save
  • Which codebase/repository to investigate
  • What type of tokens (authentication tokens, API tokens, session tokens, etc.)

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.