MinIO Identity Management Plugin：通过外部 Webhook 扩展自定义 Token 认证（AssumeRoleWithCustomToken）

MinIO 支持将自定义认证逻辑外置为 Identity Management Plugin（身份管理插件）：配置该插件的 webhook 后，MinIO 的 STS 层会启用 AssumeRoleWithCustomToken API 扩展，客户端携带一个对 MinIO 而言不透明的（opaque）token 发起请求，MinIO 将该 token 转发给插件端点完成校验，校验通过后由 MinIO 签发临时 STS 凭证。本文完整梳理该机制的认证流程、mc admin config set 配置参数、插件端 REST 请求/响应契约，并结合仓库源码说明凭证签发时的 claims 合并、有效期裁剪与错误处理逻辑，并给出可直接运行的玩具级插件示例。

一、机制定位与适用场景

从文档定义来看，Identity Management Plugin 的作用是让 MinIO 集成任意自定义认证方式。配置之后：

1. 用户或应用向 AssumeRoleWithCustomToken API 出示一个 token；
2. MinIO 将该 token 通过 POST 请求发送到配置的插件 webhook 端点；
3. 插件返回用户身份、凭证最大有效期以及附加 claims；
4. MinIO 据此生成一组临时 STS 凭证，用于访问对象存储。

文档明确指出两点使用约束：

• 认证流程与 OpenID 类似，但 token 对 MinIO 是不透明的——MinIO 只负责转发，解析与校验完全由插件完成；
• 没有 Console UI 集成，主要用于机器认证（machine authentication） 场景，而非人类用户登录。

从源码结构看，该能力在 STS 路由中注册：cmd/sts-handlers.go 中定义了 customTokenIdentity = "AssumeRoleWithCustomToken"，并在 stsRouter 上以 POST 方法、Action=AssumeRoleWithCustomToken 查询参数挂载到 sts.AssumeRoleWithCustomToken 处理器（约 L185-L187）。

二、配置方法与环境变量参数

该插件可通过 MinIO 标准配置 API（mc admin config set/get）或等价的环境变量配置。文档给出的配置项清单如下：

$ mc admin config set myminio identity_plugin --env
KEY:
identity_plugin  enable Identity Plugin via external hook

ARGS:
MINIO_IDENTITY_PLUGIN_URL*          (url)       plugin hook endpoint (HTTP(S)) e.g. "http://localhost:8181/path/to/endpoint"
MINIO_IDENTITY_PLUGIN_AUTH_TOKEN    (string)    authorization token for plugin hook endpoint
MINIO_IDENTITY_PLUGIN_ROLE_POLICY*  (string)    policies to apply for plugin authorized users
MINIO_IDENTITY_PLUGIN_ROLE_ID       (string)    unique ID to generate the ARN
MINIO_IDENTITY_PLUGIN_COMMENT       (sentence)  optionally add a comment to this setting

各参数要点：

参数	是否必填	说明
MINIO_IDENTITY_PLUGIN_URL	是（*）	插件 webhook 端点，HTTP(S) URL，如 http://localhost:8181/path/to/endpoint
MINIO_IDENTITY_PLUGIN_AUTH_TOKEN	否	访问插件端点时使用的授权 token
MINIO_IDENTITY_PLUGIN_ROLE_POLICY	是（*）	授予插件认证用户的策略，可为逗号分隔的策略名列表
MINIO_IDENTITY_PLUGIN_ROLE_ID	否	用于生成 ARN 的唯一 ID
MINIO_IDENTITY_PLUGIN_COMMENT	否	为此配置附加注释

几个容易踩坑的细节（均来自文档原文）：

