How do I allow users to connect to Amazon RDS with IAM credentials?

Last updated: 2019-11-05

I want to connect to an Amazon Relational Database Service (Amazon RDS) DB instance that is running MySQL or PostgreSQL. I want to use AWS Identity and Access Management (IAM) credentials instead of using native authentication methods. How can I do that?

Short Description

Users can connect to an Amazon RDS DB instance or cluster using IAM user or role credentials and an authentication token. IAM database authentication is more secure than native authentication methods because:

  • IAM database authentication tokens are generated using your AWS access keys. You don't need to store database user credentials.
  • Authentication tokens have a lifespan of 15 minutes, so you don't need to enforce password resets.
  • IAM database authentication requires an SSL connection, so all data transmitted to and from your RDS DB instance is encrypted.
  • If your application is running on Amazon Elastic Compute Cloud (Amazon EC2), you can use EC2 instance profile credentials to access the database. You don't need to store database passwords on your instance.

To set up IAM database authentication using IAM roles, follow these steps:

  1. Enable IAM DB authentication on the RDS DB instance.
  2. Create a database user account that uses an AWS authentication token.
  3. Add an IAM policy that maps the database user to the IAM role.
  4. Attach the IAM role to the EC2 instance.
  5. Generate an AWS authentication token to identify the IAM role.
  6. Download the SSL root certificate file or certificate bundle file.
    Note: If you use a 2015-root certificate, it will expire in 2020. To move to a 2019-root certificate, see Rotating Your SSL/TLS Certificate.
  7. Connect to the RDS DB instance using IAM role credentials and the authentication token.

Resolution

Before you begin, be sure that you launched an RDS DB instance that supports IAM database authentication and an EC2 instance to connect to the database.

Enable IAM DB authentication on the RDS DB instance

You can enable IAM database authentication by using the Amazon RDS console, AWS Command Line Interface (AWS CLI), or the Amazon RDS API. If you use the Amazon RDS console to modify the DB instance, choose Apply Immediately to enable IAM database authentication immediately. If you have other pending modifications and you choose Apply Immediately, this might cause downtime. For more information, see Using the Apply Immediately Parameter.

Create a database user account that uses an AWS authentication token

1.    Connect to the instance or cluster endpoint by running the following command. Enter the master password to log in.

PostgreSQL

$ psql -h {database or cluster endpoint} -U {Master username} -d {database name}

MySQL

$ mysql -h {database or cluster endpoint} -P {port number database is listening on} -u {master db username} -p

2.    Create a database user account that uses an AWS authentication token instead of a password:

PostgreSQL

CREATE USER {db username};

MySQL

CREATE USER {dbusername} IDENTIFIED WITH AWSAuthenticationPlugin as 'RDS';

3.    Optionally, run this command to require the user to connect to the database using SSL:

PostgreSQL

GRANT rds_iam to {db username};

MySQL

GRANT USAGE ON *.* TO '{dbusername}'@'%'REQUIRE SSL;

4.    Run the \q command to close PostgreSQL, or run the exit command to close MySQL. Then, log out from the instance.

Create an IAM role that allows Amazon RDS access

1.    Open the IAM console, and choose Roles from the navigation pane.

2.    Choose Create role, choose AWS service, and then choose EC2.

3.    For Select your use case, choose EC2, and then choose Next: Permissions.

4.    In the search bar, enter "RDS." Then, choose AmazonRDSFullAccess or a custom Amazon RDS IAM policy that grants fewer privileges.

5.    Choose Next: Review.

6.    For Role Name, enter a name for this IAM role.

7.    Choose Create Role.

Add an IAM policy that maps the database user to the IAM role

1.    From the IAM role list, choose the newly created IAM role.

2.    Choose Add inline policy.

3.    Enter the policy from Creating and Using an IAM Policy for IAM Database Access.
Note: Be sure to edit the Resource value with the details of your database resources, such as your DB instance identifier and database user name.

4.    Choose Review policy.

5.    For Name, enter a policy name.

6.    Choose Create policy.

Attach the IAM role to the EC2 instance

1.    Open the Amazon EC2 console.

2.    Choose the EC2 instance that you'll use to connect to Amazon RDS.

3.    Attach your newly created IAM role to the EC2 instance.

4.    Connect to your EC2 instance using SSH.

Generate an AWS authentication token to identify the IAM role

After you connect to your EC2 instance, run the following AWS Command Line Interface (AWS CLI) command to generate an authentication token. Copy and store the authentication token for later use.

Note: This token expires within 15 minutes of creation.

PostgreSQL

export
PGPASSWORD="$(aws rds generate-db-auth-token
--hostname={db endpoint} --port=5432
--username={db user} --region us-west-2)"

MySQL

$ aws rds generate-db-auth-token --hostname {db or cluster endpoint} --port 3306 --username {db username}

Download the SSL root certificate file or certificate bundle file

Run this command to download the root certificate that works for all Regions:

PostgreSQL and MySQL

$ wget https://s3.amazonaws.com/rds-downloads/rds-ca-2019-root.pem

Note: If you use a 2015-root certificate, it expires in 2020. To move to a 2019-root certificate, see Rotating Your SSL/TLS Certificate.

Connect to the RDS DB instance using IAM role credentials and the authentication token

After you download the certificate file, run the following commands to connect to the RDS DB instance with SSL:

PostgreSQL

$ psql -h {DB endpoint} -p 5432 "dbname={db name} user={db user} sslrootcert=/home/ec2-user/rds-combined-ca-bundle.pem sslmode=verify-ca"

MySQL

If your application doesn't accept certificate chains, run the following command to download the certificate bundle that includes both the old and new root certificates:

$ wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

RDSHOST="rdsmysql.abcdefghijk.us-west-2.rds.amazonaws.com"
TOKEN="$(aws rds generate-db-auth-token --hostname $RDSHOST --port 3306 --region us-west-2 --username jane_doe )"

mysql --host=$RDSHOST --port=3306 --ssl-ca=/sample_dir/rds-combined-ca-bundle.pem --enable-cleartext-plugin --user=jane_doe --password=$TOKEN

Note: For Windows platform applications that need a PKCS7 file, see Using SSL/TLS to Encrypt a Connection to a DB Instance to download the appropriate certificate.

Connect to the RDS DB instance using IAM role credentials and the authentication token

After you download the certificate file, connect to the RDS DB instance with SSL. For more information, see Connecting to a DB Instance Running the PostgreSQL Database Engine and Connecting to a DB Instance Running the MySQL Database Engine.


Did this article help you?

Anything we could improve?


Need more help?