Поддержка Spring Cloud Azure Kafka

Применяется к: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

Поддержка Spring Cloud Azure Kafka помогает приложениям Spring проходить проверку подлинности и подключаться к Центры событий Azure с помощью учетных данных OAuth или строк подключения. В этой статье описываются поддерживаемые типы проверки подлинности, параметры конфигурации, зависимости и сценарии использования.

Поддерживаемая версия Kafka

Текущая версия начальной версии совместима с Apache Kafka Client 2.0.0 и использует Java 8 или более поздней версии.

Поддерживаемые типы проверки подлинности

Начальный механизм поддерживает следующие типы проверки подлинности:

Простая аутентификация с использованием строки подключения
- Проверка подлинности строки прямого подключения
- Проверка подлинности строки подключения на основе ARM
Проверка подлинности учетных данных OAuth
- Аутентификация с помощью управляемой идентификации
- Проверка подлинности имени пользователя и пароля
- Аутентификация субъекта-службы
- проверка подлинности DefaultAzureCredential

Принцип работы

Проверка подлинности учетных данных OAuth

В этом разделе описывается общий процесс аутентификации OAuth в Spring Cloud Azure.

Spring Cloud Azure сначала создает один из следующих типов учетных данных в зависимости от конфигурации проверки подлинности приложения:

ClientSecretCredential
ClientCertificateCredential
UsernamePasswordCredential
ManagedIdentityCredential

Если приложение не использует один из этих типов учетных данных, оно использует цепочку учетных данных через DefaultAzureTokenCredential, чтобы получать учетные данные из свойств приложения, переменных среды, управляемой идентификации или IDE. Подробные сведения см. в аутентификации Spring Cloud Azure.

Обычная проверка подлинности строки подключения

Для режима проверки подлинности строки подключения можно использовать проверку подлинности строки подключения напрямую или использовать Azure Resource Manager для получения строки подключения. Дополнительные сведения об использовании см. в разделе Базовое использование для проверки подлинности строки подключения.

Заметка

Начиная с версии 4.3.0, аутентификация с использованием строки подключения не рекомендуется; вместо неё следует использовать OAuth-аутентификацию.

Конфигурация

Настраиваемые свойства при использовании поддержки Kafka с проверкой подлинности OAuth

Azure Spring Cloud для Kafka поддерживает следующие два уровня параметров конфигурации:

Свойства Kafka для Spring Cloud Azure для Event Hubs
Параметры глобальной конфигурации проверки подлинности credential и profile с префиксами spring.cloud.azure.
Настройки, специфичные для Kafka. Настройки уровня Kafka также доступны для биндеров Spring Boot и Spring Cloud Stream в областях common, consumer, producer или admin с разными префиксами.

Глобальные свойства предоставляются через com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Специфичные для Kafka свойства доступны через org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) и org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (биндер Spring Cloud Stream).

В следующем списке показаны все поддерживаемые параметры конфигурации.

Свойства Kafka для Spring Cloud Azure для Центров событий.
- Свойство: spring.cloud.azure.eventhubs.kafka.enabled
- Описание: следует ли включить бесплатное подключение учетных данных к Центрам событий Azure для Kafka, значение по умолчанию — true.
Параметры конфигурации глобальной проверки подлинности Azure Spring Cloud
- Префикс: spring.cloud.azure
- Поддерживаемые параметры: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*
Полный список параметров глобальной конфигурации см. в разделе свойства глобальной конфигурации.
Общая конфигурация Spring Boot Kafka
- Префикс: spring.kafka.properties.azure
- Пример: spring.kafka.properties.azure.credential.*
Параметры конфигурации потребителей Spring Kafka
- Префикс: spring.kafka.consumer.properties.azure
- Пример: spring.kafka.consumer.properties.azure.credential.*
Параметры конфигурации производителя Spring Kafka
- Префикс: spring.kafka.producer.properties.azure
- Пример: spring.kafka.producer.properties.azure.credential.*
Параметры конфигурации администратора Spring Kafka
- Префикс: spring.kafka.admin.properties.azure
- Пример: spring.kafka.admin.properties.azure.credential.*
Общая конфигурация Spring Cloud Stream Kafka Binder
- Префикс: spring.cloud.stream.kafka.binder.configuration.azure
- Пример: spring.cloud.stream.kafka.binder.configuration.azure.credential.*
Конфигурация потребителя Spring Cloud Stream Kafka Binder
- Префикс: spring.cloud.stream.kafka.binder.consumer-properties.azure
- Пример: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*
Конфигурация производителя Spring Cloud Stream Kafka Binder
- Префикс: spring.cloud.stream.kafka.binder.producer-properties.azure
- Пример: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*
Конфигурация администратора Spring Cloud Stream Kafka Binder
- Префикс: не поддерживается, используйте общую конфигурацию Spring Boot Kafka или конфигурацию администратора.

В следующей таблице показаны общие параметры конфигурации Spring Boot Kafka:

