Authentication

By default, when connecting to Valkey, Valkey GLIDEs operates in an unauthenticated mode.

Valkey GLIDE also offers support for an authenticated connection mode.

In authenticated mode, you have the following options:

• Use both a username and password, which is recommended and configured through ACLs on the server.
• Use a password only, which is applicable if the server is configured with the requirepass setting.

To provide the necessary authentication credentials to the client, you can use the ServerCredentials class.

See the Dynamic Authentication section for a detailed explanation about using ACLs with GLIDE.

Example: Connecting with Username and Password to a Cluster

import {GlideClusterClient} from "@valkey/valkey-glide";

const addresses = [
    {
        host: "address.example.com",
        port: 6379
    }
];

const credentials = {
    username: "user1",
    password: "passwordA"
};

const client = await GlideClusterClient.createClient({
    addresses: addresses,
    credentials: credentials
});

Example: Connecting with Username and Password to a Standalone server

import {GlideClient} from "@valkey/valkey-glide";
const addresses = [
    {
        host: "address.example.com",
        port: 6379
    }
];

const credentials = {
    username: "user1",
    password: "passwordA"
};

const client = await GlideClient.createClient({
    addresses: addresses,
    credentials: credentials
});

Using IAM Authentication

Starting with GLIDE 2.2+ built-in support for AWS Identity and Access Management (IAM) authentication is available when connecting to Amazon ElastiCache and MemoryDB clusters. This feature automatically handles token generation and rotation, making it simple to maintain secure connections.

See the IAM Authentication with GLIDE section for a detailed explanation.

IAM Authentication with AWS SDK

This section shows how to utilize the AWS SDK for the IAM token generation. Please refer to the AWS SDK docs for a detailed explanation regarding generating the IAM token.

Token generation

import { SignatureV4 } from "@smithy/signature-v4";
import { HttpRequest } from "@smithy/protocol-http";
import { defaultProvider } from "@aws-sdk/credential-provider-node";
import { formatUrl } from "@aws-sdk/util-format-url";
import { Sha256 } from "@aws-crypto/sha256-js";


class ElastiCacheIAMProvider {
    private user: string;
    private clusterName: string;
    private region: string;

    constructor(user: string, clusterName: string, region: string = "us-east-1") {
        this.user = user;
        this.clusterName = clusterName;
        this.region = region;
    }

    async  getCredentials() {
        const credentials = await defaultProvider()();

        const signer = new SignatureV4({
            service: "elasticache",
            credentials,
            region: this.region,
            sha256: Sha256,
        });

        const url = new URL(`https://${this.clusterName}/`);
        url.searchParams.append("Action", "connect");
        url.searchParams.append("User", this.user);

        const request = new HttpRequest({
            protocol: url.protocol,
            hostname: url.hostname,
            method: "GET",
            path: url.pathname,
            query: Object.fromEntries(url.searchParams),
            headers: {
                host: url.hostname,
            },
        });

        const signedRequest = await signer.presign(request, { expiresIn: 900 });
        return formatUrl(signedRequest).replace(/^https?:\/\//, "");
    }
}

Usage Example

import { GlideClusterClient, GlideClusterClientConfiguration, ServerCredentials, AdvancedGlideClusterClientConfiguration } from "@valkey/valkey-glide";

async function main() {
    const username = "your-username";
    const cluster_name = "your-cluster-name";
    const endpoint = "example-cluster-endpoint.use1.cache.amazonaws.com";

    const addresses = [
        {
            host: endpoint,
            port: 6379,
        },
    ];

    const provider = new ElastiCacheIAMProvider(
        username,
        cluster_name,
        "us-east-1"
    );

    const iamAuthToken = await provider.getCredentials();

    const credentials: ServerCredentials = {
        username: username,
        password: iamAuthToken
    };

    const config: GlideClusterClientConfiguration = {
        addresses: addresses,
        credentials: credentials,
        useTLS: true,
        clientName: 'my-client',
    };

    const client = await GlideClusterClient.createClient(config);

    // Update password dynamically
    const newIAMAuthToken = await provider.getCredentials();
    await client.updateConnectionPassword(newIAMAuthToken);

    // To perform immediate re-authentication, set the second parameter to true
    await client.updateConnectionPassword(newIAMAuthToken, true);
}