Laravault Auth Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package bridges Laravel’s authentication layer with HashiCorp Vault’s secrets management, enabling dynamic credential rotation, token-based auth, and secure storage of sensitive data (e.g., DB passwords, API keys). This is ideal for:
  • Enterprise-grade Laravel apps requiring compliance (e.g., SOC2, GDPR) with secrets management.
  • Microservices architectures where Vault acts as a centralized secrets provider.
  • DevOps pipelines needing ephemeral credentials (e.g., CI/CD, serverless functions).
• Laravel Integration Points:
  • Auth Drivers: Extends Laravel’s AuthManager to fetch user credentials from Vault (e.g., JWT, OAuth tokens).
  • Configuration: Leverages Laravel’s config() system to define Vault paths/roles.
  • Service Providers: Registers as a Laravel service provider for dependency injection.
• Anti-Patterns:
  • Overhead for Simple Apps: Adds complexity for projects with static credentials or no Vault infrastructure.
  • Vault Dependency: Tight coupling to Vault may limit portability if switching secrets managers later.

Integration Feasibility

• Core Features:
  • Dynamic Secrets: Fetch DB credentials, API keys, or user tokens from Vault at runtime.
  • Token Management: Auto-refresh Vault tokens using Laravel’s Cache or Queue systems.
  • Fallback Mechanisms: Supports hybrid auth (e.g., Vault + local .env backup).
• Laravel Compatibility:
  • Version Support: Explicitly tested with Laravel 8/9 (check composer.json for constraints).
  • PHP Extensions: Requires curl and openssl (common in Laravel deployments).
  • Vault PHP SDK: Underlying dependency (hashicorp/vault-php) must align with Vault server version.
• Customization:
  • Hooks: Extendable via Laravel events (e.g., vault.token.refresh).
  • Middleware: Can integrate with Laravel’s middleware pipeline for auth checks.

Technical Risk

Key Questions

1. Vault Infrastructure:
   • Is Vault already deployed (self-hosted/cloud)? What’s the auth method (e.g., approle, LDAP)?
   • Are there existing policies/roles for Laravel’s service account?
2. Credential Rotation:
   • How frequently do secrets need rotation? Does Vault support dynamic secrets (e.g., DB creds)?
3. Fallback Strategy:
   • Should the package default to .env if Vault is unavailable? What’s the priority (fail-open vs. fail-closed)?
4. Monitoring:
   • How will Vault token usage/errors be logged? (e.g., Laravel’s Log channel + ELK stack).
5. Testing:
   • Are there existing Laravel tests for Vault auth flows? How will integration tests be mocked?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Auth Systems: Works with Laravel’s built-in Auth facade, Sanctum, Passport, or custom guards.
  • Configuration: Uses Laravel’s config/vault.php (recommended structure).
  • Queues: Async token refresh via Laravel’s queue workers (e.g., vault:refresh job).
• Vault Compatibility:
  • Auth Methods: Supports approle, token, or ldap (configured in config/vault.php).
  • Secrets Engines: Tested with kv-v2, database, and transit engines.
  • Vault Version: Must align with hashicorp/vault-php (e.g., Vault 1.10+ for newer APIs).
• Third-Party Tools:
  • Terraform: Define Vault policies/roles via IaC for consistency.
  • Prometheus/Grafana: Monitor Vault metrics (e.g., vault_api_call_duration).

Migration Path

1. Preparation:
   • Audit current secrets storage (e.g., .env, AWS Secrets Manager).
   • Set up Vault with:
     • Auth method (e.g., approle for Laravel).
     • KV secrets engine for credentials.
     • Policies restricting Laravel’s access.
2. Pilot Phase:
   • Non-Critical Secrets: Migrate API keys or non-production DB credentials first.
   • Laravel Config:

     // config/vault.php
     'connections' => [
         'default' => [
             'url' => env('VAULT_ADDR'),
             'token' => env('VAULT_TOKEN'), // or use 'approle' auth
             'role' => env('VAULT_ROLE'),
         ],
     ],
     

   • Auth Driver: Extend Laravel’s AuthManager:

     Auth::extend('vault', function ($app) {
         return new VaultAuthServiceProvider($app);
     });
     

3. Full Rollout:
   • Replace .env DB credentials with Vault dynamic secrets.
   • Update Laravel’s config/database.php to fetch credentials from Vault:

     'connections' => [
         'mysql' => [
             'driver' => 'mysql',
             'host' => env('DB_HOST'),
             'username' => fn() => Vault::secret('database/laravel/username'),
             'password' => fn() => Vault::secret('database/laravel/password'),
         ],
     ],
     

4. Validation:
   • Test credential rotation (e.g., manually update Vault secrets and verify Laravel picks up changes).
   • Load-test Vault API calls under traffic spikes.

Compatibility

• Laravel Versions:
  • Tested on 8.x/9.x; may require adjustments for 10.x (check composer.json).
  • Use laravel/framework constraint: "^8.0|^9.0".
• Vault PHP SDK:
  • Pin hashicorp/vault-php version to match your Vault server (e.g., ^1.0 for Vault 1.x).
• Environment Parity:
  • Ensure all environments (local, staging, prod) have Vault access.
  • Use env() overrides for VAULT_ADDR per environment.

Sequencing

1. Phase 1: Vault Setup (DevOps):
   • Deploy Vault cluster (or use cloud offering like HashiCorp Cloud).
   • Configure auth method (e.g., approle) and policies.
2. Phase 2: Laravel Integration (Dev):
   • Install package: composer require codybuell/laravault-auth.
   • Configure config/vault.php and service provider.
   • Implement pilot secrets migration.
3. Phase 3: Auth Flow (Dev/Security):
   • Extend Laravel’s auth to use Vault for user tokens (if applicable).
   • Set up token refresh logic (e.g., cron job or queue listener).
4. Phase 4: Monitoring (Ops):
   • Add Vault health checks to Laravel’s UP endpoint.
   • Configure alerts for token expiry or Vault API failures.

Operational Impact

Maintenance

• Package Updates:
  • Monitor codybuell/laravault-auth for updates (low activity → manual review).
  • Update hashicorp/vault-php alongside Vault server upgrades.
• Configuration Drift:
  • Centralize Vault paths/roles in Laravel config (avoid hardcoding).
  • Use environment variables for sensitive values (e.g., VAULT_ROLE).
• Dependency Management:
  • Pin all Vault-related dependencies to avoid breaking changes.

Support

• Troubleshooting:
  • Common Issues:
    • Vault token expiry → Implement auto-refresh with retries.
    • Network timeouts → Configure Laravel’s HTTP client timeouts.
    • Permission denied → Audit Vault policies for Laravel’s role.
  • Debugging Tools:
    • Enable Vault’s stdout logging for API calls.
    • Use Laravel’s Log::debug() to trace Vault interactions.
• Documentation:
  • Create runbooks for:
    • Rotating Vault tokens manually.
    • Recovering from Vault outages (fallback to .env).
    • Debugging auth failures.

Scaling

• Performance:
  • Caching: Cache Vault responses for static secrets (e.g., API keys) using Laravel’s cache.
  • Rate Limiting: