fix: prevent concurrent token cache corruption (JSONDecodeError + unbuffered I/O)

[rob-zz]

Problem

When multiple az login / token acquisition calls run concurrently (e.g. parallel CI jobs or Terraform runs), the MSAL extensions token cache can become corrupted. Two distinct but related bugs cause this:

1. JSONDecodeError 'Extra data' – concurrent writers truncate or partially overwrite the cache file while another process is reading it.
2. ValueError: can't have unbuffered text I/O – CrossPlatLock opens the lock file with buffering=0 which is invalid for text mode in Python 3 (valid only for binary mode).

Both bugs manifest in azure-cli and, by extension, in Terraform (via the AzureRM / AzureAD providers which use the same MSAL token cache): Azure/azure-cli#30046

Terraform users typically see these errors when running terraform apply or terraform plan with the default parallelism (-parallelism=10): multiple provider goroutines call into the Azure SDK simultaneously, which all share the single on-disk MSAL token cache and trigger the same race conditions.

A third observable symptom is:

User '<upn>' does not exist in MSAL token cache

This appears because when _reload_if_necessary() fails due to a corrupted cache file, the in-memory cache is left empty (or not updated). MSAL's find_account() then returns None, and az-cli reports the user as absent — even though the user was previously logged in. This is not a separate bug: fixing the cache corruption eliminates this symptom too.

This was originally reported in the Terraform AzureRM provider as a "MSAL token (timing?) issue": hashicorp/terraform-provider-azurerm#27573

Root causes & fixes

1. CrossPlatLock uses buffering=0 in text mode (Python 3 incompatible)

cache_lock.py opened the lock file with open(..., 'w', buffering=0). Python 3 raises ValueError: can't have unbuffered text I/O for text-mode files with buffering=0. Fixed by removing the buffering argument (default buffering is fine for a lock file).

2. CrossPlatLock not used consistently / race conditions

token_cache.py's modify() acquires the lock after reading the cache but before writing. A concurrent writer can modify the file between the read and the write, causing the in-memory state to be stale, and the lock itself had the buffering bug above which caused it to crash before ever protecting anything.

3. FilePersistence.save writes directly, risking partial writes seen by concurrent readers

persistence.py's save() wrote directly to the target file. A concurrent reader could see a partial write, leading to JSON parse errors. Fixed by writing to a per-process temp file in the same directory and then os.replace()-ing it atomically.

Commits

• fix: CrossPlatLock races that cause JSONDecodeError('Extra data') under concurrency
• fix: FilePersistence.save uses atomic per-process temp file to prevent cache corruption
• fix: remove buffering=0 from CrossPlatLock (invalid for text mode in Python 3)

Repro

Tested locally with azure-cli 2.87.0 / Python 3.13. The following script reliably triggers both errors:

az logout
rm ~/.azure/msal_token_cache.*
az login

for i in $(seq 1 300); do
  az account get-access-token \
    --scope "https://stasdgalsdjhca${i}.queue.core.windows.net/.default" \
    --subscription <subscription-id> \
    -o none &
done
wait

Without the fix: mix of JSONDecodeError: Extra data and ValueError: can't have unbuffered text I/O across the 300 parallel processes.
With the fix: all 300 processes complete successfully.

The same race conditions are triggered by terraform apply (default -parallelism=10) when using the AzureRM or AzureAD provider, manifesting as:

• User '<upn>' does not exist in MSAL token cache (corrupted cache leaves in-memory state empty)

Related

• azure-cli issue: Concurrent az login causes 'User does not exist in MSAL token cache' due to token cache corruption (portalocker ValueError: can't have unbuffered text I/O) Azure/azure-cli#30046
• Originally reported in Terraform AzureRM provider: MSAL token (timing?) issue in azurerm_storage_account hashicorp/terraform-provider-azurerm#27573

[rob-zz]

@microsoft-github-policy-service agree