Skip to main content

Improved AWS IAM User Authentication: Automatic Recovery and Better Guidance

· 4 min read
Andriy Knysh
Andriy Knysh
Principal Architect @ Cloud Posse

Atmos now automatically detects when your AWS IAM User credentials have been rotated or revoked and prompts you for new credentials inline. No more persistent authentication failures after credential rotation. Plus, improved guidance when credentials expire.

What Changed​

This release improves the AWS IAM User authentication experience with automatic recovery and better guidance:

Automatic Credential Recovery​

When atmos auth login encounters an InvalidClientTokenId error from AWS STS, it now:

  1. Automatically clears stale credentials from the keyring
  2. Prompts for new credentials inline - no separate configure command needed
  3. Retries authentication with the new credentials
  4. Provides actionable error messages if prompting is cancelled

Improved Status and Guidance​

  • auth whoami now shows session token expiration and displays a warning with recovery instructions when credentials are invalid
  • auth exec now provides a helpful tip when subprocesses fail due to expired credentials

Session Duration Fix​

A bug was fixed where session duration configured via atmos auth user configure was not being used, causing tokens to expire after 12 hours instead of the configured 36 hours.

Applies To​

This enhancement applies to AWS IAM User identities (aws/user kind). Other identity types like AWS SSO, assume-role, and permission-set are not affected as they use different authentication flows.

The Problem​

Previously, if your AWS access keys were rotated or revoked on the AWS side:

  1. Your session token would expire (normal)
  2. atmos auth login would fail with a cryptic error
  3. atmos auth logout + atmos auth login wouldn't fix it
  4. Only full user reconfiguration would work

This was frustrating because it broke developer workflows unpredictably.

The Solution​

Now Atmos detects the root cause and handles it automatically with inline credential prompting:

$ atmos auth login dev-admin

⚠ AWS credentials are required for identity: dev-admin

AWS Access Key ID: AKIAXXXXXXXXXX
AWS Secret Access Key: ********
MFA ARN (optional): arn:aws:iam::123456789012:mfa/user
Session Duration (optional, default: 12h): 36h

✓ Credentials saved to keyring: dev-admin

Enter MFA Token: 123456

✓ Authentication successful!

  Provider   aws-user
  Identity   dev-admin
  Account    123456789012
  Region     us-east-1
  Expires    2024-12-24 04:58:00 MST (35h 59m)

No separate atmos auth user configure command needed - everything happens in one flow.

Improved Whoami Status​

The auth whoami command now properly displays session token expiration. When credentials are invalid or expired, it shows a warning with recovery instructions:

$ atmos auth whoami dev-admin
✗ Current Authentication Status

  Provider      aws-user
  Identity      dev-admin
  Expires       2025-12-30 10:11:05 EST (expired)
  Last Updated  2025-12-30 09:55:34 EST

⚠ Credentials may be expired or invalid.
  Run 'atmos auth login --identity dev-admin' to refresh.

Auth Exec Guidance​

When auth exec runs a command that fails due to expired credentials, it now provides a helpful tip:

$ atmos auth exec --identity dev-admin -- aws sts get-caller-identity
An error occurred (ExpiredToken) when calling the GetCallerIdentity operation: The security token included in the request is expired

 Tip  If credentials are expired, refresh with:
      atmos auth login --identity dev-admin

Error Detection​

Atmos now detects three common AWS STS errors for IAM User authentication:

ErrorMeaningAutomatic Action
InvalidClientTokenIdKeys rotated/revokedClears stale credentials, prompts for new ones
ExpiredTokenExceptionSession expiredGuides to re-login
AccessDeniedMissing IAM permissionsGuides to check IAM policies

Session Duration Fix​

This release also fixes a bug where session duration configured during atmos auth user configure was not being passed through correctly. If you configured 36 hours with MFA, tokens were still expiring after 12 hours (the default).

Now your configured session duration is correctly preserved and used when generating session tokens.

Architecture​

This implementation introduces a generic credential prompting interface that can be extended to other cloud providers in the future. The interface uses a field-based specification that allows each identity type to define required credentials, making it easy to add support for Azure, GCP, and other cloud providers.

Why This Matters​

  • Single command recovery: atmos auth login now handles everything inline for AWS IAM Users
  • Extended MFA sessions work correctly: 36-hour sessions with MFA now last the full duration
  • Clear guidance: Know exactly what went wrong and how to fix it
  • Actionable warnings: auth whoami shows warnings with recovery commands when credentials are invalid
  • Helpful tips: auth exec guides you to refresh credentials when commands fail
  • Proper expiration display: auth whoami shows session token expiration, not just keyring metadata
  • Automatic cleanup: No stale credentials causing repeated failures
  • Extensible design: Generic interface ready for multi-cloud credential prompting

Get Involved​

If you encounter other AWS authentication errors that should have better handling, please open an issue on GitHub.