Add comprehensive documentation for Kafka authentication refactoring

- Add package-info.java documenting authentication architecture
- Enhance AbstractKafkaPropertiesBeanPostProcessor JavaDoc
- Document authentication flow and strategy pattern usage
- Provide example configuration for OAuth2 authentication

Co-authored-by: saragluna <[email protected]>

Author: Copilot

sdk/spring/spring-cloud-azure-autoconfigure/src/main/java/com/azure/spring/cloud/autoconfigure/implementation/kafka/AbstractKafkaPropertiesBeanPostProcessor.java

@@ -28,10 +28,39 @@
 
 /**
  * Abstract base class for Kafka properties BeanPostProcessors.
- * This class provides common functionality for configuring Kafka authentication
- * using different strategies (OAuth2, connection string, etc.).
+ * <p>
+ * This class provides common functionality for configuring Kafka authentication for Azure Event Hubs
+ * using different strategies. It uses the Strategy pattern to delegate authentication configuration
+ * to pluggable {@link KafkaAuthenticationStrategy} implementations.
+ * </p>
+ * <p>
+ * The processor intercepts Kafka properties beans during Spring bean initialization and applies
+ * authentication configuration to producer, consumer, and admin properties based on the configured
+ * strategy.
+ * </p>
+ * <p>
+ * <b>Authentication Flow:</b>
+ * <ol>
+ *   <li>Bean post processor detects Kafka properties beans during initialization</li>
+ *   <li>Retrieves AzureGlobalProperties for credential configuration</li>
+ *   <li>For each set of properties (producer/consumer/admin):
+ *     <ul>
+ *       <li>Checks if authentication strategy should be applied via {@link KafkaAuthenticationStrategy#shouldApply}</li>
+ *       <li>If applicable, applies authentication via {@link KafkaAuthenticationStrategy#applyAuthentication}</li>
+ *       <li>Configures Kafka user agent for telemetry</li>
+ *       <li>Clears Azure-specific properties from raw properties map</li>
+ *     </ul>
+ *   </li>
+ * </ol>
+ * </p>
+ * <p>
+ * By default, uses {@link KafkaOAuth2AuthenticationStrategy} for OAuth2/Microsoft Entra ID authentication.
+ * Subclasses can provide alternative strategies via the constructor.
+ * </p>
  *
- * @param <T> the type of Kafka properties bean to process
+ * @param <T> the type of Kafka properties bean to process (e.g., {@link KafkaProperties})
+ * @see KafkaAuthenticationStrategy
+ * @see KafkaOAuth2AuthenticationStrategy
  */
 abstract class AbstractKafkaPropertiesBeanPostProcessor<T> implements BeanPostProcessor, ApplicationContextAware {
 

sdk/spring/spring-cloud-azure-autoconfigure/src/main/java/com/azure/spring/cloud/autoconfigure/implementation/kafka/authentication/package-info.java

@@ -0,0 +1,58 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * Authentication strategies for Azure Event Hubs Kafka support in Spring Cloud Azure.
+ * 
+ * <h2>Overview</h2>
+ * This package contains authentication strategy implementations for configuring Kafka clients
+ * to connect to Azure Event Hubs using different authentication methods.
+ * 
+ * <h2>Architecture</h2>
+ * The authentication configuration uses the Strategy pattern to support different authentication methods:
+ * <ul>
+ *   <li>{@link com.azure.spring.cloud.autoconfigure.implementation.kafka.authentication.KafkaAuthenticationStrategy} - 
+ *       The strategy interface that defines how authentication should be applied</li>
+ *   <li>{@link com.azure.spring.cloud.autoconfigure.implementation.kafka.authentication.KafkaOAuth2AuthenticationStrategy} - 
+ *       Implementation for OAuth2 authentication using Microsoft Entra ID</li>
+ * </ul>
+ * 
+ * <h2>Supported Authentication Methods</h2>
+ * 
+ * <h3>OAuth2 Authentication (Microsoft Entra ID)</h3>
+ * The {@code KafkaOAuth2AuthenticationStrategy} configures SASL/OAUTHBEARER authentication
+ * for connecting to Azure Event Hubs using Microsoft Entra ID credentials.
+ * 
+ * <p><b>Configuration Requirements:</b></p>
+ * <ul>
+ *   <li>Bootstrap server must be an Event Hubs namespace endpoint (ends with :9093)</li>
+ *   <li>Security protocol should be SASL_SSL (or not configured)</li>
+ *   <li>SASL mechanism should be OAUTHBEARER (or not configured)</li>
+ * </ul>
+ * 
+ * <p><b>Properties Configured:</b></p>
+ * <ul>
+ *   <li>{@code security.protocol} = SASL_SSL</li>
+ *   <li>{@code sasl.mechanism} = OAUTHBEARER</li>
+ *   <li>{@code sasl.jaas.config} = JAAS configuration with Azure credentials</li>
+ *   <li>{@code sasl.login.callback.handler.class} = KafkaOAuth2AuthenticateCallbackHandler</li>
+ * </ul>
+ * 
+ * <h2>Usage</h2>
+ * The authentication strategies are used automatically by the Kafka bean post processors:
+ * <ul>
+ *   <li>{@code KafkaPropertiesBeanPostProcessor} - For Spring Boot Kafka auto-configuration</li>
+ *   <li>{@code KafkaBinderConfigurationPropertiesBeanPostProcessor} - For Spring Cloud Stream Kafka binder</li>
+ * </ul>
+ * 
+ * <h2>Example Configuration</h2>
+ * <pre>{@code
+ * spring.kafka.bootstrap-servers=mynamespace.servicebus.windows.net:9093
+ * spring.cloud.azure.credential.client-id=<client-id>
+ * spring.cloud.azure.credential.client-secret=<client-secret>
+ * spring.cloud.azure.profile.tenant-id=<tenant-id>
+ * }</pre>
+ * 
+ * @since 6.1.0
+ */
+package com.azure.spring.cloud.autoconfigure.implementation.kafka.authentication;