Quickstart: Use Azure Cache for Redis with a Node.js app

Article
09/29/2024

In this quickstart, you incorporate Azure Cache for Redis into a Node.js app for access to a secure, dedicated cache that is accessible from any application in Azure.

Prerequisites

An Azure subscription. Create one
Node.js installed. For information about how to install Node and npm on a Windows computer, see Install Node.js on Windows.

Create a cache

To create a cache, sign in to the Azure portal and select Create a resource.
On the Get Started page, type Azure Cache for Redis in the search box. Then, select Create.

On the New Redis Cache page, configure the settings for your cache.

Setting	Choose a value	Description
Subscription	Drop down and select your subscription.	The subscription under which to create this new Azure Cache for Redis instance.
Resource group	Drop down and select a resource group, or select Create new and enter a new resource group name.	Name for the resource group in which to create your cache and other resources. By putting all your app resources in one resource group, you can easily manage or delete them together.
DNS name	Enter a unique name.	The cache name must be a string between 1 and 63 characters that contain only numbers, letters, or hyphens. The name must start and end with a number or letter, and can't contain consecutive hyphens. Your cache instance's host name is <DNS name>.redis.cache.chinacloudapi.cn.
Location	Drop down and select a location.	Select a region near other services that use your cache.
Cache SKU	Drop down and select a SKU.	The SKU determines the size, performance, and features parameters that are available for the cache. For more information, see Azure Cache for Redis Overview.
Cache size	Drop down and select a size of your cache	For more information, see Azure Cache for Redis Overview.

Select the Networking tab or select the Networking button at the bottom of the page.
In the Networking tab, select your connectivity method.
Select the Next: Advanced tab or select the Next: Advanced button on the bottom of the page to see the Advanced tab.
- For Basic or Standard caches, toggle the selection for a non-TLS port. You can also select if you want to enable Microsoft Entra Authentication.
- For a Premium cache, configure the settings for non-TLS port, clustering, managed identity, and data persistence. You can also select if you want to enable Microsoft Entra Authentication.
Select the Next: Tags tab or select the Next: Tags button at the bottom of the page.
Optionally, in the Tags tab, enter the name and value if you wish to categorize the resource.
Select Review + create. You're taken to the Review + create tab where Azure validates your configuration.
After the green Validation passed message appears, select Create.

It takes a while for a cache to create. You can monitor progress on the Azure Cache for Redis Overview page. When Status shows as Running, the cache is ready to use.

Install the node-redis client library

The node-redis library is the primary Node.js client for Redis. You can install the client by using npm and the following command:

npm install redis

Create a Node.js app to access a cache

Create a Node.js app that uses either Microsoft Entra ID or access keys to connect to Azure Cache for Redis. We recommend that you use Microsoft Entra ID.

Microsoft Entra ID authentication (recommended)
Access key authentication

Enable Microsoft Entra ID authentication on your cache

For an existing cache, first check to see if Microsoft Entra authentication is enabled. If it's not, complete the following steps to enable Microsoft Entra authentication. We recommend that you use Microsoft Entra ID for authentication in your applications.

In the Azure portal, select the Azure Cache for Redis instance where you'd like to use Microsoft Entra token-based authentication.
On the service menu, under Settings, select Authentication.
On the Authentication pane, check to see whether the Enable Microsoft Entra Authentication checkbox is selected. If it is, you can move on to the next section.
Otherwise, select the Enable Microsoft Entra Authentication checkbox. Then, enter the name of a valid user. Select Save. The user name that you enter is automatically assigned the Data Owner Access Policy.

You also can enter a managed identity or a service principal to connect to your cache.
In a dialog box, you're asked if you want to update your configuration, and you're informed that making the update takes several minutes to finish. Select Yes.

Important

When the enable operation is finished, the nodes in your cache reboot to load the new configuration. We recommend that you complete this operation during your standard maintenance window or outside your peak business hours. The process can take up to 30 minutes.

For information about using Microsoft Entra ID with the Azure CLI, see the identity reference pages.

