aSSO - AWS SSO Utility

A terminal user interface (TUI) application for managing AWS SSO profiles and authentication across multiple AWS Organizations and accounts.

Features

• Configure SSO Profiles: Connect to AWS SSO start pages, discover accounts and roles, and automatically generate profiles in ~/.aws/config
• Fast SSO Login: Select from configured profiles and authenticate to get temporary AWS credentials
• Quick CLI Login: Instantly switch profiles with asso <company> <environment> for shell integration
• Smart Role Selection: Automatically selects best-practice roles (PowerUserAccess > Admin > Developer) with customizable preferences
• Profile Naming: Consistent company-environment naming convention extracted from SSO URLs and account names
• Multi-Organization Support: Manage profiles across multiple AWS Organizations
• User-Friendly TUI: Interactive terminal interface built with Bubbletea with full-screen support
• Profile Search: Quick filter with / key to find profiles instantly
• Role Management: Change roles for existing profiles with saved preferences
• Credential Export: Get export commands for setting AWS credentials in your shell
• Auto Environment Detection: Detects prod, dev, staging, test, qa, sandbox environments from account names

Installation

Build from Source

go build -o asso

Install to PATH

go install

Or move the binary to your PATH:

mv asso /usr/local/bin/

Usage

Interactive TUI Mode

Run the application without arguments to launch the interactive TUI:

asso

Configure SSO

