AWS Authentication

Keep uses AWS services (SSM Parameter Store and Secrets Manager) to store your secrets. This page explains how to properly configure AWS authentication so Keep can access these vaults.

The Secret Zero Problem

Before diving into solutions, it's worth understanding the "Secret Zero" problem: if Keep fetches secrets from AWS to generate your .env file, but AWS credentials are typically stored in .env files... we have a circular dependency. You need credentials to get credentials.

The solution is to keep AWS authentication separate from your application secrets.

What NOT to Do

# .env file - DON'T DO THIS with Keep!
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
DB_PASSWORD=my-secret-password
API_KEY=sk_live_abc123

Storing AWS credentials in .env defeats the purpose of Keep. You're storing the keys to the vault alongside the secrets themselves.

Authentication Methods

Development Environment

Option 1: AWS CLI Configuration (Good)

Use the AWS CLI's standard credential file:

# Configure AWS CLI
aws configure

# This creates ~/.aws/credentials
[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
region = us-east-1

Keep automatically uses these credentials. Your .env file stays clean:

# .env - generated by Keep, no AWS credentials!
DB_PASSWORD=my-secret-password
API_KEY=sk_live_abc123

Option 2: aws-vault (Better)

aws-vault stores credentials encrypted in your OS keychain:

# Install aws-vault
brew install aws-vault  # macOS
# or download from GitHub releases

# Add your default AWS profile, or use a named profile
aws-vault add default

Edit your ~/.aws/config to set a default region and use aws-vault for credential_process:

[default]
region = us-east-1
credential_process = aws-vault exec default --json  --no-session

Edit your ~/.aws/credentials and add the same credential_process:

[default]
credential_process = aws-vault exec default --json  --no-session

Now when you run Keep (or any AWS CLI command), it will use aws-vault to fetch temporary credentials automatically.

Option 3: AWS SSO (Best for Teams)

If your organization uses AWS SSO:

# Configure SSO
aws configure sso

# Login
aws sso login --profile myproject

# Keep uses the SSO session automatically
keep show --stage=local

Production Environment

Option 1: EC2 Instance Roles (Best for AWS)

When running on EC2, ECS, or Lambda, use IAM roles:

# No credentials needed in your application!
# The AWS SDK automatically uses the instance role

# In your deployment script:
keep export --stage=production --output=.env
php artisan config:cache

Configure your EC2 instance role with appropriate IAM permissions for your vault type.

Option 2: Non-AWS Servers

For servers outside AWS, you have limited secure options:

# Option A: Credentials file on server (secured with proper permissions)
# /home/myapp/.aws/credentials (chmod 600)
[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Option B: Environment variables set during provisioning
# For systemd services: /etc/systemd/system/myapp.service.d/override.conf
[Service]
Environment="AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE"
Environment="AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

# For Docker: passed securely during container start
docker run -e AWS_ACCESS_KEY_ID=... -e AWS_SECRET_ACCESS_KEY=... myapp

# For traditional setups: /etc/environment or user's ~/.bashrc

CI/CD Pipelines

GitHub Actions

Use OIDC (recommended) or secrets:

# .github/workflows/deploy.yml
name: Deploy
on: push

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # for OIDC
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions
          aws-region: us-east-1
      
      - run: |
          vendor/bin/keep export --stage=production --output=.env
          # Deploy your application

GitLab CI

# .gitlab-ci.yml
deploy:
  script:
    # Using GitLab's AWS integration
    - vendor/bin/keep export --stage=production --output=.env
  id_tokens:
    AWS_TOKEN:
      aud: https://gitlab.com

Security Best Practices

Never Do This

❌ Store AWS credentials in your repository
❌ Put AWS credentials in .env files tracked by git
❌ Use long-lived AWS access keys in production
❌ Share AWS credentials between environments

Always Do This

✅ Use temporary credentials when possible (aws-vault, SSO, instance roles)
✅ Apply least-privilege IAM policies
✅ Rotate credentials regularly
✅ Use different credentials for each environment
✅ Audit credential usage with CloudTrail

Quick Decision Guide

Environment	Hosting	Recommended Solution
Development	Local	aws-vault or AWS SSO
Production	EC2/ECS	Instance/Task IAM Roles
Production	Lambda	Lambda Execution Role
Production	Kubernetes (EKS)	IRSA (Service Accounts)
Production	Non-AWS	~/.aws/credentials (secured)
CI/CD	GitHub Actions	OIDC with IAM Role
CI/CD	GitLab	OIDC with IAM Role
CI/CD	Other	Secure secret storage

IAM Permissions

After setting up authentication, you need to configure IAM permissions for the AWS services Keep will access:

• For AWS SSM Parameter Store: See SSM IAM Permissions
• For AWS Secrets Manager: See Secrets Manager IAM Permissions

Each vault type requires specific IAM permissions based on your usage pattern (read-only, read-write, or admin access).

PHP Application Considerations

When using Keep with PHP applications:

1. Don't hardcode AWS credentials in config

   // config/aws.php - DON'T DO THIS
   'credentials' => [
       'key'    => env('AWS_ACCESS_KEY_ID'),
       'secret' => env('AWS_SECRET_ACCESS_KEY'),
   ]

2. Let the SDK find credentials automatically

   // config/aws.php - DO THIS
   'credentials' => null, // SDK will use IAM role, ~/.aws/credentials, etc.

3. Generate .env before caching configuration

   # deployment.sh
   keep export --stage=production --output=.env
   # Then cache your application configuration if needed

Troubleshooting

"Keep can't find AWS credentials"

Check credential chain:

# 1. Environment variables
env | grep AWS

# 2. Credentials file
cat ~/.aws/credentials

# 3. Instance role (on EC2)
curl http://169.254.169.254/latest/meta-data/iam/security-credentials/

# 4. Test with AWS CLI
aws sts get-caller-identity

"Access denied when Keep tries to fetch secrets"

Verify IAM permissions:

# Test SSM access
aws ssm get-parameter --name /myapp/production/test

# Test Secrets Manager access  
aws secretsmanager get-secret-value --secret-id myapp/production/test

Summary

The Secret Zero problem is real, but solvable. By keeping AWS credentials out of your application configuration and using platform-native credential management, you maintain security while enabling Keep to manage your application secrets effectively.

Remember: Keep manages your application secrets, not your AWS credentials. Keep AWS credentials separate, secure, and platform-appropriate.