• AUTH_TOKEN 的传递方式：若提供了 MINIO_IDENTITY_PLUGIN_AUTH_TOKEN，它会被放入 MinIO 发往插件请求的 authorization 头中，插件端据此可校验请求来源。
• ROLE_POLICY 必填且支持列表：MINIO_IDENTITY_PLUGIN_ROLE_POLICY 是必需参数，可写多个逗号分隔的策略名。
• Role ARN 的确定方式：配置完成后，MinIO 服务端会在日志中打印生成的 Role ARN；默认基于插件 URL 生成。若不希望 ARN 依赖 URL（例如 URL 变更会导致 ARN 变化），应通过 MINIO_IDENTITY_PLUGIN_ROLE_ID 指定一个唯一值来稳定 ARN。

在仓库源码中可印证配置入口：cmd/config-current.go 注册了 config.IdentityPluginSubSys 的默认 KV（idplugin.DefaultKVS）与帮助信息（idplugin.Help），并在配置校验分支中对 IdentityPluginSubSys 调用 idplugin.LookupConfig 解析；服务器启动加载配置时，cmd/iam.go（约 L307-L313）同样调用 idplugin.LookupConfig 解析出插件配置，并在有效时调用 setGlobalAuthNPlugin(idplugin.New(GlobalContext, authNPluginCfg)) 将认证插件函数注入到全局 IAM 系统。

三、MinIO 与插件之间的 REST 调用契约

为验证 AssumeRoleWithCustomToken 请求中携带的自定义 token，MinIO 向配置的插件端点发起 POST 请求。完整契约如下：

3.1 请求：POST 到插件端点

Query 参数只有一个：

参数名	类型	用途
token	string	来自 AssumeRoleWithCustomToken 调用的 token，用于外部校验

如第二节所述，若配置了 MINIO_IDENTITY_PLUGIN_AUTH_TOKEN，它随请求的 authorization 头一并发出。

3.2 响应：token 有效（200 OK）

插件判定 token 有效且允许访问时，必须返回 200（OK），响应体为 application/json，结构为：

{
    "user": <string>,
    "maxValiditySeconds": <integer>,
    "claims": <key-value-pairs>
}

参数名	类型	用途
user	string	所请求凭证归属用户的标识
maxValiditySeconds	integer（>= 900 秒 且 < 365 天）	允许的最大凭证过期时长
claims	key-value pairs	关联到所请求凭证上的 claims

保留键约束：claims 对象中的 "exp"、"parent" 和 "sub" 三个键是保留键，若插件返回了这些键，MinIO 会忽略它们——这与源码行为一致：cmd/sts-handlers.go 的 AssumeRoleWithCustomToken 处理函数中，MinIO 先构造自己的核心 claims（expClaim、subClaim、roleArnClaim、parentClaim），再遍历插件返回的 claims 逐一合并，但仅当该键尚不存在时才写入（L1078-L1084 的注释明确写着 "without replacing any existing claims"），从而保证插件无法篡改有效期、身份主体等关键声明。

3.3 响应：token 无效（403 Forbidden）

token 无效或访问不被批准时，插件必须返回 403（forbidden），响应体为 application/json：

{
    "reason": <string>
}

reason 中的消息会直接返回给客户端。源码层面同样可见：当 authn.Authenticate 返回的 res.Failure 非空时，MinIO 以 ErrSTSUpstreamError 错误码将 res.Failure.Reason 作为错误消息写回客户端（cmd/sts-handlers.go L1048-L1051）。

3.4 有效期裁剪规则

客户端请求中可携带期望的凭证时长。从源码实现看，最终生效的过期时长取客户端请求值与插件返回的 maxValiditySeconds 两者中的较小值：cmd/sts-handlers.go L1059-L1064 先以插件返回的 MaxValiditySeconds 作为基准 expiry，若客户端显式请求了更短的时长则改用小值。这意味着插件永远拥有"上限否决权"，客户端无法拿到超过插件授权窗口的凭证寿命。

3.5 签发的临时凭证与审计

校验通过后，MinIO 会：

