ssof

Simple CLI tool to manage AWS SSO sessions across multiple organizations. Configure once per org, then just ssof assume <account> and you're in.

Install

pip install ssof

# Enable shell completion (bash/zsh/fish)
eval "$(ssof completion bash)"   # add to ~/.bashrc

For local development:

uv sync
eval "$(uv run ssof completion bash)"   # add to ~/.bashrc

Usage

# Configure an org
ssof config add my-org

# List cached accounts
ssof list

# Assume a role (interactive picker if no account given)
ssof assume my-account

# By account ID
ssof assume 123456789012

# With specific role
ssof assume my-account --role AdminRole

# Refresh cached accounts
ssof refresh

# Check current session status
ssof status

Commands

Multi-Org

ssof config add company-prod
ssof config add company-dev

When multiple orgs are configured, ssof assume prompts for account selection across all of them.

How it works

1. ssof config add stores your SSO start URL and region
2. Authenticates via browser and caches all accounts
3. ssof assume gets temporary credentials and writes to ~/.aws/credentials
4. Backs up previous session automatically

Config stored in ~/.ssof/config.json.

Important: this tool modifies your AWS files

ssof assume, ssof logout, and switching to a backed-up profile write directly to ~/.aws/credentials and ~/.aws/config using Python's configparser. That means:

• Comments and formatting in those files are not preserved. If you hand-edit ~/.aws/credentials or ~/.aws/config (comments, blank lines, custom ordering), configparser will silently drop comments on the next write. The first time ssof ever writes to either file, it saves a pristine, untouched copy to ~/.ssof/backups/credentials.original and ~/.ssof/backups/config.original respectively (owner-readable only), so the original is always recoverable — but the live file itself will lose that formatting.
• Profiles ssof doesn't touch are preserved. Other [profile] sections in your credentials/config files are left alone.
• ~/.aws/credentials is kept at chmod 600 (owner read/write only) after every write, matching the AWS CLI's own convention for that file, since it holds long-lived or temporary secret keys.

Requirements

• Python 3.10+
• boto3, click, questionary

License

MIT — see LICENSE.