Install the Azure Identity client library for JavaScript

The Azure Identity client library for JavaScript uses the required Microsoft Authentication Library (MSAL) to provide token authentication support. Install the library by using npm:

npm install @azure/identity

Create a Node.js app by using Microsoft Entra ID

Add environment variables for your host name and service principal ID.

The service principal ID is the object ID of your Microsoft Entra ID service principal or user. In the Azure portal, this value appears as Username.
```
set AZURE_CACHE_FOR_REDIS_HOST_NAME=contosoCache
set REDIS_SERVICE_PRINCIPAL_ID=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```
Create a script file named redistest.js.

Add the following example JavaScript to the file. This code shows you how to connect to an Azure Cache for Redis instance by using the cache host name and key environment variables. The code also stores and retrieves a string value in the cache. The PING and CLIENT LIST commands are also executed. For more examples of using Redis with the node-redis client, see Node-Redis.

const { createClient } = require("redis");
const { DefaultAzureCredential } = require("@azure/identity");

async function main() {
  // Construct a Token Credential from Identity library, e.g. ClientSecretCredential / ClientCertificateCredential / ManagedIdentityCredential, etc.
  const credential = new DefaultAzureCredential();
  const redisScope = "https://redis.azure.com/.default";

  // Fetch a Microsoft Entra token to be used for authentication. This token will be used as the password.
  let accessToken = await credential.getToken(redisScope);
  console.log("access Token", accessToken);

  // Create redis client and connect to the Azure Cache for Redis over the TLS port using the access token as password.
  const cacheConnection = createClient({
    username: process.env.REDIS_SERVICE_PRINCIPAL_ID,
    password: accessToken.token,
    url: `redis://${process.env.AZURE_CACHE_FOR_REDIS_HOST_NAME}:6380`,
    pingInterval: 100000,
    socket: { 
      tls: true,
      keepAlive: 0 
    },
  });

  cacheConnection.on("error", (err) => console.log("Redis Client Error", err));
  await cacheConnection.connect();

  // PING command
  console.log("\nCache command: PING");
  console.log("Cache response : " + await cacheConnection.ping());

  // SET
  console.log("\nCache command: SET Message");
  console.log("Cache response : " + await cacheConnection.set("Message",
      "Hello! The cache is working from Node.js!"));

  // GET
  console.log("\nCache command: GET Message");
  console.log("Cache response : " + await cacheConnection.get("Message"));

  // Client list, useful to see if connection list is growing...
  console.log("\nCache command: CLIENT LIST");
  console.log("Cache response : " + await cacheConnection.sendCommand(["CLIENT", "LIST"]));

  cacheConnection.disconnect();

  return "Done"
}

main().then((result) => console.log(result)).catch(ex => console.log(ex));

Run the script by using Node.js:
```
node redistest.js
```

Verify that the output of your code looks like this example:

Cache command: PING
Cache response : PONG

Cache command: GET Message
Cache response : Hello! The cache is working from Node.js!

Cache command: SET Message
Cache response : OK

Cache command: GET Message
Cache response : Hello! The cache is working from Node.js!

Cache command: CLIENT LIST
Cache response : id=10017364 addr=76.22.73.183:59380 fd=221 name= age=1 idle=0 flags=N db=0 sub=0 psub=0 multi=-1 qbuf=26 qbuf-free=32742 argv-mem=10 obl=0 oll=0 omem=0 tot-mem=61466 ow=0 owmem=0 events=r cmd=client user=default numops=6

Done

Create a sample JavaScript app that has reauthentication

Microsoft Entra ID access tokens have a limited lifespan of approximately 75 minutes. To maintain a connection to your cache, you must refresh the token.

This example demonstrates how to refresh the token by using JavaScript:

Create a script file named redistestreauth.js.

