If you use AWS IAM Identity Center across several accounts, the hard part is often not signing in. It is discovering every account and role, creating consistent AWS CLI profiles, and remembering which profile belongs to which SSO session.
I built aws-sso-login to make that workflow less repetitive. It is an open-source command-line tool that discovers your assigned accounts and roles, creates safe AWS CLI profile entries, and gives you one place to list, diagnose, and sign in to them.
Want the code first? View aws-sso-login on GitHub. The project is MIT licensed and installs directly with pipx.
TL;DR
- The problem: IAM Identity Center users can have many accounts, roles, sessions, and local AWS profiles to manage.
- The tool:
aws-sso-logindiscovers assignments, previews new profiles, appends them safely to your AWS config, and starts the supported AWS CLI login flow. - The useful extras: profile listing, JSON output, session-wide login, last-selection recall, device-code support, and configuration diagnostics.
- The boundaries: it needs Python 3.10+, AWS CLI v2, and Linux, macOS, or WSL. Native Windows is not supported in the first release.
Quick reference
| Task | Command | When to use it |
|---|---|---|
| Discover and configure | aws-sso-login setup | New workstation or missing profiles |
| Open the selector | aws-sso-login | Choose profiles interactively |
| Show profiles | aws-sso-login list | Check names, accounts, roles, and sessions |
| Sign in by session | aws-sso-login login --session NAME | Authenticate related profiles together |
| Headless sign-in | aws-sso-login login --all --device-code | SSH, WSL, or remote terminal |
| Diagnose config | aws-sso-login doctor --all | Find incomplete or inconsistent profiles |
Start here: if IAM Identity Center itself is new to you, read my introduction to AWS IAM Identity Center first. If your organisation is already using it, jump straight to the installation section below.
The problem: AWS SSO profiles multiply quickly
A small AWS environment may give you one account and one role. A real organisation can give you development, staging, production, security, logging, and shared-services accounts, with different permission sets in each one. Every account-and-role combination can become a separate AWS CLI profile.
Creating those profiles by hand is manageable once. It gets tedious when you configure a new laptop, rebuild WSL, join another AWS organisation, or receive additional roles. You need the correct Start URL, Identity Center region, account ID, role name, profile region, session block, and profile name. A typo may only become obvious later when an SDK or Terraform command fails.
The normal aws configure sso and aws sso login commands are still the right foundation. The missing piece for me was a simple layer that could look at the assignments AWS already knows about, plan the local profiles, and help me operate them as a group.
What aws-sso-login does
aws-sso-login works with the standard AWS shared config file. It can read modern [sso-session ...] profiles as well as legacy profiles containing inline SSO settings. On an unconfigured machine, its setup flow uses AWS device authorisation to discover the accounts and roles assigned to the current user.
- Discovers assigned IAM Identity Center accounts and roles without assuming your organisation’s naming convention.
- Lets you select assignments interactively or explicitly configure all of them.
- Previews the proposed session and profile sections before writing.
- Lists configured profiles in a readable table or JSON.
- Signs in selected profiles, every profile in a session, all profiles, or the profiles used last time.
- Supports device-code login for terminals where opening a browser is inconvenient.
- Checks local profiles with a built-in
doctorcommand.
It does not replace IAM Identity Center, invent new permissions, or bypass AWS authentication. The helper handles discovery, configuration, and command orchestration. The AWS CLI performs the final interactive login.
How the setup flow works
1. Supply the portal details
Run setup and enter your AWS Start URL (or Issuer URL), the AWS Region hosting IAM Identity Center, and a local session name. AWS does not expose a general way for a tool on a blank machine to infer your organisation’s portal, so the URL and region have to come from your administrator or existing configuration.
2. Authorise discovery
The first-time flow requests the narrow sso:account:access scope through AWS’s public device-authorisation flow. After you approve the code, it asks the IAM Identity Center Portal API for your assigned accounts and roles. The account email address returned by AWS is deliberately ignored.
3. Select and preview profiles
You choose the assignments you want locally. The tool generates predictable profile names, reuses equivalent account-and-role assignments, and adds deterministic suffixes when names collide. It shows the plan before touching the file.
4. Append configuration safely
Rather than parsing and rewriting your entire config, the tool preserves the existing text and comments and appends only new session and profile sections. Existing sections are never overwritten. The replacement is atomic, unexpected concurrent changes abort the write, and new configs and backups use mode 0600.
5. Let the AWS CLI sign you in
Once the profiles exist, normal login commands delegate to AWS CLI v2. Profiles sharing an SSO session can reuse that authenticated session, so you do not need an entirely separate browser approval for every profile.
Install aws-sso-login with pipx
You need Python 3.10 or newer and AWS CLI v2 on Linux, macOS, or WSL. If AWS CLI v2 is missing, use my AWS CLI installation and update guide before continuing.
pipx installs Python command-line applications into isolated environments while making their commands available on your path. From a terminal, run:
pipx install git+https://github.com/TurboBailey1980/aws-sso-login.gitThen confirm the command is available:
aws-sso-login --versionThe project is not on PyPI yet, so that command intentionally installs from the public GitHub repository. You can inspect the source before installing it, pin a commit for a controlled environment, or uninstall it later with pipx uninstall aws-sso-login.
Run the first setup
aws-sso-login setupFollow the device instructions, select the accounts and roles you want, review the proposed sections, and approve the write. Setup discovery and your first AWS CLI sign-in are deliberately separate authorisations: discovery proves which assignments should become profiles, while the AWS CLI obtains the session it uses for normal commands.
After setup, run the interactive selector with no arguments:
aws-sso-loginReady to try it? The aws-sso-login installation section on GitHub always contains the current requirements and command.
Automate setup without weakening the safeguards
Interactive selection is the default, but the setup command can also configure every discovered assignment in a non-interactive terminal. To prevent an accidental broad write, all portal details and both confirmation flags must be explicit:
aws-sso-login setup \
--start-url https://example.awsapps.com/start \
--sso-region eu-west-1 \
--session example-sso \
--profile-region eu-west-1 \
--all --yes --no-browserReplace the example portal and region values with your own. The command still uses AWS device authorisation for discovery, previews what it has planned, and applies the same append-only config rules. This mode is useful for repeatable development environments, but do not hard-code organisation details into a public bootstrap script.
Useful commands for daily work
List profiles as a table, or switch to JSON when another local tool needs the metadata:
aws-sso-login list
aws-sso-login list --jsonSign in to one named profile, every profile sharing a session, all profiles, or your previous selection:
aws-sso-login login development-developer
aws-sso-login login --session example-sso
aws-sso-login login --all
aws-sso-login login --lastFor an SSH session or another terminal where the automatic browser flow is awkward, request a device code:
aws-sso-login login --all --device-codeIf something does not look right, inspect every configured SSO profile:
aws-sso-login doctor --allWhy use it instead of maintaining profiles by hand?
Discovery comes from AWS
The tool asks IAM Identity Center which accounts and roles are assigned to you. That removes a large copy-and-paste step and avoids hard-coding one organisation’s account names or permission sets into the project.
Configuration writes are conservative
Existing sections are treated as yours. New sections are appended, equivalent assignments are reused, collisions are resolved predictably, file permissions are preserved, and a concurrent edit causes the operation to stop. Those safeguards matter more than shaving a few seconds from the login command.
Profiles become an operable set
The session and last-selection options are useful when your real unit of work is “all profiles in this organisation” or “the same accounts I used yesterday”, rather than one profile name at a time.
It works in headless environments
The explicit device-code option makes the workflow practical over SSH and in other remote shells. You can open the displayed URL on a separate device and return to the terminal after approval.
The privacy model is deliberately small
There is no telemetry and the application creates no logs. Discovery tokens remain in process memory and are discarded when setup ends. The tool does not print or save tokens, client registration secrets, or refresh credentials. Account IDs, names, portal URLs, and roles stay local except when AWS requires them for authentication.
One caution: list --json intentionally emits local profile metadata. Treat redirected JSON files with the same care as your AWS config.
Who is aws-sso-login for?
It is a good fit if you regularly use several IAM Identity Center accounts or roles, want repeatable workstation setup, prefer a terminal workflow, or need device-code login on WSL and remote Linux machines.
It is probably unnecessary if you have one profile that rarely changes. It is also not the right tool for long-lived IAM access keys, EC2 instance roles, GitHub Actions OIDC, or application credential vending. Those are different credential models. If your main requirement is encrypted storage and execution of several credential types, compare the workflow with my AWS Vault guide for Linux.
This is an early open-source release, currently aimed at Linux, macOS, and WSL. Review the repository, test it against a non-critical local config first, and report surprising behaviour. That feedback is exactly what helps a small utility mature.
Frequently asked questions
Is AWS SSO the same as IAM Identity Center?
AWS Single Sign-On was renamed AWS IAM Identity Center. People still search for “AWS SSO”, the AWS CLI command is still aws sso login, and existing config keys still use the sso_ prefix. This guide uses both terms where that makes the command-line context clearer.
Does aws-sso-login store my AWS credentials?
No. It does not save discovery access tokens, refresh credentials, or client secrets. It writes ordinary AWS profile configuration and delegates the supported login to AWS CLI v2.
Can it use profiles I already have?
Yes. It reads the normal AWS shared config location, including modern SSO session profiles and legacy inline SSO profiles. It also respects AWS_CONFIG_FILE when you use a non-default config.
Does it support Windows?
WSL is supported. Native Windows PowerShell and Command Prompt are not supported in the first release.
Why must I enter the Start URL?
A fresh machine has no reliable AWS API that can infer which organisation portal belongs to a user. The tool therefore asks for the Start URL or Issuer URL and the Identity Center region instead of guessing.
Try aws-sso-login and help shape the project
Read the source, install the tool, and try it with your IAM Identity Center profiles. If it saves you time, star the repository. If your organisation exposes an edge case I have missed, open an issue with sanitised details. Contributions are welcome too.
Leave a Reply