Skip to content

AWS credentials and SSO profiles

CloudPouch reads the same local configuration files the AWS CLI uses — ~/.aws/credentials and ~/.aws/config — so profiles built on static credentials, IAM Identity Center (SSO), source_profile role chaining, the AWS CLI’s browser-based aws login, or an external credential_process helper work with CloudPouch. Connecting to an AWS account usually means selecting a profile you already have, not creating anything new.

If a CloudPouch error message sent you here, go straight to the matching section: your profile configuration is not supported, the role configuration is invalid, or no AWS credentials file was found.

  • Static IAM credentials in ~/.aws/credentials (access key and secret key).
  • AWS IAM Identity Center (SSO) profiles in ~/.aws/config, including the shared sso-session format where several profiles reference one session block.
  • Role-chaining profiles that assume a role via source_profile in ~/.aws/config.
  • aws login profiles (login_session) created by the AWS CLI’s browser-based sign-in — no access keys and no Identity Center setup required.
  • Credential helper profiles that obtain credentials from an external command through credential_process.

Role chains are also supported on top of helper-backed and aws login-backed profiles, without MFA. Some profile shapes are outside that scope, and Credential helpers and role chains carries the authoritative list of them.

The shared sso-session format is the practical choice when you analyze multiple AWS accounts behind one Identity Center start URL — one browser login covers every profile that references the session:

[sso-session my-company]
sso_start_url = https://my-company.awsapps.com/start
sso_region = eu-west-1
[profile prod]
sso_session = my-company
sso_account_id = 111111111111
sso_role_name = ReadOnlyAccess
[profile dev]
sso_session = my-company
sso_account_id = 222222222222
sso_role_name = ReadOnlyAccess

When you select an SSO profile whose session has expired or was never started, CloudPouch launches the browser-based AWS SSO sign-in flow automatically. If the browser authentication is not completed or the session is invalid, CloudPouch shows an error rather than silently continuing to display cost data from the previously active profile — so what you see always belongs to the profile you selected.

A profile created by the AWS CLI’s browser-based aws login command holds an AWS Console sign-in session instead of access keys. CloudPouch works with it directly: the profile appears in the profile sidebar and works on every data screen — Billing, Compare, Cost Insights, and Savings Scan.

These profiles require AWS CLI 2.32.0 or newer — the same CLI version that created the sign-in session, because a login_session profile cannot exist without it. On a machine with no AWS CLI installed, or with an older one, CloudPouch names the problem and links to the AWS sign-in documentation instead of failing with a generic credentials error. This version requirement belongs to aws login profiles alone; a credential_process helper profile needs no AWS CLI at all.

CloudPouch never reads or stores the aws login refresh token or sign-in keys. It uses only the short-lived session credentials.

Credentials refresh during long operations

Section titled “Credentials refresh during long operations”

An aws login sign-in session lasts up to 12 hours, but the session credentials inside it live only 15 minutes. CloudPouch refreshes those credentials transparently in the background, with no action from you, which is why a Savings Scan that runs longer than 15 minutes keeps going instead of failing part way through. Credential helper profiles get the same treatment: CloudPouch refreshes helper-issued credentials automatically when they expire.

Re-authenticating an expired sign-in session

Section titled “Re-authenticating an expired sign-in session”

When the sign-in session itself expires — after up to 12 hours, or after you run aws logout — CloudPouch shows a prompt that names the affected profile and gives you the exact command to fix it:

Terminal window
aws login --profile <name>

A button next to it copies the command to your clipboard. The prompt appears in Billing, Compare, single-service Cost Insights, and the Savings Workspace, and it is the same prompt in all four. In the Savings Workspace it replaces the results area for that scan attempt, so an old run is never left sitting next to the warning as if it were current. Revoking a login grant on the AWS side is treated the same way: you get the re-authentication prompt, not a different error.

A profile whose credential_process names an external credential helper — off-the-shelf or in-house — works everywhere a profile is used in CloudPouch. The support is generic: CloudPouch runs whatever command the profile names, without a shell, and uses the short-lived credentials it prints.

Credential helpers and role chains is the reference for this: exactly which helper and role-chain shapes CloudPouch resolves, which it does not, and what a failing helper looks like.

CloudPouch lists your profiles correctly on a machine that has never had an ~/.aws/credentials file — a machine that has only ever used aws login, for example. Profiles defined in ~/.aws/config are enough. CloudPouch also honors the AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE environment variables when it looks for profile configuration, so a non-default file location works as long as CloudPouch inherits those variables.

Press Cmd + R on macOS, or Ctrl + R on Windows and Linux, to reload the profile list. The same action is available from the native application menu and from the AWS Profiles (Accounts) header in the sidebar.

