[GarrettBeatty]

Depends on #10849. This PR is stacked on it; the diff below starts after
its commits.

Problem

Role credentials from AssumeRole / AssumeRoleWithWebIdentity are always
cached in ~/.aws/cli/cache, and there is no way to choose another folder.
Some users need the cache outside the home directory, for example a
per-session or tmpfs directory, or a read-only home (#1804, also asked in
#7376 and #6628).

Solution

A new optional profile setting, read by the assume role and the assume role
with web identity credential providers, next to credential_cache from
#10849:

Setting	Values	Default
credential_cache_location	an absolute directory, or a path that starts with ~	~/.aws/cli/cache

• credential_cache_location = <dir> stores the file cache in that
  directory. ~ is expanded; environment variables aren't. With
  credential_cache = memory, the location is ignored and isn't read.
• Each hop of a role chain reads its own profile's setting. For web
  identity, the setting of the profile in use applies even when the token
  file or role ARN comes from the environment, as for credential_cache.
• A web identity source_profile hop with a location caches there.

Example ~/.aws/config

# Cache this role's credentials outside the home directory.
[profile ci]
role_arn = arn:aws:iam::123456789012:role/CI
web_identity_token_file = /var/run/secrets/token
credential_cache_location = /run/user/1000/aws-cache

Cache folder

The folder is used like the default cache folder: it's created if missing, and files are written with 0600. Choosing a location is up to the user.

Errors

All are InvalidConfigError, raised when the profile is loaded, before any
STS call. Reads and writes of the cache files behave as in the default
cache folder.

Setting	Message
credential_cache_location = (empty)	The credential_cache_location in profile "ci" is empty. Set it to a directory or remove it.
credential_cache_location = cache (relative)	The credential_cache_location "cache" in profile "ci" is not an absolute path. Use an absolute path or a path that starts with ~/.
credential_cache_location = ~nouser/cache	The credential_cache_location "~nouser/cache" in profile "ci" could not be expanded: the home directory for that user can't be found. Use an absolute path or a path that starts with ~/.
credential_cache_location = $HOME/cache	The credential_cache_location "$HOME/cache" in profile "ci" is not an absolute path. Use an absolute path or a path that starts with ~/. Environment variables aren't expanded.

A relative path is rejected rather than resolved against the current
directory, so the cache never moves with the working directory. With
credential_cache = memory, the location isn't read, so it can't cause an
error.

Limits

• Only a profile setting; there is no environment variable for it.
• Role profiles only. IAM Identity Center (SSO) tokens and credentials, and
  credential_process, are not covered by this change.
• Only the AWS CLI reads this key. The AWS SDKs and other tools that read
  the shared config file ignore it.

Testing

Run on the top commit with a temporary home directory and config, no
AWS_* environment variables, and Python 3.12:

Tests	Result
tests/unit/botocore/test_credentials.py	250 passed
tests/functional/botocore/test_credentials.py	60 passed
tests/functional/configure/test_exportcreds.py	2 passed
tests/unit/customizations/test_assumerole.py	4 passed
tests/functional/docs/test_help_output.py, tests/unit/test_clidocs.py, tests/unit/test_help.py, tests/unit/test_topictags.py	149 passed, 3 skipped
Total	465 passed, 3 skipped, 0 failed

The JSONFileCache tests (TestJSONCache, and test_utils.py -k Cache)
pass unchanged.

25 new tests on top of #10849:

• Settings: ~ and ~user expansion, empty and relative locations (and
  the environment variable note), a relative location writes nothing to the
  current directory, and memory with a location (also empty or relative)
  set.
• The folder: a missing folder and its parents are created on the first
  write, a cached file is reused by the next command, and a cache file is
  0600, as in the default folder.
• Role chains: each hop caches in its own profile's location, a location
  on the source hop only, and memory on the top hop with a location on
  the source hop.
• Web identity: a location from the profile, with the token file from the
  environment, and on a web identity source hop (and a relative one).
• Explicit credential_cache = file with no location uses the injected
  cache, and on a web identity source hop, where no cache is injected, it
  writes to ~/.aws/cli/cache.
• End to end against real STS (one account, a read-only target role, on
  an earlier revision without the directory checks):
  credential_cache_location cached only in the given directory; cache
  files are mode 600; a relative location fails before any STS call, and no
  directory is created.
• aws help config-vars renders the new paragraph.
• ruff check and ruff format --check are clean on the changed lines.
  The import order finding ruff reports in
  tests/functional/botocore/test_credentials.py (the import block at line
  13) is already on v2 and isn't touched here.

Changelog

.changes/next-release/feature-credentials-44796.json, type feature,
category credentials.

Merge order

Merge #10849 first. The commits can be squashed or kept.

This PR was generated by AI tools, and reviewed by @GarrettBeatty.