Add the following example JavaScript to the file:

 const { createClient } = require("redis");
 const { DefaultAzureCredential } = require("@azure/identity");

 async function returnPassword(credential) {
     const redisScope = "https://redis.azure.com/.default";

     // Fetch a Microsoft Entra token to be used for authentication. This token will be used as the password.
     return credential.getToken(redisScope);
 }

 async function main() {
   // Construct a Token Credential from Identity library, e.g. ClientSecretCredential / ClientCertificateCredential / ManagedIdentityCredential, etc.
   const credential = new DefaultAzureCredential();
   let accessToken = await returnPassword(credential);

   // Create redis client and connect to the Azure Cache for Redis over the TLS port using the access token as password.
   let cacheConnection = createClient({
     username: process.env.REDIS_SERVICE_PRINCIPAL_ID,
     password: accessToken.token,
     url: `redis://${process.env.AZURE_CACHE_FOR_REDIS_HOST_NAME}:6380`,
     pingInterval: 100000,
     socket: { 
       tls: true,
       keepAlive: 0 
     },
   });

   cacheConnection.on("error", (err) => console.log("Redis Client Error", err));
   await cacheConnection.connect();

   for (let i = 0; i < 3; i++) {
     try {
         // PING command
         console.log("\nCache command: PING");
         console.log("Cache response : " + await cacheConnection.ping());

         // SET
         console.log("\nCache command: SET Message");
         console.log("Cache response : " + await cacheConnection.set("Message",
             "Hello! The cache is working from Node.js!"));

         // GET
         console.log("\nCache command: GET Message");
         console.log("Cache response : " + await cacheConnection.get("Message"));

         // Client list, useful to see if connection list is growing...
         console.log("\nCache command: CLIENT LIST");
         console.log("Cache response : " + await cacheConnection.sendCommand(["CLIENT", "LIST"]));
       break;
     } catch (e) {
       console.log("error during redis get", e.toString());
       if ((accessToken.expiresOnTimestamp <= Date.now())|| (redis.status === "end" || "close") ) {
         await redis.disconnect();
         accessToken = await returnPassword(credential);
         cacheConnection = createClient({
           username: process.env.REDIS_SERVICE_PRINCIPAL_ID,
           password: accessToken.token,
           url: `redis://${process.env.AZURE_CACHE_FOR_REDIS_HOST_NAME}:6380`,
           pingInterval: 100000,
           socket: {
             tls: true,
             keepAlive: 0
           },
         });
       }
     }
   }
 }

 main().then((result) => console.log(result)).catch(ex => console.log(ex));

Run the script by using Node.js:
```
node redistestreauth.js
```

Check for output that looks similar to this example:

 Cache command: PING
 Cache response : PONG

 Cache command: GET Message
 Cache response : Hello! The cache is working from Node.js!

 Cache command: SET Message
 Cache response : OK

 Cache command: GET Message
 Cache response : Hello! The cache is working from Node.js!

 Cache command: CLIENT LIST
 Cache response : id=10017364 addr=76.22.73.183:59380 fd=221 name= age=1 idle=0 flags=N db=0 sub=0 psub=0 multi=-1 qbuf=26 qbuf-free=32742 argv-mem=10 obl=0 oll=0 omem=0 tot-mem=61466 ow=0 owmem=0 events=r cmd=client user=default numops=6

Note

For more examples of how to use Microsoft Entra ID to authenticate to Redis via the node-redis library, see the node-redis GitHub repository.

Get the host name, ports, and access key

To connect to your Azure Cache for Redis server, the cache client needs the cache's host name, ports, and an access key. Some clients might refer to these items by using slightly different names. You can get the host name, ports, and keys in the Azure portal.

To get an access key for your cache:
1. In the Azure portal, go to your cache.
2. On the service menu, under Settings, select Authentication.
3. On the Authentication pane, select the Access keys tab.
4. To copy the value for an access key, select the Copy icon in the key field.
To get the host name and ports for your cache:
1. In the Azure portal, go to your cache.
2. On the service menu, select Overview.
3. Under Essentials, for Host name, select the Copy icon to copy the host name value. The host name value has the form <DNS name>.redis.cache.chinacloudapi.cn.
4. For Ports, select the Copy icon to copy the port values.

