How do I resolve the "invalid username-password pair or user is disabled" error when I connect to my ElastiCache cluster with IAM authentication?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Create users

Complete the following steps:

1. Open the ElastiCache console.
2. From Configurations, choose User management.
3. Choose Create user, and then enter the following information:
   For User ID, enter a user ID.
   For User name, enter a username.
   Note: For IAM users, the user ID and username must be identical and lowercase.
   Select your Engine from the dropdown list.
   For Authentication mode, select IAM authentication.
   In the Access string field, enter on ~* +@all.
   Note: To give an active user access to all available keys and commands, use the on ~*+@all access string. It's a best practice to create restrictive access strings that provide only the permissions that your users need. For more information, see Specifying Permissions Using an Access String.
4. Choose Create.

Create user groups

Complete the following steps:

1. Open the ElastiCache console.
2. From Configurations, choose User group management.
3. Choose Create user group.
4. For User group ID, enter the user group ID.
5. Select your Engine from the dropdown list.
6. For the Selected users section, choose Manage.
7. From the list of users, select the user that you created earlier.
   Important: If you choose Redis for the Engine, then select the user named Default. ElastiCache automatically creates a default user with full Redis access permissions that doesn't require a password for authentication. To modify default user settings, see Creating Users and User Groups with the Console and CLI.
8. Choose Create.

Allow IAM authentication

Enable in-transit encryption (TLS) on your ElastiCache cluster.

Configure role-based access control for your cluster

Complete the following steps:

1. Open the ElastiCache console.
2. From the cluster list, select your cluster.
3. Choose Actions, and then Modify.
4. From Access control, choose User group access control list, and then select your user group.
5. Choose Preview changes.
6. Choose Save.

Configure your IAM policy

Add the elasticache:Connect action to the IAM identity that you use to connect to the ElastiCache cluster. Example IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticache:Connect"
      ],
      "Resource": [
        "AWS_RESOURCE_ARN_1",
        "AWS_RESOURCE_ARN_2"
      ]
    }
  ]
}

Note: Replace AWS_RESOURCE_ARN_1 with the Amazon Resource Name (ARN) of your ElastiCache Valkey or Redis OSS cluster, and replace AWS_RESOURCE_ARN_2 with the ARN of your IAM user for ElastiCache.

Then, attach the IAM role to the Amazon Elastic Compute Cloud (Amazon EC2) instance or AWS Lambda function that connects to the ElastiCache cluster. For more information, see Authenticating with IAM.

Note: If your IAM policy is correct but you still receive the AuthenticationError error, then check the other policy types in your organization for restrictions. For more information, see Other policy types in Managing access using policies.

Check network connectivity

Verify the network connectivity between your ElastiCache cluster and the client resource.

Generate an authentication token

If you use an IAM authentication to connect to your ElastiCache clusters, then use an authentication token instead of a password. The IAM authentication token is valid for 15 minutes.

For long-lived connections, it's a best practice to use a Valkey or Redis OSS client that supports a credentials provider interface. To extend a connection by 12 hours, send an AUTH or HELLO with a new token.

To generate an IAM authentication token and connect to your ElastiCache cluster, complete the following steps:

1. Set up the Amazon EC2 instance to run the demo application. For instructions, see Elasticache IAM authentication demo application on the GitHub website.

2. To generate the token when you use the demo app, run the following Java CLI command:

   java -cp target/ElastiCacheIAMAuthDemoApp-1.0-SNAPSHOT.jar \
   com.amazon.elasticache.IAMAuthTokenGeneratorApp --region REGION --replication-group-id REPLICATION-GROUP-ID --user-id USER-ID

   Note: Replace REGION with your AWS Region, REPLICATION-GROUP-ID with your ElastiCache replication group ID, and USER-ID with your IAM user ID for ElastiCache.

3. Use the token as the password to connect to the ElastiCache cluster. You can use the Valkey or Redis CLI or its client API libraries to connect to your ElastiCache cluster.
   Example Valkey CLI command:

   valkey-cli -h PRIMARY-ENDPOINT -p 6379 --tls -c --user USER ID -a TEMPORARY-SECURITY-CREDENTIAL

   Example Redis CLI command:

   redis6-cli -h PRIMARY-ENDPOINT -p 6379 --tls -c --user USER-ID -a TEMPORARY-SECURITY-CREDENTIAL

   Note: Replace PRIMARY-ENDPOINT with the primary endpoint of your ElastiCache cluster, USER-ID with your IAM user ID, and TEMPORARY-SECURITY-CREDENTIAL with your IAM authentication token.

   Important: When you use valkey-cli or redis-cli commands, you must include both the --tls and -a arguments. If you don't provide these arguments or you enter incorrect credentials, then you receive a NOAUTH or AUTH failed error message. If you use valkey-cli or redis-cli commands with only the --tls argument, then use AUTH user-id temporary-security-credential after you connect to complete the authentication.

   Example Lettuce Redis OSS client:

   RedisURI redisURI = RedisURI.builder()
               .withHost(CACHE-NAME)
               .withPort(6379)
               .withSsl(true)
               .withAuthentication(USER-ID, TEMPORARY-SECURITY-CREDENTIAL)
               .build();
   return RedisClient.create(redisURI);

Review components in your Redis OSS or Valkey client configuration

Verify the following configurations in your Redis OSS or Valkey client:

• Your Valkey or Redis OSS client has the correct ElastiCache cluster endpoint and port.
• Your Valkey or Redis OSS client has SSL/TLS support.
• Your username is an enabled IAM user for ElastiCache.
• You have the latest version of the Valkey or Redis OSS client that matches your ElastiCache cluster's configuration, engine type, and version parameters. Outdated or incompatible client versions cause authentication errors.
• You have configured client timeout parameters to match your requirements. Incorrect timeout settings might prematurely terminate connections and cause authentication errors.

Check Amazon CloudWatch metrics

Use Amazon CloudWatch metrics to monitor the health and activity of your ElastiCache cluster. To identify authentication issues, it's a best practice to monitor the following metrics:

• Check your Connections metrics, such as CurrConnections and NewConnections. A decrease in new connections means that authentication errors caused the failed connection attempt. ElastiCache uses 2 to 6 connections to monitor the cluster in each case. For more information, see Metrics for Valkey and Redis OSS.
• Check IamAuthenticationExpirations to monitor expired IAM authentication tokens that might result in a failed connection.
• Review IamAuthenticationThrottling to see the number of authentication attempts with IAM credentials that ElastiCache throttled.

Related information

Simplify managing access to Amazon ElastiCache for Redis clusters with IAM

ElastiCache IAM authentication demo Application on the GitHub website

How to Connect to Redis With the ElastiCache IAM Credential Provider on the Redisson website