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

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 is 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. Activate 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. Create an IAM role that allows Amazon RDS access.
5. Attach the IAM role to the Amazon EC2 instance.
6. Generate an AWS authentication token to identify the IAM role.
7. Download the SSL root certificate file or certificate bundle file.
8. Connect to the RDS DB instance using IAM role credentials and the authentication token.
9. Connect to the RDS DB instance using IAM role credentials and SSL certificates.

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.

Activate IAM DB authentication on the RDS DB instance

You can turn on 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 activate IAM database authentication. Activating IAM Authentication requires a brief outage. For more information on which modifications require outages, see Amazon RDS DB instances.

Note: If you choose Apply Immediately, any pending modifications are also applied immediately instead of 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.    By default, the database user is created with no privileges. This appears as GRANT USAGE when you run SHOW GRANTS FOR {dbusername}. To require a user account to connect using SSL, run this command:

ALTER USER {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 to the IAM role

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.

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

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

Or, you can generate a token using an AWS SDK.

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.

Related information

IAM database authentication for MariaDB, MySQL, and PostgreSQL

What are the least privileges required for a user to perform creates, deletes, modifications, backup, and recovery for an Amazon RDS DB instance?