feat(auth): add Entra ID identity provider integration

Introduces Entra ID (former Azure AD) authentication support with multiple authentication flows
and automated token lifecycle management.

Key additions:
- Add EntraIdCredentialsProvider for handling Entra ID authentication flows
- Implement MSALIdentityProvider to integrate with MSAL/EntraID authentication library
- Add support for multiple authentication methods:
  - Managed identities (system and user-assigned)
  - Client credentials with certificate
  - Client credentials with secret
  - Authorization Code flow with PKCE
- Add factory class with builder methods for each authentication flow
- Include sample Express server implementation for Authorization Code flow
- Export core auth types from client package for reuse
- Add comprehensive configuration options for authority and token management

Package exports (@redis/client):
- Added package.json "exports" field to enable auth folder barrel exports
- Included additional export paths ("./index" and "./dist/*") to maintain
  compatibility with existing deep imports across the monorepo packages

This change enables Azure-based authentication flows while maintaining consistent
token lifecycle management patterns established in the core authentication system.

Author: bobymicroby

package-lock.json

@@ -0,0 +1,13 @@
+import { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError } from './token-manager';
+export { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError };
+import { Disposable } from './types';
+export { Disposable };
+
+import { CredentialsProvider, StreamingCredentialsProvider, UnableToObtainNewCredentialsError, CredentialsError, StreamingCredentialsListener, AsyncCredentialsProvider, ReAuthenticationError, BasicAuth } from './credentials-provider';
+export { CredentialsProvider, StreamingCredentialsProvider, UnableToObtainNewCredentialsError, CredentialsError, StreamingCredentialsListener, AsyncCredentialsProvider, ReAuthenticationError, BasicAuth };
+
+import { Token } from './token';
+export { Token };
+
+import { IdentityProvider, TokenResponse } from './identity-provider';
+export { IdentityProvider, TokenResponse };

packages/client/lib/client/authx/index.ts

@@ -1,6 +1,5 @@
 import COMMANDS from '../commands';
-import { BasicAuth, CredentialsError, CredentialsProvider, StreamingCredentialsProvider, UnableToObtainNewCredentialsError  } from './authx/credentials-provider';
-import {Disposable} from './authx/types';
+import { BasicAuth, CredentialsError, CredentialsProvider, StreamingCredentialsProvider, UnableToObtainNewCredentialsError, Disposable  } from './authx/';
 import RedisSocket, { RedisSocketOptions } from './socket';
 import RedisCommandsQueue, { CommandOptions } from './commands-queue';
 import { EventEmitter } from 'node:events';

packages/client/lib/client/index.ts

