Connecting to your DB instance using IAM authentication from the command line: AWS CLI and mysql client (original) (raw)

You can connect from the command line to an Amazon RDS DB instance with the AWS CLI and mysql command line tool as described following.

Prerequisites

The following are prerequisites for connecting to your DB instance using IAM authentication:

• Enabling and disabling IAM database authentication
• Creating and using an IAM policy for IAM database access
• Creating a database account using IAM authentication

Topics

• Generating an IAM authentication token
• Connecting to a DB instance

Generating an IAM authentication token

The following example shows how to get a signed authentication token using the AWS CLI.

aws rds generate-db-auth-token \
   --hostname rdsmysql.123456789012.us-west-2.rds.amazonaws.com \
   --port 3306 \
   --region us-west-2 \
   --username jane_doe

In the example, the parameters are as follows:

• --hostname – The host name of the DB instance that you want to access
• --port – The port number used for connecting to your DBinstance
• --region – The AWS Region where the DB instance is running
• --username – The database account that you want to access

The first several characters of the token look like the following.

rdsmysql.123456789012.us-west-2.rds.amazonaws.com:3306/?Action=connect&DBUser=jane_doe&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900...

Note

You cannot use a custom Route 53 DNS record instead of the DB instance endpoint to generate the authentication token.

Connecting to a DB instance

The general format for connecting is shown following.

mysql --host=hostName --port=portNumber --ssl-ca=full_path_to_ssl_certificate --enable-cleartext-plugin --user=userName --password=authToken

The parameters are as follows:

• --host – The host name of the DB instance that you want to access
• --port – The port number used for connecting to your DB instance
• --ssl-ca – The full path to the SSL certificate file that contains the public key
  For more information about SSL/TLS support for MariaDB, see SSL/TLS support for MariaDB DB instances on Amazon RDS.
  For more information about SSL/TLS support for MySQL, see SSL/TLS support for MySQL DB instances on Amazon RDS.
  To download an SSL certificate, see Using SSL/TLS to encrypt a connection to a DB instance or cluster.
• --enable-cleartext-plugin – A value that specifies that AWSAuthenticationPlugin must be used for this connection
  If you are using a MariaDB client, the --enable-cleartext-plugin option isn't required.
• --user – The database account that you want to access
• --password – A signed IAM authentication token

The authentication token consists of several hundred characters. It can be unwieldy on the command line. One way to work around this is to save the token to an environment variable, and then use that variable when you connect. The following example shows one way to perform this workaround. In the example, /sample_dir/ is the full path to the SSL certificate file that contains the public key.

RDSHOST="mysqldb.123456789012.us-east-1.rds.amazonaws.com"
TOKEN="$(aws rds generate-db-auth-token --hostname $RDSHOST --port 3306 --region us-west-2 --username jane_doe )"

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

When you connect using AWSAuthenticationPlugin, the connection is secured using SSL. To verify this, type the following at the mysql> command prompt.

show status like 'Ssl%';

The following lines in the output show more details.

+---------------+-------------+
| Variable_name | Value                                                                                                                                                                                                                                |
+---------------+-------------+
| ...           | ...
| Ssl_cipher    | AES256-SHA                                                                                                                                                                                                                           |
| ...           | ...
| Ssl_version   | TLSv1.1                                                                                                                                                                                                                              |
| ...           | ...
+-----------------------------+

If you want to connect to a DB instance through a proxy, see Connecting to a proxy using IAM authentication.