# AWS Secrets Manager Integration

This document explains how to use AWS Secrets Manager to securely store and retrieve database credentials instead of using environment variables.

## Overview

The application now supports retrieving database credentials from AWS Secrets Manager, providing better security and credential management compared to environment variables.

## Configuration

### Environment Variables

To enable Secrets Manager, set the following environment variables:

```bash
# Enable AWS Secrets Manager
USE_SECRETS_MANAGER=true

# Name of the secret in AWS Secrets Manager
DB_SECRET_NAME=DB_CREDENTIALS

# AWS credentials for accessing Secrets Manager
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1
```

### Fallback Configuration

If Secrets Manager is disabled or fails, the application will fall back to using environment variables:

```bash
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=mip_legacy
```

## AWS Secrets Manager Setup

### 1. Create a Secret

Create a secret in AWS Secrets Manager with the following JSON structure:

```json
{
  "host": "your-db-host.com",
  "port": 3306,
  "username": "your_db_user",
  "password": "your_db_password",
  "database": "your_db_name"
}
```

**Alternative field names** (for compatibility):
- `host` or `DB_HOST`
- `port` or `DB_PORT`
- `username` or `user` or `DB_USER`
- `password` or `DB_PASSWORD`
- `database` or `db` or `DB_NAME`

### 2. IAM Permissions

Ensure your AWS credentials have the following permissions:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:region:account:secret:DB_CREDENTIALS-*"
    }
  ]
}
```

## Usage Examples

### Basic Usage

```python
from app.services.secrets_service import secrets_service

# Get database credentials
credentials = await secrets_service.get_database_credentials()

# Get a specific secret
secret = await secrets_service.get_secret("MY_CUSTOM_SECRET")
```

### Force Refresh

```python
# Clear cached credentials and fetch fresh ones
await secrets_service.refresh_credentials()
```

## Security Features

### Credential Caching

- Credentials are cached for 1 hour to reduce API calls
- Cache is automatically invalidated after TTL
- Manual cache refresh available

### Fallback Mechanism

- If Secrets Manager fails, falls back to environment variables
- Graceful degradation ensures application availability
- Comprehensive error logging for troubleshooting

### Error Handling

- Detailed error messages for different failure scenarios
- Automatic retry logic for transient failures
- Secure logging (passwords are never logged)

## Migration Guide

### From Environment Variables

1. **Create the secret** in AWS Secrets Manager
2. **Update environment variables**:
   ```bash
   # Old way
   DB_HOST=localhost
   DB_PASSWORD=secret
   
   # New way
   USE_SECRETS_MANAGER=true
   DB_SECRET_NAME=DB_CREDENTIALS
   AWS_ACCESS_KEY_ID=your_key
   AWS_SECRET_ACCESS_KEY=your_secret
   ```
3. **Test the connection** using the health endpoint
4. **Remove old DB_* variables** once confirmed working

### Testing

Use the health endpoint to verify Secrets Manager integration:

```bash
curl http://localhost:8000/health
```

Check logs for confirmation of Secrets Manager usage.

## Troubleshooting

### Common Issues

1. **AWS Credentials Not Found**
   - Ensure `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are set
   - Verify IAM permissions include Secrets Manager access

2. **Secret Not Found**
   - Check `DB_SECRET_NAME` matches the secret name in AWS
   - Verify the secret exists in the specified AWS region

3. **Permission Denied**
   - Ensure IAM user/role has `secretsmanager:GetSecretValue` permission
   - Check resource ARN in IAM policy

4. **Fallback to Environment Variables**
   - Check application logs for Secrets Manager errors
   - Verify secret JSON format matches expected structure

### Debug Mode

Enable debug logging to see detailed Secrets Manager operations:

```bash
LOG_LEVEL=DEBUG
```

## Best Practices

1. **Secret Rotation**: Regularly rotate database credentials
2. **Least Privilege**: Use IAM roles with minimal required permissions
3. **Monitoring**: Set up CloudWatch alarms for Secrets Manager API calls
4. **Backup**: Keep environment variables as fallback for critical systems
5. **Testing**: Test Secrets Manager integration in staging before production