How to Configure AWS SSO CLI Access for Linux Ubuntu

A complete guide to setting up AWS Single Sign-On (SSO) with the AWS CLI on Ubuntu

Introduction

AWS Single Sign-On (AWS SSO), now known as AWS IAM Identity Center, provides a centralized way to manage access to multiple AWS accounts and applications. Instead of managing individual IAM users with long-term credentials, SSO allows you to authenticate once and access all your permitted AWS accounts seamlessly.

This guide walks you through configuring AWS SSO for CLI access on Ubuntu Linux, including an optional utility that makes managing multiple profiles a breeze.

Prerequisites

Before you begin, ensure you have:

Ubuntu 20.04, 22.04, or 24.04 LTS
Sudo access to install packages
Your organization’s AWS SSO start URL (e.g., https://your-company.awsapps.com/start)
Your SSO region (typically us-east-1)

Step 1: Install AWS CLI v2

AWS CLI version 2 includes built-in SSO support. Install it on Ubuntu:

# Download the installer
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
# Unzip
unzip awscliv2.zip
# Install (requires sudo)
sudo ./aws/install
# Clean up
rm -rf aws awscliv2.zip

Verify Installation

aws --version

Expected output:

aws-cli/2.x.x Python/3.x.x Linux/x86_64

Step 2: Configure AWS SSO Profile

Option A: Interactive Configuration (Built-in)

Use the AWS CLI’s built-in SSO configuration wizard:

aws configure sso

You’ll be prompted for:

Prompt	Description	Example
SSO session name	A name for your SSO session (recommended)	`my-company`
SSO start URL	Your organization’s SSO portal URL	`https://my-company.awsapps.com/start`
SSO region	The region where SSO is configured	`us-east-1`
SSO registration scopes	Leave default	`sso:account:access`

After entering these details, a browser window opens for authentication. Once authenticated, you’ll see a list of available accounts and roles. Select one to create your profile.

Option B: Manual Configuration

You can also manually edit the AWS config file:

nano ~/.aws/config

Add a profile section:

[profile my-dev-account]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
region = us-east-1
output = json

Step 3: Login to AWS SSO

Authenticate with your SSO profile:

aws sso login --profile my-dev-account

A browser window opens. Complete the authentication:

Enter your corporate credentials
Approve the authorization request
Return to the terminal

Verify Authentication

aws sts get-caller-identity --profile my-dev-account

Expected output:

{
    "UserId": "AROAEXAMPLEID:user@company.com",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/AdministratorAccess/user@company.com"
}

Step 4: Set Default Profile (Optional)

To avoid typing --profile with every command, set a default:

Per-Session (Environment Variable)

export AWS_PROFILE="my-dev-account"

Permanent (Add to Shell Profile)

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

echo 'export AWS_PROFILE="my-dev-account"' >> ~/.bashrc
source ~/.bashrc

Advanced: Using aws-sso-util for Multiple Profiles

If you have access to many AWS accounts, manually configuring each profile is tedious. aws-sso-util is a Python utility that automatically populates all your accessible profiles.

Install pipx (Recommended)

# Install pipx
python3 -m pip install --user pipx
python3 -m pipx ensurepath
# Reload shell
source ~/.bashrc

Install aws-sso-util

pipx install aws-sso-util

Verify:

aws-sso-util --version

Populate All Profiles Automatically

This command discovers all accounts and roles you have access to and creates profiles for each:

aws-sso-util configure populate \
    --sso-start-url https://my-company.awsapps.com/start \
    --sso-region us-east-1 \
    --region us-east-1

A browser opens for authentication. After login, profiles are created automatically.

Customize Profile Naming

Use these options for cleaner profile names:

aws-sso-util configure populate \
    --sso-start-url https://my-company.awsapps.com/start \
    --sso-region us-east-1 \
    --account-name-case lower \
    --role-name-case lower \
    --trim-role-name "(?<=admin)istratoraccess" \
    --trim-role-name "^aws" \
    --trim-role-name "(?<=readonly)access" \
    --trim-role-name "(?<=poweruser)access" \
    --region us-east-1

This creates profiles like dev-account.admin instead of Dev-Account.AdministratorAccess.

Login to All Profiles at Once

aws-sso-util login

Working with Multiple Accounts

List All Configured Profiles

aws configure list-profiles

Switch Between Profiles

# Set for current session
export AWS_PROFILE="production.admin"
# Or use --profile flag
aws s3 ls --profile production.admin

Create Bash Function for Easy Switching

Add to ~/.bashrc:

awsp() {
    export AWS_PROFILE="$1"
    echo "AWS Profile set to: $AWS_PROFILE"
    aws sts get-caller-identity
}
# Usage: awsp dev-account.admin

Then reload: source ~/.bashrc

Common Use Cases

Use with Docker and ECR

Authenticate Docker with Amazon ECR:

# Login to SSO first
aws sso login --profile my-account.admin
# Authenticate Docker
aws ecr get-login-password --region us-east-1 --profile my-account.admin | \
    docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

Use with Terraform

Set the profile before running Terraform:

export AWS_PROFILE="infrastructure.admin"
terraform init
terraform plan

Or configure in provider.tf:

provider "aws" {
  profile = "infrastructure.admin"
  region  = "us-east-1"
}

Use with AWS CDK

export AWS_PROFILE="dev-account.admin"
cdk deploy

Use with boto3 (Python)

import boto3
session = boto3.Session(profile_name='dev-account.admin')
s3 = session.client('s3')
buckets = s3.list_buckets()

Understanding AWS Config Files

AWS stores configuration in two files in your home directory:

Config File (`~/.aws/config`)

Contains profile settings including SSO configuration:

[profile dev-account.admin]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
region = us-east-1

Credentials File (`~/.aws/credentials`)

Contains static credentials (not used with SSO, but may contain other profiles):

[legacy-access]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

View Config File

cat ~/.aws/config

Edit Config File

nano ~/.aws/config

Session Management

Check Current Session

aws sts get-caller-identity

SSO Token Expiration

SSO tokens typically last 8-12 hours. When expired, you’ll see:

Error: The SSO session associated with this profile has expired or is otherwise invalid.

Simply re-login:

aws sso login --profile my-account.admin

Logout

aws sso logout

This invalidates all cached SSO tokens stored in ~/.aws/sso/cache/.

Troubleshooting

“The SSO session has expired”

Re-authenticate:

aws sso login --profile your-profile

“Unable to locate credentials”

Ensure you’ve logged in and the profile name is correct:

# List available profiles
aws configure list-profiles
# Login to the correct profile
aws sso login --profile correct-profile-name

“An error occurred (ExpiredToken)”

Your session token has expired. Login again:

aws sso login --profile your-profile

Browser Doesn’t Open (Headless/SSH)

If running on a headless server or via SSH, the CLI displays a URL and code:

# Copy the URL and open in your local browser
# Enter the code shown in the terminal

Profile Not Found

Check the profile exists:

grep -A5 "your-profile" ~/.aws/config

Security Best Practices

Never share SSO tokens – They’re cached in ~/.aws/sso/cache/
Logout when done – Especially on shared machines

aws sso logout

Use least privilege – Request ReadOnly access for day-to-day work, Admin only when needed
Avoid static credentials – SSO provides temporary, rotating credentials
Don’t commit config files – Add .aws/ to .gitignore
Secure file permissions

chmod 600 ~/.aws/config
chmod 600 ~/.aws/credentials

Quick Reference

Action	Command
Install AWS CLI	`curl + unzip + sudo ./aws/install`
Configure SSO	`aws configure sso`
Login	`aws sso login --profile PROFILE`
Set default profile	`export AWS_PROFILE="PROFILE"`
Check identity	`aws sts get-caller-identity`
List profiles	`aws configure list-profiles`
Logout	`aws sso logout`
View config	`cat ~/.aws/config`
Edit config	`nano ~/.aws/config`
Install aws-sso-util	`pipx install aws-sso-util`
Populate all profiles	`aws-sso-util configure populate ...`

Conclusion

AWS SSO provides a secure, centralized way to access multiple AWS accounts without managing long-term credentials. With the AWS CLI v2’s built-in SSO support and tools like aws-sso-util, you can streamline your workflow and switch between accounts effortlessly.

Key takeaways:

Use aws configure sso for basic setup
Use aws-sso-util configure populate for organizations with many accounts
Set AWS_PROFILE environment variable to avoid typing --profile repeatedly
SSO tokens expire; simply run aws sso login to refresh

Happy cloud computing!