如何通过 STS Assume API 为 MinIO 获取临时访问凭证？

在客户端应用或外部服务需要访问 MinIO 对象资源，但不希望把长期凭证写进应用代码时，可以使用 MinIO STS（Security Token Service）的 AssumeRole 接口：客户端用 MinIO 上一个已存在用户的 access key 和 secret key 调用该 API，换取一组临时安全凭证，包含 AccessKeyId、SecretAccessKey 和 SessionToken，之后用这组临时凭证签名发起 MinIO API 请求。临时凭证默认有效期 1 小时，可通过 DurationSeconds 参数调整，范围为 900 秒（15 分钟）到 365 天。相比长期凭证，临时凭证短期有效、动态生成、过期后 MinIO 不再识别，无需轮转或显式吊销（见 docs/sts/README.md）。本文基于 docs/sts/assume-role.md 走一遍完整流程：启动 MinIO 服务器、创建测试用户，然后分别用 AWS CLI 和仓库自带的 Go 示例程序获取临时凭证。

启动 MinIO 并准备测试用户

AssumeRole 要求持有 MinIO 上一个现有用户的授权凭证，所以第一步是把服务器跑起来并建好用户。按 docs/sts/assume-role.md 的方式启动单盘服务器：

export MINIO_ROOT_USER=minio
export MINIO_ROOT_PASSWORD=minio123
minio server ~/test

接下来用 mc 客户端创建文档示例中的用户 foobar（密码 foo12345）。先设置别名指向服务器，再建用户：

mc alias set myminio http://localhost:9000 minio minio123 --api s3v4
mc admin user add myminio foobar foo12345

mc alias set 的用法见 docs/multi-user/admin/README.md，用户与策略管理命令来自 docs/multi-user/README.md。临时凭证的策略继承自该 MinIO 用户的凭证，所以还要给用户挂一个策略。服务器自带 writeonly、readonly、readwrite 三个默认 canned policy，这里挂 readwrite：

mc admin policy attach myminio readwrite --user=foobar

如果用户没有任何策略，继承规则意味着临时凭证也不会获得对应资源权限，后面的测试就看不到可用访问。

用 AWS CLI 请求临时凭证

把测试用户凭证写入 AWS CLI 的 profile 配置文件 ~/.aws/credentials（以下内容为 docs/sts/assume-role.md 中的原文示例）：

[foobar]
region = us-east-1
aws_access_key_id = foobar
aws_secret_access_key = foo12345

然后执行 STS AssumeRole 调用：

aws --profile foobar --endpoint-url http://localhost:9000 sts assume-role --policy '{"Version":"2012-10-17","Statement":[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:*","Resource":"arn:aws:s3:::*"}]}' --role-arn arn:xxx:xxx:xxx:xxxx --role-session-name anything

文档明确说明：在 MinIO 中 --role-arn 和 --role-session-name 没有实际含义，只需填任意满足命令行要求的值即可。--policy 是可选的 JSON 会话策略，最终会话权限等于被假设用户策略与该策略的交集，不能比用户已有策略授予更多权限。

文档给出的示例返回（以下为文档示例，实际密钥值不同）：

{
    "AssumedRoleUser": {
        "Arn": ""
    },
    "Credentials": {
        "SecretAccessKey": "xbnWUoNKgFxi+uv3RI9UgqP3tULQMdI+Hj+4psd4",
        "SessionToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOi...(略)",
        "Expiration": "2019-02-20T19:56:59-08:00",
        "AccessKeyId": "K9DTIMUVZXEXJL3ATUOY"
    }
}

命令成功返回 Credentials 块中的这四个字段，即代表临时凭证获取成功，Expiration 表示过期时间。

用仓库自带的 Go 示例程序请求临时凭证

仓库 docs/sts/assume-role.go 提供了一个可直接运行的测试客户端。在仓库的 docs/sts 目录下执行文档中的命令：

go run assume-role.go -u foobar -p foo12345 -d

各参数含义以源文件中的 flag 定义为准：

