AWS Auth

  ┌───────────────────────┐       ┌────────────────────────┐       ┌───────────────────────┐
  │  IAM Identity Center  │ ────> │       aws-auth         │ ────> │  ~/.aws/credentials   │
  │     (AWS SSO OIDC)    │       │  (Smart Role Selector) │       │ (Strict 0600 POSIX)   │
  └───────────────────────┘       └───────────┬────────────┘       └───────────┬───────────┘
                                              │                                │
                                  ┌───────────▼────────────┐       ┌───────────▼───────────┐
                                  │   MCP Server (stdio)   │       │ Terraform / K8s / CLI │
                                  │ (Claude / Cursor / AI) │       │ (Instant Compatibility)│
                                  └────────────────────────┘       └───────────────────────┘

---

💡 Why aws-auth vs Alternatives?

Feature	aws-auth	Official aws sso login	granted / assume	aws-vault
Zero-Config Account Discovery	✅ Automatic	❌ Requires manual ~/.aws/config	⚠️ Partial	❌ Manual
Model Context Protocol (MCP)	✅ Native built-in	❌ None	❌ None	❌ None
1-Second MRU / Pinned Logins	✅ Smart Prioritization	❌ None	⚠️ History prompt	❌ None
Real-time Substring & Alias Filter	✅ Instant typing	❌ None	✅ Yes	❌ None
Direct ~/.aws/credentials Sync	✅ Atomic & 0600	❌ Token cache only	⚠️ Shell wrapper	⚠️ Keychain wrapper
Legacy & GUI Tool Compatibility	✅ 100% Out of Box	⚠️ Many tools fail	⚠️ Requires wrapper	⚠️ Requires wrapper
WSL2 -> Windows Browser Bridge	✅ Automatic	❌ Fails / manual copy	⚠️ Partial	❌ No
EC2 SSM & EKS Context Switching	✅ Built-in	❌ Separate tools	❌ Separate tools	❌ No

👉 Read the full Feature Comparison Guide.

---

✨ Key Features

• ⚡ Zero-Boilerplate Discovery: No need to maintain hundreds of lines in ~/.aws/config. Enter your SSO Start URL once, and all authorized accounts and roles are loaded dynamically.
• ⭐ Smart Role Prioritization (MRU): Automatically pins your most recently used roles (e.g. QA Admin, Prod Admin) to #1 and #2. Pressing Enter logs you in within 1 second.
• 🔍 Interactive Substring Search: Type any keyword (prod, qa, admin, gpu, eks) at the selection prompt to instantly filter dozens of accounts.
• 🤖 Native Model Context Protocol (MCP) Server: Expose AWS profile switching, caller identity, and EC2/EKS exploration to LLM pair programmers (Claude Desktop, Cursor, Antigravity, Gemini).
• 🔒 Enterprise-Grade Security: Strict POSIX 0600 file permissions, atomic file replacement (os.replace), and 300-second expiration safety margins.
• 🌐 WSL2 Seamless Browser Bridge: Automatically detects WSL2 and opens authorization URLs directly in your Windows host browser.
• ☸️ DevOps Acceleration: Instant EC2 SSM shell sessions and 1-click Amazon EKS kubeconfig context switching.

---

📦 Installation

Option 1: Standalone Binary (Recommended)

Download the latest pre-compiled binary from GitHub Releases:

Windows (PowerShell 1-Liner)

Run in PowerShell to automatically download the binary and configure your PATH:

irm https://raw.githubusercontent.com/N0mansky/aws-auth/main/install.ps1 | iex

Or manual download via PowerShell:

curl.exe -L https://github.com/N0mansky/aws-auth/releases/latest/download/aws-auth-windows-amd64.exe -o aws-auth.exe

Linux (x86_64)

curl -L https://github.com/N0mansky/aws-auth/releases/latest/download/aws-auth-linux-amd64 -o aws-auth
chmod +x aws-auth && sudo mv aws-auth /usr/local/bin/

macOS (Universal)

