saml2aws-multi

GitHub last commit

A helper script providing an easy-to-use command line interface to login and retrieve AWS temporary credentials for multiple roles across different accounts using saml2aws.

Example-RoleName

All notable changes to this project will be documented in CHANGELOG.

Supports Python 3.10, 3.11, 3.12, 3.13

✨ Features

🔧 Development Tools

Poetry - Modern dependency management
Makefile - Convenient command shortcuts for common tasks
pytest - Testing framework with coverage reporting
black - Code formatting
flake8 - Python code linting

🔐 Security & Code Quality

CodeQL - Automated security analysis (workflow)
Secrets Scan - Gitleaks and TruffleHog for detecting hardcoded secrets (workflow)
Snyk - Vulnerability scanning (workflow)
Dependabot - Automated dependency updates (config)

🚀 CI/CD

GitHub Actions - Automated testing across Python 3.10-3.13
Codecov - Code coverage reporting
Stale Issue Management - Automatically closes inactive issues

Usage

$ awslogin --help
Usage: awslogin [OPTIONS] COMMAND [ARGS]...

  Get credentials for multiple accounts with saml2aws

Options:
  -l, --shortlisted TEXT          Show only roles with the given keyword(s);
                                  e.g. -l keyword1 -l keyword2...

  -s, --pre-select TEXT           Pre-select roles with the given keyword(s);
                                  e.g. -s keyword1 -s keyword2...

  -n, --profile-name-format [RoleName|RoleName-AccountAlias]
                                  Set the profile name format.  [default:
                                  RoleName]

  -r, --refresh-cached-roles      Re-retrieve the roles associated to the
                                  username and password you providedand save
                                  the roles into <home>/.saml2aws-
                                  multi/aws_login_roles.csv.  [default: False]

  -t, --session-duration TEXT     Set the session duration in seconds,
  -b, --browser-autofill          Enable browser-autofill.
  -d, --debug                     Enable debug mode.  [default: False]
  --help                          Show this message and exit.

Commands:
  chained  List chained role profiles specified in ~/.aws/config
  switch   Switch default profile
  whoami   Who am I?

Usage Examples

When you run awslogin the first time, the script retrieves the roles associated to the username and password you provided, then saves the roles to <user_home>/.saml2aws-multi/aws_login_roles.csv, such that the script does not need to call list_roles every time you run awslogin.

For example, if you have role ARNs like:
```
 RoleArn, AccountAlias
 arn:aws:iam::123456789012:role/aws-01-dev, aws-01
 arn:aws:iam::123456789012:role/aws-01-tst, aws-01
 arn:aws:iam::213456789012:role/aws-02-dev, aws-02
 arn:aws:iam::313456789012:role/aws-03-dev, aws-03
```
Then, the profile names will look like

To refresh the content of aws_login_roles.csv, just run
```
 awslogin --refresh-cached-roles
```
When you run awslogin, the script pre-selects the options you selected last time.
Use --pre-select or -s to pre-select option by keyword(s).
```
 awslogin -s dev -s tst
```
Use --shortlisted or -l to show the list of roles having profile name matching the given keyword(s).
```
 awslogin -l dev -l tst
```
To change your default profile in <user_home>/.aws/credentials, run
```
 awslogin switch
```
If you have roles in different accounts with the same role names, you can use --profile-name-format RoleName-AccountAlias, such that the profile names will include both role name and account alias. Alternatively, you can also change DEFAULT_PROFILE_NAME_FORMAT in the code to RoleName-AccountAlias.

For example, if you have role ARNs like:
```
 RoleArn, AccountAlias
 arn:aws:iam::123456789012:role/dev, aws-01
 arn:aws:iam::123456789012:role/tst, aws-01
 arn:aws:iam::213456789012:role/dev, aws-02
 arn:aws:iam::313456789012:role/dev, aws-03
```
Then, the profile names will look like

🚀 Installation

Prerequisites

Before installing, ensure you have:

Python 3.10+ installed
saml2aws installed
- See install-saml2aws.sh for a Linux installation script
- For other platforms, follow the official installation guide
saml2aws config file (~/.saml2aws) - Run saml2aws configure to create

Installation Options

Choose the installation method that best fits your use case:

Option 1: pipx (Recommended for end users)

pipx installs the CLI in an isolated environment while making it globally available:

# Install pipx if needed
pip install pipx

# Install saml2awsmulti
pipx install .

# Run from anywhere
awslogin --help
awslogin

Option 2: pip (Simple installation)

# Install directly with pip
pip install .

# Run the CLI
awslogin --help
awslogin

Option 3: Development Installation

For contributing or development work:

# Quick setup (recommended for first-time setup)
make setup-init

# Manual setup (alternative)
make setup-venv    # Configure Poetry virtualenv
make install-all   # Install all dependencies

# Run with Poetry
poetry run awslogin --help
poetry run awslogin

# Or activate the virtualenv
poetry shell
awslogin

# View all available commands
make help

📋 Development Workflow

Common Commands

make setup-init         # First-time setup (configure, lock, install everything)
make help               # Show all available commands
make install-all        # Install all dependencies (main, dev, test)
make test               # Run tests without coverage
make test-with-coverage # Run tests with coverage
make format-python      # Auto-format Python code
make lint-python        # Lint Python code
make lint-yaml          # Lint YAML files
make pre-commit         # Run all quality checks (format, lint, test)
make build              # Build the package
make clean              # Clean build artifacts

Running Tests

# Run tests with coverage
make test-with-coverage

# Run tests only
make test

# Format and lint code
make format-python
make lint-python
make lint-yaml

# Run all quality checks before committing
make pre-commit

Managing Dependencies

# Update dependencies to latest compatible versions
make update-deps

# Regenerate lock file
make lock

🏗️ Project Structure

saml2aws-multi/
├── .github/
│   ├── workflows/        # CI/CD workflows
│   └── dependabot.yml    # Dependency updates config
├── saml2awsmulti/        # Main Python package
│   ├── __init__.py
│   ├── aws_login.py      # Main CLI logic
│   ├── file_io.py
│   ├── saml2aws_helper.py
│   └── selector.py
├── tests/                # Unit tests
│   ├── test_aws_login.py
│   ├── test_file_io.py
│   ├── test_saml2aws_helper.py
│   └── test_selector.py
├── pyproject.toml        # Project metadata and dependencies
├── Makefile              # Build and test commands
├── CHANGELOG.md          # Version history and changes
├── CODE_OF_CONDUCT.md    # Community guidelines
├── CONTRIBUTING.md       # Contribution guidelines
├── SECURITY.md           # Security policy
└── README.md             # This file

🤝 Contributing

Contributions are welcome! Please see:

CONTRIBUTING.md - Contribution guidelines
CODE_OF_CONDUCT.md - Community standards

🔒 Security

For security issues, please see SECURITY.md for our security policy and reporting guidelines.

This site is open source. Improve this page.