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 应用程序使用 OAuth 凭据或连接字符串进行身份验证并连接到Azure 事件中心。本文介绍支持的身份验证类型、配置选项、依赖项和使用情况方案。

支持的 Kafka 版本

初学者的当前版本与 Apache Kafka 客户端 2.0.0 兼容，并使用 Java 8 或更高版本。

支持的身份验证类型

该 starter 支持以下身份验证类型：

纯连接字符串身份验证
- 直接使用连接字符串进行身份验证
- 基于 ARM 的连接字符串身份验证
OAuth 凭据身份验证
- 托管标识身份验证
- 用户名/密码身份验证
- 服务主体身份验证
- DefaultAzureCredential 身份验证

工作原理

OAuth 凭据身份验证

本部分介绍 Spring Cloud Azure OAuth 身份验证的总体工作流。

Spring Cloud Azure首先生成以下类型的凭据之一，具体取决于应用程序身份验证配置：

ClientSecretCredential
ClientCertificateCredential
UsernamePasswordCredential
ManagedIdentityCredential

如果应用程序不使用这些类型的凭据之一，则应用程序使用凭据链 DefaultAzureTokenCredential 从应用程序属性、环境变量、托管标识或 IDE 获取凭据。有关详细信息，请参阅 Spring Cloud Azure 身份验证。

纯连接字符串身份验证

对于连接字符串身份验证模式，可以直接使用连接字符串身份验证或使用 Azure 资源管理器检索连接字符串。有关用法的详细信息，请参阅连接字符串身份验证的基本用法部分。

注意

自 4.3.0 版本起，连接字符串身份验证已弃用，建议改用 OAuth 身份验证。

配置

将 Kafka 支持与 OAuth 身份验证配合使用时可配置的属性

适用于 Kafka 的 Spring Cloud Azure 支持以下两个级别的配置选项：

Spring Cloud Azure for Event Hubs Kafka 属性。
前缀为 spring.cloud.azure 的 credential 和 profile 的全局身份验证配置选项。
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 绑定器）暴露。

以下列表显示所有受支持的配置选项。

