Connect to a cache with a public endpoint

All public endpoint connections require IAM authentication and TLS 1.3. There are three ways to generate the IAM authentication token:

IAM policy for connecting

Before you connect, your IAM user or role needs permission to call elasticache:Connect. The AWS managed policy AdministratorAccess includes this permission for all resources.

Create an IAM policy that allows the elasticache:Connect action on the ElastiCache cache and ElastiCache user:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "elasticache:Connect",
            "Resource": [
                "arn:aws:elasticache:us-east-1:123456789012:serverlesscache:my-public-cache",
                "arn:aws:elasticache:us-east-1:123456789012:user:default.iam-user"
            ]
        }
    ]
}

Option 1: GLIDE client with built-in IAM

GLIDE 2.2 and later include built-in IAM authentication support. You configure your AWS credentials, and GLIDE handles token generation, caching, and refresh automatically. For installation instructions, see the GLIDE documentation on the GLIDE website.

Python

from glide import (
    GlideClusterClient, GlideClusterClientConfiguration, NodeAddress,
    ServerCredentials, IamAuthConfig, ServiceType,
)

config = GlideClusterClientConfiguration(
    addresses=[NodeAddress("my-public-cache-x2e9hv.public.serverless.use1.cache.amazonaws.com", 6379)],
    credentials=ServerCredentials(
        username="default.iam-user",
        iam_config=IamAuthConfig(
            cluster_name="my-public-cache",
            service=ServiceType.ELASTICACHE,
            region="us-east-1",
        ),
    ),
    use_tls=True,
)

client = await GlideClusterClient.create(config)
await client.set("key", "value")
result = await client.get("key")
print(result)  # b"value"

Java

import glide.api.GlideClusterClient;
import glide.api.models.configuration.IamAuthConfig;
import glide.api.models.configuration.ServiceType;
import glide.api.models.configuration.ServerCredentials;
import glide.api.models.configuration.GlideClusterClientConfiguration;
import glide.api.models.configuration.NodeAddress;

import java.util.List;
import java.util.Collections;

List<NodeAddress> nodes = Collections.singletonList(
    NodeAddress.builder()
        .host("my-public-cache-x2e9hv.public.serverless.use1.cache.amazonaws.com")
        .port(6379)
        .build()
);

IamAuthConfig iamConfig = IamAuthConfig.builder()
    .clusterName("my-public-cache")
    .service(ServiceType.ELASTICACHE)
    .region("us-east-1")
    .build();

GlideClusterClientConfiguration config = GlideClusterClientConfiguration.builder()
    .addresses(nodes)
    .credentials(ServerCredentials.builder()
        .username("default.iam-user")
        .iamConfig(iamConfig)
        .build())
    .useTLS(true)
    .build();

GlideClusterClient client = GlideClusterClient.createClient(config).get();
client.set("key", "value").get();
String result = client.get("key").get();
System.out.println(result);  // "value"

Option 2: Developer Toolkit for ElastiCache

The Developer Toolkit for ElastiCache (developer-toolkit-elasticache) is a standalone Python library and CLI that generates IAM authentication tokens. Use it with a Python Valkey or Redis OSS client library, such as valkey-py.

Install

pip install developer-toolkit-elasticache

Python with valkey-py

import valkey
from valkey.credentials import CredentialProvider

from developer_toolkit_elasticache import ElastiCacheIAMAuthTokenProvider

class ElastiCacheCredentialProvider(CredentialProvider):
    def __init__(self, auth):
        self._auth = auth

    def get_credentials(self):
        return self._auth.user_id, self._auth.get_token()

auth = ElastiCacheIAMAuthTokenProvider(
    serverless_cache_name="my-public-cache",
    user_id="default.iam-user",
    region="us-east-1",
)

client = valkey.ValkeyCluster(
    host="my-public-cache-x2e9hv.public.serverless.use1.cache.amazonaws.com",
    port=6379,
    ssl=True,
    credential_provider=ElastiCacheCredentialProvider(auth),
)

client.set("key", "value")
result = client.get("key")
print(result)  # b"value"

The Developer Toolkit does not automatically refresh tokens. IAM authentication tokens are valid for 15 minutes, so your application must generate a new token before the current token expires. The credentials provider in the preceding example calls get_token() for each new connection.

CLI with the Developer Toolkit

To connect with valkey-cli or redis-cli, use the Developer Toolkit CLI to generate a token:

export VALKEYCLI_AUTH=$(developer-toolkit-elasticache generate_iam_auth_token \
    --serverless-cache-name my-public-cache \
    --user-id default.iam-user \
    --region us-east-1)

valkey-cli -c -h my-public-cache-x2e9hv.public.serverless.use1.cache.amazonaws.com \
    -p 6379 \
    --tls \
    --user default.iam-user

VALKEYCLI_AUTH requires valkey-cli 9.0 or later. For redis-cli, use REDISCLI_AUTH instead of VALKEYCLI_AUTH.

For source code and additional examples, see the Developer Toolkit for ElastiCache repository on GitHub.

Option 3: Manual SigV4 signing

Generate the IAM authentication token manually using the AWS SDK. For signing code examples, see Connect with token as password.

Token and session expiration

Troubleshooting

The following table lists common connection errors, their causes, and how to resolve them.