Introduction

With AWS CLI SSO, a user is not really "logged in" just because a cache directory exists. The useful question is whether the configured profile can still obtain valid credentials and successfully call AWS APIs.

Use a Real AWS Call as the Check

The most reliable check is to run a harmless command that requires credentials. sts get-caller-identity is ideal because it does not modify resources and works in almost every account.

aws sts get-caller-identity --profile my-sso-profile

If the SSO session is still valid, the command returns the caller ARN, account ID, and user or role identity. If the session is expired, missing, or misconfigured, the CLI exits with an error. That makes it better than inspecting local cache files.

Check Exit Status in Scripts

For shell scripts, the exit code matters more than the printed JSON. Redirect the output away and branch on success or failure.

1#!/usr/bin/env bash
2set -euo pipefail
3
4PROFILE="my-sso-profile"
5
6if aws sts get-caller-identity --profile "$PROFILE" >/dev/null 2>&1; then
7  echo "SSO session is active"
8else
9  echo "SSO session is expired or unavailable"
10  exit 1
11fi

This is the simplest way to gate a deployment script, local helper, or preflight check.

Distinguish Authentication from Configuration

An SSO profile can fail even when the cached session exists, because the profile itself may be wrong. Before assuming the user needs to log in again, inspect the configured profile values.

1[profile my-sso-profile]
2sso_start_url = https://example.awsapps.com/start
3sso_region = us-east-1
4sso_account_id = 123456789012
5sso_role_name = DeveloperAccess
6region = us-east-1
7output = json

If sso_start_url, sso_region, account ID, or role name do not match the intended access path, the identity command will fail for configuration reasons rather than for session-expiration reasons.

Trigger Login Only in Interactive Flows

When you are working locally, it can be reasonable to run aws sso login after a failed check. In a non-interactive environment, that pattern is usually wrong because browser-based login is not appropriate for automation.

1PROFILE="my-sso-profile"
2
3if ! aws sts get-caller-identity --profile "$PROFILE" >/dev/null 2>&1; then
4  aws sso login --profile "$PROFILE"
5fi

Use this pattern for developer tooling, not for headless CI. For automation, prefer IAM roles, workload identity, or another non-interactive credential source.

Cache Inspection Is Only a Debug Aid

You can inspect the SSO cache if you are debugging odd behavior.

ls -lt ~/.aws/sso/cache

That can tell you whether cached entries exist and whether they were refreshed recently, but it does not prove the target profile is usable right now. Cache files can be stale, unrelated to the profile you care about, or present even when an API call still fails.

Build a Reusable Helper

If this check is part of your daily workflow, wrap it in a small shell function. Keeping the logic in one place avoids subtle differences between projects.

1aws_sso_ready() {
2  local profile="$1"
3  aws sts get-caller-identity --profile "$profile" >/dev/null 2>&1
4}
5
6if aws_sso_ready my-sso-profile; then
7  echo "ready"
8else
9  echo "not ready"
10fi

This helper works well in local scripts because it exposes a clean boolean contract through the shell exit code.

Common Pitfalls

The most common mistake is treating the presence of files in ~/.aws/sso/cache as proof of a valid session. That directory is useful for debugging, but it is not the source of truth.

Another problem is mixing AWS_PROFILE and --profile inconsistently. If one part of a script uses the environment variable and another uses a flag, you can easily test one profile while assuming you are testing another.

It is also easy to forget that a failing profile may be misconfigured rather than expired. Re-running login repeatedly will not fix a wrong account ID or role name.

Summary

• Use aws sts get-caller-identity --profile ... as the actual SSO readiness check.
• In scripts, rely on the command exit status rather than parsing cache files.
• Treat aws sso login as an interactive recovery step, not a CI pattern.
• Verify the SSO profile configuration before assuming the session is expired.
• Use cache inspection only for troubleshooting, not for the main decision.