aws login - no refresh?

[devurandom]

Describe the bug

The documentation of aws login claims that the tokens will be automatically refreshed:

• "Each time the login command is called, the CLI will acquire temporary credentials and a refresh token that correspond to your selected console session. The CLI will refresh the temporary credentials automatically as long as the refresh token is valid." (https://docs.aws.amazon.com/cli/latest/reference/login/#description)
• "[...] this will automatically generate temporary credentials. The CLI will automatically refresh these credentials for up to 12 hours." (https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html)
• "The AWS CLI and SDKs will automatically refresh the cached credentials every 15 minutes as needed. The overall session will be valid for up to the set session duration of the IAM principal (maximum of 12 hours), after which you must run aws login again." (https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html#cli-configure-sign-in-with-profile)

However, it is unclear to me how that automatic refresh is happening. There is no systemd user service or even a background process, as far as I can see, that could accomplish this.

The resulting effect I see is that the tokens expire constantly, every few minutes (<<1h) I have to run aws login again.

Regression Issue

• Select this option if this issue appears to be a regression.

Expected Behavior

• Documentation on how to control the background process that keeps refreshing the tokens, preferably using a systemd user service.
• Documentation how to manually trigger a token refresh, in case the automatic background process does not work, allowing people to set up systemd user timers themselves.

Current Behavior

• I cannot find documentation on how the automatic token refresh is being executed.
• I cannot find documentation on how to refresh the token manually.
• The token refresh does not appear to work: Tokens expire constantly in <<1h and I have to aws login again.

Reproduction Steps

aws login, wait for significantly less than 1h, run an aws command, notice that tokens are expired, run aws login again, repeat

Possible Solution

Both should provided:

• Documentation on how to control the background process that keeps refreshing the tokens, preferably using a systemd user service.
• Documentation how to manually trigger a token refresh, in case the automatic background process does not work, allowing people to set up systemd user timers themselves.

Additional Information/Context

No response

CLI version used

aws-cli/2.36.0 Python/3.14.6 Linux/7.1.6-201.fc44.x86_64 source/x86_64.fedora.44

Environment details (OS name and version, etc.)

aws-cli/2.36.0 Python/3.14.6 Linux/7.1.6-201.fc44.x86_64 source/x86_64.fedora.44

[ezet]

There is no background process — the refresh is lazy. Any aws invocation that finds fewer than 5 minutes left on the cached token (_REFRESH_THRESHOLD, awscli/botocore/credentials.py:2491) calls CreateOAuth2Token with grantType: refresh_token inline and rewrites the cache. So a session stays alive only as long as something runs aws at least every 15 minutes, and it needs no daemon or timer to do so. I confirmed this on 2.34.32: token exp 23:35:33Z, no interactive session, a plain aws sts get-caller-identity at 23:31 rolled it to 23:45:46Z with no browser.

That said, I think there is a real bug here, and it shows up exactly when you have several aws processes running concurrently — which is increasingly common with agentic tooling.

The token cache is rewritten in place, with no lock and no atomic rename. JSONFileCache.__setitem__ (awscli/botocore/utils.py:3987 on v2) opens the single cache file O_WRONLY | O_CREAT, truncates it, then writes:

with os.fdopen(
    os.open(full_key, os.O_WRONLY | os.O_CREAT, 0o600), 'w'
) as f:
    f.truncate()
    f.write(file_content)

And every refresh rotates the stored refresh token — refresh_credentials writes back the new refreshToken from the response (credentials.py:2603).

Those two together give two ways to lose the session, both requiring only that two aws processes cross the 5-minute threshold at the same time:

1. Both POST the same refresh token, both get a response, and last-writer-wins decides which token is persisted. The loser's write can leave a superseded token in the cache; every later refresh then fails and the only way out is aws login.
2. A reader hitting the file between truncate() and write() gets a short or empty read. __getitem__ turns the ValueError into KeyError, load_token returns None, and you get Unable to load a existing login session for session ... Please reauthenticate with 'aws login' (credentials.py:2513) — for a session that was perfectly healthy a millisecond earlier.

The visible symptom matches the report: fine for a while after aws login, then dead, and dead for every process at once, well inside the documented 12 hours.

Workaround, if anyone else is hitting this. Move the session into its own profile and serialise every refresh behind a lock:

[profile login-raw]
login_session = arn:aws:iam::<account>:user/<user>
region = <region>

[default]
credential_process = /usr/bin/flock -w 60 /home/<user>/.aws/login/.refresh.lock /usr/bin/aws configure export-credentials --profile login-raw --format process
region = <region>

Role profiles keep source_profile = default and are otherwise untouched. refresh_credentials already re-reads the token from disk and returns early when more than 5 minutes remain, so under the lock the first process refreshes and the rest simply reuse the result.

I tested it by starting 12 aws processes simultaneously inside the refresh window with no prior refresh — the exact collision. One write, one rotation, no torn read, session alive:

23:40:55  exp 23:55:55  refresh_token_fp 3e051a2e3efe <- bd678d5245c7
23:51:02  exp 00:06:02  refresh_token_fp d2525bbe73a7 <- 3e051a2e3efe   (12-way burst)

One caveat: aws login refuses a profile configured with credential_process (ensure_profile_does_not_have_existing_credentials), so re-authentication becomes aws login --profile login-raw.

A fix upstream would be write-to-temp-plus-os.replace in JSONFileCache.__setitem__, which closes the torn-read half on its own, plus a file lock around the refresh to close the rotation half.

Environment: aws-cli/2.34.32 Python/3.14.7 Linux/7.2.3-arch1-3 source/x86_64. Line numbers are from the v2 branch as of today.