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

5 minute read

I want to connect to an Amazon Relational Database Service (Amazon RDS) for MySQL DB instance. I want to use AWS Identity and Access Management (IAM) credentials instead of the native authentication methods.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you use the most recent AWS CLI version.

To connect to an Amazon RDS DB instance or cluster, use IAM user or role credentials and an authentication token.

Note: Use an unencrypted MySQL connection only when your client and server are in the same virtual private cloud (VPC) and the network is trusted.

Prerequisite

You must launch a DB instance that supports IAM database authentication and an Amazon Elastic Compute Cloud (Amazon EC2) instance to connect to the database.

To verify the configuration required for IAM authentication, use the AWSSupport-TroubleshootRDSIAMAuthentication AWS Systems Manager Automation runbook. You can also use the runbook to troubleshoot connectivity issues to the Amazon RDS Instance or Aurora Cluster.

Activate IAM DB authentication on the RDS DB instance

You can use the Amazon RDS console, AWS Command Line Interface (AWS CLI), or the Amazon RDS API to turn on IAM database authentication. If you use the Amazon RDS console to modify the DB instance, then choose Apply Immediately to activate IAM database authentication. For more information, see Amazon RDS DB instances.

Note: If you choose Apply Immediately, then any pending modifications also immediately apply. For more information, see Schedule modifications setting.

Create a database user account that uses an AWS authentication token

To connect to the DB instance or cluster endpoint, run the following command.

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

Note: Use your primary password to log in.

To create a database user account that uses an AWS authentication token instead of a password, run the following command:

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

By default, the database user has no privileges. The database user appears as GRANT USAGE when you run SHOW GRANTS FOR {dbusername}. To require a user account to connect through SSL, run the following command:

ALTER USER {dbusername} REQUIRE SSL;

To close MySQL, run the exit command. Then, log out from the DB instance.

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

Complete the following steps:

Open the IAM console.
In the navigation page, choose Policies.
Choose Create Policy.
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 enter the details of your database resources into the Resources section.
Choose Next.
Choose Next.
For Name, enter a policy name.
Choose Create policy.

Create an IAM role that allows Amazon RDS access

Complete the following steps:

Open the IAM console.
In the navigation page, choose Roles.
In the Trusted entity type section, choose Create role.
Choose AWS service.
In the Use case section, for Service or user case, choose EC2.
For Use case, choose EC2, and then choose Next.
In the search bar, find the IAM policy that you previously created in the Add an IAM policy that maps the database user section.
Choose Next.
For Role Name, enter a name for this IAM role.
Choose Create Role.

Attach the IAM role to the Amazon EC2 instance

Complete the following steps:

Open the Amazon EC2 console.
Choose the EC2 instance that you use to connect to Amazon RDS.
Attach your newly created IAM role to the EC2 instance.
Connect to your EC2 instance through SSH.

Generate an AWS authentication token to identify the IAM role

After you connect to your Amazon EC2 instance, run the following AWS CLI generate-db-auth-token command to generate an authentication token:

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

Note: If you receive errors when you run AWS CLI commands, then see Troubleshoot AWS CLI errors. Also, make sure that you use the most recent AWS CLI version.

Copy and store this authentication token for later use. Or, use an AWS SDK for .NET to generate a token.

Download the SSL root certificate bundle file

To download a certificate bundle for all AWS Regions, see Certificate bundles for all AWS Regions.

Use the IAM role credentials and the authentication token to connect to the RDS DB instance

After you download the certificate file, run the following command to connect to the DB instance through SSL:

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})"

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

Note: If you use a MariaDB client, then you don't include the --enable-cleartext-plugin option.