1. Select "Configure SSO (Add new profiles)" from the main menu
2. Enter your AWS SSO start URL (e.g., https://my-company.awsapps.com/start)
3. Enter the SSO region (e.g., us-east-1)
4. Open the provided URL in your browser and enter the code shown
5. After authentication, a Role Review screen appears showing all accounts with auto-selected roles:
   • Smart role selection automatically picks PowerUserAccess, Admin, or Developer based on availability
   • Navigate with ↑/↓ keys
   • Press e or r to change the role for any account
   • Press Enter to save all profiles with the selected roles
6. Profiles are saved to ~/.aws/config with the format company-environment
7. Role preferences are saved to ~/.aws/asso-preferences.json for future use

Login to AWS (Interactive)

1. Select "Login to AWS Profile" from the main menu
2. Browse profiles or press / to filter by name
3. Navigate with ↑/↓ keys or use vim bindings (j/k)
4. Press e or r on any profile to change its role
5. Press Enter to select a profile and get credentials
6. Copy the export commands shown to set credentials in your shell

Quick CLI Login Mode

For rapid profile switching, use the command-line mode:

# Basic usage
asso <company> <environment>

# Examples
asso mycompany prod
asso acme dev
asso example staging

# Use with eval to set credentials in current shell
eval $(asso mycompany prod)

This mode:

• Instantly loads credentials without interactive prompts
• Clears existing AWS environment variables first
• Outputs export commands ready for eval
• Perfect for shell scripts and automation
• Shows helpful error messages if profile not found

Shell Integration Example:

Add to your .bashrc or .zshrc:

# Quick AWS profile switcher
aws-login() {
    if [ $# -ne 2 ]; then
        echo "Usage: aws-login <company> <environment>"
        return 1
    fi
    eval $(asso $1 $2)
}

# Usage
# aws-login mycompany prod

File Locations

AWS Config File (~/.aws/config)

Profiles are saved in the standard AWS SSO format with the naming convention company-environment:

[profile mycompany-prod]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = PowerUserAccess
region = us-east-1

[profile mycompany-dev]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1
sso_account_id = 987654321098
sso_role_name = Developer
region = us-east-1

Profile Naming Convention:

• Company: Extracted from SSO start URL (e.g., my-company from https://my-company.awsapps.com/start)
• Environment: Auto-detected from account name patterns:
  • prod for Production, Prod, PRD
  • dev for Development, Dev, Develop
  • staging for Staging, Stage, STG
  • test for Test, Testing, TST
  • qa for QA, Quality
  • sandbox for Sandbox, SBX
  • Custom account names are cleaned and used as-is

A backup is created at ~/.aws/config.backup before any modifications.

Role Preferences (~/.aws/asso-preferences.json)

Role selections are saved for future use:

{
  "role_preferences": {
    "123456789012": {
      "account_id": "123456789012",
      "account_name": "Production",
      "role_name": "PowerUserAccess",
      "company": "mycompany"
    }
  }
}

When you configure SSO again for the same organization, your previous role selections are automatically applied.

SSO Token Cache (~/.aws/sso/cache/)

SSO tokens are cached following AWS CLI conventions. Tokens are shared between this tool and the AWS CLI, so you only need to authenticate once.

Keyboard Controls

Main Menu

• ↑/↓ or k/j: Navigate options
• Enter: Select option
• q or Ctrl+C: Quit

SSO Configuration (Input)

• Type to enter text
• Enter: Submit input and continue
• Backspace: Delete character
• Esc: Cancel and return to main menu

Role Review Screen

• ↑/↓ or k/j: Navigate accounts
• e or r: Edit/change role for selected account
• Enter: Save all profiles with current role selections
• Esc: Cancel and return to main menu

Role Change Screen

• ↑/↓ or k/j: Navigate available roles
• Enter: Confirm role selection
• Esc: Cancel role change and return

Profile Selection

• ↑/↓ or k/j: Navigate profiles
• /: Start filter/search mode
• e or r: Change role for selected profile
• Enter: Login with selected profile
• Esc: Back to main menu

Filter Mode (Profile Search)

• Type to filter profiles in real-time
• Backspace: Delete character from filter
• Enter: Select currently highlighted profile
• Esc: Exit filter mode and clear filter

Note: The TUI automatically adjusts to your terminal size and supports scrolling for long lists.

Requirements

• Go 1.21 or later
• AWS SSO-enabled organization
• Network access to AWS SSO endpoints

Development

Running Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run only unit tests (skip integration tests)
go test -short ./...

# Run tests with race detection
go test -race ./...

Test Coverage

The project includes comprehensive test coverage:

• Types package: Type definitions and validations
• AWS config package: Config file parsing and writing
• AWS auth package: Token management and credentials
• AWS SSO package: SSO client operations
• UI components: Bubbletea model and view tests

Current coverage: ~56% overall

• internal/aws: 51.7%
• internal/ui: 59.7%

GitHub Actions

The project includes three CI/CD workflows:

1. Tests (.github/workflows/test.yml)

   • Runs on multiple OS (Ubuntu, macOS, Windows)
   • Tests against Go 1.21, 1.22, and 1.23
   • Includes linting with golangci-lint
   • Uploads coverage to Codecov

2. Build (.github/workflows/build.yml)

   • Creates binaries for multiple platforms
   • Uploads artifacts for each build
   • Creates GitHub releases on version tags

3. Security (.github/workflows/security.yml)

   • Runs govulncheck for vulnerability scanning
   • Runs gosec for security analysis
   • Performs dependency review on PRs

Project Structure

.
├── main.go                    # Entry point with CLI mode
├── internal/
│   ├── aws/
│   │   ├── auth.go           # Token management and credentials
│   │   ├── config.go         # AWS config file operations
│   │   ├── sso.go            # AWS SSO client operations
│   │   ├── utils.go          # Company/environment extraction
│   │   └── preferences.go    # Role preference management
│   ├── ui/
│   │   ├── commands.go       # Bubbletea async commands
│   │   ├── model.go          # Main UI model and state
│   │   ├── styles.go         # UI styling with Lipgloss
│   │   └── view.go           # View rendering for all screens
│   └── types/
│       ├── types.go          # Core type definitions
│       └── preferences.go    # Preference-related types
└── go.mod

Troubleshooting

"No cached token found"

You need to configure SSO first using the "Configure SSO" option in the interactive TUI. This will authenticate and cache a token that's shared with AWS CLI.

"No profile found matching 'company-environment'"

When using CLI mode (asso <company> <env>), ensure:

1. You've configured SSO and saved profiles first
2. The profile name matches exactly (case-insensitive)
3. Check available profiles by running asso without arguments

The tool will show available profiles for the company if an exact match isn't found.

"Failed to load profiles"

Ensure ~/.aws/config exists and is properly formatted. The tool creates it automatically during SSO configuration. Check for syntax errors if you've manually edited the file.

"Failed to get role credentials"

Your SSO token may have expired (tokens typically last 8 hours). Solutions:

1. Run the interactive TUI and select "Configure SSO" to re-authenticate
2. Or run aws sso login --profile <profile-name> using AWS CLI
3. Tokens are shared between asso and AWS CLI

Profile names don't match my account names

Profile names use the format company-environment where:

• company is extracted from your SSO start URL
• environment is auto-detected from account name patterns

To see the exact profile names, launch the interactive TUI and view the profile list.

Role preferences not saving

Ensure ~/.aws directory has write permissions:

chmod 755 ~/.aws

Role preferences are stored in ~/.aws/asso-preferences.json.

TUI not filling terminal window

The TUI automatically adjusts to terminal size. If issues persist:

1. Ensure your terminal emulator is up to date
2. Try resizing the terminal window
3. Check that $TERM environment variable is set correctly

License

MIT