Skip to content
Home » Complete Guide to AWS CLI: Installation, Configuration, and Authentication Methods

Complete Guide to AWS CLI: Installation, Configuration, and Authentication Methods

  • by

Managing AWS resources efficiently requires mastering the AWS Command Line Interface (CLI). Whether you’re automating deployments, managing infrastructure, or integrating AWS services into your workflow, understanding how to properly install, configure, and authenticate with the AWS CLI is crucial. This comprehensive guide covers everything from basic access key authentication to advanced IAM Identity Center (SSO) configurations, including Docker deployments.

Prerequisites and System Requirements

Before diving into AWS CLI installation, ensure your system meets these requirements:

  • Operating System: Windows 10+, macOS 10.9+, or Linux (64-bit)
  • Python: Version 3.8 or later (for pip installation method)
  • AWS Account: Active AWS account with appropriate permissions
  • Memory: Minimum 512MB RAM available
  • Network: Internet connection for AWS service calls

Installing AWS CLI Version 2

AWS CLI v2 is the latest major version, offering improved installers, new features, and better performance. Choose your installation method based on your operating system:

macOS Installation

For macOS users, the quickest installation method uses the official PKG installer:

# Download the installer
curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"

# Install the package
sudo installer -pkg AWSCLIV2.pkg -target /

# Verify installation
aws --version

Alternatively, use Homebrew for easier updates:

# Install via Homebrew
brew install awscli

# Update to latest version
brew upgrade awscli

Linux Installation

Linux installation requires downloading and extracting the bundled installer:

# Download the installation file
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"

# Unzip the installer
unzip awscliv2.zip

# Run the installation script
sudo ./aws/install

# Verify the installation
aws --version

For ARM processors, use the ARM-specific URL:

curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o "awscliv2.zip"

Windows Installation

Windows users should download the MSI installer:

  1. Download the AWS CLI MSI installer from: https://awscli.amazonaws.com/AWSCLIV2.msi
  2. Run the downloaded MSI installer
  3. Follow the on-screen instructions
  4. Open Command Prompt or PowerShell and verify: aws --version

Configuration Method 1: AWS Access Key Authentication

The traditional method uses long-term credentials consisting of an Access Key ID and Secret Access Key. While simple, this method requires careful security considerations.

Creating IAM User Credentials

First, create an IAM user with programmatic access:

  1. Navigate to IAM Console → Users → Add User
  2. Enable “Programmatic access”
  3. Attach appropriate policies (e.g., PowerUserAccess for development)
  4. Download the credentials CSV file
  5. Store credentials securely – you won’t see the secret key again

Configuring Access Keys

Configure your credentials using the AWS CLI wizard:

aws configure

You’ll be prompted for four values:

AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json

These credentials are stored in ~/.aws/credentials (Linux/macOS) or %USERPROFILE%\.aws\credentials (Windows):

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[production]
aws_access_key_id = AKIAIOSFODNN8EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY2

Using Environment Variables

For temporary sessions or CI/CD pipelines, environment variables offer flexibility without modifying configuration files:

Linux/macOS:

# Set credentials
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-west-2

# For temporary credentials (STS)
export AWS_SESSION_TOKEN=FwoGZXIvYXdzEJr...

# Set profile
export AWS_PROFILE=production

# Verify configuration
aws sts get-caller-identity

Windows PowerShell:

# Set credentials
$Env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
$Env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
$Env:AWS_DEFAULT_REGION="us-west-2"

# Set profile
$Env:AWS_PROFILE="production"

Windows Command Prompt:

set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
set AWS_DEFAULT_REGION=us-west-2
set AWS_PROFILE=production

Configuration Method 2: IAM Identity Center (SSO) Authentication

IAM Identity Center (formerly AWS SSO) provides temporary credentials with automatic refresh, eliminating the need for long-term access keys. This is AWS’s recommended authentication method for human users.

