{
  "schema_version": 2,
  "id": "develop/clients/lettuce/amr",
  "title": "Connect to Azure Managed Redis",
  "url": "https://redis.io/docs/latest/develop/clients/lettuce/amr/",
  "summary": "Learn how to authenticate to an Azure Managed Redis (AMR) database",
  "tags": [
    "docs",
    "develop",
    "stack",
    "oss",
    "rs",
    "rc",
    "oss",
    "kubernetes",
    "clients"
  ],
  "last_updated": "2026-10-16T10:19:56+01:00",
  "page_type": "content",
  "content_hash": "5f19851f934140a8460278657e0093efaf1639c199067d038ba5afa5e2a6838b",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "The [`redis-authx-entraid`](https://github.com/redis/jvm-redis-authx-entraid) package\nlets you authenticate your app to\n[Azure Managed Redis (AMR)](https://azure.microsoft.com/en-us/products/managed-redis)\nusing [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/).\nYou can authenticate using a system-assigned or user-assigned\n[managed identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview)\nor a [service principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals),\nletting `redis-authx-entraid` fetch and renew the authentication tokens for you automatically.\n\nSee\n[Use Microsoft Entra for cache authentication](https://learn.microsoft.com/en-us/azure/azure-cache-for-redis/cache-azure-active-directory-for-authentication)\nin the Microsoft docs to learn how to configure Azure to use Entra ID authentication."
    },
    {
      "id": "install",
      "title": "Install",
      "role": "setup",
      "text": "Install [`Lettuce`](https://redis.io/docs/latest/develop/clients/lettuce) first,\nif you have not already done so.\n\nIf you are using Maven, add\nthe following dependency to your `pom.xml` file:\n\n[code example]\n\nIf you are using Gradle, add the following dependency to your\n`build.gradle` file:\n\n[code example]"
    },
    {
      "id": "create-a-tokenbasedrediscredentialsprovider-instance",
      "title": "Create a `TokenBasedRedisCredentialsProvider` instance",
      "role": "content",
      "text": "The `TokenBasedRedisCredentialsProvider` class contains the authentication details that you\nmust supply when you connect to Redis. Chain the methods of the\n`EntraIDTokenAuthConfigBuilder` class together (starting with the `builder()`\nmethod) to include the details you need, as shown in the following example:\n\n[code example]\n\nSome of the details you can supply are common to different use cases:\n\n-   `secret()`: A string containing the [authentication secret](https://learn.microsoft.com/en-us/purview/sit-defn-azure-ad-client-secret).\n-   `authority()`: A string containing the [authority](https://learn.microsoft.com/en-us/entra/identity-platform/msal-client-application-configuration#authority)\n    URL.\n-   `scopes()`: A set of strings defining the [scopes](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc)\n    you want to apply. Configure your client application to acquire a Microsoft Entra token for scope, `https://redis.azure.com/.default` or `acca5fbb-b7e4-4009-81f1-37e38fd66d78/.default`\n    with the\n    [Microsoft Authentication Library (MSAL)](https://learn.microsoft.com/en-us/entra/identity-platform/msal-overview)\n\nYou can also add configuration to authenticate with a [service principal](#serv-principal)\nor a [managed identity](#mgd-identity) as described in the sections below.\n\nWhen you have created your `TokenBasedRedisCredentialsProvider` instance, you may want to\ntest it by obtaining a token, as shown in the following example. The\n`resolveCredentialsAsync()` method requires Lettuce 7.9 or later.\n\n[code example]"
    },
    {
      "id": "serv-principal",
      "title": "Configuration for a service principal",
      "role": "configuration",
      "text": "Add `clientId()` to the `EntraIDTokenAuthConfigBuilder` chain to specify\nauthentication via a service principal, passing the ID token string as\na parameter. (See the\n[Microsoft EntraID docs](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals)\nfor more information about service principals.)\n\n[code example]"
    },
    {
      "id": "mgd-identity",
      "title": "Configuration for a managed identity",
      "role": "configuration",
      "text": "You can also authenticate to AMR using a managed identity (see the\n[Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) to learn more about managed identities).\n\nFor a system assigned managed identity, simply add the `systemAssignedManagedIdentity()`\nmethod to the `EntraIDTokenAuthConfigBuilder` chain:\n\n[code example]\n\nFor a user assigned managed identity, add `userAssignedManagedIdentity()`. This\nrequires a member of the `UserManagedIdentityType` enum (to select a\n`CLIENT_ID`, `OBJECT_ID`, or `RESOURCE_ID`) as well as the `id` string itself:\n\n[code example]"
    },
    {
      "id": "connect-using-the-withauthentication-option",
      "title": "Connect using the `withAuthentication()` option",
      "role": "content",
      "text": "When you have created your `TokenBasedRedisCredentialsProvider` instance, you are ready to\nconnect to AMR.\nThe example below shows how to include the authentication details in a\n`TokenBasedRedisCredentialsProvider` instance and pass it to the `RedisURI.Builder`\nusing the `withAuthentication()` option. It also uses a `ClusterClientOptions` object to\nenable automatic re-authentication.\n\nThe connection uses\n[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security),\nwhich is recommended and enabled by default for managed identities. See\n[TLS connection](https://redis.io/docs/latest/develop/clients/lettuce/connect#tls-connection) for more information.\n\n> [!NOTE]\n> The `Lettuce` client library doesn't manage the lifecycle of\n> the `TokenBasedRedisCredentialsProvider` instance for you. You can reuse the\n> same instance for as many clients and connections as you want. When you have\n> finished using the credentials provider, call its `close()` method, as shown\n> at the end of the example.\n\n[code example]"
    }
  ],
  "examples": [
    {
      "id": "install-ex0",
      "language": "xml",
      "code": "<dependency>\n    <groupId>redis.clients.authentication</groupId>\n    <artifactId>redis-authx-entraid</artifactId>\n    <version>0.1.1-beta1</version>\n</dependency>",
      "section_id": "install"
    },
    {
      "id": "install-ex1",
      "language": "bash",
      "code": "implementation 'redis.clients.authentication:redis-authx-entraid:0.1.1-beta1'",
      "section_id": "install"
    },
    {
      "id": "create-a-tokenbasedrediscredentialsprovider-instance-ex0",
      "language": "java",
      "code": "TokenBasedRedisCredentialsProvider credentials;\n\ntry ( EntraIDTokenAuthConfigBuilder builder = EntraIDTokenAuthConfigBuilder.builder()) {\n        builder.clientId(CLIENT_ID)\n                .secret(CLIENT_SECRET)\n                .authority(AUTHORITY) // \"https://login.microsoftonline.com/{YOUR_TENANT_ID}\";\n                .scopes(SCOPES);      // \"https://redis.azure.com/.default\";\n\n        credentials = TokenBasedRedisCredentialsProvider.create(builder.build());\n}",
      "section_id": "create-a-tokenbasedrediscredentialsprovider-instance"
    },
    {
      "id": "create-a-tokenbasedrediscredentialsprovider-instance-ex1",
      "language": "java",
      "code": "// Test that the Entra ID credentials provider can resolve credentials.\ncredentials.resolveCredentialsAsync()\n        .thenAccept(c -> System.out.println(c.getUsername()))\n        .toCompletableFuture()\n        .join();",
      "section_id": "create-a-tokenbasedrediscredentialsprovider-instance"
    },
    {
      "id": "serv-principal-ex0",
      "language": "java",
      "code": "TokenBasedRedisCredentialsProvider credentials;\n\ntry ( EntraIDTokenAuthConfigBuilder builder = EntraIDTokenAuthConfigBuilder.builder()) {\n        builder.clientId(CLIENT_ID)\n                .secret(CLIENT_SECRET)\n                .authority(AUTHORITY) // \"https://login.microsoftonline.com/{YOUR_TENANT_ID}\";\n                .scopes(SCOPES);      // \"https://redis.azure.com/.default\";\n\n        credentials = TokenBasedRedisCredentialsProvider.create(builder.build());\n}",
      "section_id": "serv-principal"
    },
    {
      "id": "mgd-identity-ex0",
      "language": "java",
      "code": "TokenBasedRedisCredentialsProvider credentials;\n\ntry ( EntraIDTokenAuthConfigBuilder builder = EntraIDTokenAuthConfigBuilder.builder()) {\n        builder.clientId(CLIENT_ID)\n                // ...\n                .systemAssignedManagedIdentity();\n\n        credentials = TokenBasedRedisCredentialsProvider.create(builder.build());\n}",
      "section_id": "mgd-identity"
    },
    {
      "id": "mgd-identity-ex1",
      "language": "java",
      "code": "TokenBasedRedisCredentialsProvider credentials;\n\ntry ( EntraIDTokenAuthConfigBuilder builder = EntraIDTokenAuthConfigBuilder.builder()) {\n        builder.clientId(CLIENT_ID)\n                // ...\n                .userAssignedManagedIdentity(\n                        UserManagedIdentityType.CLIENT_ID,\n                        \"<ID>\"\n                );\n\n        credentials = TokenBasedRedisCredentialsProvider.create(builder.build());\n}",
      "section_id": "mgd-identity"
    },
    {
      "id": "connect-using-the-withauthentication-option-ex0",
      "language": "java",
      "code": "// Entra ID credentials provider for Service Principal Identity with Client Secret.\nTokenBasedRedisCredentialsProvider credentialsSP;\ntry (EntraIDTokenAuthConfigBuilder builder = EntraIDTokenAuthConfigBuilder.builder()) {\n        builder\n                .clientId(CLIENT_ID)\n                .secret(CLIENT_SECRET).authority(AUTHORITY) // \"https://login.microsoftonline.com/{YOUR_TENANT_ID}\"\n                .scopes(SCOPES); // \"https://redis.azure.com/.default\"\n\n        credentialsSP = TokenBasedRedisCredentialsProvider.create(builder.build());\n}\n\n// Optionally test the credentials provider.\n// credentialsSP.resolveCredentialsAsync().thenAccept(c -> System.out.println(\"SPI ID :\" + c.getUsername())).toCompletableFuture().join();\n\n// Enable automatic re-authentication.\nClusterClientOptions clientOptions = ClusterClientOptions.builder()\n        .reauthenticateBehavior(\n                ClientOptions.ReauthenticateBehavior.ON_NEW_CREDENTIALS\n        ).build();\n\n// Use the Entra ID credentials provider.\nRedisURI redisURI = RedisURI.builder()\n        .withHost(HOST)\n        .withPort(PORT)\n        .withAuthentication(credentialsSP)\n        .withSsl(true)\n        .build();\n\n// Create the RedisClusterClient and set the re-authentication options.\n// Note: AMR databases have clustering enabled by default.\nRedisClusterClient redisClient = RedisClusterClient.create(redisURI);\nredisClient.setOptions(clientOptions);\n\n// Connect with the credentials provider.\ntry (StatefulRedisClusterConnection<String, String> user1 = redisClient.connect(StringCodec.UTF8)) {\n        System.out.println(\"Connected to redis as :\" + user1.sync().aclWhoami());\n        System.out.println(\"Db size :\" + user1.sync().dbsize());\n} finally {\n        redisClient.shutdown();  // Shutdown Redis client and close connections.\n        credentialsSP.close(); // Shutdown Entra ID Credentials provider.\n}",
      "section_id": "connect-using-the-withauthentication-option"
    }
  ]
}