Prise en charge d’Azure Kafka Azure Spring Cloud

  • S’applique à: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

La prise en charge de Spring Cloud Azure Kafka aide les applications Spring à s’authentifier et à se connecter à Azure Event Hubs à l’aide d’informations d’identification OAuth ou de chaînes de connexion. Cet article décrit les types d’authentification pris en charge, les options de configuration, les dépendances et les scénarios d’utilisation.

Version de Kafka prise en charge

La version actuelle du starter est compatible avec Apache Kafka Clients 2.0.0 et utilise Java 8 ou version ultérieure.

Types d’authentification pris en charge

Le démarrage prend en charge les types d’authentification suivants :

  • 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 l’application n’utilise pas l’un de ces types d’informations d’identification, l’application utilise la chaîne DefaultAzureTokenCredential d’informations d’identification pour obtenir des informations d’identification à partir des propriétés de l’application, des variables d’environnement, une 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.

Remarque

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

Paramétrage

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, utilisez la configuration commune ou administrateur spring Boot Kafka.

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

Nom Descriptif
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 le client-id paramètre est défini, l’ID client est l’ID client d’identité managée attribué 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.

Remarque

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 suivent le même modèle.

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é Descriptif
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. Cette dépendance inclut automatiquement la spring-boot-starter dépendance dans votre projet.

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

Remarque

N’oubliez pas d’ajouter le boM spring-cloud-azure-dependencies avec la dépendance précédente. 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 que Spring Cloud Azure fournit pour Kafka, vous pouvez configurer des informations d’identification spécifiques à l’aide des configurations précédentes. Vous pouvez également choisir de ne pas configurer d’informations d’identification. Dans ce cas, Spring Cloud Azure charge les informations d’identification de l’environnement. Cette section explique comment charger des informations d’identification à partir de l’environnement Azure CLI ou de l’environnement d’hébergement Azure Spring Apps.

Remarque

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 Microsoft Entra ID pour vous assurer que le principal de sécurité dispose d’une autorisation suffisante pour accéder à la ressource Azure.

La section suivante décrit les scénarios qui utilisent 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 d’une application Spring Boot qui utilise Spring Kafka ou la bibliothèque 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 le point de terminaison Event Hubs, comme indiqué 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 qui utilisent 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>
Paramétrage

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

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

Remarque

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

Pour les versions ultérieures 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, activez l’identité managée pour votre service et attribuez les rôles et Azure Event Hubs Data Sender les Azure Event Hubs Data Receiver rôles. 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 une identité managée affectée par l’utilisateur, ajoutez également 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 azure-spring-boot-samples référentiel 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.

Remarque

Depuis la version 5.0.0, lorsque vous utilisez chaîne de connexion authentification avec Spring Cloud Stream Framework, vous avez toujours besoin de la propriété suivante pour vous assurer que le chaîne de connexion fonctionne. La valeur <kafka-binder-name> doit être kafka si vous ne personnalisez pas 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 votre utilisation est 2022.0.0, vous rencontrez 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 le chaîne de connexion à l’aide de Azure Resource Manager, ajoutez la dépendance suivante :

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

Paramétrage

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. Vérifiez simplement que le principal dispose d’une autorisation suffisante pour lire les métadonnées de ressource.

Remarque

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 Microsoft Entra ID pour vous assurer que le principal de sécurité dispose d’une 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 azure-spring-boot-samples référentiel sur GitHub.

  • Last updated on