@@ -0,0 +1,355 @@
+import { NetworkError } from '@azure/msal-common';
+import {
+  LogLevel,
+  ManagedIdentityApplication,
+  ManagedIdentityConfiguration,
+  AuthenticationResult,
+  PublicClientApplication,
+  ConfidentialClientApplication, AuthorizationUrlRequest, AuthorizationCodeRequest, CryptoProvider, Configuration, NodeAuthOptions, AccountInfo
+} from '@azure/msal-node';
+import { RetryPolicy, TokenManager, TokenManagerConfig, ReAuthenticationError } from '@redis/client/lib/client/authx';
+import { EntraidCredentialsProvider } from './entraid-credentials-provider';
+import { MSALIdentityProvider } from './msal-identity-provider';
+
+const FALLBACK_SCOPE = 'https://redis.azure.com/.default';
+
+export type AuthorityConfig =
+  | { type: 'multi-tenant'; tenantId: string }
+  | { type: 'custom'; authorityUrl: string }
+  | { type: 'default' };
+
+export type PKCEParams = {
+  code: string;
+  verifier: string;
+  clientInfo?: string;
+}
+
+export type CredentialParams = {
+  clientId: string;
+  scopes?: string[];
+  authorityConfig?: AuthorityConfig;
+
+  tokenManagerConfig: TokenManagerConfig
+  onReAuthenticationError?: (error: ReAuthenticationError) => void;
+}
+
+export type AuthCodePKCEParams = CredentialParams & {
+  redirectUri: string;
+};
+
+export type ClientSecretCredentialsParams = CredentialParams & {
+  clientSecret: string;
+};
+
+export type ClientCredentialsWithCertificateParams = CredentialParams & {
+  certificate: {
+    thumbprint: string;
+    privateKey: string;
+    x5c?: string;
+  };
+};
+
+const loggerOptions = {
+  loggerCallback(loglevel: LogLevel, message: string, containsPii: boolean) {
+    if (!containsPii) console.log(message);
+  },
+  piiLoggingEnabled: false,
+  logLevel: LogLevel.Verbose
+}
+
+/**
+ * The most imporant part of the RetryPolicy is the shouldRetry function. This function is used to determine if a request should be retried based
+ * on the error returned from the identity provider. The defaultRetryPolicy is used to retry on network errors only.
+ */
+export const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  // currently only retry on network errors
+  shouldRetry: (error: unknown) => error instanceof NetworkError,
+  maxAttempts: 10,
+  initialDelayMs: 100,
+  maxDelayMs: 100000,
+  backoffMultiplier: 2,
+  jitterPercentage: 0.1
+
+};
+
+export const DEFAULT_TOKEN_MANAGER_CONFIG: TokenManagerConfig = {
+  retry: DEFAULT_RETRY_POLICY,
+  expirationRefreshRatio: 0.7 // Refresh token when 70% of the token has expired
+}
+
+/**
+ * This class is used to help with the Authorization Code Flow with PKCE.
+ * It provides methods to generate PKCE codes, get the authorization URL, and create the credential provider.
+ */
+export class AuthCodeFlowHelper {
+  private constructor(
+    readonly client: PublicClientApplication,
+    readonly scopes: string[],
+    readonly redirectUri: string
+  ) {}
+
+  async getAuthCodeUrl(pkceCodes: {
+    challenge: string;
+    challengeMethod: string;
+  }): Promise<string> {
+    const authCodeUrlParameters: AuthorizationUrlRequest = {
+      scopes: this.scopes,
+      redirectUri: this.redirectUri,
+      codeChallenge: pkceCodes.challenge,
+      codeChallengeMethod: pkceCodes.challengeMethod
+    };
+
+    return this.client.getAuthCodeUrl(authCodeUrlParameters);
+  }
+
+  async acquireTokenByCode(params: PKCEParams): Promise<AuthenticationResult> {
+    const tokenRequest: AuthorizationCodeRequest = {
+      code: params.code,
+      scopes: this.scopes,
+      redirectUri: this.redirectUri,
+      codeVerifier: params.verifier,
+      clientInfo: params.clientInfo
+    };
+
+    return this.client.acquireTokenByCode(tokenRequest);
+  }
+
+  static async generatePKCE(): Promise<{
+    verifier: string;
+    challenge: string;
+    challengeMethod: string;
+  }> {
+    const cryptoProvider = new CryptoProvider();
+    const { verifier, challenge } = await cryptoProvider.generatePkceCodes();
+    return {
+      verifier,
+      challenge,
+      challengeMethod: 'S256'
+    };
+  }
+
+  static create(params: {
+    clientId: string;
+    redirectUri: string;
+    scopes?: string[];
+    authorityConfig?: AuthorityConfig;
+  }): AuthCodeFlowHelper {
+    const config = {
+      auth: {
+        clientId: params.clientId,
+        authority: EntraIdCredentialsProviderFactory.getAuthority(params.authorityConfig ?? { type: 'default' })
+      },
+      system: {
+        loggerOptions
+      }
+    };
+
+    return new AuthCodeFlowHelper(
+      new PublicClientApplication(config),
+      params.scopes ?? ['user.read'],
+      params.redirectUri
+    );
+  }
+}
+
+/**
+ * This class is used to create credentials providers for different types of authentication flows.
+ */
+export class EntraIdCredentialsProviderFactory {
+
+  static getAuthority(config: AuthorityConfig): string {
+    switch (config.type) {
+      case 'multi-tenant':
+        return `https://login.microsoftonline.com/${config.tenantId}`;
+      case 'custom':
+        return config.authorityUrl;
+      case 'default':
+        return 'https://login.microsoftonline.com/common';
+      default:
+        throw new Error('Invalid authority configuration');
+    }
+  }
+
+  /**
+   * This method is used to create a ManagedIdentityProvider for both system-assigned and user-assigned managed identities.
+   * for user-assigned managed identities, the developer needs to pass either the client ID, full resource identifier,
+   * or the object ID of the managed identity when creating ManagedIdentityApplication.
+   *
+   * @param params
+   * @param userAssignedClientId For user-assigned managed identities, the developer needs to pass either the client ID,
+   * full resource identifier, or the object ID of the managed identity when creating ManagedIdentityApplication.
+   *
+   * @private
+   */
+  public static createManagedIdentityProvider(
+    params: CredentialParams, userAssignedClientId?: string
+  ): EntraidCredentialsProvider {
+    const config: ManagedIdentityConfiguration = {
+      // For user-assigned identity, include the client ID
+      ...(userAssignedClientId && {
+        managedIdentityIdParams: {
+          userAssignedClientId
+        }
+      }),
+      system: {
+        loggerOptions
+      }
+    };
+
+    const client = new ManagedIdentityApplication(config);
+
+    const idp = new MSALIdentityProvider(
+      () => client.acquireToken({
+        resource: params.scopes?.[0] ?? FALLBACK_SCOPE,
+        forceRefresh: true
+      }).then(x => x === null ? Promise.reject('Token is null') : x)
+    );
+
+    return new EntraidCredentialsProvider(
+      new TokenManager(idp, params.tokenManagerConfig),
+      idp,
+      { onReAuthenticationError: params.onReAuthenticationError }
+    );
+  }
+
+  /**
+   * This method is used to create a credentials provider for system-assigned managed identities.
+   * @param params
+   */
+  static createForSystemAssignedManagedIdentity(
+    params: CredentialParams
+  ): EntraidCredentialsProvider {
+    return this.createManagedIdentityProvider(params);
+  }
+
+  /**
+   * This method is used to create a credentials provider for user-assigned managed identities.
+   * It will include the client ID as the userAssignedClientId in the ManagedIdentityConfiguration.
+   * @param params
+   */
+  static createForUserAssignedManagedIdentity(
+    params: CredentialParams
+  ): EntraidCredentialsProvider {
+    return this.createManagedIdentityProvider(params, params.clientId);
+  }
+
+  private static _createForClientCredentials(
+    authConfig: NodeAuthOptions,
+    params: CredentialParams
+  ): EntraidCredentialsProvider {
+    const config: Configuration = {
+      auth: {
+        ...authConfig,
+        authority: this.getAuthority(params.authorityConfig ?? { type: 'default' })
+      },
+      system: {
+        loggerOptions
+      }
+    };
+
+    const client = new ConfidentialClientApplication(config);
+
+    const idp = new MSALIdentityProvider(
+      () => client.acquireTokenByClientCredential({
+        skipCache: true,
+        scopes: params.scopes ?? [FALLBACK_SCOPE]
+      }).then(x => x === null ? Promise.reject('Token is null') : x)
+    );
+
+    return new EntraidCredentialsProvider(new TokenManager(idp, params.tokenManagerConfig), idp,
+      { onReAuthenticationError: params.onReAuthenticationError });
+  }
+
+  /**
+   * This method is used to create a credentials provider for service principals using certificate.
+   * @param params
+   */
+  static createForClientCredentialsWithCertificate(
+    params: ClientCredentialsWithCertificateParams
+  ): EntraidCredentialsProvider {
+    return this._createForClientCredentials(
+      {
+        clientId: params.clientId,
+        clientCertificate: params.certificate
+      },
+      params
+    );
+  }
+
+  /**
+   * This method is used to create a credentials provider for service principals using client secret.
+   * @param params
+   */
+  static createForClientCredentials(
+    params: ClientSecretCredentialsParams
+  ): EntraidCredentialsProvider {
+    return this._createForClientCredentials(
+      {
+        clientId: params.clientId,
+        clientSecret: params.clientSecret
+      },
+      params
+    );
+  }
+
+  /**
+   * This method is used to create a credentials provider for the Authorization Code Flow with PKCE.
+   * @param params
+   */
+  static createForAuthorizationCodeWithPKCE(
+    params: AuthCodePKCEParams
+  ): {
+    getPKCECodes: () => Promise<{
+      verifier: string;
+      challenge: string;
+      challengeMethod: string;
+    }>;
+    getAuthCodeUrl: (
+      pkceCodes: { challenge: string; challengeMethod: string }
+    ) => Promise<string>;
+    createCredentialsProvider: (
+      params: PKCEParams
+    ) => EntraidCredentialsProvider;
+  } {
+
+    const requiredScopes = ['user.read', 'offline_access'];
+    const scopes = [...new Set([...(params.scopes || []), ...requiredScopes])];
+
+    const authFlow = AuthCodeFlowHelper.create({
+      clientId: params.clientId,
+      redirectUri: params.redirectUri,
+      scopes: scopes,
+      authorityConfig: params.authorityConfig
+    });
+
+    return {
+      getPKCECodes: AuthCodeFlowHelper.generatePKCE,
+      getAuthCodeUrl: (pkceCodes) => authFlow.getAuthCodeUrl(pkceCodes),
+      createCredentialsProvider: (pkceParams) => {
+
+        // This is used to store the initial credentials account to be used
+        // for silent token acquisition after the initial token acquisition.
+        let initialCredentialsAccount: AccountInfo | null = null;
+
+        const idp = new MSALIdentityProvider(
+          async () => {
+            if (!initialCredentialsAccount) {
+              let authResult = await authFlow.acquireTokenByCode(pkceParams);
+              initialCredentialsAccount = authResult.account;
+              return authResult;
+            } else {
+              return authFlow.client.acquireTokenSilent({
+                forceRefresh: true,
+                account: initialCredentialsAccount,
+                scopes
+              });
+            }
+
+          }
+        );
+        const tm = new TokenManager(idp, params.tokenManagerConfig);
+        return new EntraidCredentialsProvider(tm, idp, { onReAuthenticationError: params.onReAuthenticationError });
+      }
+    };
+  }
+}