Menu
Amazon Relational Database Service
User Guide (API Version 2014-10-31)

IAM Database Authentication for MySQL and Amazon Aurora

With Amazon Relational Database Service (Amazon RDS) running MySQL or Amazon Aurora, you can authenticate to your DB instance using AWS Identity and Access Management (IAM) database authentication and the native authentication methods built into the database engine. With IAM database authentication, you authenticate to your DB instance or DB cluster by using an IAM user or IAM role and an authentication token. An authentication token is a unique value that is generated using the Signature Version 4 signing process; it expires 15 minutes after you create it. By using IAM database authentication, you can use the same credentials to control access to your AWS resources and your databases. If you enable IAM database authentication, you can still use standard database authentication as well.

We recommend that you use IAM database authentication for custom applications that connect to a MySQL or Aurora database engine. IAM database authentication provides the following benefits:

  • An authentication token is more secure than a user password because it is generated using the Signature Version 4 signing process that uses your AWS access keys. For more information, see Signature Version 4 Signing Process.

  • An authentication token has a limited lifetime so you don’t need to enforce resetting user passwords. It expires 15 minutes after you create it.

  • The database doesn't store database user credentials because an AWS-generated authentication token is used instead of a database password.

  • With IAM database authentication, you must use a Secure Sockets Layer (SSL) connection, so all data transmitted from and to your DB instance or DB cluster is encrypted.

  • You can delegate credential management to IAM so that you can use IAM to access your AWS account and your database resources.

  • For applications running on Amazon EC2, you can use EC2 instance profile credentials to access the database, so you don't need to use database passwords on your EC2 instance.

If you want to authenticate to a DB instance or DB cluster using IAM database authentication, you should be aware of the following:

  • You can enable IAM database authentication when you create or modify a DB instance for MySQL or a DB cluster for Aurora. Otherwise, IAM database authentication is disabled by default.

  • If you create or copy a snapshot, the IAM database authentication setting is inherited from the source DB instance or DB cluster.

  • If you restore a DB instance or DB cluster from a snapshot, the IAM database authentication setting defaults to that of the snapshot. You can change the IAM database authentication setting during the restore.

  • If you migrate from MySQL to Aurora, the IAM database authentication setting is inherited from the MySQL DB instance.

  • If you create a Read Replica from a DB instance or an Aurora Replica from a DB cluster, the replica inherits the IAM database authentication setting of the source DB instance or DB cluster.

  • If you disable IAM database authentication, and you have database accounts in the database engine that map to IAM users, these users can't authenticate and so can't connect to the DB instance or DB cluster.

  • Changing the IAM database authentication setting doesn't cause downtime to your DB instance or DB cluster. Thus, you can either apply changes immediately or have them applied during the next maintenance window.

You can use IAM database authentication for the following database engines:

  • MySQL 5.6, minor version 5.6.34 or higher

  • MySQL 5.7, minor version 5.7.16 or higher

  • Amazon Aurora 1.10 or higher

For MySQL, you can use IAM database authentication on all supported instance classes except for db.t1.micro and db.m1.small. For Aurora, you can use IAM database authentication on all supported instance classes except for db.t2.small. For more information about the instance classes each database engine supports, see DB Instance Class.

When using IAM database authentication, you should constrain connections to 20 per second or lower, except if you are using a db.t2.micro instance class. In this case, you should constrain connections to 10 per second or lower.

For more information on connection and authentication, see the following:

Authenticating to a DB Instance or DB Cluster Using IAM Database Authentication

To enable authentication to a DB instance or DB cluster using IAM database authentication, take the following steps.

To authenticate to a DB instance or DB cluster using IAM database authentication

  1. Enable IAM database authentication on the DB instance or DB cluster by using the AWS Management Console, AWS CLI, or the Amazon RDS API. For more information, see Enabling and Disabling IAM Database Authentication.

  2. Create one or more database user accounts that use authentication tokens, which allows these accounts to be mapped to IAM users or roles. You do this by specifying an authentication plugin in the CREATE USER command. For more information, see Creating Database Accounts for IAM Database Authentication.

  3. Create an IAM policy that grants access to RDS resources by specifying DB instance or DB cluster resource IDs and also the authentication token-enabled database user accounts to use to access them. Then, attach the policy to an IAM user or role. Doing this allows the IAM user or role to connect to the DB instances or DB clusters specified, as the database user specified. For more information, see Attaching an IAM Policy Account to an IAM User or Role. For more information about IAM, see IAM Users and IAM Roles in the IAM User Guide.

  4. Use the AWS SDK for Java or AWS CLI to get an authentication token you can use to identify the IAM user or role. To learn how to get an authentication token, see Getting an Authentication Token.

  5. Connect to the database using an SSL connection, specifying the IAM user or role as the database user account and the authentication token as the password. For more information, see Connecting to a DB Instance or DB Cluster Using IAM Database Authentication.

