Connect to Azure Managed Redis

Learn how to authenticate to an Azure Managed Redis (AMR) database

The redis-authx-entraid package lets you authenticate your app to Azure Managed Redis (AMR) using Microsoft Entra ID. You can authenticate using a system-assigned or user-assigned managed identity or a service principal, letting redis-authx-entraid fetch and renew the authentication tokens for you automatically.

See Use Microsoft Entra for cache authentication in the Microsoft docs to learn how to configure Azure to use Entra ID authentication.

Install

Install jedis first, if you have not already done so.

If you are using Maven, add the following dependency to your pom.xml file:

<dependency>
    <groupId>redis.clients.authentication</groupId>
    <artifactId>redis-authx-entraid</artifactId>
    <version>0.1.1-beta1</version>
</dependency>

If you are using Gradle, add the following dependency to your build.gradle file:

implementation 'redis.clients.authentication:redis-authx-entraid:0.1.1-beta1'

Create a TokenAuthConfig instance

The TokenAuthConfig class contains the authentication details that you must supply when you connect to Redis. Chain the methods of the EntraIDTokenAuthConfigBuilder class together (starting with the builder() method) to include the details you need, as shown in the following example:

TokenAuthConfig authConfig = EntraIDTokenAuthConfigBuilder.builder()
        .secret("<secret>")
        .authority("<authority>")
        // Other options...
        .build();

Some of the details you can supply are common to different use cases:

(See Advanced configuration options below to learn more about the options for controlling token request retry and timeout behavior.)

You can also add configuration to authenticate with a service principal or a managed identity as described in the sections below.

Configuration for a service principal

Add clientId() to the EntraIDTokenAuthConfigBuilder chain to specify authentication via a service principal, passing the ID token string as a parameter. (See the Microsoft EntraID docs for more information about service principals.)

TokenAuthConfig authConfig = EntraIDTokenAuthConfigBuilder.builder()
        .clientId("<CLIENT-ID>")
         // ...
        .build();

Configuration for a managed identity

You can also authenticate to AMR using a managed identity (see the Microsoft documentation to learn more about managed identities).

For a system assigned managed identity, simply add the systemAssignedManagedIdentity() method to the EntraIDTokenAuthConfigBuilder chain:

TokenAuthConfig authConfig = EntraIDTokenAuthConfigBuilder.builder()
        .systemAssignedManagedIdentity()
         // ...
        .build();

For a user assigned managed identity, add userAssignedManagedIdentity(). This requires a member of the UserManagedIdentityType enum (to select a CLIENT_ID, OBJECT_ID, or RESOURCE_ID) as well as the id string itself:

TokenAuthConfig authConfig = EntraIDTokenAuthConfigBuilder.builder()
        .userAssignedManagedIdentity(
            UserManagedIdentityType.CLIENT_ID,
            "<ID>"
        )
         // ...
        .build();

Connect using DefaultJedisClientConfig

When you have created your TokenAuthConfig instance, you are ready to connect to AMR. The example below shows how to include the TokenAuthConfig details in a JedisClientConfig instance and use it with the UnifiedJedis connection. The connection uses Transport Layer Security (TLS), which is recommended and enabled by default for managed identities. See Connect to your production Redis with TLS for more information about TLS connections, including the implementation of the createSslSocketFactory() method used in the example.

TokenAuthConfig authConfig = EntraIDTokenAuthConfigBuilder.builder()
        // Chain of options...
        .build();

SSLSocketFactory sslFactory = createSslSocketFactory(
        "./truststore.jks",
        "secret!", // Use the password you specified for `keytool`
        "./redis-user-keystore.p12",
        "secret!" // Use the password you specified for `openssl`
);

JedisClientConfig config = DefaultJedisClientConfig.builder()
        // Include the `TokenAuthConfig` details.
        .authXManager(new AuthXManager(authConfig))
        .ssl(true).sslSocketFactory(sslFactory)
        .build();

UnifiedJedis jedis = new UnifiedJedis(
    new HostAndPort("<host>", <port>),
    config
);

// Test the connection.
System.out.println(String.format("Database size is %d", jedis.dbSize()));

Advanced configuration options

The TokenAuthConfig class has several other options that you can set with the EntraIDTokenAuthConfigBuilder.builder(). These give you more precise control over the way the token is renewed:

TokenAuthConfig authConfig = EntraIDTokenAuthConfigBuilder.builder()
        .expirationRefreshRatio(0.75)
        .lowerRefreshBoundMillis(100)
        .tokenRequestExecTimeoutInMs(100)
        .maxAttemptsToRetry(10)
        .delayInMsToRetry()
         // ...
        .build();

These options are explained below:

  • expirationRefreshRatio: a float value representing the fraction of a token's lifetime that should elapse before attempting to refresh it. For example, a value of 0.75 means that you want to refresh the token after 75% of its lifetime has passed.
  • lowerRefreshBoundMillis: the minimum amount of the token's lifetime (in milliseconds) remaining before attempting to refresh, regardless of the expirationRefreshRatio value. Set this to zero if you want the refresh time to depend only on expirationRefreshRatio.
  • tokenRequestExecTimeoutInMs: the maximum time (in milliseconds) to wait for a token request to receive a response. A timeout occurs if this limit is exceeded.
  • maxAttemptsToRetry: the maximum number of times to retry a token request before aborting.
  • delayInMsToRetry: the time (in milliseconds) to wait before retrying a token request after a failed attempt. This provides a mechanism to request throttling to prevent an excessive number of token requests.
RATE THIS PAGE
Back to top ↑