MinIO 多管理员（Multi-Admin）配置实战：自定义 admin 策略与权限分级管理

MinIO 默认只提供一套在服务器启动时通过环境变量（MINIO_ROOT_USER / MINIO_ROOT_PASSWORD）创建的根凭据（root credential），但生产环境往往需要多个可独立审计、权限各异的管理员账号。本文基于仓库文档 docs/multi-user/admin/README.md，完整讲解如何在 MinIO 中新增/删除管理员用户、通过自定义策略精细授权各类 admin:* 操作，并深入 checkAdminRequestAuth 等源码位置，说明管理员鉴权的底层实现，帮助你在多团队协作场景下实现"最小权限"的管理员体系。

1. 核心概念：默认管理员之外的二级管理员

MinIO 支持在默认运维凭据之外再添加多个管理员用户（admin users）。这些用户：

• 可以在服务器启动之后随时通过 mc admin user 动态添加、删除；
• 可以通过策略（policy）按操作粒度允许或拒绝不同的 admin 操作（如只允许管用户、不允许重启服务）；
• 与普通的 S3 用户共享同一套用户体系，其 admin 能力完全由所附加策略中的 admin:* Action 决定。

从源码结构看，每一个 admin 操作（用户管理、配置管理、存储信息、修复、服务等）在请求入口都会携带一个 policy.AdminAction 标识进行鉴权，例如 checkAdminRequestAuth 的签名就是 checkAdminRequestAuth(ctx, r, action policy.AdminAction, region)。这与 docs/multi-user/README.md 中面向普通 S3 用户的管理流程是同一套 IAM 机制，只是 Action 命名空间不同（s3:* 对 admin:*）。

前置条件

• 安装并配置 mc（MinIO Client），且客户端与服务器均使用 --api s3v4 签名；
• 已部署可访问的 MinIO 服务器（单机或分布式），持有默认 root 凭据；
• 建议通过 mc alias set myminio http://localhost:9000 <root-user> <root-password> --api s3v4 配置好管理员别名。

2. 创建自定义管理员策略

MinIO 的内置（canned）策略面向 S3 资源操作，默认不提供"完整管理员"策略，因此需要通过 mc admin policy 创建自定义策略。以下示例创建一个允许用户管理（CreateUser / DeleteUser / ConfigUpdate）并具备全部 S3 权限的策略：

cat > adminManageUser.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "admin:CreateUser",
        "admin:DeleteUser",
        "admin:ConfigUpdate"
      ],
      "Effect": "Allow",
      "Sid": ""
    },
    {
      "Action": [
        "s3:*"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::*"
      ],
      "Sid": ""
    }
  ]
}
EOF

要点说明：

• admin:* Action 不需要 Resource 字段，它们作用在服务器级管理操作上，而非某个 S3 资源；
• 第二个 Statement 授予全部 s3:* 资源权限，说明"管理员"通常也应同时是一个拥有全量 S3 权限的用户；若希望该管理员只负责管账号、不碰数据，可以删掉或收窄这条 Statement；
• 策略 Version 固定为 2012-10-17，与 AWS IAM 策略语言兼容。

将策略注册到服务器并创建用户：

# 创建名为 userManager 的自定义策略
mc admin policy attach myminio userManager adminManageUser.json

# 创建新管理员用户 admin1（用户名/密码）
mc admin user add myminio admin1 admin123

# 将 userManager 策略附加给 admin1
mc admin policy attach myminio userManager --user=admin1

完成后，admin1 即可通过 mc admin user 执行创建/删除用户的操作（因为它持有 admin:CreateUser 与 admin:DeleteUser），但无法执行策略未覆盖的管理操作，如查看存储信息、重启服务等。

3. 用新管理员验证：级联创建下级用户

新管理员创建成功后，配置一个以其身份认证的 mc 别名，用它再创建另一个用户，验证授权闭环：

# 以 admin1 的身份配置 alias
mc alias set myminio-admin1 http://localhost:9000 admin1 admin123 --api s3v4

# 使用 admin1 的权限创建普通用户 user1
mc admin user add myminio-admin1 user1 user123

# 注册并绑定 user1 的业务策略 user1policy
mc admin policy attach myminio-admin1 user1policy ~/user1policy.json
mc admin policy attach myminio-admin1 user1policy --user=user1

这个流程验证了两点：admin1 的凭据确实被服务端识别为合法管理员（其策略中的 admin:CreateUser 生效）；新创建的 user1 是一个仅受 user1policy 约束的普通 S3 用户，不具备任何 admin 能力。

4. admin 操作权限全量清单

以下是 MinIO 为管理操作定义的完整 Action 列表（引自 docs/multi-user/admin/README.md，可作为策略编写的权威参照）：

配置管理

Action	说明
admin:ConfigUpdate	更新服务器配置项（如通知、IDP、版本策略等）

用户管理

Action	说明
admin:CreateUser	创建用户
admin:DeleteUser	删除用户
admin:ListUsers	列出用户
admin:EnableUser	启用用户
admin:DisableUser	禁用用户
admin:GetUser	查询单个用户

服务管理

Action	说明
admin:ServerInfo	查看服务器信息
admin:ServerUpdate	服务器版本更新
admin:StorageInfo	查看存储信息
admin:DataUsageInfo	查看数据用量
admin:TopLocks / admin:TopLocksInfo	查看锁竞争信息
admin:OBDInfo	查看 OBD（out-of-band daemon）信息
admin:Profiling	服务器 profiling
admin:ServerTrace	服务器调用追踪
admin:ConsoleLog	获取控制台日志
admin:KMSKeyStatus / admin:KMSCreateKey	KMS 密钥状态查询/创建
admin:ServiceRestart / admin:ServiceStop	重启/停止服务
admin:Prometheus	访问 Prometheus 指标
admin:ForceUnlock	强制解除命名空间锁
admin:BandwidthMonitor	带宽监控

