EMQX Kafka 桥接 MSK IAM 认证支持(Kafka Producer / Consumer / Confluent / Azure Event Hub)
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)
整体流程如下:
- 构建 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告警日志(这通常意味着凭证进程配置不当)。
- 先调用
- 确定区域:优先使用用户显式配置的
region;若未配置(即msk_iam模式),则通过实例元数据服务请求placement/region自动获取。 - 构造待签名请求:
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())。
- 计算签名:调用
erlcloud_aws:canonical_request、to_sign、signing_key、sha256_mac完成 SigV4 签名链,得到X-Amz-Signature。 - 产出 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:mockerlcloud_ec2_meta:get_metadata_v2_session_token返回mocked token,并 mockget_instance_metadata_v2:placement/region→sa-east-1iam/security-credentials/→mocked_role\niam/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 环境下的可验证性。
相关源码与文档速查:
- 变更记录:changes/ee/feat-15218.en.md
- 认证 schema 与 union 校验:apps/emqx_bridge_kafka/src/emqx_bridge_kafka.erl
- 认证到 brod 的映射:apps/emqx_bridge_kafka/src/emqx_bridge_kafka_impl.erl
- IAM token 生成实现:apps/emqx_bridge_kafka/src/emqx_bridge_kafka_msk_iam_authn.erl
- 配置字段说明(i18n):rel/i18n/emqx_bridge_kafka.hocon
- 相关测试:emqx_bridge_kafka_action_SUITE.erl、emqx_bridge_kafka_source_SUITE.erl