Имя	Описание
`spring.kafka.properties.azure.credential.client-certificate-password`	Пароль файла сертификата.
`spring.kafka.properties.azure.credential.client-certificate-path`	Путь к файлу сертификата PEM для использования при выполнении проверки подлинности субъекта-службы с помощью Azure.
`spring.kafka.properties.azure.credential.client-id`	Идентификатор клиента, используемый для аутентификации субъекта-службы в Azure. Это устаревшее свойство.
`spring.kafka.properties.azure.credential.client-secret`	Секрет клиента, используемый при выполнении проверки подлинности субъекта-службы с помощью Azure. Это устаревшее свойство.
`spring.kafka.properties.azure.credential.managed-identity-enabled`	Следует ли включить управляемое удостоверение для проверки подлинности в Azure. Если `true` и задано `client-id`, идентификатором клиента будет идентификатор клиента управляемой идентификации, назначенной пользователем. Значение по умолчанию — `false`.
`spring.kafka.properties.azure.credential.password`	Пароль, используемый при выполнении проверки подлинности имени пользователя или пароля в Azure.
`spring.kafka.properties.azure.credential.username`	Имя пользователя, используемое при выполнении проверки подлинности имени пользователя или пароля в Azure.
`spring.kafka.properties.azure.profile.environment.active-directory-endpoint`	Конечная точка Microsoft Entra, к которой выполняется подключение.
`spring.kafka.properties.azure.profile.tenant-id`	Идентификатор клиента для ресурсов Azure. Значения, допустимые для `tenant-id`: `common`, `organizations`, `consumers`или идентификатор клиента.

Заметка

Для параметров конфигурации на разных уровнях действуют следующие правила. Более конкретные параметры конфигурации имеют более высокий приоритет, чем распространенные. Например:

Общие параметры конфигурации Spring Kafka заменяют глобальные параметры.
Параметры конфигурации потребителей Spring Kafka заменяют общие параметры.
Параметры конфигурации производителя Spring Kafka заменяют общие параметры.
Параметры конфигурации администратора Spring Kafka заменяют общие параметры.
Параметры биндера Kafka для Spring Cloud Stream следуют тому же шаблону.

Настраиваемые свойства при использовании поддержки Kafka с обычной проверкой подлинности строки подключения

В следующей таблице показаны общие параметры конфигурации Центров событий Spring Boot для Kafka:

Свойство	Описание
`spring.cloud.azure.eventhubs.kafka.enabled`	Следует ли включить поддержку Kafka Центров событий Azure. Значение по умолчанию — `true`.
`spring.cloud.azure.eventhubs.connection-string`	Строка подключения Центров событий Azure. Укажите это значение, если вы хотите предоставить строку подключения напрямую.
`spring.cloud.azure.eventhubs.namespace`	Пространство имен Центров событий Azure. Укажите это значение, если требуется получить сведения о подключении с помощью Azure Resource Manager.
`spring.cloud.azure.eventhubs.resource.resource-group`	Группа ресурсов пространства имен Центры событий Azure. Укажите это значение, если требуется получить сведения о подключении с помощью Azure Resource Manager.
`spring.cloud.azure.profile.subscription-id`	Идентификатор подписки. Укажите это значение, если требуется получить сведения о подключении с помощью Azure Resource Manager.

Настройка зависимостей

Добавьте в проект следующую зависимость. Эта зависимость автоматически добавляет в ваш проект зависимость spring-boot-starter.

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

Заметка

Не забудьте добавить BOM spring-cloud-azure-dependencies вместе с предыдущей зависимостью. Дополнительные сведения см. в разделе Начало работы руководства разработчика Spring Cloud azure.

Базовое использование

В следующих разделах показаны классические сценарии использования приложений Spring Boot.

Использование проверки подлинности OAuth

При использовании проверки подлинности OAuth, предоставляемой Spring Cloud Azure для Kafka, можно настроить определенные учетные данные с помощью предыдущих конфигураций. Кроме того, можно не настраивать учетные данные. В этом случае Spring Cloud Azure загружает учетные данные из среды. В этом разделе описывается загрузка учетных данных из среды Azure CLI или среды размещения Приложения Azure Spring.

Заметка

Если вы решили использовать субъект безопасности для проверки подлинности и авторизации с помощью Microsoft Entra ID для доступа к ресурсу Azure, ознакомьтесь с разделом "Авторизация доступа с помощью Microsoft Entra ID", чтобы убедиться, что субъект безопасности имеет достаточно разрешений для доступа к ресурсу Azure.

В следующем разделе описаны сценарии, использующие различные библиотеки экосистем Spring с проверкой подлинности OAuth.

Поддержка приложений Spring Kafka

В этом разделе описывается сценарий использования приложения Spring Boot, использующего Spring Kafka или библиотеку Kafka для интеграции Spring.

Настройка зависимостей

<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>

Обновление конфигурации

Чтобы использовать проверку подлинности OAuth, укажите конечную точку Центров событий, как показано в следующем примере:

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

