EMQX Kafka 桥接 MSK IAM 认证支持(Kafka Producer / Consumer / Confluent / Azure Event Hub)

原创2026-09-22 22:20:511,977 阅读
文章标签:物联网IoT协议消息队列后端消息路由数据集成认证鉴权可观测性云原生

EMQX Kafka 桥接 MSK IAM 认证支持(Kafka Producer / Consumer / Confluent / Azure Event Hub)

导读

EMQX 在 Kafka 桥接(Bridge)与连接器(Connector)中引入了对 AWS MSK(Managed Streaming for Apache Kafka)IAM 认证的原生支持,覆盖 Kafka Producer、Kafka Consumer、Confluent 与 Azure Event Hub 四类场景。本文以 changes/ee/feat-15218.en.md 变更记录为核心骨架,结合仓库源码与配置 schema,深入讲解 msk_iam 与 msk_iam_roles_anywhere 两种认证方式的原理、配置项、前置条件与测试验证,帮助你在 EC2 环境中用临时安全凭证连接 MSK 集群,或将凭证下发(credential process)模式用于 IAM Roles Anywhere 场景。

一、功能概览:一次引入,四类 Kafka 通道全部覆盖

本变更的核心内容为:

Added support for MSK IAM authentication for all Kafka Connectors (Kafka Producer, Kafka Consumer, Confluent, Azure Event Hub).

即:为所有 Kafka 连接器增加 MSK IAM 认证支持,涉及的组件包括:

  • Kafka Producer(Kafka 生产者 Action / Connector,用于将 MQTT 消息写入 Kafka)
  • Kafka Consumer(Kafka 消费者 Bridge,用于从 Kafka 拉取消息转发到 MQTT)
  • Confluent(emqx_bridge_confluent 桥接,用于 Confluent Cloud)
  • Azure Event Hub(emqx_bridge_azure_event_hub 桥接)

从源码结构看,这些桥接最终都复用 emqx_bridge_kafka 模块的认证配置模型(authentication 字段的 union 类型),因此在一次实现中即可让所有 Kafka 系连接器同时获得 IAM 认证能力,无需为每个桥接单独重复实现。

二、MSK IAM 认证的两种模式

在 emqx_bridge_kafka 的认证 schema 中,authentication 字段是一个 union 类型,允许的值包括 none、msk_iam、msk_iam_roles_anywhere、oauth(OAuth2 Client Credentials)、plain / scram_sha_256 / scram_sha_512(用户名密码)、kerberos(GSSAPI)。其中与 AWS IAM 相关的有两种:

2.1 msk_iam:基于 EC2 实例元数据服务(IMDS)的自动凭证获取

msk_iam 是最直接的模式,其核心特征是:

  • 前置条件:EMQX 必须运行在 AWS EC2 实例上(官方 i18n 文档明确注明 "This only works when EMQX is running on an EC2 instance");
  • 凭证来源:通过 EC2 实例元数据服务 v2(IMDSv2,即 169.254.169.254)自动获取实例角色(instance role)对应的临时安全凭证;
  • 使用方式:只需在配置中将 authentication 设置为字符串字面量 "msk_iam",无需填写任何密钥、区域等参数。

配置示例(HOCON):

authentication = "msk_iam"

在 emqx_bridge_kafka.erl 的 union 选择器(auth_union_member_selector)中,msk_iam 被直接映射为原子类型 msk_iam;随后 emqx_bridge_kafka_impl.erl 的 sasl/1 函数将其转换为 brod 客户端的 OAuth 回调风格认证:

sasl(msk_iam) ->
    {callback, brod_oauth, #{
        token_callback => fun emqx_bridge_kafka_msk_iam_authn:token_callback/1
    }};

也就是说,EMQX 通过 brod_oauth 的 token 回调机制,在每个 token 需要刷新时向 Kafka 集群提供一个由 IAM 签名的预签名 URL 作为凭证。

2.2 msk_iam_roles_anywhere:支持 IAM Roles Anywhere 的凭证下发模式

msk_iam_roles_anywhere 模式面向无法直接使用 EC2 实例角色的场景,例如 Kubernetes 中的 Pod、本地 IDC 或非 EC2 虚拟机。该模式通过 IAM Roles Anywhere 的凭证下发进程(credential process)获取临时凭证,需要显式配置以下三个字段(见 emqx_bridge_kafka.erl):