Spring Cloud Azure for Event Hubs Kafka 属性。
- 属性：spring.cloud.azure.eventhubs.kafka.enabled
- 说明：是否启用与适用于 Kafka 的 Azure 事件中心建立无凭据连接，默认值为 true。
Spring Cloud Azure 全局身份验证配置选项
- 前缀：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`	使用 Azure 执行服务主体身份验证时要使用的 PEM 证书文件的路径。
`spring.kafka.properties.azure.credential.client-id`	使用 Azure 执行服务主体身份验证时要使用的客户端 ID。这是一个遗留属性。
`spring.kafka.properties.azure.credential.client-secret`	使用 Azure 执行服务主体身份验证时要使用的客户端密码。这是一个遗留属性。
`spring.kafka.properties.azure.credential.managed-identity-enabled`	是否允许托管标识通过 Azure 进行身份验证。如果 `true` 且已设置 `client-id`，则客户端 ID 为用户分配的托管标识客户端 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 资源的租户 ID。允许 `tenant-id` 的值包括：`common`、`organizations`、`consumers`或租户 ID。

注意

不同级别的配置选项应用以下规则。特定配置选项的优先级高于常见配置选项。例如：

Spring Kafka 通用配置选项取代了全局选项。
Spring Kafka 使用者配置选项取代了常用选项。
Spring Kafka 生成者配置选项取代了常用选项。
Spring Kafka 管理员配置选项取代了常用选项。
Spring Cloud Stream Kafka Binder 选项遵循相同的模式。

使用 Kafka 支持并采用纯连接字符串身份验证时的可配置属性

下表显示了适用于 Kafka 的 Spring Boot 事件中心常见配置选项：

财产	描述
`spring.cloud.azure.eventhubs.kafka.enabled`	是否启用 Azure 事件中心 Kafka 支持。默认值为 `true`。
`spring.cloud.azure.eventhubs.connection-string`	Azure 事件中心连接字符串。如果要直接提供连接字符串，请提供此值。
`spring.cloud.azure.eventhubs.namespace`	Azure 事件中心命名空间。若要通过 Azure 资源管理器检索连接信息，请提供此值。
`spring.cloud.azure.eventhubs.resource.resource-group`	Azure 事件中心命名空间的资源组。若要通过 Azure 资源管理器检索连接信息，请提供此值。
`spring.cloud.azure.profile.subscription-id`	订阅 ID。若要通过 Azure 资源管理器检索连接信息，请提供此值。

设置依赖项

将以下依赖项添加到项目。此依赖项会自动包含项目中的 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 身份验证

使用 Spring Cloud Azure为 Kafka 提供的 OAuth 身份验证时，可以使用上述配置来配置特定凭据。或者，您也可以选择不配置任何凭据。在这种情况下，Spring Cloud Azure从环境中加载凭据。本部分介绍如何从Azure CLI环境或Azure Spring Apps托管环境加载凭据。

注意

如果选择使用安全主体对Microsoft Entra ID进行身份验证和授权以访问Azure资源，请参阅“使用 Microsoft Entra ID 授权访问”部分，以确保安全主体有足够的权限访问Azure资源。

以下部分介绍将不同的 Spring 生态系统库用于 OAuth 身份验证的方案。

Spring Kafka 应用程序支持

本部分介绍使用 Spring Kafka 或 Spring Integration Kafka 库的 Spring Boot 应用程序的使用方案。

设置依赖项

<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

Spring Cloud Stream 绑定器对 Kafka 应用程序的支持

本部分介绍使用 Spring Cloud Stream 绑定器 Kafka 库的 Spring Boot 应用程序的使用方案。

设置依赖项

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

配置

若要使用 OAuth 身份验证，请指定事件中心终结点，如以下示例所示：

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 绑定器应用程序中，kafka-binder-name 默认是 kafka。 AzureKafkaSpringCloudStreamConfiguration 配置指定了 KafkaBinderConfigurationProperties 的 OAuth 安全参数。此配置用于在 KafkaOAuth2AuthenticateCallbackHandler 中启用 Azure 标识。

对于之后 4.4.0的版本，此属性会自动为每个 Kafka 绑定器环境添加，因此无需手动添加它。

将托管标识用于 OAuth 身份验证

若要使用托管标识，请为服务启用托管标识并分配 Azure 事件中心 Data Receiver 和 Azure 事件中心 Data Sender 角色。有关详细信息，请参阅分配 Azure 角色以获取访问权限。
在 application.yml 文件中配置以下属性：
```
spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
```
重要

如果使用用户分配的托管标识，则还使用用户分配的托管标识客户端 ID 添加该属性 spring.cloud.azure.credential.client-id 。

样品

azure-spring-boot-samples请参阅 GitHub 上的存储库。

使用连接字符串身份验证

可以直接使用连接字符串身份验证或使用 Azure 资源管理器检索连接字符串。

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

注意

自 5.0.0 版本起，在 Spring Cloud Stream 框架中使用连接字符串进行身份验证时，仍需要以下属性以确保连接字符串能够正常工作。如果您未自定义 Kafka 绑定器名称，<kafka-binder-name> 的值应为 kafka：spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

如果使用的版本 spring-cloud-dependencies 是 2022.0.0，则会遇到异常 java.lang.IllegalStateException: kafka_context has not been refreshed yet。若要解决此问题，请升级到更高版本。

注意

自 4.3.0 版本起，连接字符串身份验证已弃用，建议改用 OAuth 身份验证。

自 4.5.0 版本起，在 Spring Cloud Stream 框架中使用连接字符串身份验证时，需要设置以下属性以确保连接字符串生效。如果未自定义 Kafka 绑定器名称，<kafka-binder-name> 的值应为 kafka：spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

依赖项设置

如果要迁移 Apache Kafka 应用程序以使用适用于 Kafka 的 Azure 事件中心，请添加以下依赖项。

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

如果要使用 Azure 资源管理器检索连接字符串，请添加以下依赖项：

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

配置

直接使用 Event Hubs 连接字符串

连接到 Kafka 事件中心的最简单方法是使用连接字符串。只需添加以下属性即可。

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

使用 Azure 资源管理器检索连接字符串

如果不想在应用程序中配置连接字符串，可以使用 Azure 资源管理器检索连接字符串。若要使用 Azure 资源管理器进行身份验证，还可以使用存储在 Azure CLI 或其他本地开发工具（如 Visual Studio Code 或 Intellij IDEA）中的凭据。或者，如果应用程序部署到 Azure 云，则可以使用托管标识。只需确保主体具有读取资源元数据的足够权限。

注意

若要使用 Azure 资源管理器检索连接字符串，只需添加以下属性。

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

Spring Cloud Azure Kafka 支持

支持的 Kafka 版本

支持的身份验证类型

工作原理

OAuth 凭据身份验证

纯连接字符串身份验证

配置

将 Kafka 支持与 OAuth 身份验证配合使用时可配置的属性

使用 Kafka 支持并采用纯连接字符串身份验证时的可配置属性

设置依赖项

基本用法

使用 OAuth 身份验证

Spring Kafka 应用程序支持

设置依赖项

配置更新

Spring Cloud Stream 绑定器对 Kafka 应用程序的支持

设置依赖项

配置

将托管标识用于 OAuth 身份验证

样品

使用连接字符串身份验证

依赖项设置

配置

直接使用 Event Hubs 连接字符串

使用 Azure 资源管理器检索连接字符串

样品

反馈

其他资源