docs: document AWS SSO as recommended auth method (#80)

- Update README: replace static key instructions with SSO guide
  including example ~/.aws/config and aws configure sso workflow
- Update CLAUDE.md AWS section with SSO note
- Update aws_vm.py docstring to include SSO in credential chain

No code changes needed — boto3's default credential chain already
handles SSO transparently.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: abrichr

CLAUDE.md

@@ -124,7 +124,9 @@ oa-vm pool-cleanup -y
 
 ### AWS Support
 
-WAA also runs on AWS EC2 using the same pool commands with `--cloud aws`:
+WAA also runs on AWS EC2 using the same pool commands with `--cloud aws`.
+
+**Auth**: Uses boto3's default credential chain. SSO is recommended: `aws configure sso` (one-time), then `aws sso login` before each session. Static keys (`AWS_ACCESS_KEY_ID`) also work.
 
 ```bash
 # Verify AWS setup (read-only, free)

README.md

@@ -286,13 +286,47 @@ OPENAI_API_KEY=sk-...
 AZURE_SUBSCRIPTION_ID=...
 AZURE_ML_RESOURCE_GROUP=...
 AZURE_ML_WORKSPACE_NAME=...
+```
+
+### AWS authentication
+
+AWS credentials are resolved via [boto3's default credential chain](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html). **SSO (IAM Identity Center) is recommended** for interactive use:
+
+```bash
+# One-time setup — opens a guided wizard
+aws configure sso
+# Prompts for: SSO start URL, region, account, role name, profile name
+
+# Login (opens browser, caches short-lived token)
+aws sso login
+
+# Verify it works
+oa-vm smoke-test-aws
 
-# AWS (for --cloud aws VM management)
-AWS_ACCESS_KEY_ID=...
-AWS_SECRET_ACCESS_KEY=...
-AWS_DEFAULT_REGION=us-east-1
+# All oa-vm --cloud aws commands now work automatically
+oa-vm pool-create --cloud aws --workers 1
+```
+
+<details>
+<summary>Example <code>~/.aws/config</code> for SSO</summary>
+
+```ini
+[default]
+sso_session = my-org
+sso_account_id = 111122223333
+sso_role_name = PowerUserAccess
+region = us-east-1
+
+[sso-session my-org]
+sso_start_url = https://my-org.awsapps.com/start
+sso_region = us-east-1
+sso_registration_scopes = sso:account:access
 ```
 
+</details>
+
+Static keys (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` in `.env`) also work but are not recommended for interactive use -- they don't expire and are a security risk if leaked.
+
 See [`openadapt_evals/config.py`](openadapt_evals/config.py) for all available settings.
 
 ## Custom Agents

openadapt_evals/infrastructure/aws_vm.py

@@ -6,11 +6,17 @@
 
 Requires: pip install boto3  (or: uv sync --extra aws)
 
-Auth uses boto3's default credential chain:
+Auth uses boto3's default credential chain (first match wins):
     1. Environment variables (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
-    2. Shared credentials file (~/.aws/credentials)
-    3. AWS config file (~/.aws/config)
-    4. Instance metadata (on EC2)
+    2. IAM Identity Center / SSO (~/.aws/config with sso_session)
+    3. Shared credentials file (~/.aws/credentials)
+    4. AWS config file (~/.aws/config)
+    5. Instance metadata (on EC2)
+
+SSO is the recommended approach for interactive use:
+    aws configure sso        # one-time setup
+    aws sso login            # opens browser, caches token
+    # Then all oa-vm --cloud aws commands work automatically
 
 Example:
     from openadapt_evals.infrastructure.aws_vm import AWSVMManager