Setting up AWS IAM Authentication with Amazon RDS Proxy for Aurora PostgreSQL

Amazon RDS Proxy supports IAM-based authentication for the connection between the application and the RDS Proxy. When using IAM authentication, instead of specifying a username and password, applications use an authentication token to authenticate with RDS Proxy.

When using RDS Proxy with IAM authentication, it's important to understand that IAM authentication is only used between the application and RDS Proxy. The connection between RDS Proxy and the database still uses standard database authentication methods. RDS Proxy stores these database credentials securely in Amazon Secrets Manager, centralizing and simplifying credential management for this part of the connection.

IAM database authentication works with MariaDB, MySQL, and PostgreSQL for direct connections to the database. With this authentication method, you don't need to use a password when you connect directly to a DB instance. Instead, you use an authentication token.

An authentication token is a unique string of characters that Amazon RDS generates on request. Authentication tokens are generated using AWS Signature Version 4. Each token has a lifetime of 15 minutes. You don't need to store user credentials in the application, because authentication is managed externally using IAM. You can also still use standard database authentication. The token is only used for authentication and doesn't affect the session after it is established. For more details on the IAM Authentication, refer to documentation.

In this guide, we'll walk through the process of configuring AWS IAM Authentication with Amazon RDS Proxy for your Aurora PostgreSQL database, focusing on the application-to-proxy connection.

Prerequisites

Before you get started, make sure you have the following prerequisites:

• An Aurora PostgreSQL DB cluster. For instructions, see Create an Amazon Aurora DB cluster and choose ‘Aurora PostgreSQL’ tab.
• An EC2 instance with psql. For instructions, see Launch an EC2 instance.

Target architecture

In the preceding diagram, the client is an Amazon EC2 instance where your applications will be running to communicate with the RDS Proxy. For this post, we install the psql client on the Amazon EC2 instance to connect and query the Aurora PostgreSQL database through the RDS Proxy.

The IAM roles assigned to the client (Amazon EC2) hold the necessary permissions to communicate with the RDS Proxy. The IAM role attached to the Proxy allows it to communicate with the Aurora PostgreSQL database and fetch secrets from AWS Secrets Manager.

The communication between the client and the Proxy is established through the IAM authentication token, and then the communication from the Proxy to the Aurora PostgreSQL database is established using the database credentials stored in AWS Secrets Manager. When using IAM authentication with RDS Proxy, you should set up your database users to authenticate with regular usernames and passwords. The IAM authentication applies only to the RDS Proxy retrieving the user's name and password credentials from AWS Secrets Manager. The connection from the RDS Proxy to the underlying database does not go through IAM authentication.

How to setup IAM authentication with RDS Proxy?

Complete the following steps to configure and implement the solution:

1. Log in to the EC2 instance and verify if the PostgreSQL (psql) client is installed. If not, install the client using the following command:

$ sudo yum update; sudo yum -y install postgresql15;

2. Set the following environment variables:

$ export DB_ENDPOINT=[REPLACE_ME_WITH_POSTGRESQL_ENDPOINT]
$ export PORT=5432
$ export REGION=[REPLACE_ME_WITH_YOUR_PREFERRED_AWS_REGION]
$ export ADMINUSER=tutorial_user
$ export DBNAME=sample

3. Run the following command to connect to the PostgreSQL database. When prompted, provide the password for tutorial_user.

$ psql \
   --host=$DB_ENDPOINT \
   --port=$PORT \
   --username=$ADMINUSER \
   --password \
   --dbname=$DBNAME \
   --set=sslmode=require

4. Create a new role named rdsproxyuser with login privileges and a password. Save the user name and password for later use.

CREATE ROLE rdsproxyuser WITH LOGIN PASSWORD 'REPLACE_ME_WITH_PWD';
SELECT rolname AS role_name FROM pg_roles WHERE rolname = 'rdsproxyuser';
\q

Note: While authentication is handled through IAM, the authorization to access and perform operations on the PostgreSQL database is still controlled natively by PostgreSQL using the GRANT commands.

5. Create a secret in Secrets Manager with the user name rdsproxyuser and provide the password generated in the previous step in the REPLACE_ME_WITH_PWD section:

$ aws secretsmanager create-secret --name rdsproxyuser-secret --secret-string '{"username":"rdsproxyuser" "password":'REPLACE_ME_WITH_PWD'}' --tags "Key"="tag-value" "Value"="rdsproxyuser-secret" --description "Credentials for user rdsproxyuser"

