RDS IAM Database Authentication: Setup for PostgreSQL and MySQL, the rds-db:connect Policy, Tokens, RDS Proxy, Aurora, and "PAM Authentication Failed" Fixed

RDS IAM database authentication lets your application log in to Amazon RDS or Aurora (MySQL, MariaDB or PostgreSQL) with a short-lived token from IAM instead of a stored password. Four steps set it up: enable IAM authentication on the instance or cluster; create a database user mapped to IAM (PostgreSQL: CREATE USER app_user; GRANT rds_iam TO app_user;, MySQL: CREATE USER 'app_user' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';); allow rds-db:connect on arn:aws:rds-db:REGION:ACCOUNT:dbuser:DB_RESOURCE_ID/app_user in the app's IAM role; and connect with a token from aws rds generate-db-auth-token (or the SDK) as the password, over SSL. Tokens are valid for 15 minutes, but only for opening a connection; open connections keep working. The common errors, "PAM authentication failed for user" on PostgreSQL and "Access denied for user" on MySQL, almost always mean an expired token, a token made for a different hostname or user, a missing rds_iam grant, the wrong resource ID in the policy, or SSL turned off. Below: every step with commands, Python, Node.js and Java examples, RDS Proxy, Terraform, limits, cross-account access, and each error with its fix.

Jake's computer shop keeps its repair tickets in a small PostgreSQL database on Amazon RDS. For two years the ticket app logged in with a password in a config file, the same password three people knew and nobody had changed. When Ethan moved the app to Lambda, he took the chance to get rid of the password entirely. IAM authentication took an hour to set up and two more to debug, because one character in the policy ARN was wrong. This page is the hour, without the two.

New to RDS? Our plain-English RDS explainer covers the basics, and the cards below cover the rest.

How RDS IAM authentication works

With a normal database login, your database stores a password and checks it. With IAM authentication, your database trusts AWS instead:

1. Your application, running with AWS credentials (a Lambda role, an EC2 instance role, your SSO login), asks for a database authentication token. You generate the token locally with the SDK or CLI, signed with those credentials; you do not need a network call to the database to create it.
2. Your application connects to the database as an ordinary client, giving the token in place of the password, over an encrypted (SSL/TLS) connection.
3. RDS checks the token's signature with IAM: is it valid, unexpired, for this database user, and does your identity have rds-db:connect permission for it?
4. If so, your login succeeds, and your session works exactly like any other database session.

What you gain is real: no password for you to store, rotate or leak; access you control and audit through IAM like everything else; and access you can revoke by changing a policy. You can use it with RDS for MySQL, MariaDB and PostgreSQL and with Aurora MySQL and Aurora PostgreSQL. If you run RDS for SQL Server or Oracle, you use Kerberos (Active Directory) authentication instead.

IAM authentication or a password in Secrets Manager?

Both keep passwords out of your code. Which one fits you depends on how your app connects:

If your app already runs with a role on Lambda, ECS or EC2 and opens connections at a moderate rate, IAM authentication is the simpler, password-free choice. If you need very high connection rates, an engine without IAM support, or tools that cannot handle tokens, keep a password and let Secrets Manager rotate it; our Secrets Manager guide covers that route. Many teams use both: IAM for applications, a rotated password for the one reporting tool that cannot do tokens.

Jake: "So there's no password at all? How does the database know it's us?"

Ethan: "AWS vouches for us. The app shows a pass that AWS signed fifteen minutes ago, and the database checks the signature instead of a password."

Set it up: four steps

Step 1: enable IAM authentication on the database.

# RDS instance
aws rds modify-db-instance --db-instance-identifier tickets-db \
  --enable-iam-database-authentication --apply-immediately

# Aurora cluster
aws rds modify-db-cluster --db-cluster-identifier tickets-cluster \
  --enable-iam-database-authentication --apply-immediately

In the console, it is the Database authentication section of the instance's Modify page: choose "Password and IAM database authentication." Existing password logins keep working; IAM is added alongside.

Step 2: create a database user for IAM. Connect once with the master user and run:

-- PostgreSQL (RDS or Aurora)
CREATE USER app_user;
GRANT rds_iam TO app_user;
GRANT CONNECT ON DATABASE tickets TO app_user;
GRANT SELECT, INSERT, UPDATE ON ALL TABLES IN SCHEMA public TO app_user;

-- MySQL or MariaDB (RDS or Aurora)
CREATE USER 'app_user'@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
GRANT SELECT, INSERT, UPDATE ON tickets.* TO 'app_user'@'%';

On PostgreSQL, a user with the rds_iam role can only log in with IAM tokens; password logins stop working for that user. Create a separate user for IAM rather than granting rds_iam to the master user.

Step 3: allow the IAM identity to connect. Covered in detail next, because the resource ARN is where most setups go wrong.

Step 4: connect with a token, over SSL. Covered in the connection section for the CLI, Python, Node.js and Java.

The IAM policy, and the resource ID trap

The permission is rds-db:connect, and its resource is a special ARN that names the database user:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "rds-db:connect",
    "Resource": "arn:aws:rds-db:us-east-1:111122223333:dbuser:db-ABCDEFGHIJKL01234567890XYZ/app_user"
  }]
}

