RDS IAM Database Authentication lets you ditch the static database password for a dynamic, short-lived token.
Let’s watch it in action. Imagine we have a PostgreSQL RDS instance.
First, we need to enable IAM Database Authentication on the instance. This is a simple toggle in the RDS console under "Connectivity & security" -> "IAM database authentication".
aws rds modify-db-instance \
--db-instance-identifier my-pg-instance \
--enable-iam-database-authentication \
--apply-immediately
This tells RDS to start accepting IAM roles and users as database principals. When this is enabled, RDS will attempt to create a special rdsiam user in your database. This user acts as the bridge between IAM and your database. It’s not a user you’ll ever log in as directly, but it’s crucial for the authentication flow.
Next, we need to create an IAM policy that grants permissions to generate database authentication tokens.
{
"Version": "2012-01-01",
"Statement": [
{
"Effect": "Allow",
"Action": [
"rds-db:connect"
],
"Resource": [
"arn:aws:rds-db:us-east-1:123456789012:dbuser:my-pg-instance/*"
]
}
]
}
Notice the Resource ARN. It’s specific: arn:aws:rds-db:<region>:<account-id>:dbuser:<db-instance-identifier>/<db-user-name>. The <db-user-name> part is key. This is the database user that the IAM principal will assume inside the database. You don’t create this user in your database beforehand; IAM and RDS handle it.
Now, attach this policy to an IAM user or role that your application will assume. Let’s say we have an IAM user my-app-user.
To get a database login token, your application (or you, for testing) will use the AWS SDK or the aws CLI.
aws rds generate-db-auth-token \
--hostname my-pg-instance.abcdefghijk.us-east-1.rds.amazonaws.com \
--port 5432 \
--region us-east-1 \
--username my-db-user
This command, when run by my-app-user (or any principal with the rds-db:connect permission for my-db-user), will output a temporary authentication token. This token is essentially a signed request that proves your identity to RDS.
Your application then uses this token as the password when connecting to the database. For PostgreSQL, this looks like:
PGPASSWORD=$(aws rds generate-db-auth-token --hostname my-pg-instance.abcdefghijk.us-east-1.rds.amazonaws.com --port 5432 --region us-east-1 --username my-db-user) \
psql "postgresql://my-db-user@my-pg-instance.abcdefghijk.us-east-1.rds.amazonaws.com:5432/mydatabase"
RDS validates the token against the IAM principal’s identity and the requested database username. If valid, it grants access for the duration of the token (typically 15 minutes).
The fundamental problem this solves is credential management. Instead of having a long-lived, static database password that needs to be rotated, secured, and potentially committed to code, you’re using short-lived, dynamically generated tokens tied to your AWS identity. This significantly reduces the attack surface.
The database user specified in generate-db-auth-token (my-db-user in the example) doesn’t need to exist in the database beforehand. When the first token for a specific database user is generated by an IAM principal, RDS will automatically create that user in the database with the necessary privileges granted by the IAM policy. For PostgreSQL, this means CREATE USER "my-db-user". Subsequent connections by the same IAM principal for that database user will use the existing database user.
The rds-db:connect action in the IAM policy is not just a general permission; it’s scoped to a specific database user within a specific RDS instance. This fine-grained control allows you to grant an IAM user or role the ability to log in as only read_only_user on my-reporting-db, but not as admin_user on my-transaction-db.
The tokens are signed using AWS Signature Version 4 (SigV4) process, but the actual signing is handled by the AWS SDKs when you call generate-db-auth-token. You don’t need to worry about SigV4 details yourself for this specific operation. The token itself is a JWT-like structure containing information about the IAM principal, the target database, and an expiration time, all signed by AWS.
The most surprising part is that the database user name you provide to generate-db-auth-token is what RDS uses to create the user in the database if it doesn’t exist. This means you can provision database users and their IAM-based access simultaneously.
The next step is understanding how to manage database roles and permissions within the database once users are authenticated via IAM.