• 以 custom + 键分隔符 + 插件返回的 user 构造 parentUser（L1066），并将 parent、sub、roleArn 等写入 claims；
• 通过 auth.GetNewCredentialsWithMetadata 签发带 metadata 的临时凭证，globalIAMSys.SetTempUser 持久化该临时用户（L1085-L1101）；
• 触发站点复制（site replication）的 IAM 变更钩子，把新 STS 凭证同步到复制对端（L1103-L1113）；
• 最终响应为 AssumeRoleWithCustomTokenResponse，其中 AssumedUser 即上述 parentUser（L1115-L1119）。

此外，处理函数开头即声明了 defer logger.AuditLog(...) 并对 stsToken 做过滤（L982-L983），确保审计日志中不会落盘原始自定义 token 明文。

四、示例插件实现

文档提供了一个玩具级插件实现 docs/iam/identity-manager-plugin.go（文件带 //go:build ignore，作为独立示例程序运行，不属于主构建）。其核心行为：

• 内置一张 token → 身份的静态表：

var tokens map[string]Resp = map[string]Resp{
    "aaa": {
        User:               "Alice",
        MaxValiditySeconds: 3600,
        Claims: map[string]interface{}{
            "groups": []string{"data-science"},
        },
    },
    "bbb": {
        User:               "Bart",
        MaxValiditySeconds: 3600,
        Claims: map[string]interface{}{
            "groups": []string{"databases"},
        },
    },
}

• HTTP 处理器从 r.FormValue("token") 读取 query 参数 token；查表命中则以 200 返回 user、maxValiditySeconds、claims；未命中返回 403；参数缺失返回 400 及 {"reason": "..."} 错误体；
• 监听 :8081 端口提供服务。

对照第三节的契约表可以逐条验证：该示例精确实现了 MinIO 期望的请求参数名（token）、成功/失败状态码与 JSON 结构，因此可以作为搭建生产插件时的最小参考骨架——把静态 map 换成对内部身份系统（Kerberos、内部 API 等）的真实查询即可。

五、端到端调用链小结

综合文档与源码，完整链路为：

1. 配置：mc admin config set myminio identity_plugin 设置 URL（必填）、AUTH_TOKEN、ROLE_POLICY（必填）、ROLE_ID；服务端启动/配置加载时经 cmd/iam.go 中 idplugin.LookupConfig + setGlobalAuthNPlugin 注入全局认证插件；
2. 请求：客户端向 S3 兼容端点发起 POST ?Action=AssumeRoleWithCustomToken&Token=<opaque-token>（源码注释给出的端点形态：https://minio:9000?Action=AssumeRoleWithCustomToken&Token=xxx）；
3. 前置校验：处理器依次检查 IAM 是否初始化、认证插件函数是否存在（不存在则报 "STS API 'AssumeRoleWithCustomToken' is disabled"）、Action 与 Token 参数是否合法；
4. 外发校验：authn.Authenticate(roleArn, token) 触发对插件端点的 POST ...?token=...（authorization 头携带配置中的 auth token）；
5. 凭证签发：按 3.4 节规则裁剪有效期、合并 claims、生成临时凭证并写入 SetTempUser，触发站点复制钩子，返回 XML 响应；
6. 拒绝路径：插件返回 403 时，reason 字段经 ErrSTSUpstreamError 透传给客户端。

需要再次强调的使用边界：该机制无 Console UI 集成，定位是机器对机器的自定义认证扩展；若需要人类用户的交互式登录集成，应参考仓库中其他 STS/IdP 文档（如 docs/sts/ 下的 OIDC、LDAP 等集成文档）；若需要外置的是授权（access control）而非身份认证，则对应文档为 docs/iam/access-management-plugin.md，两者可独立或组合启用——源码中 newGlobalAuthZPluginFn() == nil 分支（cmd/sts-handlers.go L1033）正体现了"未配置 AuthZ 插件时回退到本地策略名校验"的组合逻辑。