Aws Secrets Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require countxvat/aws-secrets-bundle
   

   Register the bundle in config/bundles.php (Laravel uses autoloading, so no manual registration is needed in most cases).

2. Configure services.php (Laravel) Add AWS Secrets Manager integration to Laravel’s environment configuration:

   'aws_secrets' => [
       'client_config' => [
           'region' => env('AWS_REGION', 'us-east-1'),
           'version' => 'latest',
           'credentials' => [
               'key' => env('AWS_ACCESS_KEY_ID'),
               'secret' => env('AWS_SECRET_ACCESS_KEY'),
           ],
       ],
       'cache' => env('AWS_SECRETS_CACHE', 'array'), // 'apcu', 'filesystem', or 'array'
       'delimiter' => ',',
       'ignore' => env('AWS_SECRETS_IGNORE', false), // Set to `true` for local/dev
   ],
   

3. First Use Case: Fetch a Secret Define an environment variable in .env:

   AWS_SECRET=my_secret_name
   

   Access it in Laravel via:

   $secret = env('AWS_SECRET'); // Automatically fetches from AWS Secrets Manager
   

   Or in a service container:

   $this->getSecretValue('AWS_SECRET');
   

Implementation Patterns

Workflows

1. Environment Variable Injection Use AWS_* prefixed variables to auto-fetch secrets:

   AWS_DB_PASSWORD=prod_db_password,password
   AWS_API_KEY=api_keys/prod,key_id
   

   Access via:

   $dbPassword = env('AWS_DB_PASSWORD');
   $apiKey = env('AWS_API_KEY');
   

2. Service Container Integration Bind secrets to Laravel services:

   $this->app->bind('app.secrets', function ($app) {
       return [
           'db' => $app['aws.secrets']->getSecretValue('AWS_DB_PASSWORD'),
           'api' => $app['aws.secrets']->getSecretValue('AWS_API_KEY'),
       ];
   });
   

3. Dynamic Configuration Load secrets into config files (e.g., config/aws.php):

   return [
       'credentials' => [
           'key' => env('AWS_ACCESS_KEY_ID'),
           'secret' => env('AWS_SECRET_ACCESS_KEY'),
           'token' => env('AWS_SESSION_TOKEN', null),
       ],
       'region' => env('AWS_REGION', 'us-east-1'),
   ];
   

4. Caching Strategies

   • APCu: Best for high-traffic apps (requires PHP APCu extension).

     'cache' => 'apcu',
     

   • Filesystem: Persistent across restarts (use for long-lived secrets).

     'cache' => 'filesystem',
     

   • Array: In-memory (default, no persistence).

     'cache' => 'array',
     

5. Local Development Set ignore: true in config to bypass AWS calls:

   aws_secrets:
       ignore: true
   

   Use .env.local for mock secrets:

   AWS_DB_PASSWORD=local_db_password
   

Gotchas and Tips

Pitfalls

1. Credentials Leakage

   • Risk: Hardcoding AWS credentials in config/services.php exposes them in version control.
   • Fix: Use Laravel’s .env or AWS IAM roles (EC2/ECS) instead of static keys.

2. Cache Invalidation

   • Issue: Filesystem cache may not update immediately if secrets change in AWS.
   • Fix: Clear cache manually or use apcu for real-time updates:

     php artisan cache:clear
     

3. Nested JSON Secrets

   • Problem: Delimiter , may conflict with JSON keys (e.g., AWS_SECRET=path/to/secret,sub.key).
   • Fix: URL-encode keys or use a unique delimiter (e.g., |):

     AWS_SECRET=path/to/secret|sub.key
     

     Update config:

     delimiter: '|'
     

4. Rate Limiting

   • AWS Limit: Secrets Manager has quotas.
   • Fix: Cache aggressively or batch secret fetches.

5. Local Development Quirks

   • Symptom: Secrets not loading when ignore: true.
   • Debug: Verify .env.local exists and secrets are prefixed with AWS_.

Debugging

• Enable Logging Add to config/services.php:

  'debug' => env('AWS_SECRETS_DEBUG', false),
  

  Check Laravel logs for AWS API calls:

  tail -f storage/logs/laravel.log | grep aws
  

• Manual Secret Fetch Use the service directly to test:

  $secrets = $this->app->make('aws.secrets');
  $value = $secrets->getSecretValue('AWS_SECRET_NAME');
  

Extension Points

1. Custom Secret Processor Extend the bundle’s AwsSecretsProcessor to add logic (e.g., encryption/decryption):

   namespace App\AwsSecrets;
   
   use CountXvat\AwsSecretsBundle\Processor\AwsSecretsProcessor;
   
   class CustomAwsSecretsProcessor extends AwsSecretsProcessor {
       public function process($value) {
           $decrypted = parent::process($value);
           return decrypt($decrypted); // Example: Laravel encryption
       }
   }
   

   Bind it in config/services.php:

   'aws_secrets.processor' => App\AwsSecrets\CustomAwsSecretsProcessor::class,
   

2. Event Listeners Listen for secret fetch events to log or transform values:

   use CountXvat\AwsSecretsBundle\Event\SecretFetchedEvent;
   
   public function handle(SecretFetchedEvent $event) {
       if ($event->getName() === 'AWS_DB_PASSWORD') {
           $event->setValue(str_replace('old_', 'new_', $event->getValue()));
       }
   }
   

3. Fallback Values Provide defaults if AWS fails:

   $secret = env('AWS_SECRET', 'fallback_value');
   

Performance Tips

• Batch Fetching: For multiple secrets, use getAllSecretValues():

  $secrets = $this->app['aws.secrets']->getAllSecretValues([
      'AWS_SECRET_1',
      'AWS_SECRET_2',
  ]);
  

• Region Optimization: Place secrets in the same region as your app to reduce latency.