字段 类型 是否必填 说明
type msk_iam_roles_anywhere 必填 标记认证方式,union 选择器据此分派到对应 schema 分支
endpoint binary 必填 运行 AWS IAM Roles Anywhere 凭证进程(credential process)API 的地址,必须带 http:// scheme(由 msk_iam_roles_anywhere_endpoint_validator 校验,仅接受 http 协议)
region binary 必填 MSK 集群所在的 AWS 区域

配置示例:

authentication = {
  type = "msk_iam_roles_anywhere"
  endpoint = "http://127.0.0.1:8085"   # credential process 提供的 API 地址
  region  = "us-east-1"
}

对应源码中 emqx_bridge_kafka_impl.erl 的处理:

sasl(#{type := msk_iam_roles_anywhere} = Opts) ->
    #{region := _Region, endpoint := _Endpoint} = Opts,
    {callback, brod_oauth, #{
        token_callback => emqx_bridge_kafka_msk_iam_authn:mk_token_callback(Opts)
    }};

这里通过 mk_token_callback(Opts) 将 endpoint、region 等选项固化到回调闭包中,供后续每次生成 token 时使用。

三、底层原理:token 是如何生成与签名的

无论哪种模式,最终都收敛到 emqx_bridge_kafka_msk_iam_authn.erl 中的 token 生成逻辑。该模块实现了 AWS SigV4 风格的请求签名,并最终产出一个 base64url 编码、不带 padding 的预签名 URL,作为 brod_oauth 的 token 提交给 Kafka broker。

3.1 签名参数与服务标识

关键常量:

  • SERVICE = "kafka-cluster":SigV4 签名中的服务名,对应 MSK IAM 访问控制所用的服务标识;
  • EMPTY_PAYLOAD_HASH:空请求体(GET /)的 SHA-256 哈希,即 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855;
  • 预签名 URL 的有效期为 X-Amz-Expires = 900 秒(15 分钟)。

3.2 token 生成流程(generate_token/1)

整体流程如下:

  1. 构建 AWS 配置(load_config/1):
    • 先调用 get_session_token 通过 erlcloud_ec2_meta:get_metadata_v2_session_token 获取 IMDSv2 会话 token;
    • 再请求 iam/security-credentials/ 列出实例角色,取第一个角色名;
    • 随后请求 iam/security-credentials/<Role> 获取 AccessKeyId、SecretAccessKey、Token 三元组;
    • 若返回的 Token 为空,则抛出 kafka_msk_credential_endpoint_returned_empty_token 告警日志(这通常意味着凭证进程配置不当)。
  2. 确定区域:优先使用用户显式配置的 region;若未配置(即 msk_iam 模式),则通过实例元数据服务请求 placement/region 自动获取。
  3. 构造待签名请求:GET https://kafka.<region>.amazonaws.com/,查询参数包含:
    • Action=kafka-cluster:Connect(MSK IAM 的 Connect 动作);
    • X-Amz-Security-Token、X-Amz-Algorithm=AWS4-HMAC-SHA256、X-Amz-Credential、X-Amz-Date、X-Amz-Expires、X-Amz-SignedHeaders=host;
    • 附加 User-Agent: emqx/<版本>(来自 emqx_release:version())。
  4. 计算签名:调用 erlcloud_aws:canonical_request、to_sign、signing_key、sha256_mac 完成 SigV4 签名链,得到 X-Amz-Signature。
  5. 产出 token:将所有查询参数拼接为查询字符串,生成完整 URL 后使用 base64(urlsafe、无 padding) 编码,即为 brod_oauth 所需的 token 字符串。

整个过程被包裹在 token_callback/2 的 try/catch 中:任何异常都会被记录为 kafka_msk_token_exception 警告日志并返回 {error, failed_to_fetch_token},避免崩溃影响桥接主流程。

四、配置要点与前置条件

4.1 前置条件核对清单

模式 运行环境 必需配置 凭证来源
msk_iam 必须为 AWS EC2 实例 仅 authentication = "msk_iam" EC2 实例角色(IMDSv2)
msk_iam_roles_anywhere EC2 / K8s / 本地均可 type、endpoint、region 自建 credential process 返回的临时凭证

4.2 结合 Kafka 连接器完整配置示例

以下是一个使用 msk_iam 的 Kafka Producer 连接器完整配置(字段与默认值依据 emqx_bridge_kafka.erl 的 kafka_connector_config_fields):

