Configure AWS IAM Authentication
GLIDE 2.2+ provides built-in support for AWS Identity and Access Management (IAM) authentication when connecting to Amazon ElastiCache and MemoryDB clusters. This feature automatically handles token generation and rotation, making it simple to maintain secure connections.
How It Works
Section titled “How It Works”- GLIDE automatically generates temporary authentication tokens that are valid for 15 minutes
- GLIDE refreshes the token every 5 minutes (default). On failure, it retries with exponential backoff and keeps using the last valid token until a new one is obtained
- When a new token is available, GLIDE updates its cached credentials. New and reconnecting connections use the fresh token, while pooled and isolated connections reconcile token changes before an eligible command
- During reconnection, GLIDE checks whether the cached token has expired (age ≥ 15 minutes). If so, it generates a fresh token before attempting to reconnect, ensuring a valid credential is used even when connections have been idle
- GLIDE handles re-authentication automatically when required, for example when ElastiCache or MemoryDB terminates a session after its maximum lifetime
- GLIDE handles all token management, refresh operations, and re-authentication behind the scenes
- On-demand token refresh is available via
refreshIamToken(see On-Demand Refresh below)
Required Setup
Section titled “Required Setup”-
AWS Credentials: Unless you configure a custom AWS credential provider, your application must run in an environment where the default AWS credential chain can find credentials, such as an EC2 instance with an IAM role or an ECS task with a task role.
-
TLS: IAM authentication requires TLS. GLIDE rejects an IAM client configuration when TLS is disabled.
-
Required Information:
- username: Your ElastiCache/MemoryDB username
- cluster_name: Your cluster’s name
- service: Either ElastiCache or MemoryDB
- region: The AWS region where your cluster runs
- refresh_interval_seconds (Optional): How often to refresh the token. Default is 300 seconds (5 minutes)
The cluster name and region must not be blank, and the username must not be empty.
Examples
Section titled “Examples” import java.util.Collections; import java.util.List;
import glide.api.GlideClusterClient; import glide.api.models.configuration.GlideClusterClientConfiguration; import glide.api.models.configuration.IamAuthConfig; import glide.api.models.configuration.NodeAddress; import glide.api.models.configuration.ServerCredentials; import glide.api.models.configuration.ServiceType; ...
List<NodeAddress> nodeList = Collections.singletonList( NodeAddress.builder().host("endpoint.example.com").port(6379).build());
// Configure IAM authentication // Automatically regenerates the token every 5 mins (default: 300 seconds) IamAuthConfig iamConfig = IamAuthConfig.builder() .clusterName("clustername") .service(ServiceType.ELASTICACHE) // or ServiceType.MEMORYDB .region("us-east-1") // .refreshIntervalSeconds(100) // Optional, default is 300 seconds .build();
GlideClusterClientConfiguration config = GlideClusterClientConfiguration.builder() .addresses(nodeList) .useTLS(true) .credentials( ServerCredentials.builder() .username("username") .iamConfig(iamConfig) .build()) .build();
GlideClusterClient client = GlideClusterClient.createClient(config).get();...from glide import ( GlideClusterClient, GlideClusterClientConfiguration, IamAuthConfig, NodeAddress, ServerCredentials, ServiceType,)...addresses = [NodeAddress("endpoint.example.com", 6379)]
# Configure IAM authentication# Automatically regenerates the token every 5 mins (default: 300 seconds)iam_config = IamAuthConfig( cluster_name="clustername", service=ServiceType.ELASTICACHE, # or ServiceType.MEMORYDB region="us-east-1", # refresh_interval_seconds=100, # Optional, default is 300 seconds)
credentials = ServerCredentials(username="username", iam_config=iam_config)
config = GlideClusterClientConfiguration( addresses=addresses, use_tls=True, credentials=credentials,)# For async modeclient = await GlideClusterClient.create(config)
# For sync modefrom glide_sync import GlideClusterClient as SyncGlideClusterClientsync_client = SyncGlideClusterClient.create(config)...import { GlideClusterClient, ServiceType } from "@valkey/valkey-glide";
// Automatically regenerates the token every 5 minsconst client = await GlideClusterClient.createClient({ addresses: [{ host: "endpoint.example.com", port: 6379 }], useTLS: true, credentials: { username: "username", iamConfig: { clusterName: "clustername", service: ServiceType.Elasticache, // or ServiceType.MemoryDB region: "us-east-1", // refreshIntervalSeconds: 100, // Optional, default is 300 seconds } }});package main
import ( "log"
glide "github.com/valkey-io/valkey-glide/go/v2" "github.com/valkey-io/valkey-glide/go/v2/config")
func main() { iamConfig := config.NewIamAuthConfig("clustername", config.ElastiCache, "us-east-1") credentials, err := config.NewServerCredentialsWithIam("username", iamConfig) if err != nil { log.Fatal(err) }
clientConfig := config.NewClusterClientConfiguration(). WithAddress(&config.NodeAddress{Host: "endpoint.example.com", Port: 6379}). WithUseTLS(true). WithCredentials(credentials)
client, err := glide.NewClusterClient(clientConfig) if err != nil { log.Fatal(err) } defer client.Close()}// Create ValkeyGlide client with IAM authentication// Automatically regenerates the token every 5 mins (default: 300 seconds)$client = new ValkeyGlide();$client->connect( addresses: [['host' => 'endpoint.example.com', 'port' => 6379]], use_tls: true, // REQUIRED for IAM authentication credentials: [ 'username' => 'username', // REQUIRED for IAM 'iamConfig' => [ ValkeyGlide::IAM_CONFIG_CLUSTER_NAME => 'clustername', ValkeyGlide::IAM_CONFIG_REGION => 'us-east-1', ValkeyGlide::IAM_CONFIG_SERVICE => ValkeyGlide::IAM_SERVICE_ELASTICACHE, // ValkeyGlide::IAM_CONFIG_REFRESH_INTERVAL => 100, // Optional, default is 300 seconds ] ]);
// Use the client normally - IAM tokens are managed automatically$client->set('key', 'value');$value = $client->get('key');
$client->close();...using Valkey.Glide;using static Valkey.Glide.ConnectionConfiguration;
// Configure IAM authentication// Automatically regenerates the token every 5 mins (default: 300 seconds)var iamConfig = new IamAuthConfig( clusterName: "clustername", serviceType: ServiceType.ElastiCache, // or ServiceType.MemoryDB region: "us-east-1" // refreshIntervalSeconds: 100 // Optional, default is 300 seconds);
var credentials = new ServerCredentials("username", iamConfig);
var config = new ClusterClientConfigurationBuilder() .WithAddress("endpoint.example.com", 6379) .WithTls() .WithCredentials(credentials) .Build();
await using var client = await GlideClusterClient.CreateClient(config);require "valkey"
# Configure IAM authentication# Automatically regenerates the token every 5 mins (default: 300 seconds)iam_config = Valkey::IamAuthConfig.new( cluster_name: "clustername", service: Valkey::ServiceType::ELASTICACHE, # or Valkey::ServiceType::MEMORYDB region: "us-east-1" # refresh_interval_seconds: 100, # Optional, default is 300 seconds)
client = Valkey.new( nodes: [{ host: "endpoint.example.com", port: 6379 }], cluster_mode: true, ssl: true, # REQUIRED for IAM authentication username: "username", # REQUIRED for IAM iam_config: iam_config # cannot be combined with password)
# Use the client normally - IAM tokens are managed automaticallyclient.set("key", "value")value = client.get("key")
client.closeCustom AWS credential providers
Section titled “Custom AWS credential providers”Python, Java, Node.js, and Go direct clients can obtain AWS credentials from an application callback instead of the default AWS credential chain. Use this for credential stores or custom assume-role flows that the default chain cannot resolve.
The provider must return a non-blank access key ID and secret access key. A session token and expiration time are optional. GLIDE can invoke the provider during client creation, token refresh, or reconnection, so it must return current credentials and tolerate repeated calls.
import java.util.concurrent.CompletableFuture;
import glide.api.models.configuration.AwsCredentials;import glide.api.models.configuration.IamAuthConfig;import glide.api.models.configuration.ServiceType;
IamAuthConfig iamConfig = IamAuthConfig.builder() .clusterName("clustername") .service(ServiceType.ELASTICACHE) .region("us-east-1") .credentialsProvider( () -> CompletableFuture.completedFuture( AwsCredentials.builder() .accessKeyId("access-key-id") .secretAccessKey("secret-access-key") .build())) .build();from glide import AwsCredentials, IamAuthConfig, ServiceType
iam_config = IamAuthConfig( "clustername", ServiceType.ELASTICACHE, "us-east-1", credential_provider=lambda: AwsCredentials("access-key-id", "secret-access-key"),)import { IamAuthConfig, ServiceType } from "@valkey/valkey-glide";
const iamConfig: IamAuthConfig = { clusterName: "clustername", service: ServiceType.Elasticache, region: "us-east-1", credentialProvider: () => ({ accessKeyId: "access-key-id", secretAccessKey: "secret-access-key", }),};package example
import "github.com/valkey-io/valkey-glide/go/v2/config"
func customIAMConfig() *config.IamAuthConfig { return config.NewIamAuthConfig( "clustername", config.ElastiCache, "us-east-1", ).WithCredentialProvider(func() (config.AwsCredentials, error) { return config.AwsCredentials{ AccessKeyID: "access-key-id", SecretAccessKey: "secret-access-key", }, nil })}On-Demand Refresh
Section titled “On-Demand Refresh”You can call refreshIamToken (or language equivalent) at any time to immediately request a fresh token from AWS and update the internal token cache.
// Pre-warm the token cache before a maintenance windowclient.refreshIamToken().get();# Pre-warm the token cache before a maintenance windowawait client.refresh_iam_token()// Pre-warm the token cache before a maintenance windowawait client.refreshIamToken();package example
import ( "context"
glide "github.com/valkey-io/valkey-glide/go/v2")
func refreshIAM(client *glide.ClusterClient) error { _, err := client.RefreshIamToken(context.Background()) return err}// Pre-warm the token cache before a maintenance window$client->refreshIamToken();// Pre-warm the token cache before a maintenance windowawait client.RefreshIamTokenAsync();# Pre-warm the token cache before a maintenance windowclient.refresh_iam_token