如何配置MinIO通过GitLab OIDC显示真实用户名而非默认user

核心原因 #

MinIO默认会尝试从OIDC令牌的username声明获取用户名，若找不到则回退到固定值"user"。而GitLab的OIDC令牌中，实际用户名存储在preferred_username或nickname声明中（需确保请求了正确的Scope）。

解决步骤 #

1. 确认GitLab OIDC令牌的有效声明 #

先解析GitLab返回的JWT令牌，确认可用的用户名声明：

• 复制登录后获取的JWT令牌（可从浏览器开发者工具的网络请求中找到，或通过MinIO日志查看）
• 本地使用jwt.io解析令牌，查看Payload中的字段：
  • GitLab通常会返回preferred_username（对应GitLab用户名）、nickname（同用户名）、name（用户全名）等字段

2. 配置MinIO映射GitLab的用户名声明 #

通过启动参数或环境变量指定MinIO要使用的OIDC声明：

方式一：命令行启动MinIO时配置

minio server ./data \
  --oidc-endpoint "https://gitlab.example.com" \
  --oidc-client-id "你的GitLab OIDC客户端ID" \
  --oidc-client-secret "你的GitLab OIDC客户端密钥" \
  --oidc-claim-name "preferred_username" \  # 指定GitLab的用户名声明
  --oidc-scopes "openid,profile,email"      # 必须包含profile才能获取preferred_username

方式二：环境变量配置（适合Docker/K8s/Systemd）

设置以下环境变量：

MINIO_IDENTITY_OPENID_CONFIG_URL=https://gitlab.example.com/.well-known/openid-configuration
MINIO_IDENTITY_OPENID_CLIENT_ID=你的GitLab OIDC客户端ID
MINIO_IDENTITY_OPENID_CLIENT_SECRET=你的GitLab OIDC客户端密钥
MINIO_IDENTITY_OPENID_CLAIM_NAME=preferred_username
MINIO_IDENTITY_OPENID_SCOPES=openid,profile,email

3. 验证配置效果 #

• 重启MinIO服务
• 通过GitLab OIDC重新登录MinIO控制台，确认用户名已显示为GitLab的实际用户名
• 可选：使用MinIO客户端mc验证用户信息：

mc admin user list 你的MinIO别名

常见问题排查 #

• 若仍显示"user"：检查GitLab OIDC应用的Scope是否包含profile，只有请求该Scope才能获取preferred_username声明
• 若preferred_username不存在：尝试改用nickname声明（GitLab多数版本中两者值一致）
• 旧版GitLab：若上述声明都不存在，可检查sub声明，但sub是GitLab内部用户ID，可读性较差

内容的提问来源于stack exchange，提问作者Hoang Do