Skip to content

Backend Deployment - AWS CLI v2 + IAM Identity Center (SSO) macOS Setup Guide

This guide assumes:

  • You’re on macOS (11+).
  • Your AWS root account already exists (do not use it for daily work).
  • IAM Identity Center (SSO) is already configured in your org, and you have an admin permission set assigned.
  • You want a clean, copy-pasteable workflow using SSO (recommended) and optional Homebrew notes.

Note: You will need to choose a <your-cli-profile-name> name for this profile. It is passed into many CLI commands. For the sake of the guide we chose admin-cli-sso but you should choose whatever makes sense for you.

TL;DR

  • Install AWS CLI v2
  • Run aws configure sso to create an SSO-backed profile (e.g., admin-cli-sso)
  • aws sso login --profile admin-cli-sso each time you start fresh
  • Use --profile admin-cli-sso in your CLI commands

1) Install or Update AWS CLI v2 (macOS)

curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

Verify the install

which aws
aws --version

Expected: aws resolves to /usr/local/bin/aws and shows a v2 version string.

Note AWS does not maintain third-party repositories and can’t guarantee they have the latest version. The official PKG is preferred.

Option B — Homebrew (alternate)

brew install awscli

If you switch from Homebrew to the PKG later (or vice versa), confirm your PATH and which aws binary is being used:

which aws
type -a aws

Housekeeping

If you used the PKG, it’s normal to have ~/AWSCLIV2.pkg left over. You can safely delete it:

rm -f ~/AWSCLIV2.pkg

2) Configure IAM Identity Center (SSO)

Run the guided SSO configuration once to create a reusable profile. Replace redacted values with your org’s details.

Note: <your-sso-session-name> identifies this SSO session.

aws configure sso
# Example answers:
# SSO session name (Recommended): <your-sso-session-name>
# SSO start URL [None]: https://<your-org>.awsapps.com/start
# SSO region [None]: us-east-1
# SSO registration scopes [sso:account:access]: sso:account:access
# (browser opens; sign in; choose account + role)
# Default client Region [None]: us-east-1
# CLI default output format (json if not specified) [None]: json
# Profile name [<auto-suggested>]: admin-cli-sso

You’ll authenticate in the browser, select your admin account and AdministratorAccess (or your org’s admin permission set), then save the profile name admin-cli-sso.

Sign in to start a session

aws sso login --profile admin-cli-sso

3) Validate Your Session

Confirm who you are:

aws sts get-caller-identity --profile admin-cli-sso

Basic S3 call (may be empty if you have no buckets):

aws s3 ls --profile admin-cli-sso

(Optional) Make the profile your shell default

export AWS_PROFILE=admin-cli-sso

Now you can omit --profile in the current shell session.

4) Expected ~/.aws/config Layout

After the SSO wizard, your config will look like this (keys redacted here):

[profile admin-cli-sso]
sso_session = <your-sso-session-name>
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
region = us-east-1
output = json

[sso-session <your-sso-session-name>]
sso_start_url = https://<your-org>.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

Tip If your [profile ...] references sso_session = <name>, you must also have a matching [sso-session <name>] block defining the sso_start_url, sso_region, and sso_registration_scopes.

5) Handy Commands

List all commercial regions (pretty-print one per line):

aws ec2 describe-regions \
  --all-regions \
  --query "Regions[].RegionName" \
  --output text \
  --profile admin-cli-sso | tr '\t' '\n' | sort

Quick identity check at any time:

aws sts get-caller-identity --profile admin-cli-sso

6) Common Pitfalls & Fixes

A) aws: [ERROR]: the following arguments are required: --access-token (for aws sso list-accounts)

  • The aws sso API group is a low-level interface that expects a raw --access-token argument and does not automatically read your SSO profile.
  • Use SSO-backed profiles with service commands instead (e.g., aws sts ..., aws s3 ..., aws ec2 ...), which pull credentials from your aws sso login session automatically.

  • If you need to discover accounts/roles:

  • Re-run aws configure sso (it interactively lists your accounts/roles), or

  • If your admin role has Organizations permissions, use:
aws organizations list-accounts --profile admin-cli-sso

(Requires `organizations:ListAccounts` permission.)

Why this happens aws sso list-accounts talks to the Identity Center’s OAuth endpoints and expects a bearer token you’d normally only use programmatically. It’s not the typical human workflow for SSO users.

B) aws --version shows a different version than you installed

  • You may have multiple aws binaries (e.g., Homebrew and PKG). Check precedence:
which aws
type -a aws
  • Fix PATH or remove the older install.

C) command not found: aws

  • Open a new terminal (to reload PATH), or ensure /usr/local/bin appears before other paths in your shell config.

D) S3 command “does nothing”

  • aws s3 ls prints nothing if you have no buckets (this is normal). Try another service (e.g., STS or EC2) to verify access.

7) Workflow Cheatsheet

# 1) Once per new shell session
aws sso login --profile admin-cli-sso

# 2) Run commands
aws ec2 describe-instances --profile admin-cli-sso
aws s3 ls --profile admin-cli-sso

# 3) Optional: set default for this shell
export AWS_PROFILE=admin-cli-sso

8) Safety & Best Practices

  • Never create root access keys. Reserve root for billing & break-glass tasks only.
  • Prefer IAM Identity Center (SSO) for daily/admin access.
  • Only use long-lived IAM user access keys if an old tool requires them; otherwise prefer short-lived, SSO-issued credentials.

Keep your local notes of your Start URL and SSO Region handy; they’re the only two bits you usually need to set up a new machine quickly.

Appendix: One-Shot Copy/Paste (PKG install + SSO profile)

Replace <your-org>, <account-id>, <your-sso-session-name>, <your-cli-profile-name> and adjust regions as needed.

# Install AWS CLI v2 (official PKG)
curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /
aws --version

# Configure SSO profile
aws configure sso <<'EOF'
<your-sso-session-name>
https://<your-org>.awsapps.com/start
us-east-1
sso:account:access
EOF

# When prompted by the wizard:
# - Choose your admin account (<account-id>)
# - Choose AdministratorAccess (or your admin permission set)
# - Set default region: us-east-1
# - Set output: json
# - Profile name: <your-cli-profile-name>

# Start an SSO session and test
aws sso login --profile <your-cli-profile-name>
aws sts get-caller-identity --profile <your-cli-profile-name>

# (Optional) Default the profile for this shell
export AWS_PROFILE=<your-cli-profile-name>

< Backend Deployment - AWS Account Setup

Next: Backend Deployment - AWS Tagging Guide >