Partager via

Prise en charge d’Azure Kafka Azure Spring Cloud

  • Article

Cet article s’applique à :✅ version 4.19.0 ✅ version 5.19.0

À partir de la version 4.3.0, Spring Cloud Azure pour Kafka prend en charge différents types d’informations d’identification pour authentifier et se connecter à Azure Event Hubs.

Version de Kafka prise en charge

La version actuelle du starter doit être compatible avec Apache Kafka Clients 2.0.0 à l’aide de Java 8 ou version ultérieure.

Types d’authentification pris en charge

Les types d’authentification suivants sont pris en charge :

  • Authentification par chaîne de connexion simple
    • Authentification de chaîne de connexion directe
    • Authentification de chaîne de connexion basée sur ARM
  • Authentification des informations d’identification OAuth
    • Authentification d’identité managée
    • Authentification par nom d’utilisateur/mot de passe
    • Authentification du principal de service
    • Authentification DefaultAzureCredential

Fonctionnement

Authentification des informations d’identification OAuth

Cette section décrit le flux de travail global de l’authentification OAuth Spring Cloud Azure.

Spring Cloud Azure crée d’abord l’un des types d’informations d’identification suivants en fonction de la configuration de l’authentification de l’application :

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Si aucun de ces types d’informations d’identification n’est trouvé, la chaîne d’informations d’identification via DefaultAzureTokenCredential sera utilisée pour obtenir des informations d’identification à partir des propriétés de l’application, des variables d’environnement, de l’identité managée ou des IDE. Pour plus d’informations, consultez d’authentification Spring Cloud Azure.

Authentification par chaîne de connexion simple

Pour le mode d’authentification de chaîne de connexion, vous pouvez utiliser l’authentification de chaîne de connexion directement ou utiliser Azure Resource Manager pour récupérer la chaîne de connexion. Pour plus d’informations sur l’utilisation, consultez la section Utilisation de base pour l’authentification de chaîne de connexion.

Note

Depuis la version 4.3.0, l’authentification de chaîne de connexion est déconseillée en faveur des authentifications OAuth.

Configuration

Propriétés configurables lors de l’utilisation de la prise en charge de Kafka avec l’authentification OAuth

Spring Cloud Azure pour Kafka prend en charge les deux niveaux suivants d’options de configuration :

  1. Propriétés Spring Cloud Azure pour Event Hubs Kafka.
  2. Options de configuration d’authentification globale de credential et de profile avec des préfixes de spring.cloud.azure.
  3. Configurations de niveau spécifiques à Kafka. Les configurations kafka sont également disponibles pour les classeurs Spring Boot et Spring Cloud Stream pour common, consumer, producerou les étendues admin, qui ont des préfixes différents.

Les propriétés globales sont exposées via com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Les propriétés propres à Kafka sont exposées via org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) et org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (classeur Spring Cloud Stream).

La liste suivante montre toutes les options de configuration prises en charge.

  • Propriétés Spring Cloud Azure pour Event Hubs Kafka.

    • Propriété : spring.cloud.azure.eventhubs.kafka.enabled
    • Description : indique s’il faut activer la connexion gratuite des informations d’identification à Azure Event Hubs pour Kafka, la valeur par défaut est true.

  • Options de configuration de l’authentification globale Spring Cloud Azure

    • Préfixe : spring.cloud.azure
    • Options prises en charge : spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    Pour obtenir la liste complète des options de configuration globales, consultez propriétés de configuration globale.

  • Configuration courante spring Boot Kafka

    • Préfixe : spring.kafka.properties.azure
    • Exemple : spring.kafka.properties.azure.credential.*

  • Options de configuration du consommateur Spring Kafka

    • Préfixe : spring.kafka.consumer.properties.azure
    • Exemple : spring.kafka.consumer.properties.azure.credential.*

  • Options de configuration du producteur Spring Kafka

    • Préfixe : spring.kafka.producer.properties.azure
    • Exemple : spring.kafka.producer.properties.azure.credential.*

  • Options de configuration de l’administrateur Spring Kafka

    • Préfixe : spring.kafka.admin.properties.azure
    • Exemple : spring.kafka.admin.properties.azure.credential.*

  • Configuration courante de Spring Cloud Stream Kafka Binder

    • Préfixe : spring.cloud.stream.kafka.binder.configuration.azure
    • Exemple : spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Configuration du consommateur Spring Cloud Stream Kafka Binder

    • Préfixe : spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Exemple : spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Configuration du producteur Spring Cloud Stream Kafka Binder

    • Préfixe : spring.cloud.stream.kafka.binder.producer-properties.azure
    • Exemple : spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Configuration de l’administrateur Spring Cloud Stream Kafka Binder

    • Préfixe : Non pris en charge, doit utiliser la configuration commune ou administrateur spring Boot Kafka.

Le tableau suivant présente les options de configuration courantes de Spring Boot Kafka :

