awsuser 1.0.0

CLI tool to authenticate AWS IAM users with password + MFA via Console sign-in (no access keys needed)

awsuser

AWS credential_process tool that authenticates IAM users with password + MFA via Console sign-in. Uses a headless browser to automate login and extract temporary credentials — no pre-existing access keys needed.

Installation

pip install awsuser
playwright install chromium

Note: On macOS and Windows, awsuser uses your installed Google Chrome by default. You only need playwright install chromium if Chrome isn't installed.

Quick Start

# 1. Setup a profile (writes credential_process to ~/.aws/credentials)
awsuser -a 123456789012 -u alice -p myprofile

# 2. Use it — awsuser is called automatically by the AWS CLI
aws s3 ls --profile myprofile

When the AWS CLI needs credentials, it calls awsuser which:

1. Returns cached credentials if still valid
2. Otherwise opens a GUI prompt for MFA (password comes from keyring)
3. Automates Console sign-in in a headless browser
4. Extracts credentials from CloudShell and caches them

Usage

# Setup a profile
awsuser -a 123456789012 -u alice -p myprofile

# Save password to keyring (avoids password prompt on future runs)
awsuser -a 123456789012 -u alice --save

# Watch the browser during sign-in (debugging)
awsuser -a 123456789012 -u alice --watch

# Use a specific browser
awsuser -a 123456789012 -u alice --browser firefox

How It Works

1. AWS CLI calls awsuser via credential_process
2. Checks disk cache (~/.awsuser/cache/) — returns immediately if valid
3. If expired: opens a GUI window for MFA code (password from keyring or GUI)
4. Automates Console sign-in in a headless browser
5. Opens CloudShell and runs aws configure export-credentials
6. Caches and returns credentials as JSON to the AWS CLI

Running Tests

./run_tests.sh

Documentation

• User Guide
• FAQ

License

MIT

Disclaimer

This tool automates the AWS Console sign-in flow using browser automation. It relies on the Console's UI structure which AWS may change without notice. If the tool stops working after an AWS Console update, please open an issue.