# IAM database authentication for MariaDB, MySQL, and PostgreSQL
You can authenticate to your DB instance using AWS Identity and Access Management (IAM) database authentication. IAM database authentication works with MariaDB, MySQL, and PostgreSQL. With this authentication method, you don't need to use a password when you connect to a DB instance. Instead, you use an authentication token.
An *authentication token* is a unique string of characters that Amazon RDS generates on request. Authentication tokens are generated using AWS Signature Version 4. Each token has a lifetime of 15 minutes. You don't need to store user credentials in the database, because authentication is managed externally using IAM. You can also still use standard database authentication. The token is only used for authentication and doesn't affect the session after it is established.
IAM database authentication provides the following benefits:
+ Network traffic to and from the database is encrypted using Secure Socket Layer (SSL) or Transport Layer Security (TLS). For more information about using SSL/TLS with Amazon RDS, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).
+ You can use IAM to centrally manage access to your database resources, instead of managing access individually on each DB instance.
+ For applications running on Amazon EC2, you can use profile credentials specific to your EC2 instance to access your database instead of a password, for greater security.
In general, consider using IAM database authentication when your applications create fewer than 200 connections per second, and you don't want to manage usernames and passwords directly in your application code.
The Amazon Web Services (AWS) JDBC Driver supports IAM database authentication. For more information, see [AWS IAM Authentication Plugin](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) in the [Amazon Web Services (AWS) JDBC Driver GitHub repository](https://github.com/aws/aws-advanced-jdbc-wrapper).
The Amazon Web Services (AWS) Python Driver supports IAM database authentication. For more information, see [AWS IAM Authentication Plugin](https://github.com/aws/aws-advanced-python-wrapper/blob/main/docs/using-the-python-driver/using-plugins/UsingTheIamAuthenticationPlugin.md) in the [Amazon Web Services (AWS) Python Driver GitHub repository](https://github.com/aws/aws-advanced-python-wrapper).
Navigate through the following topics to learn the process to set IAM for DB authentication:
+ [Enabling and disabling IAM database authentication](UsingWithRDS.IAMDBAuth.Enabling.md)
+ [Creating and using an IAM policy for IAM database access](UsingWithRDS.IAMDBAuth.IAMPolicy.md)
+ [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md)
+ [Connecting to your DB instance using IAM authentication](UsingWithRDS.IAMDBAuth.Connecting.md)
## Region and version availability
Feature availability and support varies across specific versions of each database engine. For more information on engine, version, and Region availability with Amazon RDS and IAM database authentication, see [Supported Regions and DB engines for IAM database authentication in Amazon RDS](Concepts.RDS_Fea_Regions_DB-eng.Feature.IamDatabaseAuthentication.md).
## CLI and SDK support
IAM database authentication is available for the [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/rds/generate-db-auth-token.html) and for the following language-specific AWS SDKs:
+ [AWS SDK for .NET](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/RDS/TRDSAuthTokenGenerator.html)
+ [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/sdk-for-cpp/latest/api/class_aws_1_1_r_d_s_1_1_r_d_s_client.html#ae134ffffed5d7672f6156d324e7bd392)
+ [AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go/api/service/rds/#pkg-overview)
+ [AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/services/rds/RdsUtilities.html)
+ [AWS SDK for JavaScript](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_rds_signer.html)
+ [AWS SDK for PHP](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.Rds.AuthTokenGenerator.html)
+ [AWS SDK for Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.generate_db_auth_token)
+ [AWS SDK for Ruby](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/RDS/AuthTokenGenerator.html)
## Limitations for IAM database authentication
When using IAM database authentication, the following limitations apply:
+ Currently, IAM database authentication doesn't support all global condition context keys.
For more information about global condition context keys, see [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*.
+ For PostgreSQL, if the IAM role (`rds_iam`) is added to a user (including the RDS master user), IAM authentication takes precedence over password authentication, so the user must log in as an IAM user.
+ For PostgreSQL, Amazon RDS does not support enabling both IAM and Kerberos authentication methods at the same time.
+ For PostgreSQL, you can't use IAM authentication to establish a replication connection.
+ You cannot use a custom Route 53 DNS record instead of the DB instance endpoint to generate the authentication token.
+ CloudWatch and CloudTrail don't log IAM authentication. These services do not track `generate-db-auth-token` API calls that authorize the IAM role to enable database connection.
+ IAM DB authentication requires compute resources on the database instance. You must have between 300 and 1000 MiB extra memory on your database for reliable connectivity. To see the memory needed for your workload, compare the RES column for RDS processes in the Enhanced Monitoring processlist before and after enabling IAM DB authentication. See [Viewing OS metrics in the RDS console](USER_Monitoring.OS.Viewing.md).
If you are using a burstable class instance, avoid running out of memory by reducing the memory used by other parameters like buffers and cache by the same amount.
+ IAM DB authentication is not supported for RDS on Outposts for any engine.
## Recommendations for IAM database authentication
We recommend the following when using IAM database authentication:
+ Use IAM database authentication when your application requires fewer than 200 new IAM database authentication connections per second.
The database engines that work with Amazon RDS don't impose any limits on authentication attempts per second. However, when you use IAM database authentication, your application must generate an authentication token. Your application then uses that token to connect to the DB instance. If you exceed the limit of maximum new connections per second, then the extra overhead of IAM database authentication can cause connection throttling.
Consider using connection pooling in your applications to mitigate constant connection creation. This can reduce the overhead from IAM DB authentication and allow your applications to reuse existing connections. Alternatively, consider using RDS Proxy for these use cases. RDS Proxy has additional costs. See [RDS Proxy pricing](https://aws.amazon.com/rds/proxy/pricing/).
+ The size of an IAM database authentication token depends on many things including the number of IAM tags, IAM service policies, ARN lengths, as well as other IAM and database properties. The minimum size of this token is generally about 1 KB but can be larger. Since this token is used as the password in the connection string to the database using IAM authentication, you should ensure that your database driver (e.g., ODBC) and/or any tools do not limit or otherwise truncate this token due to its size. A truncated token will cause the authentication validation done by the database and IAM to fail.
+ If you are using temporary credentials when creating an IAM database authentication token, the temporary credentials must still be valid when using the IAM database authentication token to make a connection request.
## Unsupported AWS global condition context keys
IAM database authentication does not support the following subset of AWS global condition context keys.
+ `aws:Referer`
+ `aws:SourceIp`
+ `aws:SourceVpc`
+ `aws:SourceVpce`
+ `aws:UserAgent`
+ `aws:VpcSourceIp`
For more information, see [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*.
# Enabling and disabling IAM database authentication
By default, IAM database authentication is disabled on DB instances. You can enable or disable IAM database authentication using the AWS Management Console, AWS CLI, or the API.
You can enable IAM database authentication when you perform one of the following actions:
+ To create a new DB instance with IAM database authentication enabled, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ To modify a DB instance to enable IAM database authentication, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
+ To restore a DB instance from a snapshot with IAM database authentication enabled, see [Restoring to a DB instance](USER_RestoreFromSnapshot.md).
+ To restore a DB instance to a point in time with IAM database authentication enabled, see [Restoring a DB instance to a specified time for Amazon RDS](USER_PIT.md).
## Console
Each creation or modification workflow has a **Database authentication** section, where you can enable or disable IAM database authentication. In that section, choose **Password and IAM database authentication** to enable IAM database authentication.
**To enable or disable IAM database authentication for an existing DB instance**
1. Open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. In the navigation pane, choose **Databases**.
1. Choose the DB instance that you want to modify.
**Note**
Make sure that the DB instance is compatible with IAM authentication. Check the compatibility requirements in [Region and version availability](UsingWithRDS.IAMDBAuth.md#UsingWithRDS.IAMDBAuth.Availability).
1. Choose **Modify**.
1. In the **Database authentication** section, choose **Password and IAM database authentication** to enable IAM database authentication. Choose **Password authentication** or **Password and Kerberos authentication** to disable IAM authentication.
1. You can also choose to enable publishing IAM DB authentication logs to CloudWatch Logs. Under **Log exports**, choose the **iam-db-auth-error log** option. Publishing your logs to CloudWatch Logs consumes storage and you incur charges for that storage. Be sure to delete any CloudWatch Logs that you no longer need.
1. Choose **Continue**.
1. To apply the changes immediately, choose **Immediately** in the **Scheduling of modifications** section.
1. Choose **Modify DB instance** .
## AWS CLI
To create a new DB instance with IAM authentication by using the AWS CLI, use the [https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance.html](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance.html) command. Specify the `--enable-iam-database-authentication` option, as shown in the following example.
```
aws rds create-db-instance \
--db-instance-identifier mydbinstance \
--db-instance-class db.m3.medium \
--engine MySQL \
--allocated-storage 20 \
--master-username masterawsuser \
--manage-master-user-password \
--enable-iam-database-authentication
```
To update an existing DB instance to have or not have IAM authentication, use the AWS CLI command [https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html). Specify either the `--enable-iam-database-authentication` or `--no-enable-iam-database-authentication` option, as appropriate.
**Note**
Make sure that the DB instance is compatible with IAM authentication. Check the compatibility requirements in [Region and version availability](UsingWithRDS.IAMDBAuth.md#UsingWithRDS.IAMDBAuth.Availability).
By default, Amazon RDS performs the modification during the next maintenance window. If you want to override this and enable IAM DB authentication as soon as possible, use the `--apply-immediately` parameter.
The following example shows how to immediately enable IAM authentication for an existing DB instance.
```
aws rds modify-db-instance \
--db-instance-identifier mydbinstance \
--apply-immediately \
--enable-iam-database-authentication
```
If you are restoring a DB instance, use one of the following AWS CLI commands:
+ `[restore-db-instance-to-point-in-time](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-instance-to-point-in-time.html)`
+ `[restore-db-instance-from-db-snapshot](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-instance-from-db-snapshot.html)`
The IAM database authentication setting defaults to that of the source snapshot. To change this setting, set the `--enable-iam-database-authentication` or `--no-enable-iam-database-authentication` option, as appropriate.
## RDS API
To create a new DB instance with IAM authentication by using the API, use the API operation [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstance.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstance.html). Set the `EnableIAMDatabaseAuthentication` parameter to `true`.
To update an existing DB instance to have IAM authentication, use the API operation [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBInstance.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBInstance.html). Set the `EnableIAMDatabaseAuthentication` parameter to `true` to enable IAM authentication, or `false` to disable it.
**Note**
Make sure that the DB instance is compatible with IAM authentication. Check the compatibility requirements in [Region and version availability](UsingWithRDS.IAMDBAuth.md#UsingWithRDS.IAMDBAuth.Availability).
If you are restoring a DB instance, use one of the following API operations:
+ [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RestoreDBInstanceFromDBSnapshot.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RestoreDBInstanceFromDBSnapshot.html)
+ [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RestoreDBInstanceToPointInTime.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RestoreDBInstanceToPointInTime.html)
The IAM database authentication setting defaults to that of the source snapshot. To change this setting, set the `EnableIAMDatabaseAuthentication` parameter to `true` to enable IAM authentication, or `false` to disable it.
# Creating and using an IAM policy for IAM database access
To allow a user or role to connect to your DB instance, you must create an IAM policy. After that, you attach the policy to a permissions set or role.
**Note**
To learn more about IAM policies, see [Identity and access management for Amazon RDS](UsingWithRDS.IAM.md).
The following example policy allows a user to connect to a DB instance using IAM database authentication.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"rds-db:connect"
],
"Resource": [
"arn:aws:rds-db:us-east-2:111122223333:dbuser:db-ABCDEFGHIJKL01234/db_user"
]
}
]
}
```
------
**Important**
A user with administrator permissions can access DB instances without explicit permissions in an IAM policy. If you want to restrict administrator access to DB instances, you can create an IAM role with the appropriate, lesser privileged permissions and assign it to the administrator.
**Note**
Don't confuse the `rds-db:` prefix with other RDS API operation prefixes that begin with `rds:`. You use the `rds-db:` prefix and the `rds-db:connect` action only for IAM database authentication. They aren't valid in any other context.
The example policy includes a single statement with the following elements:
+ `Effect` – Specify `Allow` to grant access to the DB instance. If you don't explicitly allow access, then access is denied by default.
+ `Action` – Specify `rds-db:connect` to allow connections to the DB instance.
+ `Resource` – Specify an Amazon Resource Name (ARN) that describes one database account in one DB instance. The ARN format is as follows.
```
arn:aws:rds-db:region:account-id:dbuser:DbiResourceId/db-user-name
```
In this format, replace the following:
+ `region` is the AWS Region for the DB instance. In the example policy, the AWS Region is `us-east-2`.
+ `account-id` is the AWS account number for the DB instance. In the example policy, the account number is `1234567890`. The user must be in the same account as the account for the DB instance.
To perform cross-account access, create an IAM role with the policy shown above in the account for the DB instance and allow your other account to assume the role.
+ `DbiResourceId` is the identifier for the DB instance. This identifier is unique to an AWS Region and never changes. In the example policy, the identifier is `db-ABCDEFGHIJKL01234`.
To find a DB instance resource ID in the AWS Management Console for Amazon RDS, choose the DB instance to see its details. Then choose the **Configuration** tab. The **Resource ID** is shown in the **Configuration** section.
Alternatively, you can use the AWS CLI command to list the identifiers and resource IDs for all of your DB instance in the current AWS Region, as shown following.
```
aws rds describe-db-instances --query "DBInstances[*].[DBInstanceIdentifier,DbiResourceId]"
```
If you are using Amazon Aurora, specify a `DbClusterResourceId` instead of a `DbiResourceId`. For more information, see [ Creating and using an IAM policy for IAM database access](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html) in the *Amazon Aurora User Guide*.
**Note**
If you are connecting to a database through RDS Proxy, specify the proxy resource ID, such as `prx-ABCDEFGHIJKL01234`. For information about using IAM database authentication with RDS Proxy, see [Connecting to a database using IAM authentication](rds-proxy-connecting.md#rds-proxy-connecting-iam).
+ `db-user-name` is the name of the database account to associate with IAM authentication. In the example policy, the database account is `db_user`.
You can construct other ARNs to support various access patterns. The following policy allows access to two different database accounts in a DB instance.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"rds-db:connect"
],
"Resource": [
"arn:aws:rds-db:us-east-2:123456789012:dbuser:db-ABCDEFGHIJKL01234/jane_doe",
"arn:aws:rds-db:us-east-2:123456789012:dbuser:db-ABCDEFGHIJKL01234/mary_roe"
]
}
]
}
```
------
The following policy uses the "\$1" character to match all DB instances and database accounts for a particular AWS account and AWS Region.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"rds-db:connect"
],
"Resource": [
"arn:aws:rds-db:us-east-2:111122223333:dbuser:*/*"
]
}
]
}
```
------
The following policy matches all of the DB instances for a particular AWS account and AWS Region. However, the policy only grants access to DB instances that have a `jane_doe` database account.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"rds-db:connect"
],
"Resource": [
"arn:aws:rds-db:us-east-2:123456789012:dbuser:*/jane_doe"
]
}
]
}
```
------
The user or role has access to only those databases that the database user does. For example, suppose that your DB instance has a database named *dev*, and another database named *test*. If the database user `jane_doe` has access only to *dev*, any users or roles that access that DB instance with the `jane_doe` user also have access only to *dev*. This access restriction is also true for other database objects, such as tables, views, and so on.
An administrator must create IAM policies that grant entities permission to perform specific API operations on the specified resources they need. The administrator must then attach those policies to the permission sets or roles that require those permissions. For examples of policies, see [Identity-based policy examples for Amazon RDS](security_iam_id-based-policy-examples.md).
## Attaching an IAM policy to a permission set or role
After you create an IAM policy to allow database authentication, you need to attach the policy to a permission set or role. For a tutorial on this topic, see [ Create and attach your first customer managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_managed-policies.html) in the *IAM User Guide*.
As you work through the tutorial, you can use one of the policy examples shown in this section as a starting point and tailor it to your needs. At the end of the tutorial, you have a permission set with an attached policy that can make use of the `rds-db:connect` action.
**Note**
You can map multiple permission sets or roles to the same database user account. For example, suppose that your IAM policy specified the following resource ARN.
```
arn:aws:rds-db:us-east-2:123456789012:dbuser:db-12ABC34DEFG5HIJ6KLMNOP78QR/jane_doe
```
If you attach the policy to *Jane*, *Bob*, and *Diego*, then each of those users can connect to the specified DB instance using the `jane_doe` database account.
# Creating a database account using IAM authentication
With IAM database authentication, you don't need to assign database passwords to the user accounts you create. If you remove a user that is mapped to a database account, you should also remove the database account with the `DROP USER` statement.
**Note**
The user name used for IAM authentication must match the case of the user name in the database.
**Topics**
+ [
## Using IAM authentication with MariaDB and MySQL
](#UsingWithRDS.IAMDBAuth.DBAccounts.MySQL)
+ [
## Using IAM authentication with PostgreSQL
](#UsingWithRDS.IAMDBAuth.DBAccounts.PostgreSQL)
## Using IAM authentication with MariaDB and MySQL
With MariaDB and MySQL, authentication is handled by `AWSAuthenticationPlugin`—an AWS-provided plugin that works seamlessly with IAM to authenticate your users. Connect to the DB instance as the master user or a different user who can create users and grant privileges. After connecting, issue the `CREATE USER` statement, as shown in the following example.
```
CREATE USER 'jane_doe' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
```
The `IDENTIFIED WITH` clause allows MariaDB and MySQL to use the `AWSAuthenticationPlugin` to authenticate the database account (`jane_doe`). The `AS 'RDS'` clause refers to the authentication method. Make sure the specified database user name is the same as a resource in the IAM policy for IAM database access. For more information, see [Creating and using an IAM policy for IAM database access](UsingWithRDS.IAMDBAuth.IAMPolicy.md).
**Note**
If you see the following message, it means that the AWS-provided plugin is not available for the current DB instance.
`ERROR 1524 (HY000): Plugin 'AWSAuthenticationPlugin' is not loaded`
To troubleshoot this error, verify that you are using a supported configuration and that you have enabled IAM database authentication on your DB instance. For more information, see [Region and version availability](UsingWithRDS.IAMDBAuth.md#UsingWithRDS.IAMDBAuth.Availability) and [Enabling and disabling IAM database authentication](UsingWithRDS.IAMDBAuth.Enabling.md).
After you create an account using `AWSAuthenticationPlugin`, you manage it in the same way as other database accounts. For example, you can modify account privileges with `GRANT` and `REVOKE` statements, or modify various account attributes with the `ALTER USER` statement.
Database network traffic is encrypted using SSL/TLS when using IAM. To allow SSL connections, modify the user account with the following command.
```
ALTER USER 'jane_doe'@'%' REQUIRE SSL;
```
## Using IAM authentication with PostgreSQL
To use IAM authentication with PostgreSQL, connect to the DB instance as the master user or a different user who can create users and grant privileges. After connecting, create database users and then grant them the `rds_iam` role as shown in the following example.
```
CREATE USER db_userx;
GRANT rds_iam TO db_userx;
```
Make sure the specified database user name is the same as a resource in the IAM policy for IAM database access. For more information, see [Creating and using an IAM policy for IAM database access](UsingWithRDS.IAMDBAuth.IAMPolicy.md). You must grant the `rds_iam` role to use IAM authentication. You can use nested memberships or indirect grants of the role as well.
# Connecting to your DB instance using IAM authentication
With IAM database authentication, you use an authentication token when you connect to your DB instance. An *authentication token* is a string of characters that you use instead of a password. After you generate an authentication token, it's valid for 15 minutes before it expires. If you try to connect using an expired token, the connection request is denied.
Every authentication token must be accompanied by a valid signature, using AWS signature version 4. (For more information, see [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) in the* AWS General Reference.*) The AWS CLI and an AWS SDK, such as the AWS SDK for Java or AWS SDK for Python (Boto3), can automatically sign each token you create.
You can use an authentication token when you connect to Amazon RDS from another AWS service, such as AWS Lambda. By using a token, you can avoid placing a password in your code. Alternatively, you can use an AWS SDK to programmatically create and programmatically sign an authentication token.
After you have a signed IAM authentication token, you can connect to an Amazon RDS DB instance. Following, you can find out how to do this using either a command line tool or an AWS SDK, such as the AWS SDK for Java or AWS SDK for Python (Boto3).
For more information, see the following blog posts:
+ [Use IAM authentication to connect with SQL Workbench/J to Aurora MySQL or Amazon RDS for MySQL](https://aws.amazon.com/blogs/database/use-iam-authentication-to-connect-with-sql-workbenchj-to-amazon-aurora-mysql-or-amazon-rds-for-mysql/)
+ [Using IAM authentication to connect with pgAdmin Amazon Aurora PostgreSQL or Amazon RDS for PostgreSQL](https://aws.amazon.com/blogs/database/using-iam-authentication-to-connect-with-pgadmin-amazon-aurora-postgresql-or-amazon-rds-for-postgresql/)
**Prerequisites**
The following are prerequisites for connecting to your DB instance using IAM authentication:
+ [Enabling and disabling IAM database authentication](UsingWithRDS.IAMDBAuth.Enabling.md)
+ [Creating and using an IAM policy for IAM database access](UsingWithRDS.IAMDBAuth.IAMPolicy.md)
+ [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md)
**Topics**
+ [
# Connecting to your DB instance using IAM authentication with the AWS drivers
](IAMDBAuth.Connecting.Drivers.md)
+ [
# Connecting to your DB instance using IAM authentication from the command line: AWS CLI and mysql client
](UsingWithRDS.IAMDBAuth.Connecting.AWSCLI.md)
+ [
# Connecting to your DB instance using IAM authentication from the command line: AWS CLI and psql client
](UsingWithRDS.IAMDBAuth.Connecting.AWSCLI.PostgreSQL.md)
+ [
# Connecting to your DB instance using IAM authentication and the AWS SDK for .NET
](UsingWithRDS.IAMDBAuth.Connecting.NET.md)
+ [
# Connecting to your DB instance using IAM authentication and the AWS SDK for Go
](UsingWithRDS.IAMDBAuth.Connecting.Go.md)
+ [
# Connecting to your DB instance using IAM authentication and the AWS SDK for Java
](UsingWithRDS.IAMDBAuth.Connecting.Java.md)
+ [
# Connecting to your DB instance using IAM authentication and the AWS SDK for Python (Boto3)
](UsingWithRDS.IAMDBAuth.Connecting.Python.md)
# Connecting to your DB instance using IAM authentication with the AWS drivers
The AWS suite of drivers has been designed to provide support for faster switchover and failover times, and authentication with AWS Secrets Manager, AWS Identity and Access Management (IAM), and Federated Identity. The AWS drivers rely on monitoring DB instance status and being aware of the instance topology to determine the new writer. This approach reduces switchover and failover times to single-digit seconds, compared to tens of seconds for open-source drivers.
For more information on the AWS drivers, see the corresponding language driver for your [RDS for MariaDB](MariaDB.Connecting.Drivers.md#MariaDB.Connecting.JDBCDriver), [RDS for MySQL](MySQL.Connecting.Drivers.md#MySQL.Connecting.JDBCDriver), or [RDS for PostgreSQL](PostgreSQL.Connecting.JDBCDriver.md) DB instance.
**Note**
The only features supported for RDS for MariaDB are authentication with AWS Secrets Manager, AWS Identity and Access Management (IAM), and Federated Identity.
# Connecting to your DB instance using IAM authentication from the command line: AWS CLI and mysql client
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](UsingWithRDS.IAMDBAuth.Enabling.md)
+ [Creating and using an IAM policy for IAM database access](UsingWithRDS.IAMDBAuth.IAMPolicy.md)
+ [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md)
**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](https://aws.amazon.com/blogs/database/use-iam-authentication-to-connect-with-sql-workbenchj-to-amazon-aurora-mysql-or-amazon-rds-for-mysql/).
**Topics**
+ [
## Generating an IAM authentication token
](#UsingWithRDS.IAMDBAuth.Connecting.AWSCLI.AuthToken)
+ [
## Connecting to a DB instance
](#UsingWithRDS.IAMDBAuth.Connecting.AWSCLI.Connect)
## 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 DB instance
+ `--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](MariaDB.Concepts.SSLSupport.md).
For more information about SSL/TLS support for MySQL, see [SSL/TLS support for MySQL DB instances on Amazon RDS](MySQL.Concepts.SSLSupport.md).
To download an SSL certificate, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).
+ `--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\$1dir/* 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 database using IAM authentication](rds-proxy-connecting.md#rds-proxy-connecting-iam).
# Connecting to your DB instance using IAM authentication from the command line: AWS CLI and psql client
You can connect from the command line to an Amazon RDS for PostgreSQL DB instance with the AWS CLI and psql 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](UsingWithRDS.IAMDBAuth.Enabling.md)
+ [Creating and using an IAM policy for IAM database access](UsingWithRDS.IAMDBAuth.IAMPolicy.md)
+ [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md)
**Note**
For information about connecting to your database using pgAdmin with IAM authentication, see the blog post [Using IAM authentication to connect with pgAdmin Amazon Aurora PostgreSQL or Amazon RDS for PostgreSQL](https://aws.amazon.com/blogs/database/using-iam-authentication-to-connect-with-pgadmin-amazon-aurora-postgresql-or-amazon-rds-for-postgresql/).
**Topics**
+ [
## Generating an IAM authentication token
](#UsingWithRDS.IAMDBAuth.Connecting.AWSCLI.AuthToken.PostgreSQL)
+ [
## Connecting to an Amazon RDS PostgreSQL instance
](#UsingWithRDS.IAMDBAuth.Connecting.AWSCLI.Connect.PostgreSQL)
## Generating an IAM authentication token
The authentication token consists of several hundred characters so 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 how to use the AWS CLI to get a signed authentication token using the `generate-db-auth-token` command, and store it in a `PGPASSWORD` environment variable.
```
export RDSHOST="rdspostgres.123456789012.us-west-2.rds.amazonaws.com"
export PGPASSWORD="$(aws rds generate-db-auth-token --hostname $RDSHOST --port 5432 --region us-west-2 --username jane_doe )"
```
In the example, the parameters to the `generate-db-auth-token` command 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 DB instance
+ `--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 generated token look like the following.
```
rdspostgres.123456789012.us-west-2.rds.amazonaws.com:5432/?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 an Amazon RDS PostgreSQL instance
The general format for using psql to connect is shown following.
```
psql "host=hostName port=portNumber sslmode=verify-full sslrootcert=full_path_to_ssl_certificate dbname=DBName 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
+ `sslmode` – The SSL mode to use
When you use `sslmode=verify-full`, the SSL connection verifies the DB instance endpoint against the endpoint in the SSL certificate.
+ `sslrootcert` – The full path to the SSL certificate file that contains the public key
For more information, see [Using SSL with a PostgreSQL DB instance](PostgreSQL.Concepts.General.SSL.md).
To download an SSL certificate, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).
+ `dbname` – The database that you want to access
+ `user` – The database account that you want to access
+ `password` – A signed IAM authentication token
**Note**
You cannot use a custom Route 53 DNS record instead of the DB instance endpoint to generate the authentication token.
The following example shows using psql to connect. In the example, psql uses the environment variable `RDSHOST` for the host and the environment variable `PGPASSWORD` for the generated token. Also, */sample\$1dir/* is the full path to the SSL certificate file that contains the public key.
```
export RDSHOST="rdspostgres.123456789012.us-west-2.rds.amazonaws.com"
export PGPASSWORD="$(aws rds generate-db-auth-token --hostname $RDSHOST --port 5432 --region us-west-2 --username jane_doe )"
psql "host=$RDSHOST port=5432 sslmode=verify-full sslrootcert=/sample_dir/global-bundle.pem dbname=DBName user=jane_doe password=$PGPASSWORD"
```
If you want to connect to a DB instance through a proxy, see [Connecting to a database using IAM authentication](rds-proxy-connecting.md#rds-proxy-connecting-iam).
# Connecting to your DB instance using IAM authentication and the AWS SDK for .NET
You can connect to an RDS for MariaDB, MySQL, or PostgreSQL DB instance with the AWS SDK for .NET as described following.
**Prerequisites**
The following are prerequisites for connecting to your DB instance using IAM authentication:
+ [Enabling and disabling IAM database authentication](UsingWithRDS.IAMDBAuth.Enabling.md)
+ [Creating and using an IAM policy for IAM database access](UsingWithRDS.IAMDBAuth.IAMPolicy.md)
+ [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md)
**Examples**
The following code examples show how to generate an authentication token, and then use it to connect to a DB instance.
To run this code example, you need the [AWS SDK for .NET](http://aws.amazon.com/sdk-for-net/), found on the AWS site. The `AWSSDK.CORE` and the `AWSSDK.RDS` packages are required. To connect to a DB instance, use the .NET database connector for the DB engine, such as MySqlConnector for MariaDB or MySQL, or Npgsql for PostgreSQL.
This code connects to a MariaDB or MySQL DB instance. Modify the values of the following variables as needed:
+ `server` – The endpoint of the DB instance that you want to access
+ `user` – The database account that you want to access
+ `database` – The database that you want to access
+ `port` – The port number used for connecting to your DB instance
+ `SslMode` – The SSL mode to use
When you use `SslMode=Required`, the SSL connection verifies the DB instance endpoint against the endpoint in the SSL certificate.
+ `SslCa` – The full path to the SSL certificate for Amazon RDS
To download a certificate, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).
**Note**
You cannot use a custom Route 53 DNS record instead of the DB instance endpoint to generate the authentication token.
```
using System;
using System.Data;
using MySql.Data;
using MySql.Data.MySqlClient;
using Amazon;
namespace ubuntu
{
class Program
{
static void Main(string[] args)
{
var pwd = Amazon.RDS.Util.RDSAuthTokenGenerator.GenerateAuthToken(RegionEndpoint.USEast1, "mysqldb.123456789012.us-east-1.rds.amazonaws.com", 3306, "jane_doe");
// for debug only Console.Write("{0}\n", pwd); //this verifies the token is generated
MySqlConnection conn = new MySqlConnection($"server=mysqldb.123456789012.us-east-1.rds.amazonaws.com;user=jane_doe;database=mydB;port=3306;password={pwd};SslMode=Required;SslCa=full_path_to_ssl_certificate");
conn.Open();
// Define a query
MySqlCommand sampleCommand = new MySqlCommand("SHOW DATABASES;", conn);
// Execute a query
MySqlDataReader mysqlDataRdr = sampleCommand.ExecuteReader();
// Read all rows and output the first column in each row
while (mysqlDataRdr.Read())
Console.WriteLine(mysqlDataRdr[0]);
mysqlDataRdr.Close();
// Close connection
conn.Close();
}
}
}
```
This code connects to a PostgreSQL DB instance.
Modify the values of the following variables as needed:
+ `Server` – The endpoint of the DB instance that you want to access
+ `User ID` – The database account that you want to access
+ `Database` – The database that you want to access
+ `Port` – The port number used for connecting to your DB instance
+ `SSL Mode` – The SSL mode to use
When you use `SSL Mode=Required`, the SSL connection verifies the DB instance endpoint against the endpoint in the SSL certificate.
+ `Root Certificate` – The full path to the SSL certificate for Amazon RDS
To download a certificate, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).
**Note**
You cannot use a custom Route 53 DNS record instead of the DB instance endpoint to generate the authentication token.
```
using System;
using Npgsql;
using Amazon.RDS.Util;
namespace ConsoleApp1
{
class Program
{
static void Main(string[] args)
{
var pwd = RDSAuthTokenGenerator.GenerateAuthToken("postgresmydb.123456789012.us-east-1.rds.amazonaws.com", 5432, "jane_doe");
// for debug only Console.Write("{0}\n", pwd); //this verifies the token is generated
NpgsqlConnection conn = new NpgsqlConnection($"Server=postgresmydb.123456789012.us-east-1.rds.amazonaws.com;User Id=jane_doe;Password={pwd};Database=mydb;SSL Mode=Require;Root Certificate=full_path_to_ssl_certificate");
conn.Open();
// Define a query
NpgsqlCommand cmd = new NpgsqlCommand("select count(*) FROM pg_user", conn);
// Execute a query
NpgsqlDataReader dr = cmd.ExecuteReader();
// Read all rows and output the first column in each row
while (dr.Read())
Console.Write("{0}\n", dr[0]);
// Close connection
conn.Close();
}
}
}
```
If you want to connect to a DB instance through a proxy, see [Connecting to a database using IAM authentication](rds-proxy-connecting.md#rds-proxy-connecting-iam).
# Connecting to your DB instance using IAM authentication and the AWS SDK for Go
You can connect to an RDS for MariaDB, MySQL, or PostgreSQL DB instance with the AWS SDK for Go as described following.
**Prerequisites**
The following are prerequisites for connecting to your DB instance using IAM authentication:
+ [Enabling and disabling IAM database authentication](UsingWithRDS.IAMDBAuth.Enabling.md)
+ [Creating and using an IAM policy for IAM database access](UsingWithRDS.IAMDBAuth.IAMPolicy.md)
+ [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md)
**Examples**
To run these code examples, you need the [AWS SDK for Go](http://aws.amazon.com/sdk-for-go/), found on the AWS site.
Modify the values of the following variables as needed:
+ `dbName` – The database that you want to access
+ `dbUser` – The database account that you want to access
+ `dbHost` – The endpoint of the DB instance that you want to access
**Note**
You cannot use a custom Route 53 DNS record instead of the DB instance endpoint to generate the authentication token.
+ `dbPort` – The port number used for connecting to your DB instance
+ `region` – The AWS Region where the DB instance is running
In addition, make sure the imported libraries in the sample code exist on your system.
**Important**
The examples in this section use the following code to provide credentials that access a database from a local environment:
`creds := credentials.NewEnvCredentials()`
If you are accessing a database from an AWS service, such as Amazon EC2 or Amazon ECS, you can replace the code with the following code:
`sess := session.Must(session.NewSession())`
`creds := sess.Config.Credentials`
If you make this change, make sure you add the following import:
`"github.com/aws/aws-sdk-go/aws/session"`
**Topics**
+ [
## Connecting using IAM authentication and the AWS SDK for Go V2
](#UsingWithRDS.IAMDBAuth.Connecting.GoV2)
+ [
## Connecting using IAM authentication and the AWS SDK for Go V1.
](#UsingWithRDS.IAMDBAuth.Connecting.GoV1)
## Connecting using IAM authentication and the AWS SDK for Go V2
You can connect to a DB instance using IAM authentication and the AWS SDK for Go V2.
The following code examples show how to generate an authentication token, and then use it to connect to a DB instance.
This code connects to a MariaDB or MySQL DB instance.
```
package main
import (
"context"
"database/sql"
"fmt"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/feature/rds/auth"
_ "github.com/go-sql-driver/mysql"
)
func main() {
var dbName string = "DatabaseName"
var dbUser string = "DatabaseUser"
var dbHost string = "mysqldb.123456789012.us-east-1.rds.amazonaws.com"
var dbPort int = 3306
var dbEndpoint string = fmt.Sprintf("%s:%d", dbHost, dbPort)
var region string = "us-east-1"
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic("configuration error: " + err.Error())
}
authenticationToken, err := auth.BuildAuthToken(
context.TODO(), dbEndpoint, region, dbUser, cfg.Credentials)
if err != nil {
panic("failed to create authentication token: " + err.Error())
}
dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s?tls=true&allowCleartextPasswords=true",
dbUser, authenticationToken, dbEndpoint, dbName,
)
db, err := sql.Open("mysql", dsn)
if err != nil {
panic(err)
}
err = db.Ping()
if err != nil {
panic(err)
}
}
```
This code connects to a PostgreSQL DB instance.
```
package main
import (
"context"
"database/sql"
"fmt"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/feature/rds/auth"
_ "github.com/lib/pq"
)
func main() {
var dbName string = "DatabaseName"
var dbUser string = "DatabaseUser"
var dbHost string = "postgresmydb.123456789012.us-east-1.rds.amazonaws.com"
var dbPort int = 5432
var dbEndpoint string = fmt.Sprintf("%s:%d", dbHost, dbPort)
var region string = "us-east-1"
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic("configuration error: " + err.Error())
}
authenticationToken, err := auth.BuildAuthToken(
context.TODO(), dbEndpoint, region, dbUser, cfg.Credentials)
if err != nil {
panic("failed to create authentication token: " + err.Error())
}
dsn := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s",
dbHost, dbPort, dbUser, authenticationToken, dbName,
)
db, err := sql.Open("postgres", dsn)
if err != nil {
panic(err)
}
err = db.Ping()
if err != nil {
panic(err)
}
}
```
If you want to connect to a DB instance through a proxy, see [Connecting to a database using IAM authentication](rds-proxy-connecting.md#rds-proxy-connecting-iam).
## Connecting using IAM authentication and the AWS SDK for Go V1.
You can connect to a DB instance using IAM authentication and the AWS SDK for Go V1
The following code examples show how to generate an authentication token, and then use it to connect to a DB instance.
This code connects to a MariaDB or MySQL DB instance.
```
package main
import (
"database/sql"
"fmt"
"log"
"github.com/aws/aws-sdk-go/aws/credentials"
"github.com/aws/aws-sdk-go/service/rds/rdsutils"
_ "github.com/go-sql-driver/mysql"
)
func main() {
dbName := "app"
dbUser := "jane_doe"
dbHost := "mysqldb.123456789012.us-east-1.rds.amazonaws.com"
dbPort := 3306
dbEndpoint := fmt.Sprintf("%s:%d", dbHost, dbPort)
region := "us-east-1"
creds := credentials.NewEnvCredentials()
authToken, err := rdsutils.BuildAuthToken(dbEndpoint, region, dbUser, creds)
if err != nil {
panic(err)
}
dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s?tls=true&allowCleartextPasswords=true",
dbUser, authToken, dbEndpoint, dbName,
)
db, err := sql.Open("mysql", dsn)
if err != nil {
panic(err)
}
err = db.Ping()
if err != nil {
panic(err)
}
}
```
This code connects to a PostgreSQL DB instance.
```
package main
import (
"database/sql"
"fmt"
"github.com/aws/aws-sdk-go/aws/credentials"
"github.com/aws/aws-sdk-go/service/rds/rdsutils"
_ "github.com/lib/pq"
)
func main() {
dbName := "app"
dbUser := "jane_doe"
dbHost := "postgresmydb.123456789012.us-east-1.rds.amazonaws.com"
dbPort := 5432
dbEndpoint := fmt.Sprintf("%s:%d", dbHost, dbPort)
region := "us-east-1"
creds := credentials.NewEnvCredentials()
authToken, err := rdsutils.BuildAuthToken(dbEndpoint, region, dbUser, creds)
if err != nil {
panic(err)
}
dsn := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s",
dbHost, dbPort, dbUser, authToken, dbName,
)
db, err := sql.Open("postgres", dsn)
if err != nil {
panic(err)
}
err = db.Ping()
if err != nil {
panic(err)
}
}
```
If you want to connect to a DB instance through a proxy, see [Connecting to a database using IAM authentication](rds-proxy-connecting.md#rds-proxy-connecting-iam).
# Connecting to your DB instance using IAM authentication and the AWS SDK for Java
You can connect to an RDS for MariaDB, MySQL, or PostgreSQL DB instance with the AWS SDK for Java as described following.
**Prerequisites**
The following are prerequisites for connecting to your DB instance using IAM authentication:
+ [Enabling and disabling IAM database authentication](UsingWithRDS.IAMDBAuth.Enabling.md)
+ [Creating and using an IAM policy for IAM database access](UsingWithRDS.IAMDBAuth.IAMPolicy.md)
+ [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md)
+ [Set up the AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-install.html)
For examples on how to use the SDK for Java 2.x, see [Amazon RDS examples using SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/java_rds_code_examples.html). You can also use the AWS Advanced JDBC Wrapper, see [AWS Advanced JDBC Wrapper documentation](https://github.com/aws/aws-advanced-jdbc-wrapper/blob/main/docs/Documentation.md).
**Topics**
+ [
## Generating an IAM authentication token
](#UsingWithRDS.IAMDBAuth.Connecting.Java.AuthToken)
+ [
## Manually constructing an IAM authentication token
](#UsingWithRDS.IAMDBAuth.Connecting.Java.AuthToken2)
+ [
## Connecting to a DB instance
](#UsingWithRDS.IAMDBAuth.Connecting.Java.AuthToken.Connect)
## Generating an IAM authentication token
If you are writing programs using the AWS SDK for Java, you can get a signed authentication token using the `RdsIamAuthTokenGenerator` class. Using this class requires that you provide AWS credentials. To do this, you create an instance of the `DefaultAWSCredentialsProviderChain` class. `DefaultAWSCredentialsProviderChain` uses the first AWS access key and secret key that it finds in the [default credential provider chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default). For more information about AWS access keys, see [Managing access keys for users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
**Note**
You cannot use a custom Route 53 DNS record instead of the DB instance endpoint to generate the authentication token.
After you create an instance of `RdsIamAuthTokenGenerator`, you can call the `getAuthToken` method to obtain a signed token. Provide the AWS Region, host name, port number, and user name. The following code example illustrates how to do this.
```
package com.amazonaws.codesamples;
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
import com.amazonaws.services.rds.auth.GetIamAuthTokenRequest;
import com.amazonaws.services.rds.auth.RdsIamAuthTokenGenerator;
public class GenerateRDSAuthToken {
public static void main(String[] args) {
String region = "us-west-2";
String hostname = "rdsmysql.123456789012.us-west-2.rds.amazonaws.com";
String port = "3306";
String username = "jane_doe";
System.out.println(generateAuthToken(region, hostname, port, username));
}
static String generateAuthToken(String region, String hostName, String port, String username) {
RdsIamAuthTokenGenerator generator = RdsIamAuthTokenGenerator.builder()
.credentials(new DefaultAWSCredentialsProviderChain())
.region(region)
.build();
String authToken = generator.getAuthToken(
GetIamAuthTokenRequest.builder()
.hostname(hostName)
.port(Integer.parseInt(port))
.userName(username)
.build());
return authToken;
}
}
```
## Manually constructing an IAM authentication token
In Java, the easiest way to generate an authentication token is to use `RdsIamAuthTokenGenerator`. This class creates an authentication token for you, and then signs it using AWS signature version 4. For more information, see [Signature version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) in the *AWS General Reference.*
However, you can also construct and sign an authentication token manually, as shown in the following code example.
```
package com.amazonaws.codesamples;
import com.amazonaws.SdkClientException;
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
import com.amazonaws.auth.SigningAlgorithm;
import com.amazonaws.util.BinaryUtils;
import org.apache.commons.lang3.StringUtils;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.Charset;
import java.security.MessageDigest;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.SortedMap;
import java.util.TreeMap;
import static com.amazonaws.auth.internal.SignerConstants.AWS4_TERMINATOR;
import static com.amazonaws.util.StringUtils.UTF8;
public class CreateRDSAuthTokenManually {
public static String httpMethod = "GET";
public static String action = "connect";
public static String canonicalURIParameter = "/";
public static SortedMap canonicalQueryParameters = new TreeMap();
public static String payload = StringUtils.EMPTY;
public static String signedHeader = "host";
public static String algorithm = "AWS4-HMAC-SHA256";
public static String serviceName = "rds-db";
public static String requestWithoutSignature;
public static void main(String[] args) throws Exception {
String region = "us-west-2";
String instanceName = "rdsmysql.123456789012.us-west-2.rds.amazonaws.com";
String port = "3306";
String username = "jane_doe";
Date now = new Date();
String date = new SimpleDateFormat("yyyyMMdd").format(now);
String dateTimeStamp = new SimpleDateFormat("yyyyMMdd'T'HHmmss'Z'").format(now);
DefaultAWSCredentialsProviderChain creds = new DefaultAWSCredentialsProviderChain();
String awsAccessKey = creds.getCredentials().getAWSAccessKeyId();
String awsSecretKey = creds.getCredentials().getAWSSecretKey();
String expiryMinutes = "900";
System.out.println("Step 1: Create a canonical request:");
String canonicalString = createCanonicalString(username, awsAccessKey, date, dateTimeStamp, region, expiryMinutes, instanceName, port);
System.out.println(canonicalString);
System.out.println();
System.out.println("Step 2: Create a string to sign:");
String stringToSign = createStringToSign(dateTimeStamp, canonicalString, awsAccessKey, date, region);
System.out.println(stringToSign);
System.out.println();
System.out.println("Step 3: Calculate the signature:");
String signature = BinaryUtils.toHex(calculateSignature(stringToSign, newSigningKey(awsSecretKey, date, region, serviceName)));
System.out.println(signature);
System.out.println();
System.out.println("Step 4: Add the signing info to the request");
System.out.println(appendSignature(signature));
System.out.println();
}
//Step 1: Create a canonical request date should be in format YYYYMMDD and dateTime should be in format YYYYMMDDTHHMMSSZ
public static String createCanonicalString(String user, String accessKey, String date, String dateTime, String region, String expiryPeriod, String hostName, String port) throws Exception {
canonicalQueryParameters.put("Action", action);
canonicalQueryParameters.put("DBUser", user);
canonicalQueryParameters.put("X-Amz-Algorithm", "AWS4-HMAC-SHA256");
canonicalQueryParameters.put("X-Amz-Credential", accessKey + "%2F" + date + "%2F" + region + "%2F" + serviceName + "%2Faws4_request");
canonicalQueryParameters.put("X-Amz-Date", dateTime);
canonicalQueryParameters.put("X-Amz-Expires", expiryPeriod);
canonicalQueryParameters.put("X-Amz-SignedHeaders", signedHeader);
String canonicalQueryString = "";
while(!canonicalQueryParameters.isEmpty()) {
String currentQueryParameter = canonicalQueryParameters.firstKey();
String currentQueryParameterValue = canonicalQueryParameters.remove(currentQueryParameter);
canonicalQueryString = canonicalQueryString + currentQueryParameter + "=" + currentQueryParameterValue;
if (!currentQueryParameter.equals("X-Amz-SignedHeaders")) {
canonicalQueryString += "&";
}
}
String canonicalHeaders = "host:" + hostName + ":" + port + '\n';
requestWithoutSignature = hostName + ":" + port + "/?" + canonicalQueryString;
String hashedPayload = BinaryUtils.toHex(hash(payload));
return httpMethod + '\n' + canonicalURIParameter + '\n' + canonicalQueryString + '\n' + canonicalHeaders + '\n' + signedHeader + '\n' + hashedPayload;
}
//Step 2: Create a string to sign using sig v4
public static String createStringToSign(String dateTime, String canonicalRequest, String accessKey, String date, String region) throws Exception {
String credentialScope = date + "/" + region + "/" + serviceName + "/aws4_request";
return algorithm + '\n' + dateTime + '\n' + credentialScope + '\n' + BinaryUtils.toHex(hash(canonicalRequest));
}
//Step 3: Calculate signature
/**
* Step 3 of the &AWS; Signature version 4 calculation. It involves deriving
* the signing key and computing the signature. Refer to
* http://docs.aws.amazon
* .com/general/latest/gr/sigv4-calculate-signature.html
*/
public static byte[] calculateSignature(String stringToSign,
byte[] signingKey) {
return sign(stringToSign.getBytes(Charset.forName("UTF-8")), signingKey,
SigningAlgorithm.HmacSHA256);
}
public static byte[] sign(byte[] data, byte[] key,
SigningAlgorithm algorithm) throws SdkClientException {
try {
Mac mac = algorithm.getMac();
mac.init(new SecretKeySpec(key, algorithm.toString()));
return mac.doFinal(data);
} catch (Exception e) {
throw new SdkClientException(
"Unable to calculate a request signature: "
+ e.getMessage(), e);
}
}
public static byte[] newSigningKey(String secretKey,
String dateStamp, String regionName, String serviceName) {
byte[] kSecret = ("AWS4" + secretKey).getBytes(Charset.forName("UTF-8"));
byte[] kDate = sign(dateStamp, kSecret, SigningAlgorithm.HmacSHA256);
byte[] kRegion = sign(regionName, kDate, SigningAlgorithm.HmacSHA256);
byte[] kService = sign(serviceName, kRegion,
SigningAlgorithm.HmacSHA256);
return sign(AWS4_TERMINATOR, kService, SigningAlgorithm.HmacSHA256);
}
public static byte[] sign(String stringData, byte[] key,
SigningAlgorithm algorithm) throws SdkClientException {
try {
byte[] data = stringData.getBytes(UTF8);
return sign(data, key, algorithm);
} catch (Exception e) {
throw new SdkClientException(
"Unable to calculate a request signature: "
+ e.getMessage(), e);
}
}
//Step 4: append the signature
public static String appendSignature(String signature) {
return requestWithoutSignature + "&X-Amz-Signature=" + signature;
}
public static byte[] hash(String s) throws Exception {
try {
MessageDigest md = MessageDigest.getInstance("SHA-256");
md.update(s.getBytes(UTF8));
return md.digest();
} catch (Exception e) {
throw new SdkClientException(
"Unable to compute hash while signing request: "
+ e.getMessage(), e);
}
}
}
```
## Connecting to a DB instance
The following code example shows how to generate an authentication token, and then use it to connect to an instance running MariaDB or MySQL.
To run this code example, you need the [AWS SDK for Java](http://aws.amazon.com/sdk-for-java/), found on the AWS site. In addition, you need the following:
+ MySQL Connector/J. This code example was tested with `mysql-connector-java-5.1.33-bin.jar`.
+ An intermediate certificate for Amazon RDS that is specific to an AWS Region. (For more information, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).) At runtime, the class loader looks for the certificate in the same directory as this Java code example, so that the class loader can find it.
+ Modify the values of the following variables as needed:
+ `RDS_INSTANCE_HOSTNAME` – The host name of the DB instance that you want to access.
+ `RDS_INSTANCE_PORT` – The port number used for connecting to your PostgreSQL DB instance.
+ `REGION_NAME` – The AWS Region where the DB instance is running.
+ `DB_USER` – The database account that you want to access.
+ `SSL_CERTIFICATE` – An SSL certificate for Amazon RDS that is specific to an AWS Region.
To download a certificate for your AWS Region, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md). Place the SSL certificate in the same directory as this Java program file, so that the class loader can find the certificate at runtime.
This code example obtains AWS credentials from the [default credential provider chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default).
**Note**
Specify a password for `DEFAULT_KEY_STORE_PASSWORD` other than the prompt shown here as a security best practice.
```
package com.amazonaws.samples;
import com.amazonaws.services.rds.auth.RdsIamAuthTokenGenerator;
import com.amazonaws.services.rds.auth.GetIamAuthTokenRequest;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
import com.amazonaws.auth.AWSStaticCredentialsProvider;
import java.io.File;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.security.KeyStore;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;
import java.util.Properties;
import java.net.URL;
public class IAMDatabaseAuthenticationTester {
//&AWS; Credentials of the IAM user with policy enabling IAM Database Authenticated access to the db by the db user.
private static final DefaultAWSCredentialsProviderChain creds = new DefaultAWSCredentialsProviderChain();
private static final String AWS_ACCESS_KEY = creds.getCredentials().getAWSAccessKeyId();
private static final String AWS_SECRET_KEY = creds.getCredentials().getAWSSecretKey();
//Configuration parameters for the generation of the IAM Database Authentication token
private static final String RDS_INSTANCE_HOSTNAME = "rdsmysql.123456789012.us-west-2.rds.amazonaws.com";
private static final int RDS_INSTANCE_PORT = 3306;
private static final String REGION_NAME = "us-west-2";
private static final String DB_USER = "jane_doe";
private static final String JDBC_URL = "jdbc:mysql://" + RDS_INSTANCE_HOSTNAME + ":" + RDS_INSTANCE_PORT;
private static final String SSL_CERTIFICATE = "rds-ca-2019-us-west-2.pem";
private static final String KEY_STORE_TYPE = "JKS";
private static final String KEY_STORE_PROVIDER = "SUN";
private static final String KEY_STORE_FILE_PREFIX = "sys-connect-via-ssl-test-cacerts";
private static final String KEY_STORE_FILE_SUFFIX = ".jks";
private static final String DEFAULT_KEY_STORE_PASSWORD = "changeit";
public static void main(String[] args) throws Exception {
//get the connection
Connection connection = getDBConnectionUsingIam();
//verify the connection is successful
Statement stmt= connection.createStatement();
ResultSet rs=stmt.executeQuery("SELECT 'Success!' FROM DUAL;");
while (rs.next()) {
String id = rs.getString(1);
System.out.println(id); //Should print "Success!"
}
//close the connection
stmt.close();
connection.close();
clearSslProperties();
}
/**
* This method returns a connection to the db instance authenticated using IAM Database Authentication
* @return
* @throws Exception
*/
private static Connection getDBConnectionUsingIam() throws Exception {
setSslProperties();
return DriverManager.getConnection(JDBC_URL, setMySqlConnectionProperties());
}
/**
* This method sets the mysql connection properties which includes the IAM Database Authentication token
* as the password. It also specifies that SSL verification is required.
* @return
*/
private static Properties setMySqlConnectionProperties() {
Properties mysqlConnectionProperties = new Properties();
mysqlConnectionProperties.setProperty("verifyServerCertificate","true");
mysqlConnectionProperties.setProperty("useSSL", "true");
mysqlConnectionProperties.setProperty("user",DB_USER);
mysqlConnectionProperties.setProperty("password",generateAuthToken());
return mysqlConnectionProperties;
}
/**
* This method generates the IAM Auth Token.
* An example IAM Auth Token would look like follows:
* btusi123---cmz7kenwo2ye---rds---cn-north-1.amazonaws.com.rproxy.govskope.us.cn:3306/?Action=connect&DBUser=iamtestuser&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20171003T010726Z&X-Amz-SignedHeaders=host&X-Amz-Expires=899&X-Amz-Credential=AKIAPFXHGVDI5RNFO4AQ%2F20171003%2Fcn-north-1%2Frds-db%2Faws4_request&X-Amz-Signature=f9f45ef96c1f770cdad11a53e33ffa4c3730bc03fdee820cfdf1322eed15483b
* @return
*/
private static String generateAuthToken() {
BasicAWSCredentials awsCredentials = new BasicAWSCredentials(AWS_ACCESS_KEY, AWS_SECRET_KEY);
RdsIamAuthTokenGenerator generator = RdsIamAuthTokenGenerator.builder()
.credentials(new AWSStaticCredentialsProvider(awsCredentials)).region(REGION_NAME).build();
return generator.getAuthToken(GetIamAuthTokenRequest.builder()
.hostname(RDS_INSTANCE_HOSTNAME).port(RDS_INSTANCE_PORT).userName(DB_USER).build());
}
/**
* This method sets the SSL properties which specify the key store file, its type and password:
* @throws Exception
*/
private static void setSslProperties() throws Exception {
System.setProperty("javax.net.ssl.trustStore", createKeyStoreFile());
System.setProperty("javax.net.ssl.trustStoreType", KEY_STORE_TYPE);
System.setProperty("javax.net.ssl.trustStorePassword", DEFAULT_KEY_STORE_PASSWORD);
}
/**
* This method returns the path of the Key Store File needed for the SSL verification during the IAM Database Authentication to
* the db instance.
* @return
* @throws Exception
*/
private static String createKeyStoreFile() throws Exception {
return createKeyStoreFile(createCertificate()).getPath();
}
/**
* This method generates the SSL certificate
* @return
* @throws Exception
*/
private static X509Certificate createCertificate() throws Exception {
CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
URL url = new File(SSL_CERTIFICATE).toURI().toURL();
if (url == null) {
throw new Exception();
}
try (InputStream certInputStream = url.openStream()) {
return (X509Certificate) certFactory.generateCertificate(certInputStream);
}
}
/**
* This method creates the Key Store File
* @param rootX509Certificate - the SSL certificate to be stored in the KeyStore
* @return
* @throws Exception
*/
private static File createKeyStoreFile(X509Certificate rootX509Certificate) throws Exception {
File keyStoreFile = File.createTempFile(KEY_STORE_FILE_PREFIX, KEY_STORE_FILE_SUFFIX);
try (FileOutputStream fos = new FileOutputStream(keyStoreFile.getPath())) {
KeyStore ks = KeyStore.getInstance(KEY_STORE_TYPE, KEY_STORE_PROVIDER);
ks.load(null);
ks.setCertificateEntry("rootCaCertificate", rootX509Certificate);
ks.store(fos, DEFAULT_KEY_STORE_PASSWORD.toCharArray());
}
return keyStoreFile;
}
/**
* This method clears the SSL properties.
* @throws Exception
*/
private static void clearSslProperties() throws Exception {
System.clearProperty("javax.net.ssl.trustStore");
System.clearProperty("javax.net.ssl.trustStoreType");
System.clearProperty("javax.net.ssl.trustStorePassword");
}
}
```
If you want to connect to a DB instance through a proxy, see [Connecting to a database using IAM authentication](rds-proxy-connecting.md#rds-proxy-connecting-iam).
# Connecting to your DB instance using IAM authentication and the AWS SDK for Python (Boto3)
You can connect to an RDS for MariaDB, MySQL, or PostgreSQL DB instance with the AWS SDK for Python (Boto3) as described following.
**Prerequisites**
The following are prerequisites for connecting to your DB instance using IAM authentication:
+ [Enabling and disabling IAM database authentication](UsingWithRDS.IAMDBAuth.Enabling.md)
+ [Creating and using an IAM policy for IAM database access](UsingWithRDS.IAMDBAuth.IAMPolicy.md)
+ [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md)
In addition, make sure the imported libraries in the sample code exist on your system.
**Examples**
The code examples use profiles for shared credentials. For information about the specifying credentials, see [Credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html) in the AWS SDK for Python (Boto3) documentation.
The following code examples show how to generate an authentication token, and then use it to connect to a DB instance.
To run this code example, you need the [AWS SDK for Python (Boto3)](http://aws.amazon.com/sdk-for-python/), found on the AWS site.
Modify the values of the following variables as needed:
+ `ENDPOINT` – The endpoint of the DB instance that you want to access
+ `PORT` – The port number used for connecting to your DB instance
+ `USER` – The database account that you want to access
+ `REGION` – The AWS Region where the DB instance is running
+ `DBNAME` – The database that you want to access
+ `SSLCERTIFICATE` – The full path to the SSL certificate for Amazon RDS
For `ssl_ca`, specify an SSL certificate. To download an SSL certificate, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).
**Note**
You cannot use a custom Route 53 DNS record instead of the DB instance endpoint to generate the authentication token.
This code connects to a MariaDB or MySQL DB instance.
Before running this code, install the PyMySQL driver by following the instructions in the [ Python Package Index](https://pypi.org/project/PyMySQL/).
```
import pymysql
import sys
import boto3
import os
ENDPOINT="mysqldb.123456789012.us-east-1.rds.amazonaws.com"
PORT="3306"
USER="jane_doe"
REGION="us-east-1"
DBNAME="mydb"
os.environ['LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN'] = '1'
#gets the credentials from .aws/credentials
session = boto3.Session(profile_name='default')
client = session.client('rds')
token = client.generate_db_auth_token(DBHostname=ENDPOINT, Port=PORT, DBUsername=USER, Region=REGION)
try:
conn = pymysql.connect(auth_plugin_map={'mysql_clear_password':None},host=ENDPOINT, user=USER, password=token, port=PORT, database=DBNAME, ssl_ca='SSLCERTIFICATE', ssl_verify_identity=True, ssl_verify_cert=True)
cur = conn.cursor()
cur.execute("""SELECT now()""")
query_results = cur.fetchall()
print(query_results)
except Exception as e:
print("Database connection failed due to {}".format(e))
```
This code connects to a PostgreSQL DB instance.
Before running this code, install `psycopg2` by following the instructions in [Psycopg documentation](https://pypi.org/project/psycopg2/).
```
import psycopg2
import sys
import boto3
import os
ENDPOINT="postgresmydb.123456789012.us-east-1.rds.amazonaws.com"
PORT="5432"
USER="jane_doe"
REGION="us-east-1"
DBNAME="mydb"
#gets the credentials from .aws/credentials
session = boto3.Session(profile_name='RDSCreds')
client = session.client('rds')
token = client.generate_db_auth_token(DBHostname=ENDPOINT, Port=PORT, DBUsername=USER, Region=REGION)
try:
conn = psycopg2.connect(host=ENDPOINT, port=PORT, database=DBNAME, user=USER, password=token, sslrootcert="SSLCERTIFICATE")
cur = conn.cursor()
cur.execute("""SELECT now()""")
query_results = cur.fetchall()
print(query_results)
except Exception as e:
print("Database connection failed due to {}".format(e))
```
If you want to connect to a DB instance through a proxy, see [Connecting to a database using IAM authentication](rds-proxy-connecting.md#rds-proxy-connecting-iam).
# Troubleshooting for IAM DB authentication
Following, you can find troubleshooting ideas for some common IAM DB authentication issues and information on CloudWatch logs and metrics for IAM DB authentication.
## Exporting IAM DB authentication error logs to CloudWatch Logs
IAM DB authentication error logs are stored on the database host, and you can export these logs your CloudWatch Logs account. Use the logs and remediation methods in this page to troubleshoot IAM DB authentication issues.
You can enable log exports to CloudWatch Logs from the console, AWS CLI, and RDS API. For console instructions, see [Publishing database logs to Amazon CloudWatch Logs](USER_LogAccess.Procedural.UploadtoCloudWatch.md).
To export your IAM DB authentication error logs to CloudWatch Logs when creating a DB instance from the AWS CLI, use the following command:
```
aws rds create-db-instance --db-instance-identifier mydbinstance \
--region us-east-1 \
--db-instance-class db.t3.large \
--allocated-storage 50 \
--engine postgres \
--engine-version 16 \
--port 5432 \
--master-username master \
--master-user-password password \
--publicly-accessible \
--enable-iam-database-authentication \
--enable-cloudwatch-logs-exports=iam-db-auth-error
```
To export your IAM DB authentication error logs to CloudWatch Logs when modifying a DB instance from the AWS CLI, use the following command:
```
aws rds modify-db-instance --db-instance-identifier mydbinstance \
--region us-east-1 \
--cloudwatch-logs-export-configuration '{"EnableLogTypes":["iam-db-auth-error"]}'
```
To verify if your DB instance is exporting IAM DB authentication logs to CloudWatch Logs, check if the `EnabledCloudwatchLogsExports` parameter is set to `iam-db-auth-error` in the output for the `describe-db-instances` command.
```
aws rds describe-db-instances --region us-east-1 --db-instance-identifier mydbinstance
...
"EnabledCloudwatchLogsExports": [
"iam-db-auth-error"
],
...
```
## IAM DB authentication CloudWatch metrics
Amazon RDS delivers near-real time metrics about IAM DB authentication to your Amazon CloudWatch account. The following table lists the IAM DB authentication metrics available using CloudWatch:
| Metric | Description |
| --- | --- |
| `IamDbAuthConnectionRequests` | Total number of connection requests made with IAM DB authentication. |
| `IamDbAuthConnectionSuccess` | Total number of successful IAM DB authentication requests. |
| `IamDbAuthConnectionFailure` | Total number of failed IAM DB authentication requests. |
| `IamDbAuthConnectionFailureInvalidToken` | Total number of failed IAM DB authentication requests due to invalid token. |
| `IamDbAuthConnectionFailureInsufficientPermissions` | Total number of failed IAM DB authentication requests due to incorrect policies or permissions. |
| `IamDbAuthConnectionFailureThrottling` | Total number of failed IAM DB authentication requests due to IAM DB authentication throttling. |
| `IamDbAuthConnectionFailureServerError` | Total number of failed IAM DB authentication requests due to an internal server error in the IAM DB authentication feature. |
## Common issues and solutions
You might encounter the following issues when using IAM DB authention. Use the remediation steps in the table to solve the issues:
| Error | Metric(s) | Cause | Solution |
| --- | --- | --- | --- |
| `[ERROR] Failed to authenticate the connection request for user db_user because the provided token is malformed or otherwise invalid. (Status Code: 400, Error Code: InvalidToken)` | `IamDbAuthConnectionFailure` `IamDbAuthConnectionFailureInvalidToken` | The IAM DB authentiation token in the connection request is either not a valid SigV4a token, or it is not formatted correctly. | Check your token generation strategy in your application. In some cases, make sure you are passing the token with valid formatting. Truncating the token (or incorrect string formatting) will make the token invalid. |
| `[ERROR] Failed to authenticate the connection request for user db_user because the token age is longer than 15 minutes. (Status Code: 400, Error Code:ExpiredToken)` | `IamDbAuthConnectionFailure` `IamDbAuthConnectionFailureInvalidToken` | The IAM DB authentication token has expired. Tokens are only valid for 15 minutes. | Check your token caching and/or token re-use logic in your application. You should not re-use tokens that are older than 15 minutes. |
| `[ERROR] Failed to authorize the connection request for user db_user because the IAM policy assumed by the caller 'arn:aws:sts::123456789012:assumed-role/ / ' is not authorized to perform `rds-db:connect` on the DB instance. (Status Code: 403, Error Code:NotAuthorized)` | `IamDbAuthConnectionFailure` `IamDbAuthConnectionFailureInsufficientPermissions` | This error might be due to the following reasons: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Troubleshooting.html) | Verify that the IAM role and/or policy you are assuming in your application. Make sure you assume the same policy to generate the token as to connect to the DB. |
| `[ERROR] Failed to authorize the connection request for user db_user due to IAM DB authentication throttling. (Status Code: 429, Error Code: ThrottlingException)` | `IamDbAuthConnectionFailure` `IamDbAuthConnectionFailureThrottling` | You are making too many connection requests to your DB in a short amount of time. IAM DB authentication throttling limit is 200 connections per second. | Reduce the rate of establishing new connections with IAM authentication. Consider implementing connection pooling using RDS Proxy in order to reuse established connections in your application. |
| `[ERROR] Failed to authorize the connection request for user db_user due to an internal IAM DB authentication error. (Status Code: 500, Error Code: InternalError)` | `IamDbAuthConnectionFailure` `IamDbAuthConnectionFailureThrottling` | There was an internal error while authorizing the DB conneciton with IAM DB authentication. | Reach out to https://aws.amazon.com/premiumsupport/ to investigate the issue. |