The list refreshes in place: your current view, the results already in memory, and any scan still running all survive the reload. A profile created while CloudPouch is open — running aws login --profile new-client in a terminal, or editing ~/.aws/config — shows up immediately, with no restart.

Cost work usually spans accounts, so profile switching is a first-class action:

  • Press Cmd/Ctrl + K to open the quick AWS profile switcher (Search AWS profiles…).
  • Type to filter by profile name, move with Up/Down, select with Enter, close with Esc.
  • The switcher covers every profile CloudPouch resolves: named profiles, SSO profiles, aws login profiles, credential helper profiles, and the supported role chains.

If ~/.aws/credentials has no default profile, CloudPouch shows a welcome screen instead of failing on startup.

Credential precedence and what has not changed

Section titled “Credential precedence and what has not changed”

Static-key, assume-role, and IAM Identity Center (SSO) profiles behave exactly as they did before aws login and credential_process support existed. Adding those two profile types changes nothing about how an existing profile resolves — nothing you already had needs reconfiguring.

When one profile mixes credential types (say a profile carrying both static keys and a credential_process line), CloudPouch checks it in a fixed order and uses the first mechanism it finds: static keys, then an assumed role (role_arn), then IAM Identity Center (SSO), then aws login (login_session), then credential_process. That order follows the AWS CLI’s for the combinations people actually write, but it is not identical to it: for example, static keys in ~/.aws/config win over credential_process here, while the AWS CLI ranks them the other way round. aws sts get-caller-identity --profile <name> therefore shows which identity the AWS CLI picks, not necessarily which one CloudPouch picks. The reliable fix for a mixed profile is to remove the mechanism you do not want it to use.

  1. Configure the profile with the AWS CLI (aws configure, aws configure sso, or aws login), or point it at your credential helper with credential_process.
  2. Verify it can read the account you want to analyze — for example, aws sts get-caller-identity --profile prod.
  3. Open CloudPouch and select the profile.

The permissions attached to that profile are all CloudPouch gets — it needs read access only. See AWS read-only access for the model and AWS permissions for a ready-made policy.

CloudPouch says your profile configuration is not supported

Section titled “CloudPouch says your profile configuration is not supported”

CloudPouch resolves the profile shapes listed under Supported profile types. A defined set of other shapes — mostly MFA-gated profiles and profiles that source their credentials from somewhere CloudPouch does not read — sits outside that scope, and the message names the profile it could not resolve.

Open Credential helpers and role chains and find your profile’s shape in the list there. That list is the authoritative one, and where a workaround exists it sits next to the entry. The usual one is to let a credential helper do the work CloudPouch cannot — MFA prompting, in particular — and point a wrapper profile’s credential_process at that helper, which is a shape CloudPouch does resolve.

Note that the profile may still work perfectly with the AWS CLI. The AWS CLI supports profile shapes CloudPouch does not, so “it works in the terminal” does not mean the profile is misconfigured.

CloudPouch says the role configuration is invalid

Section titled “CloudPouch says the role configuration is invalid”

This one is about the role-assumption part of the profile rather than the credentials underneath it. Check, in ~/.aws/config:

  • The source_profile exists and names a profile CloudPouch itself resolves. A chain is only as good as the profile at its root.
  • role_arn identifies the role you intend to assume — a complete role ARN for a role the source identity is allowed to assume. Confirm with aws sts assume-role or by selecting the profile in the AWS CLI.

Then check your chain against Credential helpers and role chains, which lists the supported configurations, the profile shapes CloudPouch does not resolve, and the workarounds available for some of them.

CloudPouch cannot find an AWS credentials file

Section titled “CloudPouch cannot find an AWS credentials file”

CloudPouch does not need ~/.aws/credentials to exist. Profiles defined in ~/.aws/config are enough, which is what makes an aws login-only or helper-only machine work. If CloudPouch reports that it found no credentials file and no profiles:

  • Check that ~/.aws/config exists and defines at least one profile. On a fresh machine neither file exists until you run aws configure, aws configure sso, or aws login.
  • Check the file location overrides. If you keep AWS configuration somewhere else, AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE must be visible to CloudPouch itself. An export in your shell profile reaches a terminal-launched process but does not necessarily reach an application launched from the Dock or Start menu.
  • Check the profile heading syntax. Profiles in ~/.aws/config need the [profile name] form, while ~/.aws/credentials uses bare [name]. A profile written the wrong way in the wrong file is invisible to the AWS CLI and to CloudPouch alike.
  • Reload after fixing it. Press Cmd + R (macOS) or Ctrl + R (Windows and Linux) — no restart needed.