Add environment variables for your host name and primary access key. Use these variables from your code instead of including the sensitive information directly in your code.

set AZURE_CACHE_FOR_REDIS_HOST_NAME=contosoCache
set AZURE_CACHE_FOR_REDIS_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Connect to the cache

Note

Don't create a new connection for each operation in your code. Instead, reuse connections as much as possible.

Create a new Node.js app

Create a new script file named redistest.js.

Add the following example JavaScript to the file:

const redis = require("redis");

// Environment variables for cache
const cacheHostName = process.env.AZURE_CACHE_FOR_REDIS_HOST_NAME;
const cachePassword = process.env.AZURE_CACHE_FOR_REDIS_ACCESS_KEY;

if(!cacheHostName) throw Error("AZURE_CACHE_FOR_REDIS_HOST_NAME is empty")
if(!cachePassword) throw Error("AZURE_CACHE_FOR_REDIS_ACCESS_KEY is empty")

async function testCache() {

    // Connection configuration
    const cacheConnection = redis.createClient({
        // redis for TLS
        url: `redis://${cacheHostName}:6380`,
        password: cachePassword
    });

    // Connect to Redis
    await cacheConnection.connect();

    // PING command
    console.log("\nCache command: PING");
    console.log("Cache response : " + await cacheConnection.ping());

    // GET
    console.log("\nCache command: GET Message");
    console.log("Cache response : " + await cacheConnection.get("Message"));

    // SET
    console.log("\nCache command: SET Message");
    console.log("Cache response : " + await cacheConnection.set("Message",
        "Hello! The cache is working from Node.js!"));

    // GET again
    console.log("\nCache command: GET Message");
    console.log("Cache response : " + await cacheConnection.get("Message"));

    // Client list, useful to see if connection list is growing...
    console.log("\nCache command: CLIENT LIST");
    console.log("Cache response : " + await cacheConnection.sendCommand(["CLIENT", "LIST"]));

    // Disconnect
    cacheConnection.disconnect()

    return "Done"
}

testCache().then((result) => console.log(result)).catch(ex => console.log(ex));

This code shows you how to connect to an Azure Cache for Redis instance by using the cache host name and key environment variables. The code also stores and retrieves a string value in the cache. The PING and CLIENT LIST commands are also executed. For more examples of using Redis with the node_redis client, see Node-Redis.

Run the script by using Node.js:
```
node redistest.js
```

Verify that the output looks similar to this example:

Cache command: PING
Cache response : PONG

Cache command: GET Message
Cache response : Hello! The cache is working from Node.js!

Cache command: SET Message
Cache response : OK

Cache command: GET Message
Cache response : Hello! The cache is working from Node.js!

Cache command: CLIENT LIST
Cache response : id=10017364 addr=76.22.73.183:59380 fd=221 name= age=1 idle=0 flags=N db=0 sub=0 psub=0 multi=-1 qbuf=26 qbuf-free=32742 argv-mem=10 obl=0 oll=0 omem=0 tot-mem=61466 ow=0 owmem=0 events=r cmd=client user=default numops=6

Done

Clean up resources

If you want to continue to use the resources you created in this article, keep the resource group.

Otherwise, to avoid charges related to the resources, if you're finished using the resources, you can delete the Azure resource group that you created.

Warning

Deleting a resource group is irreversible. When you delete a resource group, all the resources in the resource group are permanently deleted. Make sure that you do not accidentally delete the wrong resource group or resources. If you created the resources inside an existing resource group that has resources you want to keep, you can delete each resource individually instead of deleting the resource group.

Delete a resource group

Sign in to the Azure portal, and then select Resource groups.
Select the resource group to delete.

If there are many resource groups, in Filter for any field, enter the name of the resource group you created to complete this article. In the list of search results, select the resource group.
Select Delete resource group.
In the Delete a resource group pane, enter the name of your resource group to confirm, and then select Delete.