Documentation updates

Author: epierce

README.md

@@ -4,9 +4,9 @@
 
 ## Project Overview
 
-**Type:** CLI (Python command-line tool)  
-**Language:** Python 3.10+  
-**Architecture:** Modular authentication system with pluggable MFA providers  
+**Type:** CLI (Python command-line tool)
+**Language:** Python 3.10+
+**Architecture:** Modular authentication system with pluggable MFA providers
 **Released Version:** 2.8.2
 **Latest Version:** 2.9.0-pre
 
@@ -15,18 +15,17 @@
 | Property | Value |
 |----------|-------|
 | **Tech Stack** | Python 3.10+, boto3, requests, fido2 |
-| **Entry Point** | `bin/gimme-aws-creds` → `gimme_aws_creds.main` |
-| **Config File** | `~/.okta_aws_login_config` |
-| **Output** | `~/.aws/credentials` or stdout |
+| **Entry Point** | `bin/gimme-aws-creds` -> `gimme_aws_creds.main` |
+| **Config File** | `~/.okta_aws_login_config` (override via `OKTA_CONFIG`) |
+| **AWS Output** | `~/.aws/credentials` or stdout |
+| **Alibaba Cloud Output** | `~/.aliyun/config.json` or stdout (override via `ALIBABA_CLOUD_SHARED_CREDENTIALS_FILE`) |
 
 ## Generated Documentation
 
 ### Core Documentation
 
 - [Project Overview](./project-overview.md) - Executive summary, features, tech stack
 - [Architecture](./architecture.md) - System design, components, authentication flows
-- [Source Tree Analysis](./source-tree-analysis.md) - Directory structure, module responsibilities
-- [Development Guide](./development-guide.md) - Setup, testing, contributing
 
 ## Existing Documentation
 
@@ -62,47 +61,72 @@ gimme-aws-creds --action-configure
 
 # Get credentials
 gimme-aws-creds
