From b5bd3a277ae9cf926fe4a1cbd075d97e082d7b1a Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Thu, 13 Feb 2025 16:29:43 +0000 Subject: [PATCH 1/5] DOC-4816 added Jedis AMR connection page --- content/develop/clients/jedis/amr.md | 161 +++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 content/develop/clients/jedis/amr.md diff --git a/content/develop/clients/jedis/amr.md b/content/develop/clients/jedis/amr.md new file mode 100644 index 000000000..10348c117 --- /dev/null +++ b/content/develop/clients/jedis/amr.md @@ -0,0 +1,161 @@ +--- +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +description: Learn how to authenticate to an Azure Managed Redis (AMR) database +linkTitle: Connect to AMR +title: Connect to Azure Managed Redis +weight: 2 +--- + +The [`redis-authx-entraid`](https://github.com/redis/jvm-redis-authx-entraid) package +lets you authenticate your app to +[Azure Managed Redis (AMR)](https://azure.microsoft.com/en-us/products/managed-redis) +using [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/). +You can authenticate using a system-assigned or user-assigned +[managed identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) +or a [service principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals), +letting `redis-authx-entraid` fetch and renew the authentication tokens for you automatically. + +## Install + +Install [`jedis`]({{< relref "/develop/clients/jedis" >}}) first, +if you have not already done so. + +If you are using Maven, add +the following dependency to your `pom.xml` file: + +```xml + + redis.clients.authentication + redis-authx-entraid + 0.1.1-beta1 + +``` + +If you are using Gradle, add the following dependency to your +`build.gradle` file: + +```bash +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: + +```java +TokenAuthConfig authConfig = EntraIDTokenAuthConfigBuilder.builder() + .secret("") + .authority("") + // Other options... + .build(); +``` + +Some of the details you can supply are common to different use cases: + +- `secret()`: A string containing the [authentication secret](https://learn.microsoft.com/en-us/purview/sit-defn-azure-ad-client-secret). +- `authority()`: A string containing the [authority](https://learn.microsoft.com/en-us/entra/identity-platform/msal-client-application-configuration#authority) + URL. +- `scopes()`: A set of strings defining the [scopes](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc) + you want to apply. + +You can also add configuration to authenticate with a [service principal](#serv-principal) +or a [managed identity](#mgd-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](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals) +for more information about service principals.) + +```java +TokenAuthConfig authConfig = EntraIDTokenAuthConfigBuilder.builder() + .clientId("") + // ... + .build(); +``` + +### Configuration for a managed identity {#mgd-identity} + +You can also authenticate to AMR using a managed identity (see the +[Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) to learn more about managed identities). + +For a system assigned managed identity, simply add the `systemAssignedManagedIdentity()` +method to the `EntraIDTokenAuthConfigBuilder` chain: + +```java +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: + +```java +TokenAuthConfig authConfig = EntraIDTokenAuthConfigBuilder.builder() + .userAssignedManagedIdentity( + UserManagedIdentityType.CLIENT_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. + +{{< note >}} Azure requires you to use +[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) +when you connect. See +[Connect to your production Redis with TLS]({{< relref "/develop/clients/jedis/connect#connect-to-your-production-redis-with-tls" >}}) for more information about +TLS connections, including the implementation of the `createSslSocketFactory()` +method used in the example. +{{< /note >}} + +```java +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("", ), + config +); + +// Test the connection. +System.out.println(String.format("Database size is %d", jedis.dbSize())); +``` From de79a8e436f7ca0541fcfaeb56aa9d550d915ddc Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Wed, 19 Feb 2025 09:46:40 +0000 Subject: [PATCH 2/5] DOC-4816 added suggested link and removed TLS requirement --- content/develop/clients/jedis/amr.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/content/develop/clients/jedis/amr.md b/content/develop/clients/jedis/amr.md index 10348c117..a872295a8 100644 --- a/content/develop/clients/jedis/amr.md +++ b/content/develop/clients/jedis/amr.md @@ -24,6 +24,10 @@ You can authenticate using a system-assigned or user-assigned or a [service principal](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals), letting `redis-authx-entraid` fetch and renew the authentication tokens for you automatically. +See +[Use Microsoft Entra for cache authentication](https://learn.microsoft.com/en-us/azure/azure-cache-for-redis/cache-azure-active-directory-for-authentication) +in the Microsoft docs to learn how to configure Azure to use Entra ID authentication. + ## Install Install [`jedis`]({{< relref "/develop/clients/jedis" >}}) first, @@ -124,14 +128,12 @@ 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. - -{{< note >}} Azure requires you to use -[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) -when you connect. See +The connection uses +[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security), +which is recommended and enabled by default for managed identities. See [Connect to your production Redis with TLS]({{< relref "/develop/clients/jedis/connect#connect-to-your-production-redis-with-tls" >}}) for more information about TLS connections, including the implementation of the `createSslSocketFactory()` method used in the example. -{{< /note >}} ```java TokenAuthConfig authConfig = EntraIDTokenAuthConfigBuilder.builder() From 8e03e26332621cbf06c8aca95415a38365863d00 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Thu, 20 Feb 2025 09:38:13 +0000 Subject: [PATCH 3/5] DOC-4816 minor fixes --- content/develop/clients/jedis/amr.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/develop/clients/jedis/amr.md b/content/develop/clients/jedis/amr.md index a872295a8..916e8f863 100644 --- a/content/develop/clients/jedis/amr.md +++ b/content/develop/clients/jedis/amr.md @@ -72,7 +72,9 @@ Some of the details you can supply are common to different use cases: - `authority()`: A string containing the [authority](https://learn.microsoft.com/en-us/entra/identity-platform/msal-client-application-configuration#authority) URL. - `scopes()`: A set of strings defining the [scopes](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc) - you want to apply. + 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` + with the + [Microsoft Authentication Library (MSAL)](https://learn.microsoft.com/en-us/entra/identity-platform/msal-overview) You can also add configuration to authenticate with a [service principal](#serv-principal) or a [managed identity](#mgd-identity) as described in the sections below. From 70cb2771ba154b4fac44990c1dd779e745d29779 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Thu, 20 Feb 2025 13:36:15 +0000 Subject: [PATCH 4/5] DOC-4816 added advanced config options --- content/develop/clients/jedis/amr.md | 38 ++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/content/develop/clients/jedis/amr.md b/content/develop/clients/jedis/amr.md index 916e8f863..94c62d341 100644 --- a/content/develop/clients/jedis/amr.md +++ b/content/develop/clients/jedis/amr.md @@ -76,6 +76,10 @@ Some of the details you can supply are common to different use cases: with the [Microsoft Authentication Library (MSAL)](https://learn.microsoft.com/en-us/entra/identity-platform/msal-overview) +(See [Advanced configuration options](#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](#serv-principal) or a [managed identity](#mgd-identity) as described in the sections below. @@ -163,3 +167,37 @@ UnifiedJedis jedis = new UnifiedJedis( // 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: + +```java +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 complete before retrying. +- `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. From 4b953b90673f58f253754b8187497788ba5ac7fa Mon Sep 17 00:00:00 2001 From: andy-stark-redis <164213578+andy-stark-redis@users.noreply.github.com> Date: Mon, 24 Feb 2025 09:33:50 +0000 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: atakavci --- content/develop/clients/jedis/amr.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/develop/clients/jedis/amr.md b/content/develop/clients/jedis/amr.md index 94c62d341..85dd366eb 100644 --- a/content/develop/clients/jedis/amr.md +++ b/content/develop/clients/jedis/amr.md @@ -72,7 +72,7 @@ Some of the details you can supply are common to different use cases: - `authority()`: A string containing the [authority](https://learn.microsoft.com/en-us/entra/identity-platform/msal-client-application-configuration#authority) URL. - `scopes()`: A set of strings defining the [scopes](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc) - 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` + 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` (as detailed at [Microsoft Entra ID for authentication](https://learn.microsoft.com/en-us/azure/azure-cache-for-redis/managed-redis/managed-redis-entra-for-authentication#microsoft-entra-client-workflow)) with the [Microsoft Authentication Library (MSAL)](https://learn.microsoft.com/en-us/entra/identity-platform/msal-overview) @@ -196,8 +196,8 @@ These options are explained below: 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 complete before retrying. + 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. + retrying a token request after a failed attempt. This provides a mechanism to request throttling to prevent an excessive number of token requests.