feat(auth): add EntraId integration tests

- Add integration tests for token renewal and re-authentication flows
- Update credentials provider to use uniqueId as username instead of account username
- Add test utilities for loading Redis endpoint configurations
- Split TypeScript configs into separate files for samples and integration tests

Author: bobymicroby

packages/authx/lib/token-manager.spec.ts

@@ -328,7 +328,7 @@ describe('TokenManager', () => {
         assert.equal(listener.receivedTokens.length, 1, 'Should not receive new token after failure');
         assert.equal(listener.errors.length, 1, 'Should receive error');
         assert.equal(listener.errors[0].message, 'Fatal error', 'Should have correct error message');
-        assert.equal(listener.errors[0].isFatal, true, 'Should be a fatal error');
+        assert.equal(listener.errors[0].isRetryable, false, 'Should be a fatal error');
 
         // verify that the token manager is stopped and no more requests are made after the error and expected refresh time
         await delay(80);
@@ -352,7 +352,7 @@ describe('TokenManager', () => {
             initialDelayMs: 100,
             maxDelayMs: 1000,
             backoffMultiplier: 2,
-            shouldRetry: (error: unknown) => error instanceof Error && error.message === 'Temporary failure'
+            isRetryable: (error: unknown) => error instanceof Error && error.message === 'Temporary failure'
           }
         };
 
@@ -389,7 +389,7 @@ describe('TokenManager', () => {
         // Should have first error but not stop due to retry config
         assert.equal(listener.errors.length, 1, 'Should have first error');
         assert.ok(listener.errors[0].message.includes('attempt 1'), 'Error should indicate first attempt');
-        assert.equal(listener.errors[0].isFatal, false, 'Should not be a fatal error');
+        assert.equal(listener.errors[0].isRetryable, true, 'Should not be a fatal error');
         assert.equal(manager.isRunning(), true, 'Should continue running during retries');
 
         // Advance past first retry (delay: 100ms due to backoff)
@@ -401,7 +401,7 @@ describe('TokenManager', () => {
 
         assert.equal(listener.errors.length, 2, 'Should have second error');
         assert.ok(listener.errors[1].message.includes('attempt 2'), 'Error should indicate second attempt');
-        assert.equal(listener.errors[0].isFatal, false, 'Should not be a fatal error');
+        assert.equal(listener.errors[0].isRetryable, true, 'Should not be a fatal error');
         assert.equal(manager.isRunning(), true, 'Should continue running during retries');
 
         // Advance past second retry (delay: 200ms due to backoff)
@@ -435,7 +435,7 @@ describe('TokenManager', () => {
             maxDelayMs: 1000,
             backoffMultiplier: 2,
             jitterPercentage: 0,
-            shouldRetry: (error: unknown) => error instanceof Error && error.message === 'Temporary failure'
+            isRetryable: (error: unknown) => error instanceof Error && error.message === 'Temporary failure'
           }
         };
 
@@ -470,7 +470,7 @@ describe('TokenManager', () => {
         // First error
         assert.equal(listener.errors.length, 1, 'Should have first error');
         assert.equal(manager.isRunning(), true, 'Should continue running after first error');
-        assert.equal(listener.errors[0].isFatal, false, 'Should not be a fatal error');
+        assert.equal(listener.errors[0].isRetryable, true, 'Should not be a fatal error');
 
         // Advance past first retry
         await delay(100);
@@ -483,7 +483,7 @@ describe('TokenManager', () => {
         // Second error
         assert.equal(listener.errors.length, 2, 'Should have second error');
         assert.equal(manager.isRunning(), true, 'Should continue running after second error');
-        assert.equal(listener.errors[1].isFatal, false, 'Should not be a fatal error');
+        assert.equal(listener.errors[1].isRetryable, true, 'Should not be a fatal error');
 
         // Advance past second retry
         await delay(200);
@@ -495,7 +495,7 @@ describe('TokenManager', () => {
 
         // Should stop after max retries
         assert.equal(listener.errors.length, 3, 'Should have final error');
-        assert.equal(listener.errors[2].isFatal, true, 'Should not be a fatal error');
+        assert.equal(listener.errors[2].isRetryable, false, 'Should be a fatal error');
         assert.equal(manager.isRunning(), false, 'Should stop after max retries exceeded');
         assert.equal(identityProvider.getRequestCount(), 4, 'Should have made exactly 4 requests');
 

packages/authx/lib/token-manager.ts

@@ -5,18 +5,70 @@ import { Token } from './token';
  * The configuration for retrying token refreshes.
  */
 export interface RetryPolicy {
-  // The maximum number of attempts to retry token refreshes.
+  /**
+   * The maximum number of attempts to retry token refreshes.
+   */
   maxAttempts: number;
-  // The initial delay in milliseconds before the first retry.
+
+  /**
+   * The initial delay in milliseconds before the first retry.
+   */
   initialDelayMs: number;
-  // The maximum delay in milliseconds between retries (the calculated delay will be capped at this value).
+
+  /**
+   * The maximum delay in milliseconds between retries.
+   * The calculated delay will be capped at this value.
+   */
   maxDelayMs: number;
-  // The multiplier for exponential backoff between retries. e.g. 2 will double the delay each time.
+
+  /**
+   * The multiplier for exponential backoff between retries.
+   * @example
+   * A value of 2 will double the delay each time:
+   * - 1st retry: initialDelayMs
+   * - 2nd retry: initialDelayMs * 2
+   * - 3rd retry: initialDelayMs * 4
+   */
   backoffMultiplier: number;
-  // The percentage of jitter to apply to the delay. e.g. 0.1 will add or subtract up to 10% of the delay.
+
+  /**
+   * The percentage of jitter to apply to the delay.
+   * @example
+   * A value of 0.1 will add or subtract up to 10% of the delay.
+   */
   jitterPercentage?: number;
-  // A custom function to determine if a retry should be attempted based on the error and attempt number.
-  shouldRetry?: (error: unknown, attempt: number) => boolean;
+
+  /**
+   * Function to classify errors from the identity provider as retryable or non-retryable.
+   * Used to determine if a token refresh failure should be retried based on the type of error.
+   *
+   * The default behavior is to retry all types of errors if no function is provided.
+   *
+   * Common use cases:
+   * - Network errors that may be transient (should retry)
+   * - Invalid credentials (should not retry)
+   * - Rate limiting responses (should retry)
+   *
+   * @param error - The error from the identity provider3
+   * @param attempt - Current retry attempt (0-based)
+   * @returns `true` if the error is considered transient and the operation should be retried
+   *
+   * @example
+   * ```typescript
+   * const retryPolicy: RetryPolicy = {
+   *   maxAttempts: 3,
+   *   initialDelayMs: 1000,
+   *   maxDelayMs: 5000,
+   *   backoffMultiplier: 2,
+   *   isRetryable: (error) => {
+   *     // Retry on network errors or rate limiting
+   *     return error instanceof NetworkError ||
+   *            error instanceof RateLimitError;
+   *   }
+   * };
+   * ```
+   */
+  isRetryable?: (error: unknown, attempt: number) => boolean;
 }
 
 /**
@@ -36,14 +88,13 @@ export interface TokenManagerConfig {
 }
 
 /**
- * IDPError is an error that occurs while calling the underlying IdentityProvider.
+ * IDPError indicates a failure from the identity provider.
  *
- * It can be transient and if retry policy is configured, the token manager will attempt to obtain a token again.
- * This means that receiving non-fatal error is not a stream termination event.
- * The stream will be terminated only if the error is fatal.
+ * The `isRetryable` flag is determined by the RetryPolicy's error classification function - if an error is
+ * classified as retryable, it will be marked as transient and the token manager will attempt to recover.
  */
 export class IDPError extends Error {
-  constructor(public readonly message: string, public readonly isFatal: boolean) {
+  constructor(public readonly message: string, public readonly isRetryable: boolean) {
     super(message);
     this.name = 'IDPError';
   }
@@ -105,7 +156,6 @@ export class TokenManager<T> {
    */
   public start(listener: TokenStreamListener<T>, initialDelayMs: number = 0): Disposable {
     if (this.listener) {
-      console.log('TokenManager is already running, stopping the previous instance');
       this.stop();
     }
 
@@ -142,14 +192,14 @@ export class TokenManager<T> {
   private shouldRetry(error: unknown): boolean {
     if (!this.config.retry) return false;
 
-    const { maxAttempts, shouldRetry } = this.config.retry;
+    const { maxAttempts, isRetryable } = this.config.retry;
 
     if (this.retryAttempt >= maxAttempts) {
       return false;
     }
 
-    if (shouldRetry) {
-      return shouldRetry(error, this.retryAttempt);
+    if (isRetryable) {
+      return isRetryable(error, this.retryAttempt);
     }
 
     return false;
@@ -172,10 +222,10 @@ export class TokenManager<T> {
       if (this.shouldRetry(error)) {
         this.retryAttempt++;
         const retryDelay = this.calculateRetryDelay();
-        this.notifyError(`Token refresh failed (attempt ${this.retryAttempt}), retrying in ${retryDelay}ms: ${error}`, false)
+        this.notifyError(`Token refresh failed (attempt ${this.retryAttempt}), retrying in ${retryDelay}ms: ${error}`, true)
         this.scheduleNextRefresh(retryDelay);
       } else {
-        this.notifyError(error, true);
+        this.notifyError(error, false);
         this.stop();
       }
     }
@@ -255,13 +305,13 @@ export class TokenManager<T> {
     return this.currentToken;
   }
 
-  private notifyError = (error: unknown, isFatal: boolean): void => {
+  private notifyError(error: unknown, isRetryable: boolean): void {
     const errorMessage = error instanceof Error ? error.message : String(error);
 
     if (!this.listener) {
       throw new Error(`TokenManager is not running but received an error: ${errorMessage}`);
     }
 
-    this.listener.onError(new IDPError(errorMessage, isFatal));
+    this.listener.onError(new IDPError(errorMessage, isRetryable));
   }
 }

packages/client/README.md

@@ -1,3 +1,125 @@
-# @redis/client
+# @redis/entraid
+
+Token-based authentication provider for Redis clients using Microsoft Entra ID (formerly Azure Active Directory).
+
+## Features
+
+- Token-based authentication using Microsoft Entra ID
+- Automatic token refresh before expiration
+- Automatic re-authentication of all connections after token refresh
+- Support for multiple authentication flows:
+    - Managed identities (system-assigned and user-assigned)
+    - Service principals (with or without certificates)
+    - Authorization Code with PKCE flow
+- Built-in retry mechanisms for transient failures
+
+## Installation
+
+```bash
+npm install @redis/entraid
+```
+
+## Usage
+
+### Basic Setup with Client Credentials ( Service Principal )
+
+```typescript
+import { createClient } from '@redis/client';
+import { EntraIdCredentialsProviderFactory } from '@redis/entraid';
+
+const provider = EntraIdCredentialsProviderFactory.createForClientCredentials({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+  authorityConfig: {
+    type: 'multi-tenant',
+    tenantId: 'your-tenant-id'
+  },
+  tokenManagerConfig: {
+    expirationRefreshRatio: 0.8 // Refresh token after 80% of its lifetime
+  }
+});
+
+const client = createClient({
+  url: 'redis://your-host',
+  credentialsProvider: provider
+});
+
+await client.connect();
+```
+
+## Important Limitations
+
+### RESP2 PUB/SUB Limitations
+
+#### ⚠️ When using RESP2 (Redis Serialization Protocol 2), there are important limitations with PUB/SUB:
+
+- **No Re-Authentication in PUB/SUB Mode**: In RESP2, once a connection enters PUB/SUB mode, the socket is blocked and
+  cannot process out-of-band commands like AUTH. This means that connections in PUB/SUB mode cannot be re-authenticated
+  when tokens are refreshed.
+
+- **Connection Eviction**: As a result, PUB/SUB connections will be evicted by the Redis proxy when their tokens expire.
+  The client will need to establish new connections with fresh tokens.
+
+
+### Transaction Safety
+
+#### ⚠️ Important Note About Transactions
+
+When using token-based authentication, special care must be taken with Redis transactions. 
+The token manager runs in the background and may attempt to re-authenticate connections at any time by sending AUTH commands.
+This can interfere with manually constructed transactions.
+
+##### ✅ Recommended: Use the Official Transaction API
+
+Always use the official transaction API provided by the client:
+
+```typescript
+// Correct way to handle transactions
+const multi = client.multi();
+multi.set('key1', 'value1');
+multi.set('key2', 'value2');
+await multi.exec();
+```
+
+##### ❌ Avoid: Manual Transaction Construction
+
+Do not manually construct transactions by sending individual MULTI/EXEC commands:
+
+```typescript
+// Incorrect and potentially dangerous
+await client.sendCommand(['MULTI']);
+await client.sendCommand(['SET', 'key1', 'value1']);
+await client.sendCommand(['SET', 'key2', 'value2']);
+await client.sendCommand(['EXEC']); // Risk of AUTH command being injected before EXEC
+```
+
+The official transaction API ensures proper coordination between transaction commands and authentication updates.
+It prevents the token manager from injecting AUTH commands in the middle of your transaction, which is particularly 
+important in applications where transaction atomicity is critical, such as payment processing or inventory management.
+
+
+## Error Handling
+
+The provider includes built-in retry mechanisms for transient errors:
+
+```typescript
+const provider = EntraIdCredentialsProviderFactory.createForClientCredentials({
+  // ... other config ...
+  tokenManagerConfig: {
+    retry: {
+      maxAttempts: 3,
+      initialDelayMs: 100,
+      maxDelayMs: 1000,
+      backoffMultiplier: 2
+    }
+  }
+});
+```
+
+### Other Considerations
+
+- Token refresh operations are asynchronous and may occur in the background
+- During token refresh, there is a critical window where all connections must be re-authenticated before the old token
+  expires
+
 
-The source code and documentation for this package are in the main [node-redis](https://github.com/redis/node-redis) repo.