Gokapi项目集成Keycloak认证问题解析与解决方案

问题背景

在Gokapi项目中集成Keycloak作为认证提供者时，用户可能会遇到登录后显示"未授权"的问题。这种情况通常发生在配置OAuth2/OIDC集成时，即使Keycloak中的用户拥有正确的权限组，Gokapi仍然拒绝其访问。

问题现象

用户报告了以下关键现象：

1. 所有用户（包括管理员）登录后都被Gokapi拒绝
2. Keycloak日志中出现"Invalid format of the code"警告
3. 用户组信息未出现在访问令牌中，尽管已在Keycloak中配置了组映射

根本原因分析

经过深入调查，发现问题的核心在于组信息的传递方式。Keycloak默认的组映射行为与Gokapi的预期不符：

1. Keycloak默认会在组名称前添加前缀（如"/admin"）
2. Gokapi配置中指定的组名（如"admins"）与Keycloak实际传递的组名不匹配
3. 组范围(scope)配置虽然正确设置为"groups"，但需要额外的自定义映射器才能正确传递组信息

解决方案

要解决此问题，需要在Keycloak中创建自定义的组映射器：

1. 在Keycloak客户端的"Mapper"选项卡中创建新的映射器
2. 选择"Group Membership"类型
3. 配置Token Claim Name为"groups"
4. 设置Full group path为"off"
5. 确保Add to ID token和Add to access token都启用

这种配置确保组信息以Gokapi期望的格式（无前缀的纯组名）包含在令牌中。

配置验证

成功配置后，可以通过以下方式验证：

1. 检查访问令牌内容，确认包含正确的组信息
2. 确保Gokapi配置中的OAuthGroups与Keycloak中的组名完全匹配
3. 测试不同权限级别的用户（管理员和普通用户）的访问控制

扩展说明

值得注意的是，当前Gokapi版本仅支持基于组的访问控制，尚不支持更细粒度的用户级文件访问控制。这意味着所有被授权的用户（属于配置组中的用户）将拥有相同的访问权限。

对于需要更精细权限控制的场景，可以考虑：

1. 在Keycloak中创建更详细的组结构
2. 在Gokapi配置中指定多个不同权限级别的组
3. 等待未来版本可能实现的用户级访问控制功能

总结

Keycloak与Gokapi的集成需要特别注意组信息的传递格式。通过正确配置自定义组映射器，可以解决用户授权失败的问题。这种解决方案不仅适用于当前报告的问题，也为其他类似集成场景提供了参考模式。