Why am I getting an Access Denied error when I try to connect to Amazon RDS for MySQL using IAM authentication?

Short description

The following resolution identifies possible reasons that you can't connect Amazon RDS for MySQL or Aurora DB instance using IAM authentication.

Resolution

IAM authentication is turned off

By default, IAM authentication is turned off. Review the configuration settings for your Amazon RDS for MySQL cluster, and make sure that IAM authentication is turned off. From the Amazon RDS console, modify the instance by choosing Database Authentication. Then, choose Password and IAM database authentication and Continue to update your configuration settings.

Note: If you choose Apply Immediately when updating your cluster configuration settings, then all pending modifications are applied immediately instead of during a maintenance window. This action can cause an extended outage for your Amazon RDS for MySQL instance. For more information, see Using the Apply Immediately setting.

Insufficient IAM role permissions

To connect to your Amazon RDS for MySQL instance using IAM database authentication, you must have access to the rds-db:connect action. The rds-db:connect action allows connections to the DB instance.

For example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "rds-db:connect"
      ],
      "Resource": [
        "arn:aws:rds-db:region:account-id:dbuser:(DbiResourceId or DbClusterResourceId)/db-user-name"
      ]
    }
  ]
}

Note: Replace db-user-name with the database account user that's associated with the IAM authentication.

Make sure that you use the correct resource ID instead of only specifying the ARN. To find a DB instance's resource ID, choose the Resource tab in the AWS Management Console. Then, choose the Configuration tab to view the resource ID.

For more information, see Creating and using an IAM policy for IAM database access.

If you use an SCP policy, then make sure that your policy allows connections to the DB instance. For more information, see Creating, updating, and deleting service control policies.

Database user is improperly configured

With Amazon RDS for MySQL, IAM authentication is handled by AWSAuthenticationPlugin. To connect to your Amazon RDS for MySQL instance using IAM authentication, use AWSAuthenticationPlugin. To confirm that this plugin is associated with your IAM role, run the following command:

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

You receive an output similar to this:

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

If the IAM role is restricted to using a specific host, make sure that you're using the correct hostname. Also, make sure that you have proper permissions to access the specified database.

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

show grants for <user>;

To grant privileges to another user, use the following command syntax. For more information see GRANT Statement (on the MySQL website).

grant select on <mydb>.<mytable> to <user>;

Incorrect connection string

To connect to the Amazon RDS for MySQL database, use the --enable-cleartext-plugin option in your connection string. The --enable-cleartext-plugin syntax acts as an authentication token.

For example:

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

The --enable-cleartext-plugin syntax also indicates that AWSAuthenticationPlugin must be used for the database connection. The plugin is required when configuring the database user. If the AWSAuthenticationPlugin is incorrectly configured, then IAM authentication doesn't work. In this case, you see an Access Denied error when you try to connect to your database.

Note: If you're using a MariaDB client, then the --enable-cleartext-plugin syntax isn't required. First, save the token to an environment variable instead. Then, use that variable when you connect to your MySQL DB instance. For 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 connect to a MySQL DB instance using an environment variable, see Connecting to a DB instance.

Related information

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

IAM database authentication

IAM database authentication for MariaDB, MySQL, and PostgreSQL