用户/组管理

admin:AddUserToGroup、admin:RemoveUserFromGroup、admin:GetGroup、admin:ListGroups、admin:EnableGroup、admin:DisableGroup

策略管理

admin:CreatePolicy、admin:DeletePolicy、admin:GetPolicy、admin:AttachUserOrGroupPolicy、admin:ListUserPolicies

修复（Heal）管理

admin:Heal —— 执行数据/磁盘修复操作。

服务账号（Service Account）管理

admin:CreateServiceAccount、admin:UpdateServiceAccount、admin:RemoveServiceAccount、admin:ListServiceAccounts

桶配额管理

admin:SetBucketQuota、admin:GetBucketQuota

桶目标（复制）管理

admin:SetBucketTarget、admin:GetBucketTarget

远端存储层（Tier）管理

admin:SetTier、admin:ListTier

全量授权

admin:* —— 授予上述全部管理权限，等效于"完整管理员"（但仍建议与 s3:* 分开声明，便于审计策略意图）。

5. 源码实现解析：一个管理请求如何被鉴权

理解上面的权限清单如何落地，关键在 checkAdminRequestAuth：

// checkAdminRequestAuth checks for authentication and authorization for the incoming
// request. It only accepts V2 and V4 requests. Presigned, JWT and anonymous requests
// are automatically rejected.
func checkAdminRequestAuth(ctx context.Context, r *http.Request, action policy.AdminAction, region string) (auth.Credentials, APIErrorCode) {
    cred, owner, s3Err := validateAdminSignature(ctx, r, region)
    if s3Err != ErrNone {
        return cred, s3Err
    }
    if globalIAMSys.IsAllowed(policy.Args{
        AccountName:     cred.AccessKey,
        Groups:          cred.Groups,
        Action:          policy.Action(action),
        ConditionValues: getConditionValues(r, "", cred),
        IsOwner:         owner,
        Claims:          cred.Claims,
    }) {
        // Request is allowed return the appropriate access key.
        return cred, ErrNone
    }

    return cred, ErrAccessDenied
}

从这段实现可以确认几个事实：

1. 签名强约束：admin 请求只接受 V2/V4 签名，预签名 URL、JWT 直接凭据和匿名请求在 validateAdminSignature 阶段即被拒绝；
2. 策略驱动：每个 admin 操作以 policy.AdminAction 传入（例如用户管理类 handler 集中在 admin-handlers-users.go，服务信息类在 admin-handlers.go），最终以 policy.Action(action) 交给 globalIAMSys.IsAllowed 做策略匹配——也就是说，你在策略 JSON 里写的 admin:CreateUser 等 Action 就是这里的匹配键；
3. owner 直通：policy.Args 中的 IsOwner 字段携带了"该凭据是否为默认 root 凭据"的判定结果。从源码结构看，默认 root 凭据（启动时环境变量创建的那套）天然拥有全部 admin 能力，而后续添加的管理员则完全依赖策略授权——这正是"多管理员权限分级"在实现上的分界线；
4. 拒绝即 ErrAccessDenied：策略不匹配时请求返回 AccessDenied，客户端（mc）会收到对应的 S3 错误码，便于脚本化排错。

此外，checkAdminRequestAuth 对 session token 的校验（如 getSessionToken）表明通过 STS/服务账号体系派生的凭据同样走这条鉴权路径，因此服务账号的 admin 能力也由其策略中的 admin:* Action 决定。

6. 使用外部 IDP 管理管理员用户

除本地用户外，管理员用户也可以由外部身份提供商（IDP，如 OpenID Connect、LDAP/AD）托管：只需向 IDP 签发的临时凭据对应的策略附加上述 admin:* 权限，这些用户即成为外部管理的 admin 用户。这一路径依赖仓库中的 STS 相关文档与实现（参见 docs/sts/ 目录下的 web-identity、ldap、openid 等配置示例），适用于将管理员身份统一收敛到企业 IdP 的场景。

需要注意的前提：

• IDP 派生凭据属于"非 owner"凭据，其 admin 能力必须由策略显式授予，IsOwner 直通仅对默认 root 凭据有效；
• 建议在 IDP 策略中按最小权限原则只授予必要的 admin:* 子集（例如只给 admin:CreateUser、admin:ListUsers），而不是 admin:*。

7. 操作核对清单

• [ ] 已用 root 凭据配置 mc 别名，且 API 为 s3v4；
• [ ] 自定义策略 JSON 中 admin:* 与 s3:* 语句分别声明，Version 为 2012-10-17；
• [ ] mc admin policy attach 完成策略注册后，再用 --user= 完成用户绑定（两个步骤缺一不可）；
• [ ] 新管理员的可用操作边界已按第 4 节权限清单核对；
• [ ] 删除管理员前先用 mc admin user remove 清理，避免留下无策略的孤立凭据。

延伸阅读（仓库内路径）

• 普通多用户（非管理员）管理流程：docs/multi-user/README.md
• 管理员鉴权核心实现：cmd/auth-handler.go
• 用户管理 handler：cmd/admin-handlers-users.go
• 管理 API 路由：cmd/admin-router.go
• IAM 系统实现：cmd/iam.go
• 策略/身份测试用例：cmd/admin-handlers-users_test.go、cmd/auth-handler_test.go