ArtifactType	nupkg
Documentation	https://learn.microsoft.com/azure/azure-cache-for-redis
Language	C#
Tags	Redis,Cache,StackExchange.Redis,Microsoft,Azure

Microsoft.Azure.StackExchangeRedis Extension

The Microsoft.Azure.StackExchangeRedis package is an extension for the StackExchange.Redis client library that enables using Microsoft Entra ID to authenticate connections from a Redis client application to an Azure Cache for Redis resource. This extension acquires an access token for an Azure managed identity, service principal, or user and configures a StackExchange.Redis connection to use the token for authentication. Before the token expires, it acquires a fresh token and re-authenticates the connection to maintain uninterrupted communication with the cache indefinitely.

Subscription connections

With the default RESP2 protocol, StackExchange.Redis actually creates two connections behind the scenes: an "interactive" connection for normal Redis commands (GET, SET, etc.), plus a "subscription" connection for pub/sub messages. The interactive connection is the one that's proactively re-authenticated with fresh tokens, while the subscription connection cannot be re-authenticated. When using RESP2 you will see subscription connections being closed by the Redis server when their token expires, and then immediately restored by StackExchange.Redis using a current token. To avoid these interruptions, we recommend using the RESP3 protocol which bundles all traffic (interactive and pub/sub) on a single connection to Redis, which will be proactively re-authenticated. Opt in to RESP3 by specifying protocol=resp3 in the connection string, or by setting configurationOptions.Protocol = RedisProtocol.Resp3 as shown in sample/Sample.cs. If RESP2 is used, it's expected to see "MicrosoftEntraTokenExpired" in Redis error metrics due to the subscription connections.

Usage

See sample/Sample.cs for detailed examples of how to use the extension for all supported authentication scenarios.

High level instructions:

1. Add a reference to the Microsoft.Azure.StackExchangeRedis NuGet package in your Redis client project.

2. In your Redis connection code, first create a ConfigurationOptions instance. You can use the .Parse() method to create an instance from a Redis connection string or the cache host name alone.

var configurationOptions = ConfigurationOptions.Parse($"{cacheHostName}:6380");

3. Use one of the ConfigureForAzure* extension methods supplied by this package to configure the authentication options:

// DefaultAzureCredential
await configurationOptions.ConfigureForAzureWithTokenCredentialAsync(new DefaultAzureCredential());

// User-assigned managed identity
await configurationOptions.ConfigureForAzureWithUserAssignedManagedIdentityAsync(managedIdentityClientId);

// System-assigned managed identity
await configurationOptions.ConfigureForAzureWithSystemAssignedManagedIdentityAsync();

// Service principal secret
await configurationOptions.ConfigureForAzureWithServicePrincipalAsync(clientId, tenantId, secret);

// Service principal certificate
await configurationOptions.ConfigureForAzureWithServicePrincipalAsync(clientId, tenantId, certificate);

// Service principal certificate with Subject Name + Issuer (SNI) authentication (Microsoft internal use only)
await configurationOptions.ConfigureForAzureAsync(new AzureCacheOptions
{
    ClientId = clientId,
    ServicePrincipalTenantId = tenantId,
    ServicePrincipalCertificate = certificate,
    SendX5C = true // Enables Subject Name + Issuer authentication
});

4. Create the connection, passing in the ConfigurationOptions instance

var connectionMultiplexer = await ConnectionMultiplexer.ConnectAsync(configurationOptions);

5. Use the connectionMultiplexer to interact with Redis as you normally would.

Running the sample

The sample directory contains a project showing how to connect to an Azure Redis cache using the various authentication mechanisms supported by this extension. Borrow code from this sample for your own project, or simply run it to test the authentication configuration on your cache. It will prompt you for the type of authentication to use and then the necessary credentials. To run the sample:

1. Create an Azure Cache for Redis resource
2. Configure AAD authentication on your cache using the instructions in Use Microsoft Entra ID for cache authentication
   • Optional: if you're using DefaultAzureCredential authentication, ensure that either an Azure user is signed on the machine where you're running your code, or environment variables have been set to supply Azure credentials. For details see: How to authenticate .NET apps to Azure services using the .NET Azure SDK.
3. dotnet run <path to Microsoft.Azure.StackExchangeRedis.Sample.csproj>, or run the project in Visual Studio or your favorite IDE
4. Follow the prompts to enter your credentials and test the connection to the cache
5. To see how the connection is maintained by periodically re-authenticating with fresh tokens, let the sample run for longer than a token lifespan (1+ hours).

NOTE: The sample project uses a <ProjectReference> to the extension project in this repo. To run the project on its own using the released Microsoft.Azure.StackExchangeRedis NuGet package, replace the <ProjectReference> in Microsoft.Azure.StackExchangeRedis.Sample.csproj with a <PackageReference>.

ASP.NET samples

The ASP.NET_Samples directory contains multiple samples demonstrating how to use this extension with ASP.NET applications:

ASP.NET Core samples

• Direct - Shows how to use the asynchronous ConfigureForAzure*() methods to create a Redis connection in a dependency injection scenario. This sample wraps the Redis connection in a singleton Redis.cs service that's injected into components that need to use a StackExchange.Redis connection directly (e.g. SampleController.cs). During startup, code in Program.cs resolves the Redis service singleton and awaits the async call to initialize it and create the Redis connection.
• OutputCache - Demonstrates ASP.NET Core output caching backed by Azure Redis.
• SessionState - Demonstrates ASP.NET Core session state backed by Redis distributed caching.

ASP.NET Framework sample

• ASP.NET_Framework/SessionState - Demonstrates custom session state caching using Azure Redis Cache in ASP.NET Framework 4.8, featuring distributed locking, JSON serialization, and complete session lifecycle management. This sample does not rely upon the deprecated Microsoft.Web.RedisSessionStateProvider

Contributing

Please read our CONTRIBUTING.md which outlines all of our policies, procedures, and requirements for contributing to this project.

Versioning

We use SemVer for versioning. For the versions available, see the releases.

License

This project is licensed under the MIT License - see the LICENSE file for details.