tacticmedia/rds-auth-middleware

Doctrine DBAL driver middleware for Amazon RDS: IAM token authentication and master-password refresh from Secrets Manager.

dev-main 2026-08-15 00:52 UTC

Requires

• php: >=8.3
• async-aws/core: ^1.28
• async-aws/secrets-manager: ^2.0
• doctrine/dbal: ^4.0
• psr/cache: ^2.0 || ^3.0
• psr/clock: ^1.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.52
• friendsofphp/php-cs-fixer: ^3.95.11
• phpstan/phpstan: ^2.1.0
• phpstan/phpstan-doctrine: ^2.0.27
• phpstan/phpstan-symfony: ^2.0.20
• phpunit/phpunit: ^12.5 || ^13.3
• rector/rector: ^2.5.2
• roave/security-advisories: dev-latest
• symfony/cache: ^7.4 || ^8.0
• symfony/http-client: ^7.4 || ^8.0

Conflicts

• symfony/polyfill-uuid: <1.13.1

MIT

• dbal
• doctrine
• postgresql
• aws
• iam
• rds
• secrets-manager

Published on Packagist.org on 2026-08-15 00:53 UTC

README

Important: Symfony users should install tacticmedia/rds-auth-bundle instead, which configures this package through bundle configuration.

A Doctrine DBAL driver middleware that supplies the database credential for an Amazon RDS instance. At connection time it selects one of three modes:

• When IAM username is configured: replace the user and password with a short-lived RDS IAM authentication token.
• When the Secret ARN is configured: connect with the configured password; when the database rejects it, read the current password from Secrets Manager and retry once. This recovers from automated RDS ManageMasterUserPassword rotation without a deployment.
• Neither configured: pass the connection parameters through unchanged.

Before you choose IAM authentication, read its limitations: AWS requires 300 to 1000 MiB extra database memory for it, which rules out small instances. The managed password mode exists for exactly those deployments.

Installation

composer require tacticmedia/rds-auth-middleware

Quick start

use Doctrine\DBAL\Configuration;
use Doctrine\DBAL\DriverManager;
use TacticMedia\RdsAuth\RdsAuthMiddleware;
use TacticMedia\RdsAuth\RdsIamTokenProvider;
use TacticMedia\RdsAuth\RdsSecretPasswordProvider;

$region = getenv('AWS_REGION') ?: 'us-east-1';

$middleware = new RdsAuthMiddleware(
    new RdsIamTokenProvider($region),
    new RdsSecretPasswordProvider($region),
    getenv('RDS_IAM_USERNAME') ?: null,          // null disables the IAM path
    getenv('RDS_SECRET_ARN') ?: null,            // null disables the refresh path
    $cachePool,                                  // any PSR-6 pool; omit to disable caching
);

$configuration = new Configuration();
$configuration->setMiddlewares([$middleware]);

$connection = DriverManager::getConnection($params, $configuration);

Documentation

• Getting started - requirements, installation, wiring, mode selection
• IAM token authentication - token flow, AWS-side setup, TLS, limitations
• Managed password - Secrets Manager rotation recovery, failure detection
• Caching - PSR-6 behaviour, TTLs, invariants, key format
• Database engines - engine detection, ports, TLS per engine
• Architecture - class map, connection flow, design decisions
• Testing - suites, Docker services, environment variables, fixtures

Development

composer test               # PHPUnit unit suite
composer test:integration   # PHPUnit integration suite, needs Docker services
composer qa                 # rector, cs, stan, test in sequence

See docs/testing.md for the Docker services, environment variables, and reference fixtures.

License

MIT. See LICENSE.