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

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

### Profile with MFA

For profiles that require MFA authentication:

```ini
[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:

```ini
[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`:

```ini
[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:

```json
{
  "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:

```bash
AWS_CONFIG_PATH=/path/to/custom/.aws
```

### Required Files

Ensure these files exist in your AWS credentials directory:

1. **`config`** - Contains profile configurations
   ```ini
   [profile my-profile]
   region = us-west-2
   mfa_serial = arn:aws:iam::123456789012:mfa/username
   ```

2. **`credentials`** - Contains access keys
   ```ini
   [my-profile]
   aws_access_key_id = AKIAIOSFODNN7EXAMPLE
   aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
   ```

## Testing Your Configuration

### Verify AWS CLI Access

```bash
# 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

```bash
# 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:
  ```ini
  [profile my-profile]
  region = us-west-2
  ```