Connecting to your DB cluster using IAM authentication from the command line: Amazon CLI and mysql client - Amazon Aurora
Generating an IAM authentication tokenConnecting to a DB cluster
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Connecting to your DB cluster using IAM authentication from the command line: Amazon CLI and mysql client

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

Prerequisites

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

Note

For information about connecting to your database using SQL Workbench/J with IAM authentication, see the blog post Use IAM authentication to connect with SQL Workbench/J to Aurora MySQL or Amazon RDS for MySQL.

Generating an IAM authentication token

The following example shows how to get a signed authentication token using the Amazon 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 cluster that you want to access

  • --port – The port number used for connecting to your DB cluster

  • --region – The Amazon Region where the DB cluster 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 or an Aurora custom endpoint instead of the DB cluster endpoint to generate the authentication token.

Connecting to a DB cluster

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 cluster that you want to access

  • --port – The port number used for connecting to your DB cluster

  • --ssl-ca – The full path to the SSL certificate file that contains the public key

    For more information, see Using TLS with Aurora MySQL DB clusters.

    To download an SSL certificate, see Using SSL/TLS to encrypt a connection to a DB 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="mysqlcluster.cluster-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 cluster through a proxy, see Connecting to a proxy using IAM authentication.