Why do I receive an "Access Denied" error message when I use IAM authentication to connect to Amazon RDS for MySQL?

Short description

You might receive error messages for the following reasons:

• Insufficient IAM role permissions
• IAM authentication is turned off
• Misconfigured database user
• Incorrect connection string

You might receive an error message that looks similar to the following:

"ERROR 1045 (28000): Access denied for user 'root'@'10.0.4.253' (using password: YES)"

Resolution

Use the AWSSupport-TroubleshootRDSIAMAuthentication runbook

To automatically verify the configuration required for IAM authentication with an Amazon RDS instance, use the AWSSupport-TroubleshootRDSIAMAuthentication runbook. To resolve your issue, follow the resolutions that the runbook provides.

If the runbook doesn't resolve your issue, then continue to the other resolution sections.

Check IAM role permissions

To use IAM database authentication to connect to your Amazon RDS for MySQL instance, you must have access to the rds-db:connect action. For more information, see Creating and using an IAM policy for IAM database access.

Be sure that you use the correct resource ID and not just specify an Amazon Resource Name (ARN). To find the resource ID for your database (DB) instance, complete the following steps:

1. Open the Amazon RDS console.
2. In the navigation pane, choose Databases.
3. Choose your DB instance, and then choose the Configuration tab.
4. Under Configuration, find the Resource ID for your DB instance.
   Note: For more information, see Creating and using an IAM policy for IAM database access.

If you use a service control policy (SCP), then make sure your policy allows connections to your DB instance. For more information, see Update an SCP.

Turn on IAM authentication

By default, IAM authentication is turned off for database instances. Review the configuration settings for your Amazon RDS for MySQL instance or Aurora DB cluster, and make sure that IAM authentication is turned on.

Note: If you choose Apply Immediately, then all pending changes take effect immediately instead of during a maintenance window. This action can interrupt your Amazon RDS for MySQL instance. For more information, see Using the schedule modifications setting.

Verify database user configuration

The AWSAuthenticationPlugin plugin authenticates users in Amazon RDS for MySQL. To connect to your Amazon RDS for MySQL instance through IAM authentication, use AWSAuthenticationPlugin.

To confirm that your IAM role uses this plugin, run the following command:

select user,plugin,host from mysql.user where user like '%db-user-name%';

Note: Replace db-user-name with your database username.

Example output:

+------+-------------------------+------+
| user | plugin | host |
+------+-------------------------+------+
| root | AWSAuthenticationPlugin | % |
+------+-------------------------+------+
1 row in set (0.00 sec)

If the IAM role uses a specific host, then you must use that hostname. Also, make sure that you have the correct permissions to access the specified database.

To view the permissions granted to a user, run the following command:

show grants for user;

Note: Replace user with the username.

To grant privileges to other users, run the following command:

grant select on mydb.mytable to user;

Note: Replace mydb with your database instance name, mytable with your table name, and user with your username.

For more information, see GRANT statement on the MySQL website.

Fix the connection string

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

To connect to the Amazon RDS for MySQL database, use the --enable-cleartext-plugin parameter in your connection string. The --enable-cleartext-plugin parameter acts as an authentication token. You must use AWSAuthenticationPlugin when you connect to the database and configure the database user. If you don't correctly configure the AWSAuthenticationPlugin, then you receive an "Access Denied" error message when you connect to your database through IAM authentication.

Use the following example connection string:

mysql -h endpoint -P 3306 --enable-cleartext-plugin --user=RDSConnect --password=$

Note: Replace endpoint with the host name of the DB instance that you want to access.

If you use the MariaDB client, then you don't need the --enable-cleartext-plugin parameter. Instead, store the token in an environment variable first. Then, use environment variables when you connect to your MySQL DB instance.

Use the following example:

RDSHOST="rdsmysql.123456789012.us-west-2.rds.amazonaws.com"
TOKEN="$(aws rds generate-db-auth-token --hostname $RDSHOST --port 3306 --region us-west-2 --username db-user-name)"
mysql --host=$RDSHOST --port=3306 --enable-cleartext-plugin --user=db-user-name --password=$TOKEN

For more information about how to use an environment variable to connect to a MySQL DB instance, see Connecting to a DB instance.

Related information

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

IAM database authentication

IAM database authentication for MariaDB, MySQL, and PostgreSQL