curl -L https://github.com/N0mansky/aws-auth/releases/latest/download/aws-auth-macos-universal -o aws-auth
chmod +x aws-auth && sudo mv aws-auth /usr/local/bin/

Option 2: Install via pip

pip install git+https://github.com/N0mansky/aws-auth.git

Option 3: Clone & Install from Source

git clone https://github.com/N0mansky/aws-auth.git
cd aws-auth

./install.sh                      # Linux / macOS / WSL2
powershell .\install.ps1          # Windows (PowerShell)
.\install.bat                     # Windows (Command Prompt)

---

🚀 Quick Start

1. Interactive Login

aws-auth

Available account-role combinations (Showing 1-10 of 18):
+-----+------------------------------+-----------------+------------------------------+-------------+
| #   | Account                      | Account ID      | Role                         | Region      |
+-----+------------------------------+-----------------+------------------------------+-------------+
| 1   | ⭐ Production-App (PROD)        | (111222333444)  | AdministratorAccess     | us-east-1   |
| 2   | ⭐ Staging-Web (QA)          | (555666777888)  | AdministratorAccess     | us-east-1   |
| 3   | Analytics-Data                  | (999888777666)  | AdministratorAccess     | us-east-1   |
...
Select number 1-10 (default: 1) (type keyword to filter): [ENTER]

✅ Profile 'production-app-admin' set as default in ~/.aws/credentials.

2. Configure Portal & Custom Aliases

aws-auth --configure

Customize environment labels and preferred accounts in ~/.aws-auth/config.json:

{
  "sso_start_url": "https://my-company.awsapps.com/start",
  "sso_region": "us-east-1",
  "preferred_accounts": ["Staging-Web", "Production-App"],
  "aliases": {
    "555666777888": "QA",
    "111222333444": "PROD"
  }
}

---

🤖 AI Agent Integration (Model Context Protocol)

aws-auth runs as a high-performance MCP Server over stdio.

Add to Claude Desktop (claude_desktop_config.json) or Cursor:

{
  "mcpServers": {
    "aws-auth": {
      "command": "aws-auth",
      "args": ["--mcp"]
    }
  }
}

What AI Assistants Can Do with aws-auth:

• Check active AWS Account, Region, and IAM Role ARN (aws_get_caller_identity).
• Switch active AWS profile (aws_switch_profile) without human intervention.
• Inspect running EC2 instances and Amazon EKS clusters (aws_list_ec2_instances, aws_list_eks_clusters).
• Update local Kubernetes context (aws_update_kubeconfig).

👉 Read the full MCP Setup & Tool Reference Guide.

---

🛠️ CLI Command Reference

# Core Authentication
aws-auth                     # Interactive SSO login & smart role switch
aws-auth --configure         # Interactive SSO portal setup
aws-auth --identity          # Show current STS caller identity
aws-auth --refresh-cache     # Force refresh remote account/role metadata

# Profile Management
aws-auth --list-profiles     # List all stored AWS profiles
aws-auth --switch-profile    # Switch active default profile
aws-auth --set-default NAME  # Set specific profile as default
aws-auth --delete NAME       # Delete profile credentials

# Resource Discovery & DevOps
aws-auth --list-ec2          # List EC2 instances and connect via SSM
aws-auth --list-eks          # List EKS clusters and update kubeconfig

# Scripting & Headless Automation
aws-auth --list-profiles --json
aws-auth --identity --json
eval $(aws-auth --export-env prod-profile)  # Export AWS keys to current shell

# AWS credential_process standard
aws-auth --credential-process my-profile

---

📚 Documentation

• 📊 Comparison with AWS CLI, Granted & AWS-Vault
• 🤖 Model Context Protocol (MCP) Guide
• 🐧 WSL2 Setup & Windows Integration Guide
• 💻 Linux Detailed Installation
• 🪟 Windows Detailed Installation

---

🤝 Contributing

Contributions are welcome! Please check out CONTRIBUTING.md for details on setting up a development environment and running tests.

---

📄 License

This project is licensed under the MIT License.