SGO/wiki/AWS-Configuration.md

AWS Configuration

Prerequisites

Before using SGO, ensure you have:

1. AWS CLI configured with credentials
2. Appropriate IAM permissions
3. MFA device configured (if required by your profiles)

AWS Profiles Setup

SGO reads profiles from ~/.aws/config. Ensure your AWS configuration files are set up correctly.

Basic Profile Configuration

[profile my-aws-account]
region = us-west-2

Profile with MFA

For profiles that require MFA authentication:

[profile nonprod-p1p2-admin]
region = us-west-2
mfa_serial = arn:aws:iam::131340773912:mfa/your-username

Multiple Profiles

You can have multiple profiles in your config file:

[default]
region = us-east-1

[profile production]
region = us-west-2
mfa_serial = arn:aws:iam::123456789012:mfa/john.doe

[profile development]
region = us-west-2

[profile staging]
region = us-east-1
mfa_serial = arn:aws:iam::987654321098:mfa/john.doe

MFA Device Setup

Finding Your MFA Device ARN

1. Go to AWS IAM Console
2. Navigate to Users → Your User → Security Credentials
3. Scroll to Multi-factor authentication (MFA)
4. Copy the ARN from "Assigned MFA device"

Example ARN format:

arn:aws:iam::123456789012:mfa/username

Adding MFA to Profile

Add the mfa_serial line to your profile in ~/.aws/config:

[profile my-profile]
region = us-west-2
mfa_serial = arn:aws:iam::123456789012:mfa/username

How MFA Works in SGO

1. The import page shows all profiles from ~/.aws/config
2. Profiles with mfa_serial configured will show an MFA input field
3. Profiles without mfa_serial can import without entering a code
4. Enter your current MFA/TOTP code (6 digits) for profiles that require it
5. Click "Start Import" to begin authentication and data import
6. MFA session is valid for 1 hour
7. During the session window (55 minutes), you can refresh without re-entering codes

MFA Code Sources

You can get MFA codes from:

• Authenticator apps (Google Authenticator, Microsoft Authenticator, Authy, etc.)
• Hardware MFA devices
• SMS (if configured)

Note: MFA codes expire every 30 seconds, so enter them promptly.

Required IAM Permissions

Your AWS user/role needs the following permissions to use SGO:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeSecurityGroups",
        "iam:ListAccountAliases",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

Permission Breakdown

• ec2:DescribeInstances - List and describe EC2 instances
• ec2:DescribeSecurityGroups - List and describe security groups
• iam:ListAccountAliases - Get friendly account names
• sts:GetCallerIdentity - Get account ID

AWS Credentials Location

Default Location

SGO expects AWS credentials at:

• Linux/macOS: ~/.aws/
• Windows: %USERPROFILE%\.aws\

Custom Location

If your AWS credentials are in a non-standard location, specify it in your .env file:

AWS_CONFIG_PATH=/path/to/custom/.aws

Required Files

Ensure these files exist in your AWS credentials directory:

1. config - Contains profile configurations

   [profile my-profile]
   region = us-west-2
   mfa_serial = arn:aws:iam::123456789012:mfa/username
   

2. credentials - Contains access keys

   [my-profile]
   aws_access_key_id = AKIAIOSFODNN7EXAMPLE
   aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
   

Testing Your Configuration

Verify AWS CLI Access

# Test default profile
aws sts get-caller-identity

# Test specific profile
aws sts get-caller-identity --profile my-profile

# Test with MFA
aws sts get-caller-identity --profile my-profile
# (will prompt for MFA if configured)

Verify Permissions

# Test EC2 access
aws ec2 describe-instances --profile my-profile --max-results 1

# Test security groups access
aws ec2 describe-security-groups --profile my-profile --max-results 1

Common Configuration Issues

No Profiles Found

Problem: Import page shows "No AWS profiles found"

Solution:

• Verify ~/.aws/config exists and contains profiles
• Check file permissions (should be readable)
• Ensure profiles are properly formatted in config file

MFA Authentication Fails

Problem: "MFA authentication failed" error

Solution:

• Verify MFA code is current (not expired)
• Check mfa_serial is correct in ~/.aws/config
• Ensure AWS credentials in ~/.aws/credentials are valid
• Try generating a new MFA code

Permission Denied

Problem: "Access Denied" or "Unauthorized" errors

Solution:

• Verify your IAM user/role has required permissions
• Check if your credentials have expired
• Ensure you're using the correct profile

Wrong Region

Problem: Not seeing resources you expect

Solution:

• Verify the region setting in your profile
• Remember: EC2 resources are region-specific
• Try setting the region explicitly:

  [profile my-profile]
  region = us-west-2