Three details in that ARN cause most failures:

• The service is rds-db, not rds.
• The middle part is the resource ID, not the database name. It looks like db- followed by letters and digits for an instance, or cluster- followed by letters and digits for an Aurora cluster. Find it with aws rds describe-db-instances --db-instance-identifier tickets-db --query "DBInstances[0].DbiResourceId", or aws rds describe-db-clusters --query "DBClusters[0].DbClusterResourceId" for Aurora. Using tickets-db there is the single most common mistake.
• The user name at the end must match the database user exactly, including case.

Attach the policy to whatever identity your app runs as: the Lambda execution role, the EC2 instance role, the ECS task role, or your own SSO role for testing. A wildcard such as dbuser:db-ABC.../* allows every database user on that instance; prefer naming the user.

Jake: "Which character was wrong in yours?"

Ethan: "I wrote the database's name where the resource ID goes. It looked completely reasonable and was completely wrong."

Connect with a token: CLI, Python, Node.js and Java

Download the RDS certificate bundle once, so clients can verify the server (global-bundle.pem from AWS's trust store), then generate a token and use it as the password.

From the command line (PostgreSQL):

HOST=tickets-db.abcdefghij12.us-east-1.rds.amazonaws.com
export PGPASSWORD="$(aws rds generate-db-auth-token --hostname $HOST --port 5432 --region us-east-1 --username app_user)"
psql "host=$HOST port=5432 dbname=tickets user=app_user sslmode=verify-full sslrootcert=global-bundle.pem"

From the command line (MySQL): the MySQL client must send the token in clear text inside the encrypted connection, so it needs one extra flag:

TOKEN="$(aws rds generate-db-auth-token --hostname $HOST --port 3306 --region us-east-1 --username app_user)"
mysql --host=$HOST --port=3306 --user=app_user --password="$TOKEN" \
  --enable-cleartext-plugin --ssl-ca=global-bundle.pem

Python (boto3 and psycopg2):

import boto3
import psycopg2

HOST = "tickets-db.abcdefghij12.us-east-1.rds.amazonaws.com"
rds = boto3.client("rds", region_name="us-east-1")

def connect():
    token = rds.generate_db_auth_token(DBHostname=HOST, Port=5432, DBUsername="app_user", Region="us-east-1")
    return psycopg2.connect(host=HOST, port=5432, dbname="tickets", user="app_user",
                            password=token, sslmode="verify-full", sslrootcert="global-bundle.pem")

with connect() as conn, conn.cursor() as cur:
    cur.execute("SELECT count(*) FROM tickets")
    print(cur.fetchone())

Node.js (AWS SDK v3 and the pg package):

import { Signer } from "@aws-sdk/rds-signer";
import pg from "pg";
import fs from "node:fs";

const host = "tickets-db.abcdefghij12.us-east-1.rds.amazonaws.com";
const signer = new Signer({ hostname: host, port: 5432, username: "app_user", region: "us-east-1" });

const client = new pg.Client({
  host, port: 5432, database: "tickets", user: "app_user",
  password: await signer.getAuthToken(),
  ssl: { ca: fs.readFileSync("global-bundle.pem").toString() },
});
await client.connect();
console.log((await client.query("SELECT count(*) FROM tickets")).rows);

Java and Spring Boot: the AWS Advanced JDBC Wrapper handles tokens for you with its IAM plugin, so the application configuration names a user and no password. With plain JDBC, generate the token with the SDK's RDS utilities and pass it as the password. In either case, configure the connection pool to create connections with a fresh token, because a pool that caches the first token fails 15 minutes later when it opens a new connection.

The token generation itself needs AWS credentials. If it fails with "could not load credentials" in Node.js, our SDK credentials guide covers that first problem.

Test your setup in five minutes

Before you change your application, prove each piece works from your own machine. If you test in this order, the first failing step tells you exactly where your problem is:

1. Check that IAM auth is enabled: aws rds describe-db-instances --db-instance-identifier tickets-db --query "DBInstances[0].IAMDatabaseAuthenticationEnabled" should print true.
2. Check your identity: aws sts get-caller-identity shows which role or user your token will be signed as. Make sure that identity has the rds-db:connect policy.
3. Check the user exists with the right setup: as the master user, run \du app_user in psql and look for rds_iam in its roles (or SELECT user, plugin FROM mysql.user; on MySQL and look for AWSAuthenticationPlugin).
4. Generate a token and connect with psql or mysql using the commands below, from a machine that can reach the database.
5. Only then move to your code. If the command line works and your app does not, the difference is in your app: the hostname it generates the token for, its credentials, or its SSL settings.

You can run this test in five minutes, and it saves you hours of guessing inside application logs.

Tokens, expiry and connection pools

An authentication token is valid for 15 minutes, and it is only checked when a connection opens. That leads to three practical rules:

• Generate a new token for each new connection, or at least every few minutes. Generating one is a fast local signing step, not a network call, so there is no reason to cache it long.
• Open connections stay open past 15 minutes. A long-running session or a pooled connection is not cut off when its token expires; only new logins need a fresh token.
• Connection pools need a token callback. Pools that take a fixed password at startup break after 15 minutes. Use the pool's hook for supplying the password per connection (for example, a password function in node-postgres, or the JDBC wrapper's IAM plugin), so each new connection gets a fresh token.

The token is tied to the hostname, port, Region and user it was generated for. A token made for the instance endpoint does not work against a cluster endpoint, a reader endpoint, a custom DNS name or an RDS Proxy endpoint, and vice versa: generate it for exactly the host you connect to.

Connecting from your laptop to a private database

Most production databases are not reachable from the internet, so you cannot connect from your laptop directly. The tidy way in is Session Manager port forwarding through an EC2 instance in the same VPC, with no SSH keys and no open inbound ports:

aws ssm start-session --target i-0123456789abcdef0 \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters host=tickets-db.abcdefghij12.us-east-1.rds.amazonaws.com,portNumber=5432,localPortNumber=5432

While that runs, your laptop's port 5432 leads to the database. Two details trip people up here:

• Generate the token for the real database hostname, not localhost. RDS checks the hostname inside the token, and it must be the database endpoint, even though your client connects to localhost.
• Hostname verification fails through a tunnel, because the server's certificate names the database endpoint, not localhost. Use sslmode=verify-ca (checks the certificate chain but not the name) for this local session, or add the endpoint name to your hosts file pointing at 127.0.0.1 and keep verify-full.

Your own IAM identity needs rds-db:connect for the user you log in as, plus Session Manager permissions for the instance. Giving yourself a separate, read-only database user for this kind of access keeps your laptop sessions away from the application's write permissions.

Jake: "So even you can't just log in from home anymore?"

Ethan: "I can, through the tunnel, as a read-only user, with my own login. Which is exactly how it should have been all along."

IAM authentication from Lambda

Lambda is where IAM authentication shines: the function already has a role, so there is nothing to store at all. Add rds-db:connect to the execution role, put the function in the database's VPC with a security group the database allows on its port, and connect as above, creating the connection outside the handler so warm invocations reuse it.

Two Lambda-specific cautions. A sudden burst of new invocations means a burst of new connections, and IAM authentication is designed for moderate connection rates (see limits), so busy functions should sit behind RDS Proxy, covered next. And a timeout connecting (rather than an authentication error) is a network problem, not an IAM one; our Lambda to RDS timeout guide walks through it.

RDS Proxy with IAM authentication

RDS Proxy sits between your application and the database, pooling connections. With IAM authentication on the proxy, clients authenticate to the proxy with IAM tokens, and the proxy holds the pooled connections to the database.

• In the proxy's settings, set client authentication to require IAM.
• Give your application's role rds-db:connect on the proxy's resource: arn:aws:rds-db:REGION:ACCOUNT:dbuser:prx-PROXY_RESOURCE_ID/app_user, using the proxy's resource ID (it starts with prx-).
• Generate the token for the proxy endpoint hostname, not the database's.
• Configure how the proxy itself logs in to the database: traditionally with a Secrets Manager secret holding the database user's credentials, which the proxy reads with its own role.

This combination is the standard answer for serverless applications: IAM tokens for the app, connection pooling in the proxy, and no password in your code.

Terraform and CloudFormation

Terraform: enable IAM authentication with one argument, and build the policy ARN from the resource ID attribute so it is always right:

resource "aws_db_instance" "tickets" {
  identifier                          = "tickets-db"
  engine                              = "postgres"
  instance_class                      = "db.t4g.micro"
  allocated_storage                   = 20
  username                            = "postgres"
  manage_master_user_password         = true
  iam_database_authentication_enabled = true
  # ...
}

data "aws_iam_policy_document" "db_connect" {
  statement {
    actions   = ["rds-db:connect"]
    resources = ["arn:aws:rds-db:${var.region}:${data.aws_caller_identity.me.account_id}:dbuser:${aws_db_instance.tickets.resource_id}/app_user"]
  }
}

For Aurora, the same argument goes on aws_rds_cluster, and the cluster's cluster_resource_id attribute provides the cluster- ID. CloudFormation uses EnableIAMDatabaseAuthentication: true on the DB instance or cluster, and !GetAtt MyDB.DbiResourceId to build the ARN.

Creating the database user (GRANT rds_iam or AWSAuthenticationPlugin) happens inside the database, so neither tool does it on its own; run it once by hand, from a migration script, or with a database provider for Terraform.

Aurora specifics

If you run Aurora rather than a single RDS instance, the same steps apply with three differences:

• Enable it on the cluster (modify-db-cluster), not on individual instances.
• Use the cluster resource ID, which starts with cluster-, in the rds-db:connect ARN. One policy then covers the writer, the readers and any instance that joins later.
• Generate the token for the endpoint you connect to: the cluster (writer) endpoint, the reader endpoint, or a custom endpoint. A token for the writer endpoint does not work on the reader endpoint. Our writer vs reader endpoint guide explains which to use when.

Aurora Serverless v2 supports IAM authentication the same way, which suits its pattern of scaling with demand: no password to distribute as your applications scale out.

Switching a live app from a password to IAM, without downtime

1. Enable IAM authentication on the database. Password logins keep working, so nothing breaks.
2. Create a new database user for IAM (for example, app_iam) with the same privileges as the current application user. Leave the old user alone for now.
3. Add rds-db:connect for the new user to your application's role.
4. Change your app to connect as the new user with a fresh token per connection, and deploy it to one instance or a canary first.
5. Watch the connection logs until all connections arrive as the new user.
6. Retire the password: lock or drop the old user, and delete the password from config files and secrets.

Because both logins work side by side during the switch, you can roll back at any point by redeploying the old version. Using a new user, rather than converting the old one, is what makes that rollback safe: on PostgreSQL, granting rds_iam to the old user would immediately stop its password from working.

Limits and when not to use IAM authentication

• Connection rate. IAM authentication is recommended for workloads opening fewer than about 200 new IAM-authenticated connections per second. Above that, use connection pooling (RDS Proxy) or password authentication with Secrets Manager.
• Engines. MySQL, MariaDB and PostgreSQL on RDS and Aurora. Not RDS for SQL Server, Oracle or Db2, which use directory-based authentication.
• SSL is required. Clients that cannot use TLS cannot use IAM tokens.
• Tools. Desktop clients and BI tools must be able to take a token as a password; most can, but each new session needs a fresh token, which is awkward for long-lived saved connections. Many teams keep a password user for such tools and IAM for applications.
• Token tied to host. Every distinct endpoint needs its own token, as above.

Seeing who connected

Once you have several roles connecting as different database users, you will want a record of who logged in and when. Your database's own logs do this best:

• PostgreSQL: set log_connections to 1 in your DB parameter group, and export the PostgreSQL log to CloudWatch Logs from the instance's log export settings. Each successful login then shows the database user and client address.
• MySQL: turn on the general log or, better for production, the audit plugin your engine version supports, and export it to CloudWatch Logs.

Because each application should log in as its own database user, tied to its own IAM role, these logs tell you which application connected, which your IAM policies then tie to a specific role. That link from a database session back to an AWS identity is one of the quieter benefits of moving off shared passwords.

Cross-account access

The rds-db:connect permission must be granted in the database's own account, so an application in another account cannot simply be given the permission there. The usual pattern:

1. In the database account, create a role with rds-db:connect on the database user, whose trust policy allows the application's role from the other account to assume it.
2. In the application account, allow the application's role to sts:AssumeRole on that role.
3. In the application, assume the role first, then generate the token with the assumed role's credentials.
4. Make sure the network path exists: VPC peering, Transit Gateway or PrivateLink between the accounts' VPCs, with security groups allowing the database port.

The token is signed with whatever credentials generated it, so it is the assumed role's identity that RDS checks.

Every IAM authentication error and its fix

The PostgreSQL "PAM" error is frustratingly generic: it looks the same for an expired token, a wrong policy and a disabled feature. Work through it in order: is IAM authentication enabled on the instance; does the user have rds_iam; does the policy name rds-db:connect with the right resource ID and user; is the token fresh and generated for this exact host, port and user; and is SSL on? One of those five is nearly always the answer. For password-based login failures that are not about IAM, our Postgres authentication guide and MySQL 1045 guide cover the rest.

Frequently asked questions

The ticket app now runs on Lambda with no password anywhere: not in the code, not in the config, not in three people's heads. The function's role carries rds-db:connect for one database user, and the old shared password was retired the same afternoon. Jake's only question was what happens if someone steals the Lambda code. "They get code," Ethan said. "No key comes with it. The pass is issued to the role, fresh every time, and it expires in fifteen minutes."

Revision note. Written October 19, 2026. The safest password is the one that does not exist; the next safest expires in fifteen minutes.