Prerequisites for SSO Setup

  1. IAM Identity Center must be enabled in your organization
  2. You need your SSO Start URL (e.g., https://my-company.awsapps.com/start)
  3. SSO must be configured in the region where Identity Center is set up
  4. AWS CLI version 2.0 or later

Configuring SSO with Session Support

AWS CLI 2.22.0+ introduces SSO sessions with automatic token refresh. Configure using:

aws configure sso

Follow the interactive prompts:

SSO session name (Recommended): my-company-sso
SSO start URL [None]: https://my-company.awsapps.com/start
SSO region [None]: us-east-1
SSO registration scopes [None]: sso:account:access
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:

https://device.sso.us-east-1.amazonaws.com/

Then enter the code:

HXFZ-LBQM

There are 2 AWS accounts available to you.
> DeveloperAccount, [email protected] (111122223333)
  ProductionAccount, [email protected] (444455556666)

Using the account ID 111122223333

There are 2 roles available to you.
> ReadOnly
  FullAccess

Using the role name "FullAccess"

CLI default client Region [None]: us-west-2
CLI default output format [None]: json
CLI profile name [111122223333_FullAccess]: dev-profile

This creates configuration in ~/.aws/config:

[profile dev-profile]
sso_session = my-company-sso
sso_account_id = 111122223333
sso_role_name = FullAccess
region = us-west-2
output = json

[sso-session my-company-sso]
sso_region = us-east-1
sso_start_url = https://my-company.awsapps.com/start
sso_registration_scopes = sso:account:access

Using SSO Profiles

After configuration, authenticate and use your SSO profile:

# Login to SSO
aws sso login --profile dev-profile

# Use the profile for AWS commands
aws s3 ls --profile dev-profile

# Set as default profile
export AWS_PROFILE=dev-profile

# Now all commands use SSO credentials
aws ec2 describe-instances

Managing SSO Sessions

# View current session status
aws sts get-caller-identity

# Logout from SSO
aws sso logout

# Login with a specific profile
aws sso login --profile production-profile

Docker Deployment of AWS CLI

Running AWS CLI in Docker provides consistency across environments and eliminates installation dependencies. Here are multiple approaches for different use cases:

Basic Docker Usage with Environment Variables

The simplest method passes credentials as environment variables:

# Basic command with credentials
docker run --rm -it \
  -e AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE \
  -e AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  -e AWS_DEFAULT_REGION=us-west-2 \
  amazon/aws-cli s3 ls

# Include session token for temporary credentials
docker run --rm -it \
  -e AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE \
  -e AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  -e AWS_SESSION_TOKEN=FwoGZXIvYXdzEJr... \
  -e AWS_DEFAULT_REGION=us-west-2 \
  amazon/aws-cli sts get-caller-identity

Mounting AWS Credentials Directory

For persistent configurations, mount your local AWS configuration:

# Mount credentials and config files
docker run --rm -it \
  -v ~/.aws:/root/.aws:ro \
  amazon/aws-cli s3 ls

# Use specific profile
docker run --rm -it \
  -v ~/.aws:/root/.aws:ro \
  -e AWS_PROFILE=production \
  amazon/aws-cli ec2 describe-instances

# Mount local directory for file operations
docker run --rm -it \
  -v ~/.aws:/root/.aws:ro \
  -v $(pwd):/aws \
  amazon/aws-cli s3 cp /aws/file.txt s3://my-bucket/

Creating Custom Docker Image

Build a custom image with pre-configured settings:

# Dockerfile
FROM amazon/aws-cli:latest

# Set default environment variables
ENV AWS_DEFAULT_REGION=us-west-2
ENV AWS_DEFAULT_OUTPUT=json

# Copy custom scripts
COPY scripts/ /scripts/
RUN chmod +x /scripts/*.sh

# Set working directory
WORKDIR /aws

ENTRYPOINT ["aws"]

Build and use:

# Build custom image
docker build -t my-aws-cli .

# Run with credentials
docker run --rm -it \
  -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \
  my-aws-cli s3 ls

Docker Compose for Complex Workflows

For applications requiring AWS CLI, use Docker Compose:

# docker-compose.yml
version: '3.8'

services:
  aws-cli:
    image: amazon/aws-cli:latest
    environment:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - AWS_SESSION_TOKEN
      - AWS_DEFAULT_REGION=us-west-2
      - AWS_PROFILE
    volumes:
      - ~/.aws:/root/.aws:ro
      - ./data:/aws
    working_dir: /aws
    command: s3 sync /aws s3://my-bucket/

  app:
    build: .
    environment:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - AWS_DEFAULT_REGION=us-west-2
    depends_on:
      - aws-cli

Security Best Practices for Docker

When using AWS CLI in Docker, follow these security guidelines:

  1. Never hardcode credentials in Dockerfiles
  2. Use read-only mounts (:ro) for credential files
  3. Implement IAM roles when running on EC2/ECS/EKS
  4. Use Docker secrets for Swarm deployments
  5. Rotate credentials regularly
  6. Limit container permissions with security policies

Advanced Configuration Techniques

Multiple Profile Management

Manage multiple AWS accounts efficiently:

# ~/.aws/config
[default]
region = us-west-2
output = json

[profile development]
aws_access_key_id = AKIADEV...
aws_secret_access_key = devkey...
region = us-east-1

[profile staging]
role_arn = arn:aws:iam::222222222222:role/StagingRole
source_profile = default
region = eu-west-1

[profile production]
sso_session = company-sso
sso_account_id = 333333333333
sso_role_name = ProductionAccess
region = us-west-2

Switch between profiles:

# Use specific profile for single command
aws s3 ls --profile production

# Set default profile for session
export AWS_PROFILE=staging

# List all configured profiles
aws configure list-profiles

# View current profile configuration
aws configure list

Credential Provider Chain

AWS CLI checks for credentials in this order:

  1. Command line options (--region, --output, --profile)
  2. Environment variables (AWS_ACCESS_KEY_ID, etc.)
  3. CLI credentials file (~/.aws/credentials)
  4. CLI configuration file (~/.aws/config)
  5. Container credentials (ECS/Fargate)
  6. Instance profile credentials (EC2)

Assume Role Configuration

Configure cross-account access with assume role:

[profile cross-account]
role_arn = arn:aws:iam::444444444444:role/CrossAccountRole
source_profile = default
role_session_name = MySessionName
external_id = unique-external-id
mfa_serial = arn:aws:iam::111111111111:mfa/username
duration_seconds = 3600

Troubleshooting Common Issues

SSO Token Expiration

If you encounter The SSO session token has expired:

# Re-authenticate
aws sso login --profile your-profile

# Check token expiration
cat ~/.aws/sso/cache/*.json | jq '.expiresAt'

Clock Synchronization Issues

For WSL2 or Docker users experiencing authentication failures:

# Sync WSL2 clock
sudo hwclock -s

# Or use ntpdate
sudo ntpdate time.nist.gov

Credential Precedence Conflicts

When environment variables override profile settings:

# Clear environment variables
unset AWS_ACCESS_KEY_ID
unset AWS_SECRET_ACCESS_KEY
unset AWS_SESSION_TOKEN

# Verify which credentials are being used
aws configure list
aws sts get-caller-identity

Best Practices and Security Recommendations

  1. Use IAM Identity Center (SSO) for human users instead of long-term access keys
  2. Implement least privilege – grant minimum required permissions
  3. Rotate credentials regularly – automate rotation where possible
  4. Enable MFA for sensitive operations
  5. Use temporary credentials via STS for applications
  6. Audit credential usage with CloudTrail
  7. Store credentials securely – never commit to version control
  8. Use AWS Secrets Manager or Parameter Store for application credentials
  9. Implement SCPs (Service Control Policies) for organizational controls
  10. Monitor for exposed credentials with AWS Security Hub

Conclusion

Mastering AWS CLI authentication methods enables secure and efficient cloud resource management. Whether you’re using traditional access keys for automation, IAM Identity Center for team collaboration, or Docker containers for consistent deployments, choosing the right authentication method depends on your specific use case and security requirements.

Start with IAM Identity Center for interactive use, leverage environment variables for CI/CD pipelines, and implement Docker containers for portable deployments. Remember to prioritize security by using temporary credentials, implementing least privilege, and regularly rotating secrets.

As your AWS infrastructure grows, these authentication patterns will form the foundation of your cloud operations, enabling everything from simple S3 operations to complex multi-account deployments. Keep your CLI updated, follow AWS security best practices, and regularly review your authentication configurations to maintain a secure and efficient cloud environment.

]]>

Tags:

Leave a Reply

Your email address will not be published. Required fields are marked *