Enabling and Disabling IAM Database Authentication

You can enable DB instances or DB clusters for IAM database authentication by using the AWS Management Console, AWS CLI, or the Amazon RDS API. IAM database authentication is disabled by default.

Amazon RDS Management Console

You can enable and disable IAM database authentication in the console as follows:

  • If you create a DB instance or DB cluster, you can enable IAM database authentication by setting Enable IAM DB Authentication to Yes in the Database Options group of the Configure Advanced Settings page.

  • If you modify a DB instance or DB cluster, you can enable IAM database authentication by setting Enable IAM DB Authentication to Yes in the Database Options group of the Modify DB Instance page.

  • If you restore a DB instance or DB cluster, you can disable IAM database authentication by setting Enable IAM DB Authentication to No in the Database Options group of the Restore DB Instance page.

AWS CLI

You can enable and disable IAM database authentication by using the AWS CLI as follows:

  • If you create a DB instance or DB cluster with the CLI, you can enable IAM database authentication with the create-db-instance command (MySQL) or create-db-cluster command (Aurora). IAM database authentication is off by default for a DB instance or DB cluster. To enable IAM database authentication, specify --enable-iam-database-authentication.

  • If you modify a DB instance or DB cluster with the CLI, you can enable or disable IAM database authentication with the modify-db-instance command (MySQL) or modify-db-cluster command (Aurora). To enable IAM database authentication, specify --enable-iam-database-authentication. To disable IAM database authentication, specify --no-enable-iam-database-authentication.

  • If you restore a DB instance using the restore-db-instance-to-point-in-time or restore-db-instance-from-db-snapshot commands, or restore a DB cluster using the restore-db-cluster-to-point-in-time or restore-db-cluster-from-snapshot commands, the IAM database authentication setting defaults to that of the source snapshot. You can change the IAM database authentication setting by specifying either --enable-iam-database-authentication to enable it or --no-enable-iam-database-authentication to disable it.

The following example creates a MySQL DB instance named mydbinstance with IAM database authentication enabled.

For Linux, OS X, or Unix:

Copy
aws rds create-db-instance \ --db-instance-identifier mydbinstance \ --db-instance-class db.m3.medium \ --engine MySQL \ --allocated-storage 20 \ --master-username masterawsuser \ --master-user-password masteruserpassword \ --enable-iam-database-authentication

For Windows:

Copy
aws rds create-db-instance ^ --db-instance-identifier mydbinstance ^ --db-instance-class db.m3.medium ^ --engine MySQL ^ --allocated-storage 20 ^ --master-username masterawsuser ^ --master-user-password masteruserpassword ^ --enable-iam-database-authentication

The following example enables IAM database authentication for the mysqldb DB instance. The changes are applied immediately. You can use --no-apply-immediately instead of --apply-immediately to apply the changes during the next maintenance window instead.

For Linux, OS X, or Unix:

Copy
aws rds modify-db-instance \ --db-instance-identifier mysqldb \ --apply-immediately \ --enable-iam-database-authentication

For Windows:

Copy
aws rds modify-db-instance ^ --db-instance-identifier mysqldb ^ --apply-immediately ^ --enable-iam-database-authentication

Amazon RDS API

You can enable and disable IAM database authentication by using the Amazon RDS API as follows:

  • If you create a DB instance or DB cluster with the API, you can enable IAM database authentication with the CreateDBInstance action (MySQL) or CreateDBCluster action (Amazon Aurora). IAM database authentication is off by default for a DB instance or DB cluster. To enable IAM database authentication, specify true for EnableIAMDatabaseAuthentication.

  • If you modify a DB instance or DB cluster with the API, you can enable or disable IAM database authentication with the ModifyDBInstance action (MySQL) or ModifyDBCluster action (Aurora). To enable IAM database authentication, specify true for EnableIAMDatabaseAuthentication. To disable IAM database authentication, specify false for EnableIAMDatabaseAuthentication.

  • If you restore a DB instance using the RestoreDBInstanceToPointInTime or RestoreDBInstanceFromDBSnapshot actions, or restore a DB cluster using the RestoreDBClusterToPointInTime or RestoreDBClusterFromSnapshot actions, the IAM database authentication setting defaults to that of the source snapshot. You can change the IAM database authentication setting by specifying either true for EnableIAMDatabaseAuthentication to enable it or false for EnableIAMDatabaseAuthentication to disable it.

Creating Database Accounts for IAM Database Authentication

