How do I allow users to authenticate to an Amazon RDS MySQL DB instance using their IAM credentials?

Last updated: 2021-06-22

I want to connect to an Amazon Relational Database Service (Amazon RDS) DB instance that is running MySQL. 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 of the following:

  • 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 a secure socket layer (SSL) connection. All data transmitted to and from your DB instance will be encrypted.
  • If your application is running on Amazon Elastic Compute Cloud (Amazon EC2), then you can use your 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 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 Amazon EC2 instance.

5.    Generate an AWS authentication token to identify the IAM role.

6.    Download the SSL root certificate file or certificate bundle file.

7.    Connect to the DB instance using IAM role credentials and the authentication token or an SSL certificate.

Resolution

Before you begin, you must launch a DB instance that supports IAM database authentication and an Amazon 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, then choose Apply Immediately to enable IAM database authentication right away. Enabling IAM Authentication requires a brief outage. For more information on which modifications require outages, see Settings for DB instances.

Note: If you choose Apply Immediately, any pending modifications are also applied immediately instead during your maintenance window. This can cause an extended outage for your instance. For more information, see Using the apply immediately setting.

Create a database user account that uses an AWS authentication token

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

$ 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:

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

3.    (Optional) Run this command to require the user to connect to the database using SSL:

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

4.    Run the exit command to close MySQL. Then, log out from the DB instance.

Add an IAM policy that maps the database user

1.    Open the IAM console.

2.    Choose Policies from the navigation pane.

3.    Choose Create Policy.

4.    Enter a policy that allows the rds-db:connect Action to the required user. For more information on creating this policy, see Creating and using an IAM policy for IAM database access.

Note: Make sure to edit the Resource value with the details of your database resources, such as your DB instance identifier and database user name.

5.    Choose Next: Tags.

6.    Choose Next: Review.

7.    For Name, enter a policy name.

8.    Choose Create policy.

Create an IAM role that allows Amazon RDS access

1.    Open the IAM console.

2.    Choose Roles from the navigation pane.

3.    Choose Create role.

4.    Choose AWS service.

5.    Choose EC2.

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

7.    In the search bar, find the IAM policy that you previously created in the “Add an IAM policy that maps the database user” section.

8.    Choose Next: Tags.

9.    Choose Next: Review.

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

11.    Choose Create Role.

Attach the IAM role to the Amazon EC2 instance

1.    Open the Amazon EC2 console.

2.    Choose the EC2 instance that you 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 Amazon EC2 instance, run the following AWS CLI command to generate an authentication token:

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

Copy and store this authentication token for later use. The token expires within 15 minutes of creation.

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

Download the SSL root certificate file or certificate bundle file

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

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

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

After you download the certificate file, run one of the following commands to connect to the DB instance with SSL.

Note: If your application doesn't accept certificate chains, then run the following command to download the certificate bundle:

$ 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 {db username})"

Depending on the certificate that you are using (RootCA or Bundle), run one of the following commands:

RootCA command:

mysql --host=$RDSHOST --port=3306 --ssl-ca=/sample_dir/rds-ca-2019-root.pem --enable-cleartext-plugin --user={db username} --password=$TOKEN

Bundle command:

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

Note: If you're using a MariaDB client, the --enable-cleartext-plugin option isn't required.

Connect to the RDS DB instance using IAM role credentials and SSL certificates

After you download the certificate file, connect to the DB instance with SSL. For more information, see Connecting to a DB instance running the MySQL database engine.