amr.md

categories	description	linkTitle	title	weight
docs develop stack oss rs rc oss kubernetes clients	Learn how to authenticate to an Azure Managed Redis (AMR) database	Connect to AMR	Connect to Azure Managed Redis	2

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.

Install

Install [lettuce]({{< relref "/develop/clients/lettuce" >}}) 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:

• secret(): A string containing the authentication secret.
• authority(): A string containing the authority URL.
• scopes(): A set of strings defining the scopes you want to apply.

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 {#serv-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 {#mgd-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 the withAuthentication() option

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 TokenBasedRedisCredentialsProvider instance and pass it to the RedisURI.Builder using the withAuthentication() option.

{{< note >}} Azure requires you to use Transport Layer Security (TLS) when you connect, as shown in the example. {{< /note >}}

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

TokenBasedRedisCredentialsProvider credentialsProvider =
        TokenBasedRedisCredentialsProvider.create(tokenAuthConfig);

RedisURI uri = RedisURI.Builder.redis("<host>", <port>)
        .withAuthentication(credentialsProvider)
        .withSsl(true)
        .build();

RedisClient client = RedisClient.create(uri);

SslOptions sslOptions = SslOptions.builder().jdkSslProvider()
        .truststore(new File(
            "<path_to_truststore.jks_file>"),
            "<password_for_truststore.jks_file>"
        )
        .build();

client.setOptions(ClientOptions.builder()
        .sslOptions(sslOptions)
        .build());

StatefulRedisConnection<String, String> connection = client.connect();
RedisAsyncCommands<String, String> asyncCommands = connection.async();

// Test the connection.
CompletableFuture<Void> testDBSize = asyncCommands.dbsize()
        .thenAccept(r -> {
            System.out.println(String.format("Database size: %d", r));
        })
        .toCompletableFuture();

testDBSize.join();