To connect to a DB instance or DB cluster using IAM database authentication, you create database user accounts that can accept authentication tokens, which allow these user accounts to be mapped to IAM users or roles.

To do this, you must use an authentication plugin. In this case, you specify AWSAuthenticationPlugin as the authentication plugin by using the IDENTIFIED WITH argument of the CREATE USER command. This creates a database user account has no stored password but instead can accept an AWS authentication token in its place.

You manage database accounts that are associated with authentication plugins in the same way as other database user accounts, by connecting to the DB instance or DB cluster from a standard database client application and running SQL commands like ALTER USER and DROP USER.

To create a database user account that uses an authentication token, create a database user account using the CREATE USER MySQL command as shown following.

Copy
CREATE USER jane_doe IDENTIFIED WITH AWSAuthenticationPlugin as 'RDS';

In the preceding command, the following is true:

  • IDENTIFIED WITH associates the database user account with the plugin AWSAuthenticationPlugin, which manages IAM database authentication.

  • The as 'RDS" keyword maps the database account to the IAM user or role. The IAM user or role must be in the Amazon IAM ARN format. In this case, the database account is mapped to the arn:aws:iam::123456789012:user/jane_doe IAM user. If IAM database authentication is enabled, jane_doe can authenticate to your DB instance. To learn more about the Amazon IAM ARN format, see IAM ARNs. To learn more about how to create an IAM user or role, see Creating an IAM User in Your AWS Account. To learn more about managing IAM users, see Managing IAM Users.

Note

After removing IAM users that are mapped to database accounts, you should remove the users by running the DROP USER MySQL command.

Attaching an IAM Policy Account to an IAM User or Role

To allow an IAM user or role to connect to Amazon RDS DB instances or DB clusters, you must create an IAM policy and attach the policy to the IAM user or role. An IAM policy specifies permissions to an AWS resource, and the action the IAM user or role can take. In this case, you allow access to database user accounts by specifying the following policy attributes:

  • Effect: Specify Allow to allow access to DB instances or DB clusters. The default Effect value is Deny, which to denies access to DB instances or DB clusters.

  • Action: Specify the rds-db:connect Action value to allow connections to one or more DB instances or DB clusters.

  • Resource: Specify a database user account Amazon Resource Name (ARN), which is composed as follows.

    Copy
    arn:aws:rds-db:region:account-id:dbuser:dbi-resource-id/database-user-name

    You can allow connections to a particular database user account in a DB instance or DB cluster by specifying its dbi resource ID, as shown in the following example.

    Copy
    arn:aws:rds-db:us-west-2:12345678:dbuser:db-12ABC34DEFG5HIJ6KLMNOP78QR/jane_doe

    You can find the dbi resource ID on the details page for the DB instance or DB cluster in the Amazon RDS Management Console. You can also get a DB instance dbi resource ID from the DbiResourceId element in the DBInstance object returned by the AWS CLI describe-db-instances command or Amazon RDS API DescribeDBInstances action, or a DB cluster dbi resource ID from the DbClusterResourceId element in the DBCluster object returned by the AWS CLI describe-db-clusters command or Amazon RDS API DescribeDBClusters action.

    Alternatively, you can allow connections to a database user account in all of your DB instances or DB clusters by specifying * instead of a dbi resource ID, as shown in the following example. Note that all of the DB instances or DB clusters must have the specified authentication token-enabled database user account.

    Copy
    arn:aws:rds-db:us-west-2:12345678:dbuser:*/jane_doe

    The database user must be associated with the AWSAuthenticationPlugin plugin that manages IAM database authentication, as described in Creating Database Accounts for IAM Database Authentication.

    The IAM user or role has access to only those databases that the database user does. For example, if you have databases A and B on your DB instance, and database user jane_doe only has access to database A, IAM users or roles that access that DB instance using that account will also only have access to database A. The same limitation is true for other database objects like tables, views, and so forth.

    You can map multiple IAM users or roles to the same database user account. For example, IAM users A and B can both have policies that give them access to a DB instance by specifying the database user ARN arn:aws:rds-db:us-west-2:12345678:dbuser:db-12ABC34DEFG5HIJ6KLMNOP78QR/jane_doe as a resource.

To learn more about IAM policies, see Overview of IAM Policies.

The example policy following allows connections to two DB instances using two database user accounts.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "rds-db:connect" ], "Resource": [ "arn:aws:rds-db:us-west-2:12345678:dbuser:db-12ABC34DEFG5HIJ6KLMNOP78QR/jane_doe", "arn:aws:rds-db:us-east-1:12345678:dbuser:db-23ABC45DEFG6HIJ7KLMNOP89QR/mary_roe" ] } ] }

