Keycloak用户接入Hashicorp Vault时的OIDC映射问题咨询

问题根源 #

当前Vault默认使用OIDC ID Token中的sub字段（Keycloak返回的用户UUID）作为用户ID和名称，导致显示一串随机ID而非实际用户名。但Token中已包含username、email等有效字段，只需调整Vault的OIDC映射规则即可解决。

配置步骤 #

1. 确保Keycloak返回所需用户字段到ID Token #

在Keycloak客户端配置中，确认已添加必要的用户属性到ID Token：

• 进入Keycloak控制台，打开目标客户端的客户端范围标签，添加内置的profile、email范围（或自定义需要的字段）。
• 若需自定义字段，在Mappers标签中添加"User Property"类型的映射，将username、fullName等用户属性映射到对应的ID Token claims中，确保这些字段出现在Token payload里。

2. 更新Vault OIDC认证方法的用户标识配置 #

执行以下命令，将Vault的用户标识字段从默认的sub改为username：

vault write auth/oidc/config \
  oidc_client_id="你的Keycloak客户端ID" \
  oidc_client_secret="你的Keycloak客户端密钥" \
  oidc_discovery_url="https://你的Keycloak地址/auth/realms/你的Realm名称" \
  user_claim="username"

3. 配置角色级别的Claim映射 #

针对你的OIDC角色，设置具体的字段映射，将Keycloak返回的claims同步到Vault用户实体属性：

vault write auth/oidc/role/你的角色名称 \
  user_claim="username" \
  claim_mappings="email=email,full_name=name" \
  entity_alias="username"

• claim_mappings：定义Keycloak Token中的claim与Vault用户属性的对应关系，格式为Vault属性=Token字段。
• entity_alias="username"：确保Vault实体别名使用用户名而非UUID。

4. 验证配置 #

注销当前Vault会话，重新通过Keycloak OIDC登录，查看用户信息：

vault token lookup

此时用户信息中的Name、ID应显示实际用户名，而非UUID。

注意事项 #

• 确保Keycloak客户端已开启Include ID Token in response选项，保证claims被正确包含在返回的Token中。
• 若需要查看用户实体的详细信息，需为用户分配包含以下规则的policy：

path "identity/entity/id/{{identity.entity.id}}" {
  capabilities = ["read"]
}

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