6. To verify the values of the secret you created, enter the following command to display the user name and password stored in the secret:

$ aws secretsmanager get-secret-value --secret-id rdsproxyuser-secret

7. On the Amazon RDS console, choose Proxies in the navigation pane.

8. Choose Create proxy.

9. For Engine family, select PostgreSQL.
10. For Proxy identifier, enter a unique name.
11. Keep the default values for Idle client connection timeout.

12. For Database, choose your database.
13. For Include reader endpoint, deselect Add reader endpoint.

14. For Identity and access management (IAM) role, choose Create IAM role.
15. For Secrets Manager secrets, choose the secret you created earlier.
16. For IAM authentication, choose Required.

17. Select Require Transport Layer Security (this is mandatory if IAM authentication is enabled).
18. Choose the relevant subnets based where your Aurora database is residing.
19. Choose Create proxy.

Upon successful creation, a green banner will display, as shown in the following screenshot.

It may take approximately 5 minutes for the proxy to be available.

20. Choose the proxy identifier and copy the proxy endpoint.

21. Navigate back to the Amazon EC2 console and set the environment values:

$ export PROXY_ENDPOINT=[REPLACE_ME_WITH_RDS_PROXY_WRITER_ENDPOINT]
$ export PORT=5432
$ export REGION=[REPLACE_ME_WITH_YOUR_PREFERRED_AWS_REGION]
$ export PROXYUSER=rdsproxyuser
$ export DBNAME=sample

22. Run the following psql connect command with the RDS proxy endpoint and user credentials:

$ psql \
--host=$PROXY_ENDPOINT \
--port=$PORT \
--username=$PROXYUSER \
--password \
--dbname=$DBNAME \
--set=sslmode=require

23. Generate the IAM authentication token:

$ export PROXYAUTHTOKEN="$(aws rds generate-db-auth-token --hostname $PROXY_ENDPOINT --port $PORT --region $REGION --username $PROXYUSER)"
$ echo $PROXYAUTHTOKEN

24. Run the psql connect command with the RDS proxy endpoint and user name, and for the password, provide the IAM authentication token you generated in the previous step.

Congratulations, you have successfully connected to the Amazon Aurora PostgreSQL database using Amazon RDS Proxy with IAM authentication.

Troubleshooting

In this section, we discuss some common issues and provide troubleshooting tips:

1. You receive the exception "FATAL: The IAM authentication failed for the role rdsproxyuser. Check the IAM token for this role and try again."

There are a few potential reasons for this issue:

• You might be using a password instead of an IAM authentication token. (If the proxy authentication type requires IAM.)
• The IAM authentication tokens have expired. IAM authentication tokens are only valid for 15 minutes, so they need to be refreshed regularly.
• When a new proxy is created, it can take 2–3 minutes before it is available to accept connections. This is the time required for the proxy to be provisioned and become operational.

2. You get the message "password is incorrect" even though you’re using the correct password

To resolve the issue, verify the password stored in Secrets Manager. If you’re using a random password generator to create the password, it may have added double quotes (") before and after the randomly generated password. Make sure to remove these extra double quotes before adding the password to Secrets Manager. The password stored in Secrets Manager should only contain the raw, unformatted password without any additional characters. Confirming that the password is stored correctly in Secrets Manager, without any extra formatting, will help address the authentication problem you’re experiencing.

3. You observe the error "aws: error: argument --region: expected one argument"

Before you run the command, make sure the necessary environment variables are set correctly. The command may rely on specific environment variables being present and configured properly.

• The connection times out while connecting to the proxy – To troubleshoot the issue, check if the necessary security groups are properly configured to allow the required communication flows. Specifically, validate the following:
• The security group attached to the EC2 instance allows outbound traffic to the security group of the proxy.
• The security group of the proxy allows inbound traffic from the EC2 instance's security group, as well as outbound traffic to the security group of the Aurora PostgreSQL database.
• The security group of the Aurora PostgreSQL database allows inbound traffic from the proxy's security group.

4. You get the error "connection terminated abruptly"

• You can resolve this the same way as the connection timeout issue.

Note: Kindly ensure you delete the AWS services that you created to avoid incurring costs.

Article co-authors:

• Manju Arakere