SSO with aws-envs: ssostart and sso-config-generator

If you use aws-envs to manage multiple AWS organizations on one device, you likely use AWS SSO in at least some of them. Two tools make the SSO side of that workflow significantly smoother: ssostart for login, and sso-config-generator for keeping your profiles up to date. This article covers both.

If you're not yet familiar with aws-envs, start with our introduction to aws-envs.

The Problem with aws sso login

The standard AWS SSO login command works, but it has friction when used across multiple environments:

• It always uses the global ~/.aws/config, so you need to ase to the right environment first
• In an SSH session or remote environment, it tries to open a browser—which may not be available
• It doesn't know about your aws-envs setup, so there's no tab completion for environment names
• As you gain access to more accounts and roles, your ~/.aws/config grows unwieldy fast

ssostart: Environment-Aware SSO Login

ssostart is a drop-in replacement for aws sso login that integrates directly with aws-envs.

Installation

brew tap easytocloud/tap
brew install ssostart

Usage

# Login using the currently active aws-env
ssostart

# Login to a specific environment (without switching the active env globally)
ssostart clientA

# Login to a specific profile in a specific environment
ssostart clientA --profile admin

When you pass an environment name, ssostart sets AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE to point at that environment's files—session-scoped, so it doesn't affect other terminal windows. Then it initiates the SSO login.

Smart Context Detection

ssostart detects how you're running and picks the right authentication method automatically:

This matters when you're SSHed into a development machine or a cloudX instance: aws sso login would fail trying to open a browser. ssostart falls back to device code authentication gracefully.

Tab Completion

The Homebrew formula installs zsh completion. The first argument completes from your available aws-envs:

ssostart <TAB>   # lists acme, clientA, personal, ...

Default Options

Create ~/.ssostartrc to set options that apply to every invocation:

--region eu-west-1

sso-config-generator: Build Your Entire AWS CLI Config Automatically

Even with SSO login working well, maintaining ~/.aws/config by hand across many accounts and roles is tedious. In an organization with dozens of accounts, the file becomes hundreds of lines long, and any new account or role assignment requires a manual update.

sso-config-generator solves this. After you log in with SSO, it enumerates all the accounts and roles you have access to and writes a named profile for each one.

Running It

No installation required:

uvx sso-config-generator

How Profiles Are Named

Profiles follow a clear, consistent convention:

<RoleName>@<AccountName>

For example, access to the AdministratorAccess role in DevAccount becomes the profile AdministratorAccess@DevAccount. You can then use it immediately:

aws s3 ls --profile AdministratorAccess@DevAccount
# or
export AWS_PROFILE=AdministratorAccess@DevAccount

Prerequisites

sso-config-generator needs an initial "browser" profile in your config to authenticate with SSO and query your entitlements. Add this to your environment's ~/.aws/config once:

[sso-session sso]
sso_region              = eu-west-1
sso_start_url           = https://your-org.awsapps.com/start
sso_registration_scopes = sso:account:access

[profile sso-browser]
sso_session    = sso
sso_account_id = 123456789012
sso_role_name  = OrganizationAccountRole
region         = eu-west-1
output         = json

Then log in and generate:

ssostart              # or: aws sso login --profile sso-browser
uvx sso-config-generator

OU-Based Directory Structure

With --use-ou-structure, the generator also creates a local directory tree that mirrors your AWS Organization's OU structure. Each account directory gets a .envrc file (for use with direnv) that sets AWS_PROFILE automatically when you cd into it:

~/aws-accounts/
  production/
    app-account/
      .envrc   → export AWS_PROFILE=AdministratorAccess@AppAccount
    data-account/
      .envrc
  staging/
    ...

cd into an account directory and you're automatically pointing at the right profile—no manual asp required.

A Complete SSO Workflow with aws-envs

Putting it all together, a first-time setup for a new SSO-based environment looks like this:

# 1. Create a new environment
ase --add clientA

# 2. Add the sso-browser profile manually (one time)
#    edit ~/.aws/aws-envs/clientA/config

# 3. Log in
ssostart clientA

# 4. Generate all profiles
uvx sso-config-generator

# 5. Start working
asp AdministratorAccess@DevAccount
aws ec2 describe-instances

After the initial setup, the daily workflow is just:

ssostart clientA   # refresh the SSO session

Profiles stay accurate as long as you re-run sso-config-generator after your entitlements change.

Related Tools