AWS Authentication

Securely manage AWS credentials for your TrackPost integration. This guide covers IAM user creation, permissions, and security best practices.

Overview

TrackPost connects to AWS SES using IAM (Identity and Access Management) credentials. This guide ensures your setup is both functional and secure.

Why Use IAM?

• Least Privilege - Grant only necessary permissions
• Audit Trail - Track API usage via CloudTrail
• Credential Rotation - Easy to rotate keys regularly
• No Root Access - Never use root account credentials

Creating an IAM User

Step 1: Access IAM Console

1. Log in to AWS Console
2. Navigate to IAM → Users
3. Click Create user

Step 2: Configure User Details

1. User name: trackpost-ses (or any descriptive name)
2. Access type: Select Access key - Programmatic access
3. Click Next: Permissions

Step 3: Set Permissions

Option A: Attach Policy Directly (Recommended)

1. Select Attach policies directly
2. Click Create policy
3. Go to JSON tab
4. Paste this policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ses:SendEmail",
        "ses:SendRawEmail",
        "ses:GetSendQuota",
        "ses:GetIdentityVerificationAttributes",
        "ses:GetIdentityNotificationAttributes",
        "ses:VerifyEmailIdentity",
        "ses:VerifyDomainIdentity",
        "ses:SetIdentityNotificationTopic",
        "ses:SetIdentityFeedbackForwardingEnabled",
        "ses:DescribeConfigurationSet"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "sns:CreateTopic",
        "sns:Subscribe",
        "sns:Publish",
        "sns:ConfirmSubscription",
        "sns:GetTopicAttributes"
      ],
      "Resource": "*"
    }
  ]
}

5. Click Next: Tags
6. Add optional tags (e.g., Project=TrackPost, Environment=Production)
7. Click Next: Review
8. Name the policy: TrackPostSESAccess
9. Click Create policy
10. Go back to user creation and attach this policy

Option B: Add to Group (For Multiple Users)

If you have multiple users managing TrackPost:

1. Create a group: IAM → User groups → Create group
2. Name: TrackPostAdmins
3. Attach the policy above
4. Add users to this group

Step 4: Review and Create

1. Review the user details
2. Click Create user
3. Important: On the success page, you’ll see:
   • Access key ID (e.g., AKIAIOSFODNN7EXAMPLE)
   • Secret access key (click “Show” to reveal)
4. Download the CSV or copy these credentials immediately
5. Click Close

Adding Credentials to TrackPost

Via Dashboard

1. Log in to TrackPost Dashboard
2. Go to Settings → AWS Configuration
3. Enter:
   • Access Key ID: From IAM user creation
   • Secret Access Key: From IAM user creation
   • AWS Region: Your preferred SES region
4. Click Save
5. Click Test Connection to verify

Via CLI

trackpost aws setup
# Follow interactive prompts to enter credentials

AWS Regions

Choose an AWS region close to your users:

Regional Considerations

• Latency: Choose closest to your users
• Compliance: Some regions have different compliance standards
• Pricing: Varies slightly by region
• SES Availability: SES is available in most regions

Security Best Practices

1. Never Use Root Account

• Always create IAM users with limited permissions
• Root account has unrestricted access to your entire AWS account

2. Rotate Credentials Regularly

Recommended Schedule: Every 90 days

How to Rotate:

1. Create new access keys for the IAM user:

   • IAM → Users → trackpost-ses → Security credentials
   • Click Create access key
   • Copy new credentials

2. Update TrackPost with new credentials:

   • Dashboard → Settings → AWS Configuration
   • Update Access Key ID and Secret Access Key
   • Save and test

3. Deactivate old keys:

   • IAM → Users → trackpost-ses → Security credentials
   • Find old access key
   • Click Actions → Deactivate
   • Wait 24 hours to ensure no issues
   • Click Actions → Delete

3. Use Environment Variables (Never Hardcode)

