Farhin shows you how to
authenticate to an RDS instance
using IAM credentials

farhin_authenticate_rds

I want to connect to an Amazon Relational Database Service (Amazon RDS) DB instance using AWS Identity and Access Management (IAM) credentials instead of using native authentication methods. How can I do that?

Amazon RDS users can connect to an RDS DB instance or cluster using IAM user or role credentials and an authentication token. IAM database authentication is more secure than native authentication methods in the following ways:

  • IAM database authentication tokens are generated using your AWS access keys. You don't need to store database user credentials.
  • Authentication tokens have a lifespan of 15 minutes, so you don't need to enforce password resets.
  • IAM database authentication requires an SSL connection, so all data transmitted to and from your RDS DB instance is encrypted.
  • If your application is running on Amazon Elastic Compute Cloud (Amazon EC2), you can use EC2 instance profile credentials to access the database. You don't need to store database passwords on your instance.

To set up IAM database authentication using IAM roles, follow these steps:

  1. Enable IAM DB authentication on the RDS DB instance.
  2. Create a database user account that uses an AWS authentication token.
  3. Add an IAM policy that maps the database user to the IAM role.
  4. Attach the IAM role to the EC2 instance.
  5. Generate an AWS authentication token to identify the IAM role.
  6. Download the SSL root certificate file or certificate bundle file.
  7. Connect to the RDS DB instance using IAM role credentials and the authentication token.

Note: IAM database authentication is available only for certain database engines and instance types. For the list of supported engines and instances, see Availability for IAM Database Authentication.

Before you begin this procedure, be sure that you have launched the following:

Enable IAM DB authentication on the RDS DB instance

To enable IAM database authentication, you can use the AWS Management Console, AWS Command Line Interface (AWS CLI), or the Amazon RDS API.

For instructions, see Enabling and Disabling IAM Database Authentication.

Note: On the Modify DB Instance page, under Maintenance, choose Apply Immediately to enable IAM database authentication immediately. Depending on other pending modifications, choosing Apply Immediately might cause downtime.

Create a database user account that uses an AWS authentication token

1.    Connect to the instance or cluster endpoint by running the following command. Be sure to enter the master password to log in.

$ mysql -h {database or cluster endpoint} -P {port number database is listening on} -u {master db username} -p

2.    Run this command to create a database user account that uses an AWS authentication token instead of a password:

CREATE USER {db username} IDENTIFIED WITH AWSAuthenticationPlugin as 'RDS';

3.    Optionally, run this command to require the user to connect to the database using SSL:  

GRANT USAGE ON *.* TO '{dbusername2}'@'%'REQUIRE SSL;

4.    Run the exit command to close MySQL. Then, log out from the instance.

Create an IAM role that allows Amazon RDS access

1.    Open the IAM console. Then, choose Roles from the navigation pane.

2.    Choose Create role.

3.    Choose AWS service, and then choose EC2.

4.    For Select your use case, choose EC2, and then choose Next: Permissions.

5.    In the search bar, enter "RDS". Then, choose AmazonRDSFullAccess or a custom RDS IAM policy that grants fewer privileges.

6.    Choose Next: Review.

7.     For Role Name, enter a name for this IAM role.

8.    Choose Create Role.

Add an IAM policy that maps the database user to the IAM role

1.    From the IAM role list, open your newly created IAM role.

2.    Choose Add inline policy.

3.    Enter the policy from Creating and Using an IAM Policy for IAM Database Access.
Note: Be sure to edit the "Resource" value with the details of your database resources, such as your DB instance identifier and database user name.

4.    Choose Review policy.

5.    For Name, enter a policy name.

6.    Choose Create policy.

Attach the IAM role to the EC2 instance

1.    Open the Amazon EC2 console.

2.    Choose the EC2 instance you will use to connect to Amazon RDS.

3.    Attach your newly created IAM role to the EC2 instance.

4.    Reconnect to your EC2 instance using SSH.

Generate an AWS authentication token to identify the IAM role

After you connect to your EC2 instance, run the following AWS Command Line Interface (AWS CLI) command to generate an authentication token. Copy and store the authentication token for later use.

Note: This token expires within 15 minutes of creation.

$ aws rds generate-db-auth-token --hostname {db or cluster endpoint} --port 3306 --username {db username}

Download the SSL root certificate file or certificate bundle file

Run this command to download the root certificate that works for all regions:

$ wget https://s3.amazonaws.com/rds-downloads/rds-ca-2015-root.pem

If your application does not accept certificate chains, run the following command to download the certificate bundle that includes both the old and new root certificates:  

$ wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

RDSHOST="rdsmysql.abcdefghijk.us-west-2.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/rds-combined-ca-bundle.pem --enable-cleartext-plugin --user=jane_doe --password=$TOK

Note: For Windows platform applications that need a PKCS7 file, see Using SSL to Encrypt a Connection to a DB Instance to download the appropriate certificate.

Connect to the RDS DB instance using IAM role credentials and the authentication token

After you download the certificate file, run the following command to connect to the RDS DB instance with SSL using the MySQL utility.


Did this page help you? Yes | No

Back to the AWS Support Knowledge Center

Need help? Visit the AWS Support Center

Published: 2018-03-13

Updated: 2018-11-16