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

Short description

If you can't connect to an Amazon RDS for MySQL or Aurora DB instance using IAM authentication, then check for the following reasons:

• IAM authentication is turned off
• Insufficient IAM role permissions
• Database user is improperly configured
• Incorrect connection string

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, you can 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, 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 successfully 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.

Additionally, make sure that you're using 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 about the elements listed in the example IAM policy, see Creating and using an IAM policy for IAM database access.

Database user is improperly configured

With Amazon RDS for MySQL, IAM authentication is handled by AWSAuthenticationPlugin. So, to connect to your Amazon RDS for MySQL instance using IAM authentication, you must use AWSAuthenticationPlugin. To confirm that this plugin is associated with your IAM role, run this 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 this command syntax:

show grants for <user>;

To grant privileges to another user, use this command syntax:

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

Incorrect connection string

When you connect to the Amazon RDS for MySQL database, you must use the --enable-cleartext-plugin option in your connection string. The --enable-cleartext-plugin syntax is used for passing the password, acting 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, and is required for IAM authentication to work. If AWSAuthenticationPlugin is incorrectly configured, then IAM authentication doesn't work. As a result, you'll get an Access Denied error when you try to connect to your database.

Also, because authentication tokens consist of several characters (which can be unwieldy on the command line), 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 MySQL DB instance using their IAM credentials?

IAM database authentication

IAM database authentication for MySQL and PostgreSQL