配置FusionAuth与Minio SSO时JWT缺失groups声明的问题

问题现象 #

配置Minio使用FusionAuth作为OpenID提供商时，出现以下错误：

<?xml version="1.0" encoding="UTF-8"?>
<ErrorResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/"><Error><Type></Type><Code>InvalidParameterValue</Code><Message>groups claim missing from the JWT token, credentials will not be generated</Message></Error><RequestId>175A7B8469F151BB</RequestId></ErrorResponse>

查看FusionAuth生成的JWT Payload，确实缺少groups字段：

{
  "aud": "55ad32c7-99eb-40e9-abc0-479c2f18c18e",
  "exp": 1682796819,
  "iat": 1682793219,
  "iss": "acme.com",
  "sub": "ad58f73f-79fd-4806-86f7-cd9d48b65400",
  "jti": "85e0a440-c254-4684-9c7b-caa830c1d491",
  "authenticationType": "PASSWORD",
  "email": "admin@admin.com",
  "email_verified": true,
  "at_hash": "wLcTvHBgOMQblFXSJCEr2w",
  "c_hash": "N9XJhvfh8Cz0sKnWjw3TEQ",
  "scope": "openid offline_access",
  "sid": "8ed4559c-1d86-41db-9312-cfd2e42d0fc4",
  "auth_time": 1682793219,
  "tid": "42178a6c-35ab-6c81-f8f9-4696fc894a60"
}

解决步骤 #

1. 在FusionAuth应用中配置自定义groups声明 #

FusionAuth默认不会将用户的角色/组自动放入JWT的groups字段，需要手动添加自定义声明：

• 登录FusionAuth管理后台，进入对应Minio应用的设置页面
• 切换到「JWT」标签页，找到「自定义声明」区域
• 添加一个新的声明：
  • 名称：groups
  • 值：根据需求选择表达式：
    • 若使用用户角色：user.roles?.collect { it.name }（提取当前应用下用户角色的名称，返回字符串数组）
    • 若使用用户组：user.groups?.collect { it.name }（提取用户所属组的名称，返回字符串数组）
  • 确保声明的包含条件设置为Always，保存配置

2. 验证角色/组的应用关联 #

• 确认你创建的角色/组属于当前Minio对应的FusionAuth应用（FusionAuth的角色是应用级别的，跨应用的角色不会被包含在JWT中）
• 进入用户详情页，检查用户确实已关联目标角色/组，且关联关系生效

3. 核对Minio配置 #

• 确认Minio的OpenID设置中，「Claim Name」字段配置为groups（与FusionAuth自定义声明的名称一致）
• 确保Minio存储桶策略的名称与FusionAuth中角色/组的名称完全匹配（大小写敏感）

完成以上配置后，重新发起认证请求，检查JWT Payload是否包含groups字段，即可解决Minio的认证错误。

内容的提问来源于stack exchange，提问作者Ryan Walker