Nom Description
spring.kafka.properties.azure.credential.client-certificate-password Mot de passe du fichier de certificat.
spring.kafka.properties.azure.credential.client-certificate-path Chemin d’un fichier de certificat PEM à utiliser lors de l’authentification du principal de service avec Azure.
spring.kafka.properties.azure.credential.client-id ID client à utiliser lors de l’authentification du principal de service avec Azure. Il s’agit d’une propriété héritée.
spring.kafka.properties.azure.credential.client-secret Clé secrète client à utiliser lors de l’authentification du principal de service avec Azure. Il s’agit d’une propriété héritée.
spring.kafka.properties.azure.credential.managed-identity-enabled Indique s’il faut activer l’identité managée pour s’authentifier auprès d’Azure. Si true et que l'client-id est défini, utilisez l’ID client comme ID client d’identité managée affecté par l’utilisateur. La valeur par défaut est false.
spring.kafka.properties.azure.credential.password Mot de passe à utiliser lors de l’exécution de l’authentification par nom d’utilisateur/mot de passe avec Azure.
spring.kafka.properties.azure.credential.username Nom d’utilisateur à utiliser lors de l’exécution de l’authentification par nom d’utilisateur/mot de passe avec Azure.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint Point de terminaison Microsoft Entra auquel se connecter.
spring.kafka.properties.azure.profile.tenant-id ID de locataire pour les ressources Azure. Les valeurs autorisées pour tenant-id sont : common, organizations, consumersou l’ID de locataire.

Note

Les options de configuration de différents niveaux appliquent les règles suivantes. Les options de configuration plus spécifiques ont une priorité plus élevée que les options courantes. Par exemple:

  • Les options de configuration courantes spring Kafka remplacent les options globales.
  • Les options de configuration du consommateur Spring Kafka remplacent les options courantes.
  • Les options de configuration du producteur Spring Kafka remplacent les options courantes.
  • Les options de configuration de l’administrateur Spring Kafka remplacent les options courantes.
  • Les options Spring Cloud Stream Kafka Binder sont tout comme celles ci-dessus.

Propriétés configurables lors de l’utilisation de la prise en charge de Kafka avec l’authentification par chaîne de connexion simple

Le tableau suivant présente les hubs d’événements Spring Boot pour les options de configuration courantes de Kafka :

Propriété Description
spring.cloud.azure.eventhubs.kafka.enabled Indique s’il faut activer la prise en charge d’Azure Event Hubs Kafka. La valeur par défaut est true.
spring.cloud.azure.eventhubs.connection-string Chaîne de connexion Azure Event Hubs. Indiquez cette valeur lorsque vous souhaitez fournir directement la chaîne de connexion.
spring.cloud.azure.eventhubs.namespace Espace de noms Azure Event Hubs. Indiquez cette valeur lorsque vous souhaitez récupérer les informations de connexion via Azure Resource Manager.
spring.cloud.azure.eventhubs.resource.resource-group Groupe de ressources de l’espace de noms Azure Event Hubs. Indiquez cette valeur lorsque vous souhaitez récupérer les informations de connexion via Azure Resource Manager.
spring.cloud.azure.profile.subscription-id ID d’abonnement. Indiquez cette valeur lorsque vous souhaitez récupérer les informations de connexion via Azure Resource Manager.

Configuration des dépendances

Ajoutez la dépendance suivante à votre projet. Cela inclut automatiquement la dépendance spring-boot-starter dans votre projet transitivement.

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>

Note

N’oubliez pas d’ajouter le spring-cloud-azure-dependencies boM avec la dépendance ci-dessus. Pour plus d’informations, consultez la section Prise en main du guide du développeur Spring Cloud Azure.

Utilisation de base

Les sections suivantes montrent les scénarios d’utilisation classiques de l’application Spring Boot.

Utiliser l’authentification OAuth

Lorsque vous utilisez l’authentification OAuth fournie par Spring Cloud Azure pour Kafka, vous pouvez configurer les informations d’identification spécifiques à l’aide des configurations ci-dessus. Vous pouvez également choisir de configurer des informations d’identification, auquel cas Spring Cloud Azure charge les informations d’identification à partir de l’environnement. Cette section décrit les utilisations qui chargent les informations d’identification à partir de l’environnement Azure CLI ou de l’environnement d’hébergement Azure Spring Apps.

Note

Si vous choisissez d’utiliser un principal de sécurité pour authentifier et autoriser avec Microsoft Entra ID pour accéder à une ressource Azure, consultez la section Autoriser l’accès avec l’ID Microsoft Entra pour vous assurer que le principal de sécurité a reçu l’autorisation suffisante pour accéder à la ressource Azure.

La section suivante décrit les scénarios utilisant différentes bibliothèques d’écosystèmes Spring avec l’authentification OAuth.

Prise en charge des applications Spring Kafka

Cette section décrit le scénario d’utilisation de l’application Spring Boot à l’aide de la bibliothèque Spring Kafka ou Spring Integration Kafka.

Configuration des dépendances
<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<!-- Using Spring Kafka library only-->
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:2.8.6-->
</dependency>
<!-- Using Spring Integration library only -->
<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:5.5.12-->
</dependency>

Mise à jour de configuration

Pour utiliser l’authentification OAuth, spécifiez simplement le point de terminaison Event Hubs, comme illustré dans l’exemple suivant :

