aws-sso-rs

Fetch your local ~/.aws/credentials for every AWS account you can access, using AWS SSO.

Built with ❤ in Rust

Note

AI coding assistants are used in this project for architecture and design guidance, documentation, keeping the repository structure clean and documenting the code. They may also help with non-critical code such as tests, examples or tooling, always reviewed by the maintainer. They are not used for unsafe code or to change the core behaviour of the application unless explicitly instructed. See AGENTS.md for the rules agents follow here.

Table of contents

• Why aws-sso-rs
• Requirements
• Installation
• Usage
• Profile naming and overrides
• Switching AWS_PROFILE
• Limitations
• Development
• Roadmap
• License

Why aws-sso-rs

If your organization has dozens of AWS accounts behind AWS IAM Identity Center (AWS SSO), getting CLI credentials for each of them is tedious. aws-sso-rs runs the SSO device authorization flow once and then fetches the credentials for every account and role you have access to, in parallel, writing them as ready-to-use profiles in ~/.aws/credentials.

• One browser approval, all accounts.
• Concurrent fetching of accounts (15 at a time), see Limitations.
• Profile names are predictable (AccountName@RoleName) and can be overridden.
• Single static binary for Linux and macOS (amd64 and arm64).

Requirements

• AWS IAM Identity Center configured with your IdP (Google Workspace, Okta, ...), and your start URL, for example https://mycompany.awsapps.com/start.
• A browser in which you are already authenticated with your IdP. It has only been tested with Google Workspace.
• fzf (optional), only for the profile switcher.

Installation

From crates.io

cargo install aws-sso-rs

Pre-built binary

The installer detects your OS and architecture, verifies the SHA256 checksum of the download and installs the binary in /usr/local/bin. It needs curl and unzip.

curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/containerscrew/aws-sso-rs/main/install.sh | sh

Install a specific version, or choose another directory:

curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/containerscrew/aws-sso-rs/main/install.sh | sh -s -- -v "v1.5.0"
curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/containerscrew/aws-sso-rs/main/install.sh | INSTALLATION_PATH="$HOME/.local/bin" sh

You can also download the zip for your platform from the releases page.

From source

git clone https://github.com/containerscrew/aws-sso-rs.git
cd aws-sso-rs
cargo build --release
./target/release/aws-sso-rs --help

Note

Windows is not tested nor released. You can try compiling it yourself with cargo build --release.

Usage

aws-sso-rs --start-url https://mycompany.awsapps.com/start --aws-region eu-west-1

1. Your default browser opens the AWS verification page. Check that the device code matches the one shown in the terminal and approve the request.
2. aws-sso-rs waits for your approval on its own, no need to go back to the terminal. The request expires after a few minutes; if it does, run the command again.
3. The credentials of all your accounts are fetched and written to ~/.aws/credentials.

Warning

aws-sso-rs currently overwrites ~/.aws/credentials with the profiles it fetches, so any other profile in that file (for example default) is lost. Back it up first. Merging instead of overwriting is the first item of the roadmap.

Note

The credentials are temporary (the duration is set by your SSO permission set, usually 1 hour). Run the tool again when they expire.

Options

Flag	Description	Default
-s, --start-url	AWS SSO start URL. Required.
-r, --aws-region	Region where SSO is configured.	us-east-1
--role-overrides	Rename role names in the profiles, role=newname[,role2=newname2].
--account-overrides	Rename account names in the profiles, account=new[,account2=new2].
-l, --log-level	error, warn, info, debug or trace.	info
--with-timestamp	Show a timestamp in each log line.	off

aws-sso-rs -s https://mycompany.awsapps.com/start -r eu-west-1

Logging

--log-level sets the base level for every target, including the AWS SDK and its dependencies, so --log-level debug is very verbose. For finer control, use the RUST_LOG environment variable: its per-target directives are applied on top of --log-level.

# debug logs of aws-sso-rs only, everything else stays at --log-level (info)
RUST_LOG=aws_sso_rs=debug aws-sso-rs -s https://mycompany.awsapps.com/start -r eu-west-1

# debug logs of aws-sso-rs plus the AWS SDK HTTP calls
RUST_LOG=aws_sso_rs=debug,aws_config=trace,aws_smithy_runtime=debug aws-sso-rs -s https://mycompany.awsapps.com/start -r eu-west-1

Note

A global directive in RUST_LOG (one without a target, e.g. RUST_LOG=warn) takes precedence over --log-level. A directive with a target (e.g. aws_sso_rs=warn) does not.

Rust AWS SDK logging documentation here

Profile naming and overrides

Each account and role pair becomes a profile named AccountName@RoleName (spaces in the account name are removed):

[Development@AdministratorAccess]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET
aws_session_token = YOUR_SESSION_TOKEN
region = YOUR_REGION

Rename the account part with --account-overrides:

aws-sso-rs -s https://mycompany.awsapps.com/start -r eu-west-1 --account-overrides Development=dev

[Development@AdministratorAccess]  ->  [dev@AdministratorAccess]

Use an empty value in --role-overrides to drop the role from the profile name:

aws-sso-rs -s https://mycompany.awsapps.com/start -r eu-west-1 --role-overrides AdministratorAccess="" --account-overrides Development=dev

[Development@AdministratorAccess]  ->  [dev]

Note

A non-empty --role-overrides value currently replaces the whole profile name, so it only makes sense when a single account has that role. This is tracked in the roadmap.

Switching AWS_PROFILE

A small shell function lets you pick one of the generated profiles with fzf.

Bash / Zsh

Add this to your ~/.zshrc or ~/.bashrc:

function aws-profile() {
    local AWS_PROFILES
    AWS_PROFILES=$(sed -n -e 's/^\[\(.*\)\]/\1/p' ~/.aws/credentials | fzf)
    if [[ -n "$AWS_PROFILES" ]]; then
        export AWS_PROFILE=$AWS_PROFILES
        echo "Selected profile: $AWS_PROFILES"
    else
        echo "No profile selected"
    fi
}

Fish

Save this as ~/.config/fish/functions/aws-profile.fish:

function aws-profile
    set -l selected (sed -n -e 's/^\[\(.*\)\]/\1/p' ~/.aws/credentials | fzf)
    if test -n "$selected"
        set -gx AWS_PROFILE $selected
        echo "Selected profile: $selected"
    else
        echo "No profile selected"
    end
end

Then run aws-profile in your terminal:

Limitations

• Concurrency is capped at 15 accounts at a time. This is a deliberate default to avoid AWS API throttling (HTTP 429 / TooManyRequestsException) from the IAM Identity Center portal API. Requests that are throttled are retried by the AWS SDK with backoff.

Development

git clone https://github.com/containerscrew/aws-sso-rs.git
cd aws-sso-rs
cargo build
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

• Commits follow Conventional Commits. Releases are cut with cocogitto (cog bump), configured in cog.toml.
• Hooks in .pre-commit-config.yaml are run by prek, a drop-in replacement for pre-commit. Install the git hooks with cog install-hook --all, which runs prek on every commit.
• Everything in CI (security audit, lint, tests, release and crates.io publish) lives in .github/workflows/ci.yml. Pushing a v*.*.* tag builds the binaries for Linux and macOS, creates the GitHub release and publishes the crate.

Roadmap

See roadmap.md.

License

aws-sso-rs is distributed under the terms of the GPL-3.0 license.