MinIO 自定义 Token 身份认证AssumeRoleWithCustomToken STS API 完全指南【免费下载链接】minioMinIO is a high-performance, S3 compatible object store, open sourced under GNU AGPLv3 license.项目地址: https://gitcode.com/GitHub_Trending/mi/minioMinIO 通过扩展 STS API 提供AssumeRoleWithCustomToken接口配合 Identity Management Plugin身份管理插件Webhook可让自建认证体系为对象存储签发临时凭证。本文以 custom-token-identity.md 为核心完整讲解该接口的请求/响应契约、Role ARN 的生成原理并结合仓库源码展示一个可运行的插件参考实现帮助你打通自有认证 Token → MinIO 临时凭据的完整链路。一、什么是 AssumeRoleWithCustomTokenMinIO 原生的身份认证体系支持静态用户、LDAP、OpenID Connect 等。但当业务系统希望接入自有的认证方式如自建 SSO、内部统一登录、游戏/物联网设备 Token 体系时可以启用 MinIO 的 Identity Management Plugin身份管理插件Webhook 扩展。启用插件后MinIO 服务器就暴露一个额外的 STS API 扩展接口AssumeRoleWithCustomToken。用户或应用只需持有一个对 MinIO 完全不透明opaque的 Token即可调用该接口换取访问对象存储的临时凭证。MinIO 本身不解析这个 Token而是将其原样转发给配置好的插件端点做校验。该流程与 OpenID 认证思路相近区别在于OpenID 下 MinIO 需要理解 JWT 结构而自定义 Token 模式下 MinIO 只需搬运Token一切验证逻辑都收敛在外部插件中集成自由度更高。有一点需要特别注意该认证方式没有控制台 UI 集成主要面向机器间认证machine-to-machine场景。整体架构┌──────────────┐ AssumeRoleWithCustomToken ┌────────────────┐ POST token ┌─────────────────────┐ │ 客户端/应用 │ ────────(opaque Token)──────▶ │ MinIO Server │ ──────────────▶ │ Identity Plugin │ └──────────────┘ ◀─────── 临时 STS 凭证 ────── │ (STS API 扩展) │ ◀── user/claims ─ │ (自定义认证 Webhook) │ └────────────────┘ └─────────────────────┘二、前置条件配置 Identity Management PluginAssumeRoleWithCustomToken只有在配置了身份管理插件后才会生效。从 STS 处理逻辑 的源码可以看到如果未初始化认证插件newGlobalAuthNPluginFn()返回nil接口会直接拒绝请求并返回错误STS API AssumeRoleWithCustomToken is disabled。插件可通过 MinIO 标准配置 APImc admin config set/get或环境变量两种方式配置。配置子系统的完整实现位于 internal/config/identity/plugin/config.go以下是各配置项的环境变量形式及含义环境变量类型必填说明MINIO_IDENTITY_PLUGIN_URLurl是插件 hook 端点HTTP/HTTPS如http://localhost:8181/path/to/endpointMINIO_IDENTITY_PLUGIN_AUTH_TOKENstring否调用插件端点时附带的授权 Token作为 Authorization 请求头发送MINIO_IDENTITY_PLUGIN_ROLE_POLICYstring是为插件授权用户应用的一组策略名多个用逗号分隔MINIO_IDENTITY_PLUGIN_ROLE_IDstring否用于生成 Role ARN 的唯一 IDMINIO_IDENTITY_PLUGIN_COMMENTsentence否对该配置项的注释说明从源码 LookupConfig 可以确认几个关键行为MINIO_IDENTITY_PLUGIN_ROLE_POLICY为必填项缺失时启动配置会直接报错A role policy must be specified for Identity Management Plugin若设置了AUTH_TOKENMinIO 在向插件发起认证请求时会将Authorization请求头设置为该值配置载入阶段会以POST空请求对插件端点做一次连通性Validate探测无法连通时配置会被拒绝插件启用后MinIO 还会每分钟发起一次HEAD健康检查doPeriodicHealthCheck并持续统计可达性、RTT 等指标见 Metrics 实现。Role ARN 是如何生成的Role ARN 是整个认证流程的关键标识。在 LookupConfig 中可以看到 ARN 的完整生成逻辑ARN 的 resource 部分以idmp-前缀开始若未配置MINIO_IDENTITY_PLUGIN_ROLE_IDMinIO 会对插件 URL 计算 SHA-1再以 Base64 URL 安全编码追加到idmp-之后这样生成的 ARN 在服务重启后保持不变若配置了ROLE_ID则会校验其只包含[A-Za-z0-9_-]字符正则^[A-Za-z0-9_-]$随后拼接为idmp-ROLE_ID最终通过arn.NewIAMRoleARN生成形如arn:minio:iam:::role/idmp-...的 ARN。插件配置完成后MinIO 服务启动日志会打印该 Role ARN参考示例中的arn:minio:iam:::role/idmp-vGxBdLkOc8mQPU1-UQbBh-yWWVQ。若想使用更可控的固定值就通过MINIO_IDENTITY_PLUGIN_ROLE_ID指定。同时插件与 Role ARN → 策略的映射关系会通过 GetRoleInfo 注入 IAM 系统的 rolesMap见 cmd/iam.go供后续鉴权使用。三、STS API 请求参数配置好插件并取得 Role ARN 后即可向 MinIO 端点发送 POST 请求来获取临时凭证。请求方法在 STS 路由注册中被绑定为POST携带以下 Query 参数参数类型必填说明ActionString是值必须为AssumeRoleWithCustomTokenVersionString是值必须为2011-06-15TokenString是交由身份插件验证的自定义 TokenRoleArnString是必须与身份插件生成的 Role ARN 完全匹配DurationSecondsInteger否生成的临时凭证有效期最小为 900 秒从 AssumeRoleWithCustomToken 处理器 的源码可以印证以下细节Token为空会直接返回Invalid empty Token parameter providedRoleArn通过globalIAMSys.GetRolePolicy解析必须能匹配到插件映射的 Role 与策略否则请求被拒绝若未启用独立的授权插件AuthZ PluginMinIO 会校验 Role 关联的策略确实存在否则报None of the given policies are defined有效期取两者的较小值最终凭证的过期时间 min(客户端传入的 DurationSeconds, 插件返回的 maxValiditySeconds)。代码中的实现是expiry先取插件返回值当客户端传了DurationSeconds且更小时则覆盖见 cmd/sts-handlers.go。使用 curl 发起请求主文档中给出的示例请求如下curl -XPOST http://localhost:9001/?ActionAssumeRoleWithCustomTokenVersion2011-06-15TokenaaaRoleArnarn:minio:iam:::role/idmp-vGxBdLkOc8mQPU1-UQbBh-yWWVQ实际使用时请将主机与端口替换为你部署环境中对外暴露的 MinIO API/STS 端点并将Token、RoleArn换成插件真实签发的 Token 与启动日志中打印的 ARN。也可以额外追加DurationSeconds3600来显式限制凭证有效期。四、响应格式与字段解析AssumeRoleWithCustomToken的 XML 响应结构与 AWS STSAssumeRoleWithWebIdentity类似。主文档给出的格式化响应如下?xml version1.0 encodingUTF-8? AssumeRoleWithCustomTokenResponse xmlnshttps://sts.amazonaws.com/doc/2011-06-15/ AssumeRoleWithCustomTokenResult Credentials AccessKeyId24Y5H9VHE14H47GEOKCX/AccessKeyId SecretAccessKeyHaBfQ9B1AeWWb84hvp4tlFBo9aPhUTdLFIeg/SecretAccessKey Expiration2022-05-25T19:56:34Z/Expiration SessionTokeneyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiIyNFk1SDlWSEUxNEg0N0dFT0tDWCIsImV4cCI6MTY1MzUwODU5NCwiZ3JvdXBzIjpbImRhdGEtc2NpZW5jZSJdLCJwYXJlbnQiOiJjdXN0b206QWxpY2UiLCJyb2xlQXJuIjoiYXJuOm1pbmlvOmlhbTo6OnJvbGUvaWRtcC14eHgiLCJzdWIiOiJjdXN0b206QWxpY2UifQ.1tO1LmlUNXiy-wl-ZbkJLWTpaPlhaGqHehsi21lNAmAGCImHHsPb-GA4lRq6GkvHAODN5ZYCf_S-OwpOOdxFwA/SessionToken /Credentials AssumedUsercustom:Alice/AssumedUser /AssumeRoleWithCustomTokenResult ResponseMetadata RequestId16F26E081E36DE63/RequestId /ResponseMetadata /AssumeRoleWithCustomTokenResponse响应结构在 cmd/sts-datatypes.go 中定义为AssumeRoleWithCustomTokenResponse包含三层核心信息Credentials返回AccessKeyId、SecretAccessKey、Expiration与SessionToken四元组。拿到后即可用标准的 S3 客户端配合 session token访问对象存储AssumedUser被假定用户的标识。观察示例中custom:Alice可以看出 MinIO 会把插件返回的user加上custom:前缀构成父用户parent user。该拼接逻辑见 cmd/sts-handlers.goparentUser : custom getKeySeparator() res.Success.UserResponseMetadata.RequestId请求 ID用于问题排查与日志关联。从实现看生成的SessionToken本身就是携带声明信息claims的 JWT处理器会把exp、sub、roleArn、parent以及插件返回的业务 claims 一并写入 token claims再调用auth.GetNewCredentialsWithMetadata生成凭据见 cmd/sts-handlers.go。五、身份插件的 REST 契约了解完 STS 侧接口后还需要理解 MinIO 调用插件的 HTTP 契约这是自定义认证能否打通的关键。请求POST 到插件端点当收到AssumeRoleWithCustomToken请求后MinIO 会构造一个 POST 请求发送到配置的插件 URL参数Query值类型用途tokenstring来自AssumeRoleWithCustomToken调用、待外部验证的 Token实现细节见 Authenticate 方法Token 以 Query 参数token附加到插件 URL若配置了AUTH_TOKEN则同时附带Authorization头。该认证调用带 5 秒超时只有当插件返回的 HTTP 状态码为200或403时才会被处理其他状态码统一报错Invalid status code %d from auth plugin。成功响应200 OKToken 有效且授权通过时插件必须返回 HTTP200响应体Content-Type为application/json结构如下{ user: string, maxValiditySeconds: integer, claims: key-value-pairs }字段值类型用途userstring所请求临时凭证的属主标识会构成 AssumedUser 的custom:前缀部分maxValiditySecondsinteger允许的最大过期时长取值需在 900 秒含到 365 天含之间claimskey-value 对需要关联到临时凭证上的附加声明关于maxValiditySeconds认证响应校验中定义了上下限常量minValidityDurationSeconds 900maxValidityDurationSeconds 365 * 24 * 3600超出该区间的返回值会导致认证失败。关于claims需要注意一个保留键规则exp、parent、sub三个键被 MinIO 保留插件返回的这些键会被忽略。从处理器源码可以看到原因——MinIO 会先自行填充exp、sub、roleArn、parent等核心声明随后在合并插件 claims 时跳过已存在的键if _, ok : claims[k]; !ok因此插件无法覆盖这些内部声明。其余自定义 claims如业务分组groups则会被原样写入凭证。失败响应403 ForbiddenToken 无效或访问被拒绝时插件必须返回 HTTP403响应体Content-Type为application/json结构如下{ reason: string }reason中的错误信息会原样回传给调用方处理器中将该错误封装为 STSErrSTSUpstreamError见 cmd/sts-handlers.go。六、参考实现一个可运行的插件端点仓库中附带了一个可直接运行的玩具级 Go 示例 docs/iam/identity-manager-plugin.go可用于本地验证上述契约。它的逻辑非常直观在内存中维护了一个tokens映射表将两个预置 Token 分别映射到用户与声明Tokenaaa→ 用户AlicemaxValiditySeconds 3600claims 含分组[data-science]Tokenbbb→ 用户BartmaxValiditySeconds 3600claims 含分组[databases]处理器从请求中读取token参数缺失时报token parameter not given返回 400未命中映射表时返回403 Forbidden命中时打印日志并返回200 OK 上述 JSON 结构服务监听在:8081。注意该文件头部带有//go:build ignore构建约束属于独立运行的示例程序不会被编译进 MinIO 主程序。运行方式go run docs/iam/identity-manager-plugin.go结合前文的配置可用如下环境变量让 MinIO 指向该插件仅为示意实际需按你的策略名与端点调整export MINIO_IDENTITY_PLUGIN_URLhttp://localhost:8081/ export MINIO_IDENTITY_PLUGIN_AUTH_TOKEN export MINIO_IDENTITY_PLUGIN_ROLE_POLICYconsoleAdmin # 示例策略可按需替换 export MINIO_IDENTITY_PLUGIN_ROLE_IDtest-plugin随后使用第一节的 curl 命令携带 Tokenaaa与启动日志中打印的 Role ARN 即可换取临时凭证——这正是主文档示例请求中Tokenaaa且返回custom:Alice与groups: [data-science]的由来示例插件与文档请求完全对应。七、端到端工作流程小结整个自定义 Token 认证流程可归纳为以下步骤部署并注册插件实现符合 REST 契约的身份插件端点参考第六节示例确保能正确处理tokenQuery 参数并返回约定的成功/失败 JSON配置 MinIO通过环境变量或mc admin config set设置identity_plugin子系统的 URL、Role Policy 等参数重启后从服务日志读取生成的 Role ARN客户端换取凭证向 MinIO API 端点发起POST ?ActionAssumeRoleWithCustomTokenVersion2011-06-15TokenxxxRoleArnarn:minio:iam:::role/idmp-...获得临时AccessKeyId / SecretAccessKey / SessionToken使用临时凭证访问对象存储任意支持 S3 协议且支持 session token 的客户端均可使用这套凭据完成后续读写操作凭据过期后需要重新走第 3 步。八、注意事项AssumeRoleWithCustomToken仅在配置了 Identity Management Plugin 后才可用且没有控制台 UI 集成设计初衷是机器认证场景Token 是不透明的安全性完全取决于插件端点的验证质量生产环境务必为插件端点启用 HTTPS 与鉴权客户端请求的DurationSeconds与插件返回的maxValiditySeconds会取较小值作为最终有效期插件返回的最大值必须落在 900 秒至 365 天区间内插件 claims 中的exp、parent、sub为保留键会被 MinIO 内部生成的同名声明覆盖忽略生成的临时凭证父用户统一以custom:前缀标识便于与静态用户、LDAP 等其它认证来源在审计与策略管理上区分。参考资料AssumeRoleWithCustomToken 主文档本指南的核心契约来源Identity Management Plugin 配置指南插件的配置项与 REST 契约详解插件参考实现可直接运行的 Go 示例STS 处理器实现AssumeRoleWithCustomToken的完整处理逻辑插件配置解析Role ARN 生成、认证请求与响应解析源码STS 响应结构体定义XML 响应对应的 Go 类型【免费下载链接】minioMinIO is a high-performance, S3 compatible object store, open sourced under GNU AGPLv3 license.项目地址: https://gitcode.com/GitHub_Trending/mi/minio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考