ssof 0.1.0

A simple CLI tool to manage AWS SSO sessions

Tori - AWS SSO Session Manager

Ultra-simple CLI tool to manage AWS SSO sessions across multiple organizations. Configure once per org, then just tori assume <account> and you're in!

Installation

Tori uses uv for dependency management.

# Install uv if you don't have it
brew install uv  # or: curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies and install tori in editable mode
uv sync

# Run tori via uv (no activation needed)
uv run tori --help

# Or activate the venv to use `tori` directly
source .venv/bin/activate
tori --help

Quick Start

1. Configure Tori with your SSO details:

tori configure my-org

Enter your SSO start URL and region when prompted. Tori will authenticate and cache all available accounts.

2. List available accounts:

tori list

This shows all AWS accounts you have access to via SSO across all configured orgs.

3. Assume a role:

tori assume my-account-name

This will:

• Authenticate with AWS SSO (if needed)
• Get temporary credentials
• Back up your current default profile (if exists) to a named profile
• Configure your default AWS CLI profile automatically
• You're ready to use AWS CLI immediately!

Commands

tori configure <org-name>

Configure AWS SSO settings for an organization. You can configure multiple orgs.

Example:

tori configure my-company
# Enter SSO start URL: https://my-company.awsapps.com/start
# Enter SSO region: us-east-1

The first org you configure becomes the default. All accounts will be cached automatically.

tori assume <account> [org-name]

Assume an AWS SSO role and configure the default AWS profile with credentials.

Examples:

# Assume by account name (uses default org)
tori assume production

# Assume by account ID
tori assume 123456789012

# Assume from specific org
tori assume production my-company

# Assume with specific role (skips interactive selection)
tori assume production my-company --role AdminRole

Profile Backup: When you assume a new role, Tori automatically backs up your current default profile to profile_<account_id>_<role_name> so you can switch back later.

tori refresh [org-name]

Refresh cached accounts for an organization. Use this when new accounts or roles are added.

Examples:

# Refresh default org
tori refresh

# Refresh specific org
tori refresh my-company

tori list [org-name]

List all configured orgs and their AWS SSO accounts.

Examples:

# List all orgs and accounts
tori list

# List accounts for specific org
tori list my-company

tori status

Check your current AWS credentials status and see all backed up profiles.

tori default <org-name>

Set the default organization to use when org name is not specified.

Example:

tori default my-company

Configuration

Tori stores its configuration in ~/.tori/config.yaml:

default_org: my-company
orgs:
  my-company:
    sso_start_url: https://my-company.awsapps.com/start
    sso_region: us-east-1
    cached_accounts:
      production:
        accountId: '123456789012'
        accountName: production
        email: [e-mail]
        roles:
          - AdminRole
          - ReadOnlyRole
  another-org:
    sso_start_url: https://another-org.awsapps.com/start
    sso_region: us-west-2
    cached_accounts: {}
active_profiles:
  profile_123456789012_AdminRole:
    account_id: '123456789012'
    role_name: AdminRole
    timestamp: '2025-11-21T10:30:00'

Credentials are automatically written to ~/.aws/credentials (default profile).

Multi-Org Workflow

Tori supports multiple SSO organizations:

1. Configure multiple orgs:

tori configure company-prod
tori configure company-dev
tori configure client-org

2. Set a default org (optional):

tori default company-prod

3. Assume roles:

# Uses default org
tori assume my-account

# Uses specific org
tori assume my-account company-dev

4. List all orgs:

tori list

Profile Management

When you assume a new role, Tori:

1. Backs up your current default profile to a named profile
2. Sets the new credentials as the default profile
3. Tracks all backed up profiles in the config

Backed up profile naming: profile_<account_id>_<role_name>

View backed up profiles:

tori status

Switch back to a previous profile: Simply use tori assume with the account and role you want to switch to.

How it Works

1. One-time setup per org: Store your SSO start URL and region
2. Automatic caching: Accounts and roles are cached during configuration
3. Explicit refresh: Only re-fetch accounts when you run tori refresh
4. Assume roles:
   • Authenticate via AWS SSO (browser-based, only when needed)
   • Get temporary credentials for the selected account and role
   • Backup current default profile
   • Write new credentials to default AWS profile
   • Use AWS CLI normally!

No need to manage multiple profiles manually or remember account details - just use the account name!

Requirements

• Python 3.8+
• boto3 (AWS SDK)
• click (CLI framework)
• questionary (interactive prompts)
• pyyaml (config management)
• Internet connection for SSO authentication