The example policy following allows connections to all of the DB instances and DB clusters in the us-west-2 region for the given account, that have an authentication token-enabled database user account for jane_doe.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "rds-db:connect" ], "Resource": [ "arn:aws:rds-db:us-west-2:12345678:dbuser:*/jane_doe" ] } ] }

To learn how to attach the rds-db:connect IAM policy to an IAM user or role, see the Create and Attach Your First Customer Managed Policy tutorial in the IAM User Guide. In the tutorial, specify an rds-db:connect policy, such as the policy preceding.

Getting an Authentication Token

With IAM database authentication, you authenticate to the database engine by using an IAM user or role and an authentication token. An authentication token is a value created by the AWS Signature Version 4 algorithm, which has a 15-minute lifetime. If an expired token is used to connect to the database, the connection request is denied.

You can get an authentication token in several ways; each way is explained in the following sections:

If your application is running on an Amazon EC2 instance, you can use EC2 instance profile credentials. For more information about EC2 instance profile credentials, see Using IAM Roles to Grant Access to AWS Resources on Amazon EC2 and Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances in the IAM User Guide.

Getting an Authentication Token Using the AWS SDK for Java

To get an authentication token using the DefaultAWSCredentialsProviderChain class, first create an instance of the RdsIamAuthTokenGenerator class, which is in the AWS SDK for Java. Then call the getToken() method.

To create an instance of RdsIamAuthTokenGenerator, you must provide AWS credentials. To provide AWS credentials, create an instance of the DefaultAWSCredentialsProviderChain class, which is also in the AWS SDK for Java. That class uses the first AWS access key and AWS secret key it finds in the default credential provider chain. For more information about AWS access keys, see Managing Access Keys for IAM Users. With an instance of RdsIamAuthTokenGenerator, call the getToken() method.

The example following gets an authentication token using DefaultAWSCredentialsProviderChain.

Copy
private static String generateAuthToken() { // Generate an authentication token using AWS credentials in the default credential provider chain. RdsIamAuthTokenGenerator generator = RdsIamAuthTokenGenerator.builder() .credentials(new DefaultAWSCredentialsProviderChain()) .region(regionName) .build(); String authToken = generator.getAuthToken(GetIamAuthTokenRequest .builder() .hostname(rds_instance_hostname) .port(rds_instance_port) .userName("iam-database-user") .build()); return authToken; }

Getting an Authentication Token Using the AWS CLI

You can use the AWS CLI to obtain an authentication token, using the generate-db-auth-token CLI command. The generate-db-auth-token command takes the following format:

Copy
generate-db-auth-token --hostname <value> --port <value> --username <value>

The parameters for the generate-db-auth-token CLI command are defined as follows:

  • hostname — (string) The hostname of the database to connect to.

  • port — (integer) The port number the database is listening on.

  • username — (string) The username to log in as.

The following example generates an authentication token for the hostname on port 3306 for the user name iamuser.

Copy
aws rds generate-db-auth-token --hostname iam-db-auth-test.eu-central-1.rds.amazonaws.com --port 3306 --username iamuser

Connecting to a DB Instance or DB Cluster Using IAM Database Authentication

To connect to your DB instance using IAM database authentication, you must use an SSL connection that contains an authentication token as the password to encrypt the connection to the database engine. For more information, see Using SSL to Encrypt a Connection to a DB Instance and Using Secure Connections.

The example following uses the authToken value from the preceding example to connect to a DB instance running MySQL. To get the endpoint of the Amazon RDS instance, you can use the AWS Management Console or the AWS CLI describe-db-instances command for MySQL, or the RDS API action describe-db-clusters for Aurora.

Note

You can connect to the instances in an Aurora DB cluster by using one of several endpoints for a DB cluster: cluster endpoint, reader endpoint, or instance endpoint. For more information, see Aurora Endpoints.

Copy
private static Connection getDBConnectionUsingIam() { String jdbcUrl = "jdbc:mysql://" + rds_instance_endpoint; Properties mysqlConnectionProperties = new Properties(); mysqlConnectionProperties.setProperty("verifyServerCertificate", "true"); mysqlConnectionProperties.setProperty("useSSL", "true"); System.setProperty("javax.net.ssl.trustStore","path_to_truststore"); System.setProperty("javax.net.ssl.trustStorePassword","trustore_password"); mysqlConnectionProperties.setProperty("user", "iam-database-user"); // Call a method to generate an authentication token (see above example) String authToken = generateAuthToken(); // Set authentication token as password mysqlConnectionProperties.setProperty("password", authToken); Connection connection = DriverManager.getConnection(jdbcUrl, mysqlConnectionProperties); }

Related Topics