authentication = "msk_iam"
bootstrap_hosts = "b-1.example.msk.us-east-1.amazonaws.com:9098,b-2.example.msk.us-east-1.amazonaws.com:9098"
connect_timeout = "5s"
min_metadata_refresh_interval = "3s"
metadata_request_timeout = "5s"
request_timeout = "30s"
enable = true
socket_opts = {
  sndbuf = "1MB"
  recbuf = "1MB"
  nodelay = true
  tcp_keepalive = "none"
}
ssl = {
  enable = true
  server_name_indication = "auto"
}

使用 msk_iam_roles_anywhere 时只需替换 authentication 块并确保 endpoint 指向可访问的 credential process 服务。

说明:authentication 字段的 union 校验逻辑位于 emqx_bridge_kafka.erl,若传入了不在预期范围内的值,会抛出包含 expected => "none | msk_iam | msk_iam_roles_anywhere | oauth | plain | scram_sha_256 | scram_sha_512 | kerberos" 的错误提示,可用于快速定位配置拼写问题。

五、测试验证:仓库中如何验证 MSK IAM 认证

仓库通过 meck 模拟 IMDSv2 元数据服务,对两种模式进行了端到端测试,可在不依赖真实 AWS 环境的情况下验证认证流程:

  • emqx_bridge_kafka_action_SUITE.erl 中的 mock_iam_metadata_v2_calls/0:mock erlcloud_ec2_meta:get_metadata_v2_session_token 返回 mocked token,并 mock get_instance_metadata_v2:
    • placement/region → sa-east-1
    • iam/security-credentials/ → mocked_role\n
    • iam/security-credentials/mocked_role → 包含 AccessKeyId、SecretAccessKey、Token 的 JSON
  • t_msk_iam_authn(Producer 侧见 emqx_bridge_kafka_action_SUITE.erl,Consumer 侧见 emqx_bridge_kafka_source_SUITE.erl):通过 authentication => <<"msk_iam">> 创建连接器,并断言 token 回调被调用;
  • t_msk_iam_roles_anywhere_authn(emqx_bridge_kafka_action_SUITE.erl 及 emqx_bridge_kafka_source_SUITE.erl):传入 type、endpoint、region 配置创建连接器,覆盖正常凭证返回与空 Token 报错(kafka_msk_credential_endpoint_returned_empty_token)两条路径。

此外,emqx_bridge_kafka_tests.erl 在认证用例矩阵中也包含 {"MSK IAM", <<"msk_iam">>},确保该认证方式参与常规 schema 校验用例。

六、与其他认证方式的横向对比

emqx_bridge_kafka 的 authentication union 支持多达 7 种方式,便于你在不同安全要求下选择:

认证方式 适用场景 配置复杂度 凭证生命周期
none 内网无认证 Kafka 最低 无
plain / scram_sha_256 / scram_sha_512 传统用户名密码 / SASL SCRAM 低 静态
oauth(Client Credentials) 支持 OAuth 的 Kafka(如 Confluent Cloud) 中 由 OAuth 服务端签发
kerberos 企业 Kerberos GSSAPI 环境 高 由 KDC 管理
msk_iam AWS EC2 上的 MSK 极低(零配置) 15 分钟自动轮换(IMDSv2)
msk_iam_roles_anywhere K8s / 非 EC2 环境访问 MSK 中(需自建 credential process) 由 credential process 轮换

从安全角度,msk_iam 无需在配置中存放任何长期密钥,临时凭证由 AWS 自动轮换(预签名 URL 有效期 900 秒),显著降低凭证泄露风险,这也是该特性对生产环境的重要价值。

七、小结

MSK IAM 认证支持让 EMQX 的 Kafka 系连接器(Producer、Consumer、Confluent、Azure Event Hub)能够在 AWS 生态中免静态密钥接入:EC2 场景下只需一行 authentication = "msk_iam",非 EC2 场景则通过 msk_iam_roles_anywhere + credential process 完成凭证下发。底层由 emqx_bridge_kafka_msk_iam_authn.erl 基于 IMDSv2 与 SigV4 签名实现 token 生成,并通过 brod_oauth 回调接入 broker 认证链路,仓库内置的 meck 测试用例则保证了该链路在 CI 环境下的可验证性。

相关源码与文档速查:

登录后查看全文
emqx