# IAM policy: RDS IAM database authentication

IAM policy examples · Updated 17 November 2026

**Short answer:** Allow rds-db:connect on arn:aws:rds-db:<region>:<account>:dbuser:<DbiResourceId>/<db-user>. The resource ID is the instance's DbiResourceId (db-…) or the Aurora cluster's resource ID (cluster-…), not its name. The database user must also be set up for IAM auth, and clients connect with a 15-minute token instead of a password.

## The policy

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ConnectAsAppUser",
      "Effect": "Allow",
      "Action": "rds-db:connect",
      "Resource": "arn:aws:rds-db:eu-west-2:123456789012:dbuser:db-ABCDEFGHIJKL01234567890ABC/app_user"
    }
  ]
}
```

## How the ARN is built

- **Service prefix `rds-db`**, not `rds`.
- **Resource ID**: for an instance, its `DbiResourceId`; for an Aurora cluster, its `DbClusterResourceId`. Both are immutable IDs, unlike the instance name.
- **Database user name** after the slash, exactly as created in the database. `dbuser:db-ABCDEFGHIJKL01234567890ABC/*` allows every user, which is rarely what you want.

```
aws rds describe-db-instances --db-instance-identifier orders-prod \
  --query 'DBInstances[0].DbiResourceId' --output text
```

## Set it up end to end

```
# 1. turn on IAM auth for the instance
aws rds modify-db-instance --db-instance-identifier orders-prod \
  --enable-iam-database-authentication --apply-immediately

# 2. create the database user (PostgreSQL)
#    CREATE USER app_user; GRANT rds_iam TO app_user;
# (MySQL: CREATE USER app_user IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';)

# 3. attach the policy to the app's role
aws iam put-role-policy --role-name orders-api-task \
  --policy-name rds-connect --policy-document file://rds-connect.json

# 4. connect with a token
export PGPASSWORD="$(aws rds generate-db-auth-token \
  --hostname orders-prod.abc123xyz.eu-west-2.rds.amazonaws.com \
  --port 5432 --username app_user --region eu-west-2)"
psql "host=orders-prod.abc123xyz.eu-west-2.rds.amazonaws.com port=5432 dbname=orders user=app_user sslmode=verify-full sslrootcert=global-bundle.pem"
```

The token is generated locally by signing a request with your credentials; no API call is made, so a bad policy only shows up when the database rejects the login.

## Things to know

- **Tokens last 15 minutes**, but only for opening a connection. An established connection stays open after the token expires.
- **TLS is required** for IAM authentication. Use the RDS CA bundle and verify the hostname.
- **Connection rate**: IAM authentication adds work to each new connection. Use connection pooling, or RDS Proxy (which also supports IAM auth), for workloads that open many connections per second.
- **Cross-account**: the role in the other account needs this policy with your account and resource ID; no change is needed on the database side.

## Check IAM auth is on

```
aws rds describe-db-instances --db-instance-identifier orders-prod \
  --query 'DBInstances[0].[IAMDatabaseAuthenticationEnabled,DbiResourceId]' --output text
```

## Common mistakes

- **Using the instance name** (`orders-prod`) in the ARN instead of the resource ID.
- **Database user not granted `rds_iam`** (PostgreSQL) or not created with the authentication plugin (MySQL): the error is a normal password failure. See [password authentication failed](https://cloudconsole.dev/errors/rds-postgres-password-authentication-failed) and [MySQL access denied for user](https://cloudconsole.dev/errors/rds-mysql-access-denied-for-user).
- **Token generated for a different host, port or region** than the one you connect to; the signature covers all three.
- **Using a reader or custom endpoint hostname** is fine, but the token must be generated for that exact hostname.

## Questions

### How long is an RDS IAM authentication token valid?

15 minutes for opening new connections. Connections already open are not closed when the token expires.

### Why do I get password authentication failed with IAM auth?

The database user isn't set up for IAM auth, the token was made for a different host, port or region, or the IAM policy's resource ID or user name doesn't match.

## When this happens away from your desk

Database login failures at night are often a credential change, not an outage. Checking the instance status and recent connection errors from a phone tells you which kind of problem you have.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [IAM database authentication for MariaDB, MySQL, and PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html)
- [Creating and using an IAM policy for IAM database access](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html)

## Related

- [FATAL: password authentication failed for user (RDS PostgreSQL)](https://cloudconsole.dev/errors/rds-postgres-password-authentication-failed)
- [ERROR 1045 (28000): Access denied for user on RDS MySQL](https://cloudconsole.dev/errors/rds-mysql-access-denied-for-user)
- [Could not connect to RDS: connection timed out](https://cloudconsole.dev/errors/rds-connection-timed-out)
- [ECS task role vs task execution role](https://cloudconsole.dev/iam/ecs-task-role-vs-execution-role)
- [IAM policy: read one secret from Secrets Manager](https://cloudconsole.dev/iam/secrets-manager-read-one-secret)
- [ABAC: tag-based access control policy example](https://cloudconsole.dev/iam/abac-tags)

---

Source: https://cloudconsole.dev/iam/rds-iam-database-auth

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