+
+# Debug a configuration / authentication issue
+gimme-aws-creds --debug
 ```
 
 ## Module Quick Reference
 
 | Module | Purpose |
 |--------|---------|
-| `main.py` | Main orchestrator, credential handling |
-| `common.py` | Shared utilities: HTTP session factory, SAML parsing, User-Agent, `OktaHttpMixin`, token exchange |
-| `config.py` | Configuration management |
+| `main.py` | Main orchestrator, credential handling, AWS/AliCloud dispatch |
+| `common.py` | Shared utilities: HTTP session factory, SAML parsing, `user_agent()`, `request_headers_json()`, `OktaHttpMixin`, `okta_token_exchange()`, `FakeAssertion`, `RoleSet` |
+| `config.py` | Configuration management (CLI args, profiles, env vars, source tracking for `--debug`) |
+| `debug_formatter.py` | HTTP request/response debug formatting, sensitive-data redaction, resolved-configuration reporting |
 | `okta_classic.py` | Okta Classic authentication + MFA |
-| `okta_identity_engine.py` | Okta Identity Engine (OIE) auth |
-| `aws.py` | AWS role resolution, SAML parsing |
-| `alibaba_cloud.py` | Alibaba Cloud (AliCloud) RAM credential support |
-| `duo.py` / `duo_universal.py` | DUO MFA handlers |
-| `webauthn.py` / `u2f.py` | FIDO/hardware key MFA |
-| `ui.py` | User interface abstraction |
+| `okta_identity_engine.py` | Okta Identity Engine (OIE) auth via Device Authorization flow |
+| `aws.py` | AWS role resolution, SAML parsing, account-alias lookup |
+| `alibaba_cloud.py` | Alibaba Cloud (AliCloud) RAM credential support (Native-to-Web SSO) |
+| `duo.py` / `duo_universal.py` | DUO MFA handlers (iframe + Universal Prompt) |
+| `webauthn.py` / `dummy_webauthn.py` / `u2f.py` | FIDO2 / hardware key MFA (`dummy_webauthn.py` is a fallback used when WebAuthn is unavailable on the platform) |
+| `registered_authenticators.py` | Persists registered FIDO authenticator credential IDs |
+| `default.py` | Default `Resolver` implementation for app/role enumeration prompts |
+| `ui.py` | User interface abstraction (`UserInterface`, `CLIUserInterface`) |
 | `errors.py` | Exception hierarchy |
 
 ## Authentication Flows
 
 ### Okta Classic
-1. Username/password → Okta authn API
+1. Username/password -> Okta authn API
 2. MFA challenge (if required)
-3. Session token → SAML assertion
-4. AWS STS → Temporary credentials
+3. Session token -> SAML assertion
+4. AWS STS -> Temporary credentials
 
 ### Okta Identity Engine
 1. Device authorization request
 2. User authenticates in browser
-3. Token exchange → Web SSO token
-4. SAML assertion → AWS STS
+3. Token exchange -> Web SSO token
+4. SAML assertion -> AWS STS (or Alibaba Cloud STS for AliCloud profiles)
+
+## Cloud Provider Support
+
+| Provider | Auth Flow | STS API | Output |
+|----------|-----------|---------|--------|
+| **AWS** | Classic or OIE | `sts:AssumeRoleWithSAML` (boto3) | `~/.aws/credentials` |
+| **Alibaba Cloud** | OIE only (Native-to-Web SSO) | RAM `AssumeRoleWithSAML` (alibabacloud-sts SDK) | `~/.aliyun/config.json` |
+
+Alibaba Cloud support is opt-in via the `gimme-aws-creds[alicloud]` extra and the `enable_alicloud` profile setting.
 
 ## Key Integration Points
 
-- **Okta APIs**: `/api/v1/authn`, `/oauth2/v1/*`
-- **AWS STS**: `assume_role_with_saml`
-- **DUO Security**: iframe/Universal Prompt flows
-- **FIDO2**: Hardware authenticator support
+- **Okta APIs**: `/api/v1/authn`, `/oauth2/v1/device/authorize`, `/oauth2/v1/token`
+- **AWS STS**: `assume_role_with_saml` (standard, GovCloud, and China partitions)
+- **Alibaba Cloud STS**: `AssumeRoleWithSAML` (1 hour session cap)
+- **DUO Security**: iframe + Universal Prompt flows
+- **FIDO2 / WebAuthn**: Hardware authenticator support via `fido2` and `ctap-keyring-device`
+
+## Debug & Troubleshooting
+
+The `--debug` flag enables structured HTTP request/response logging via `debug_formatter.py`:
+
+- Colorized request/response sections written to stderr
+- Sensitive fields (`access_token`, `id_token`, `sessionToken`, `stateToken`, `password`, `SAMLResponse`, `SAMLAssertion`, `passCode`, `Authorization`, `Cookie`, etc.) are redacted
+- Embedded `AssumeRoleWithSAMLResponse` payloads from AWS STS are redacted
+- A "Resolved Configuration" report shows the final config values and the source of each (CLI flag, env var, profile, inheritance, default)
 
 ---
 
-*Documentation generated: 2026-01-09*  
-*Last updated: 2026-04-05*  
+*Documentation generated: 2026-01-09*
+*Last updated: 2026-05-05*
 *Scan level: exhaustive*

docs/architecture.md

@@ -2,7 +2,7 @@
 
 ## Executive Summary
 
-**gimme-aws-creds** is a Python CLI tool that acquires temporary AWS credentials via AWS STS using Okta as a SAML Identity Provider (IdP). It supports both Okta Classic and Okta Identity Engine authentication flows with comprehensive MFA support.
+**gimme-aws-creds** is a Python CLI tool that acquires temporary AWS credentials via AWS STS using Okta as a SAML Identity Provider (IdP). It supports both Okta Classic and Okta Identity Engine authentication flows with comprehensive MFA support, and can also retrieve Alibaba Cloud RAM credentials via the same Okta authentication flow.
 
 ## Project Metadata
 
@@ -23,54 +23,73 @@ Organizations using Okta for SSO to AWS need a way to obtain temporary AWS crede
 1. Authenticating users via Okta (Classic or Identity Engine)
 2. Handling multi-factor authentication (MFA) flows
 3. Retrieving SAML assertions from Okta
-4. Exchanging SAML assertions for AWS STS temporary credentials
-5. Writing credentials to `~/.aws/credentials` or outputting to stdout
+4. Exchanging SAML assertions for AWS STS (or Alibaba Cloud RAM) temporary credentials
+5. Writing credentials to `~/.aws/credentials` (or `~/.aliyun/config.json`) or outputting to stdout
 
 ## Key Features
 
 - **Dual Okta Platform Support**: Works with both Okta Classic and Okta Identity Engine domains
-- **Comprehensive MFA**: Push, TOTP, SMS, Email, Voice Call, DUO, WebAuthn, U2F, Hardware Tokens
-- **Multiple Output Formats**: Shell exports, JSON, Windows PowerShell
-- **Profile Management**: Multiple configuration profiles with inheritance
-- **AWS Account Resolution**: Resolves account IDs to friendly aliases
-- **Credential Storage**: Automatic storage in AWS credentials file with expiration tracking
-- **Lambda Integration**: Optional gimme-creds-lambda proxy for API key-less operation
+- **Comprehensive MFA**: Push, TOTP, SMS, Email, Voice Call, DUO (iframe + Universal Prompt), WebAuthn, U2F, hardware tokens
+- **Multi-Cloud Output**: AWS STS (standard, GovCloud, China partitions) and Alibaba Cloud RAM
+- **Multiple Output Formats**: Shell exports (`export`), JSON, Windows PowerShell (`windows`)
+- **Profile Management**: Multiple configuration profiles with inheritance via `inherits = parent_profile`
+- **AWS Account Resolution**: Resolves account IDs to friendly aliases by scraping the AWS sign-in page
+- **Credential Storage**: Automatic storage in AWS credentials file with `x_security_token_expires` (RFC3339) for expiration tracking
+- **Lambda Integration**: Optional [gimme-creds-lambda](https://github.com/Nike-Inc/gimme-aws-creds/tree/master/lambda) proxy for API key-less operation
+- **Debug & Diagnostics**: `--debug` produces structured request/response logs and a "Resolved Configuration" report (with source attribution: CLI / env / profile / default), with automatic redaction of sensitive payloads (SAML responses, OAuth tokens, passwords, authorization headers)
+- **Source-Attribution Tracking**: `Config` records, per value, whether it came from a CLI flag, environment variable, profile setting, inherited profile, or default
 
 ## Technology Stack
 
 | Category | Technology | Version |
 |----------|------------|---------|
 | **Language** | Python | `3.10+` |
-| **AWS SDK** | boto3 | `>=1.7.70,<2.0.0` |
-| **HTTP** | requests | `>=2.25.0,<3.0.0` |
-| **HTML Parsing** | beautifulsoup4 | `>=4.6.0,<5.0.0` |
-| **Okta SDK** | okta | `>=2.9.0,<3.0.0` |
-| **FIDO2/WebAuthn** | fido2 | `>=0.9.1,<0.10.0` |
-| **JWT** | pyjwt | `>=2.4.0,<3.0.0` |
-| **Keyring** | keyring | `>=21.4.0` |
+| **AWS SDK** | boto3 | `>=1.42.24,<2.0.0` |
+| **HTTP** | requests | `>=2.31.0,<3.0.0` |
+| **HTTP transport** | urllib3 | `>=2.6.3,<3.0.0` |
+| **HTML Parsing** | beautifulsoup4 | `>=4.14.3,<5.0.0` |
 | **HTML5** | html5lib | `>=1.1,<2.0.0` |
+| **Okta SDK** | okta | `>=2.9.13,<3.0.0` |
+| **FIDO2/WebAuthn** | fido2 | `>=0.9.1,<0.10.0` |
+| **CTAP keyring (FIDO via system keychain)** | ctap-keyring-device | `==1.0.6` (non-Win or Python <3.10 on Windows) |
+| **JWT** | pyjwt | `>=2.10.1,<3.0.0` |
+| **Keyring** | keyring | `>=25.6.0,<26.0.0` |
 | **URL Parsing** | furl | `>=2.1.4,<3.0.0` |
+| **(Optional) Alibaba Cloud STS** | alibabacloud-sts20150401 | `>=1.2.0,<2.0.0` (extras `[alicloud]`) |
+
+### Development / Test Dependencies
+
+| Tool | Purpose |
+|------|---------|
+| `pytest` (`>=7.2.2`) | Unit test runner |
+| `responses` (`>=0.5.1,<1.0.0`) | HTTP mocking for `requests` |
+| `alibabacloud_sts20150401` | Required for `tests/test_alibaba_cloud.py` |
 
 ## Architecture Pattern
 
 The project follows a **Command-Line Application Pattern** with:
+
 - Modular authentication providers (Okta Classic, Okta Identity Engine)
-- Pluggable MFA factor handlers
-- Strategy pattern for AWS role resolution
-- Dependency injection for UI abstraction
-- Shared utility layer (`common.py`) for HTTP session management, SAML parsing, and cross-cutting concerns
+- Pluggable MFA factor handlers (Okta factors, DUO, FIDO2, U2F)
+- Strategy pattern for AWS / Alibaba Cloud role resolution (`DefaultResolver`)
+- Dependency injection for UI abstraction (`UserInterface`)
+- Shared utility layer (`common.py`) for HTTP session management, SAML parsing, OAuth token exchange, and cross-cutting concerns
 - Mixin-based code reuse (`OktaHttpMixin`) for Okta HTTP client classes
+- Dedicated debug/diagnostics layer (`debug_formatter.py`) with sensitive-data redaction and configuration source attribution
+- Lazy-loaded, cached properties on `GimmeAWSCreds` (`config`, `okta`, `auth_session`, `aws_results`, `saml_data`, `aws_roles`)
 
 ## Installation Methods
 
 1. **PyPI**: `pip install gimme-aws-creds`
-2. **GitHub**: `pip install git+github.com/Nike-Inc/gimme-aws-creds`
-3. **Homebrew**: `brew install gimme-aws-creds`
-4. **Nix**: Flake and shell.nix support
-5. **Docker**: Dockerfile included
+2. **PyPI (with Alibaba Cloud)**: `pip install "gimme-aws-creds[alicloud]"`
+3. **GitHub**: `pip install git+https://github.com/Nike-Inc/gimme-aws-creds`
+4. **Homebrew (macOS)**: `brew install gimme-aws-creds`
+5. **Nix**: `flake.nix` (`nix develop`) and `shell.nix` (`nix-shell`) provided
+6. **Docker**: `Dockerfile` included; mount `~/.aws/credentials` and `~/.okta_aws_login_config` into the container
 
 ## Related Documentation
 
 - [Architecture](./architecture.md)
-- [Source Tree Analysis](./source-tree-analysis.md)
-- [Development Guide](./development-guide.md)
+- [README.md](../README.md) - End-user documentation
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guide
+- [lambda/README.md](../lambda/README.md) - Optional gimme-creds-lambda proxy

docs/development-guide.md

@@ -327,7 +327,7 @@ def update_config_file(self):
                 preferred_mfa_type = (optional, Okta Classic only) Select this MFA device type automatically
                 include_path - (optional) includes the full role path to the role name for profile
                 enable_keychain = (optional, Okta Classic only) enable the use of the system keychain to store the user's password
-                enable_alicloud = (optional, OIE only) y/n — use Native-to-Web SSO scope for Alibaba Cloud RAM
+                enable_alicloud = (optional, OIE only) y/n - use Native-to-Web SSO scope for Alibaba Cloud RAM
                 alicloud_saml_url = (optional, Alibaba Cloud only) explicit SAML SSO URL for the Alibaba Cloud app in Okta; falls back to the app link if not set
                 alicloud_region = (optional, Alibaba Cloud only) Alibaba Cloud STS region used for AssumeRoleWithSAML (default: cn-hangzhou)
 

docs/index.md

@@ -1,5 +1,5 @@
 -r requirements.txt
-# Optional Alibaba Cloud SDK (matches setup.py extras_require['alicloud']) — needed for Alibaba Cloud STS tests
+# Optional Alibaba Cloud SDK (matches setup.py extras_require['alicloud']) - needed for Alibaba Cloud STS tests
 alibabacloud_sts20150401>=1.2.0,<2.0.0
 responses>=0.5.1,<1.0.0
 pytest>=7.2.2

docs/project-overview.md

@@ -200,7 +200,7 @@ def test_env_okta_config_path_label(self):
             argv=['--profile', 'myprofile'],
         )
         # Reuse the config file already on disk under test_ui2.HOME? Not
-        # quite — env points to the original cfg_path.
+        # quite - env points to the original cfg_path.
         config = Config(gac_ui=test_ui2, create_config=False)
         config.conf_profile = 'myprofile'
         conf_dict = config.get_config_dict()