spring.kafka.bootstrap-servers=<NAMESPACENAME>.servicebus.windows.net:9093

Prise en charge de l’application Kafka du classeur Spring Cloud Stream

Cette section décrit le scénario d’utilisation pour les applications Spring Boot à l’aide de la bibliothèque Kafka du classeur Spring Cloud Stream.

Configuration des dépendances
<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-stream-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:3.2.3-->
</dependency>
Configuration

Pour utiliser l’authentification OAuth, spécifiez simplement le point de terminaison Event Hubs, comme indiqué dans l’exemple suivant :

spring.cloud.stream.kafka.binder.brokers=<NAMESPACENAME>.servicebus.windows.net:9093

Note

Si vous utilisez la version 4.3.0, n’oubliez pas de définir la propriété spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration pour activer l’ensemble du flux de travail d’authentification OAuth, où kafka-binder-name est kafka par défaut dans une seule application de classeur Kafka. La configuration AzureKafkaSpringCloudStreamConfiguration spécifie les paramètres de sécurité OAuth pour KafkaBinderConfigurationProperties, qui est utilisé dans KafkaOAuth2AuthenticateCallbackHandler pour activer Azure Identity.

Pour la version après 4.4.0, cette propriété est ajoutée automatiquement pour chaque environnement de classeur Kafka. Vous n’avez donc pas besoin de l’ajouter manuellement.

Utiliser l’identité managée pour l’authentification OAuth

  1. Pour utiliser l’identité managée, vous devez activer l’identité managée pour votre service et attribuer les rôles Azure Event Hubs Data Receiver et Azure Event Hubs Data Sender. Pour plus d’informations, consultez Attribuer des rôles Azure pour les droits d’accès.

  2. Configurez les propriétés suivantes dans votre fichier application.yml :

    spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true

    Important

    Si vous utilisez l’identité managée affectée par l’utilisateur, vous devez également ajouter la propriété spring.cloud.azure.credential.client-id avec votre ID client d’identité managée affectée par l’utilisateur.

Échantillons

Consultez le référentiel azure-spring-boot-samples sur GitHub.

Utiliser l’authentification de chaîne de connexion

Vous pouvez utiliser l’authentification de chaîne de connexion directement ou utiliser Azure Resource Manager pour récupérer la chaîne de connexion.

Note

Depuis la version 5.0.0, lors de l’utilisation de l’authentification de chaîne de connexion avec Spring Cloud Stream Framework, la propriété suivante est toujours nécessaire pour vous assurer que la chaîne de connexion peut prendre effet, où la valeur de <kafka-binder-name> doit être kafka lorsqu’il n’existe aucune configuration personnalisée pour votre nom de classeur Kafka : spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Si la version de spring-cloud-dependencies que vous avez utilisée est 2022.0.0, vous rencontrerez l’exception java.lang.IllegalStateException: kafka_context has not been refreshed yet. Pour résoudre ce problème, effectuez une mise à niveau vers une version ultérieure.

Configuration des dépendances

Ajoutez les dépendances suivantes si vous souhaitez migrer votre application Apache Kafka pour utiliser Azure Event Hubs pour Kafka.

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>

Si vous souhaitez récupérer la chaîne de connexion à l’aide d’Azure Resource Manager, ajoutez la dépendance suivante :

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-resourcemanager</artifactId>
</dependency>

Configuration

Utiliser directement la chaîne de connexion Event Hubs

La façon la plus simple de se connecter à Event Hubs pour Kafka est avec la chaîne de connexion. Ajoutez simplement la propriété suivante.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Utiliser Azure Resource Manager pour récupérer la chaîne de connexion

Si vous ne souhaitez pas configurer la chaîne de connexion dans votre application, vous pouvez utiliser Azure Resource Manager pour récupérer la chaîne de connexion. Pour vous authentifier auprès d’Azure Resource Manager, vous pouvez également utiliser des informations d’identification stockées dans Azure CLI ou un autre outil de développement local tel que Visual Studio Code ou Intellij IDEA. Vous pouvez également utiliser Managed Identity si votre application est déployée sur Azure Cloud. Assurez-vous que le principal dispose d’une autorisation suffisante pour lire les métadonnées de ressource.

Note

Si vous choisissez d’utiliser un principal de sécurité pour authentifier et autoriser avec Microsoft Entra ID pour accéder à une ressource Azure, consultez la section Autoriser l’accès avec l’ID Microsoft Entra pour vous assurer que le principal de sécurité a reçu l’autorisation suffisante pour accéder à la ressource Azure.

Pour utiliser Azure Resource Manager pour récupérer la chaîne de connexion, ajoutez simplement la propriété suivante.

spring:
  cloud:
    azure:
      profile:
        subscription-id: ${AZURE_SUBSCRIPTION_ID}
      eventhubs:
        namespace: ${AZURE_EVENTHUBS_NAMESPACE}
        resource:
          resource-group: ${AZURE_EVENTHUBS_RESOURCE_GROUP}

Échantillons

Consultez le référentiel azure-spring-boot-samples sur GitHub.