Metadata-Version: 2.4
Name: awsuser
Version: 1.0.0
Summary: CLI tool to authenticate AWS IAM users with password + MFA via Console sign-in (no access keys needed)
Project-URL: Homepage, https://github.com/tmb28054/awsuser
Project-URL: Repository, https://github.com/tmb28054/awsuser
Project-URL: Issues, https://github.com/tmb28054/awsuser/issues
Project-URL: Changelog, https://github.com/tmb28054/awsuser/blob/main/CHANGELOG.md
Author: Topaz Bott
License-Expression: MIT
License-File: LICENSE
Keywords: auth,aws,cli,user
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: keyring>=23.0
Requires-Dist: playwright>=1.40
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: pylint>=3.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# 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

```bash
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

```bash
# 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

```bash
# 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

```bash
./run_tests.sh
```

## Documentation

- [User Guide](docs/user-guide.md)
- [FAQ](docs/faq.md)

## 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.