• -sts-ep：STS 端点地址，默认 http://localhost:9000；
• -u / -p：MinIO 用户名与密码（上一步创建的 foobar）；
• -d：只打印生成的凭证，然后退出；
• -e：为生成的凭证指定有效期时长；
• -b：要列出的 bucket，默认取用户名；
• -s：包含会话策略的文件，策略内容会作为 STS 请求的 Policy 参数。

文档示例输出（文档示例，令牌值以实际运行为准）：

Only displaying credentials:
AccessKeyID: 27YDRYEM0S9B44AJJX9X
SecretAccessKey: LHPdHeaLiYk+pDZ3hgN3sdwXpJC2qbhBfZ8ii9Z3
SessionToken: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOi...(略)

副作用提示：查看 docs/sts/assume-role.go 源码可以看到，不传 -d 时程序在拿到凭证后还会调用 madmin 的 ServiceRestart 重启 MinIO 服务，再用临时凭证对 -b 指定的 bucket（默认用户名同名 bucket）做 ListObjects。常规验证请带 -d 运行；只有确实想测试“临时凭证能否操作对象 API”时才去掉 -d，并知晓它会重启服务器进程。该程序依赖 github.com/minio/minio-go/v7 与 github.com/minio/madmin-go/v3，在仓库内运行 go run 时使用 go.mod 锁定的版本。

直接组装 HTTP 请求

不使用 CLI 或 Go 客户端时，也可以直接发起 API 请求。docs/sts/assume-role.md 给出的示例请求形态如下（minio:9000 需替换为你实际的 MinIO 地址；AUTHPARAMS 为 SigV4 签名授权参数，文档以占位符表示，不是可直接复制的完整 URL）：

http://minio:9000/?Action=AssumeRole&DurationSeconds=3600&Version=2011-06-15&Policy={"Version":"2012-10-17","Statement":[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:*","Resource":"arn:aws:s3:::*"}]}&AUTHPARAMS

各请求参数及限制（来自同一文档）：

参数	说明
Version	必填，唯一支持值 2011-06-15（借用 AWS STS API 的值以兼容）
AUTHPARAMS	STS API 授权信息，支持 AWS Signature V4 签名授权
DurationSeconds	可选，Integer；最小 900，最大 31536000（365 天），默认 3600 秒；超出范围会导致操作失败
Policy	可选，JSON 格式的内联会话策略；长度 1–2048；结果权限为既有策略与该策略的交集

响应为 XML，结构与 AWS STS AssumeRole 一致。文档示例响应（文档示例，凭据值以实际为准）：

<AssumeRoleResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
  <AssumeRoleResult>
    <AssumedRoleUser>
      <Arn/>
      <AssumeRoleId/>
    </AssumedRoleUser>
    <Credentials>
      <AccessKeyId>Y4RJU1RNFGK48LGO9I2S</AccessKeyId>
      <SecretAccessKey>sYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg</SecretAccessKey>
      <Expiration>2019-08-08T20:26:12Z</Expiration>
      <SessionToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOi...(略)</SessionToken>
    </Credentials>
  </AssumeRoleResult>
  <ResponseMetadata>
    <RequestId>c6104cbe-af31-11e0-8154-cbc7ccf896c7</RequestId>
  </ResponseMetadata>
</AssumeRoleResponse>

限制与注意点

• 有效期：DurationSeconds 低于 900 或高于 31536000 时操作失败；不传时默认 3600 秒。凭证到达 Expiration 后，MinIO 不再识别该凭证，用其发起的任何 API 请求都会被拒绝，需要重新请求新的临时凭证。
• 权限边界：临时凭证策略继承自 MinIO 用户凭证；传入 Policy 只会收窄权限（取交集），不能扩大权限。
• 占位参数：AWS CLI 的 --role-arn、--role-session-name 在 MinIO 中无语义，仅为满足命令行校验的占位值。
• 服务端副作用：Go 示例程序不带 -d 时会重启 MinIO 服务，测试环境之外使用需格外小心。

更多背景可查阅 docs/sts/README.md（STS 总览与 Identity Federation 各路径）和 docs/multi-user/README.md（用户与策略管理完整命令）。