Поддержка приложений с биндером Kafka в Spring Cloud Stream

В этом разделе описывается сценарий использования приложений Spring Boot, использующих библиотеку Kafka для привязки Spring Cloud Stream.

Настройка зависимостей

<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>

Конфигурация

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

Заметка

Если вы используете версию 4.3.0, задайте spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration свойство, чтобы включить весь рабочий процесс проверки подлинности OAuth. Значение kafka-binder-name по умолчанию используется kafka в одном приложении привязки Kafka. AzureKafkaSpringCloudStreamConfiguration Конфигурация задает параметры безопасности OAuth для KafkaBinderConfigurationProperties. Эта конфигурация используется в KafkaOAuth2AuthenticateCallbackHandler для включения Azure Identity.

В версиях после 4.4.0 это свойство автоматически добавляется для каждой среды binder Kafka, поэтому его не нужно добавлять вручную.

Использование управляемого удостоверения для проверки подлинности OAuth

Чтобы использовать управляемое удостоверение, включите его для вашего сервиса и назначьте роли Центры событий Azure Data Receiver и Центры событий Azure Data Sender. Дополнительные сведения см. в статье Назначение ролей Azure для прав доступа.
Настройте следующие свойства в файле application.yml:
```
spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
```
Важно

Если вы используете управляемое удостоверение, назначаемое пользователем, добавьте свойство spring.cloud.azure.credential.client-id с идентификатором клиента управляемого удостоверения, назначаемого пользователем.

Образцы

См. репозиторий azure-spring-boot-samples на сайте GitHub.

Использование проверки подлинности строки подключения

Для получения строки подключения можно использовать проверку подлинности строки подключения напрямую или использовать Azure Resource Manager.

Spring Cloud Azure 5.x
Spring Cloud Azure 4.x

Заметка

Начиная с версии 5.0.0, при использовании аутентификации по строке подключения с фреймворком Spring Cloud Stream вам по-прежнему требуется следующее свойство, чтобы строка подключения работала. Значение <kafka-binder-name> должно быть kafka, если вы не настраиваете имя биндинга Kafka: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Если версия 2022.0.0, которую вы используете, — spring-cloud-dependencies, возникает исключение java.lang.IllegalStateException: kafka_context has not been refreshed yet. Чтобы решить эту проблему, выполните обновление до более поздней версии.

Заметка

Начиная с версии 4.5.0, при использовании аутентификации по строке подключения в фреймворке Spring Cloud Stream необходимо задать следующее свойство, чтобы строка подключения работала корректно. Значение <kafka-binder-name> должно быть kafka, если вы не задаёте собственное имя биндера Kafka: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Настройка зависимостей

Добавьте следующие зависимости, если вы хотите перенести приложение Apache Kafka для использования Центров событий Azure для Kafka.

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

Если вы хотите получить строка подключения с помощью Azure Resource Manager, добавьте следующую зависимость:

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

Конфигурация

Используйте строку подключения Центров событий напрямую

Самый простой способ подключения к Центрам событий для Kafka — это строка подключения. Просто добавьте следующее свойство.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}

Получение строки подключения с помощью Azure Resource Manager

Если вы не хотите настроить строку подключения в приложении, можно использовать Azure Resource Manager для получения строки подключения. Для проверки подлинности с помощью Azure Resource Manager можно также использовать учетные данные, хранящиеся в Azure CLI или другом локальном средстве разработки, например Visual Studio Code или Intellij IDEA. Кроме того, можно использовать управляемое удостоверение, если приложение развернуто в облаке Azure. Просто убедитесь, что субъект имеет достаточно разрешений для чтения метаданных ресурса.

Заметка

Чтобы использовать Azure Resource Manager для получения строки подключения, просто добавьте следующее свойство.

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

Образцы

См. репозиторий azure-spring-boot-samples на сайте GitHub.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-09-21

Поддержка Spring Cloud Azure Kafka

Поддерживаемая версия Kafka

Поддерживаемые типы проверки подлинности

Принцип работы

Проверка подлинности учетных данных OAuth

Обычная проверка подлинности строки подключения

Конфигурация

Настраиваемые свойства при использовании поддержки Kafka с проверкой подлинности OAuth

Настраиваемые свойства при использовании поддержки Kafka с обычной проверкой подлинности строки подключения

Настройка зависимостей

Базовое использование

Использование проверки подлинности OAuth

Поддержка приложений Spring Kafka

Настройка зависимостей

Обновление конфигурации

Поддержка приложений с биндером Kafka в Spring Cloud Stream

Настройка зависимостей

Конфигурация

Использование управляемого удостоверения для проверки подлинности OAuth

Образцы

Использование проверки подлинности строки подключения

Настройка зависимостей

Конфигурация

Используйте строку подключения Центров событий напрямую

Получение строки подключения с помощью Azure Resource Manager

Образцы

Обратная связь

Дополнительные ресурсы