❌ Don’t do this:

const client = new TrackPostClient({
  apiKey: 'tp_live_abc123',
  awsAccessKeyId: 'AKIA...', // ❌ Hardcoded!
  awsSecretAccessKey: 'secret...' // ❌ Hardcoded!
});

✅ Do this instead:

// .env file (add to .gitignore!)
TRACKPOST_AWS_ACCESS_KEY_ID=AKIA...
TRACKPOST_AWS_SECRET_ACCESS_KEY=secret...

// Your code
const client = new TrackPostClient({
  apiKey: process.env.TRACKPOST_API_KEY,
  awsAccessKeyId: process.env.TRACKPOST_AWS_ACCESS_KEY_ID,
  awsSecretAccessKey: process.env.TRACKPOST_AWS_SECRET_ACCESS_KEY
});

4. Enable CloudTrail for Audit

Track API usage:

1. Go to CloudTrail in AWS Console
2. Click Create trail
3. Name: TrackPostAudit
4. Enable logging for SES and SNS events
5. Store logs in S3 for review

5. Use AWS Secrets Manager (Optional)

For enhanced security, store credentials in AWS Secrets Manager:

1. Secrets Manager → Store a new secret
2. Secret type: Other type of secret
3. Add key-value pairs:
   • accessKeyId: Your access key
   • secretAccessKey: Your secret key
4. Name: trackpost/aws-credentials
5. TrackPost can retrieve these programmatically

6. Monitor with CloudWatch

Set up alerts for:

• High bounce rates
• Unusual sending volumes
• SES configuration changes

CloudWatch Alarms:

1. Go to CloudWatch → Alarms → Create alarm
2. Select SES metrics
3. Set thresholds for your use case

Credential Troubleshooting

“Invalid credentials” Error

Check:

1. Access Key ID and Secret Access Key are correct
2. No extra spaces or characters
3. IAM user still exists and is active
4. Credentials are for the correct AWS account

“Access denied” Error

Check:

1. IAM policy attached to user
2. Policy includes all required actions (SES and SNS)
3. User is not in a group with restrictive policies
4. No explicit “Deny” statements in policies

“Token has expired” Error

Temporary credentials (from STS) have expired. For TrackPost, use long-term access keys, not temporary session tokens.

Credentials Not Working in Specific Region

Check:

1. SES is available in the selected region
2. Your account has SES access in that region
3. IAM permissions are region-agnostic (they usually are)

Multi-Account Setup

If you manage multiple TrackPost workspaces or environments:

Separate IAM Users per Environment

Cross-Account Access (Advanced)

If your TrackPost account is in a different AWS account than SES:

1. Create IAM role in SES account:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::TRACKPOST_ACCOUNT_ID:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "your-external-id"
        }
      }
    }
  ]
}

2. Attach SES permissions to this role
3. Configure TrackPost to assume this role

Credential Storage Options

Option 1: TrackPost Dashboard (Default)

• Credentials stored encrypted in TrackPost database
• Easy to update via dashboard
• Good for most use cases

Option 2: Environment Variables

export TRACKPOST_AWS_ACCESS_KEY_ID=AKIA...
export TRACKPOST_AWS_SECRET_ACCESS_KEY=secret...
export TRACKPOST_AWS_REGION=us-east-1

Option 3: AWS Secrets Manager

More secure, but requires additional setup:

// Retrieve from Secrets Manager
const secret = await secretsManager
  .getSecretValue({ SecretId: 'trackpost/aws-credentials' })
  .promise();

const credentials = JSON.parse(secret.SecretString);

Comparison

Next Steps

• Domain Setup - Verify your sending domain
• Deliverability - Configure SPF, DKIM, DMARC
• Security Best Practices - Common security pitfalls
• CLI Setup - Configure AWS via CLI

Resources

• AWS IAM Documentation
• AWS SES Security Best Practices
• AWS Security Best Practices