盘古AI的Keycloak集成方法是什么？

盘古AI的Keycloak集成方法详解

Keycloak作为开源的身份与访问管理（IAM）解决方案，支持OAuth2、OpenID Connect等协议，能够为企业应用提供安全的单点登录（SSO）和身份验证服务，将盘古AI与Keycloak集成，可实现统一的用户认证、权限管理及安全策略控制，以下是分步骤的集成指南：

环境准备与前置条件

Keycloak服务部署
- 确保Keycloak服务器已部署并运行（支持Docker、Kubernetes或独立服务器部署）。
- 访问Keycloak管理控制台（默认地址：http://<KEYCLOAK_HOST>:8080/admin），使用初始管理员账号登录。
盘古AI服务配置
- 确认盘古AI应用支持OAuth2/OpenID Connect协议。
- 获取盘古AI的客户端ID（Client ID）、客户端密钥（Client Secret）及重定向URI（Redirect URI），这些信息通常由盘古AI管理员提供。

Keycloak端配置步骤

创建Realm（领域）
- 在Keycloak控制台中,点击左侧菜单的“Master”下拉框，选择“Add Realm”。
- 输入自定义Realm名称（如pangu-realm），点击“Create”。
配置客户端（Client）
- 在目标Realm下,点击“Clients”→“Create”。
- 填写盘古AI的客户端ID（如pangu-client），选择“OpenID Connect”协议。
- 在“Settings”标签页中配置以下参数：
  - Root URL：盘古AI的基础URL（如https://pangu-ai.example.com）。
  - Valid Redirect URIs：盘古AI回调地址（如https://pangu-ai.example.com/callback）。
  - Web Origins：与Root URL一致。
- 切换至“Credentials”标签页，记录生成的“Client Secret”（后续盘古AI配置需使用）。
- 启用“Implicit Flow”或“Authorization Code Flow”（根据盘古AI要求选择）。
配置角色与权限（可选）
- 在“Roles”标签页创建自定义角色（如pangu-admin、pangu-user）。
- 通过“Clients”→目标客户端→“Role Mappings”标签页，将角色映射至客户端。
设置协议映射（Protocol Mappers）
- 在客户端配置中,点击“Mappers”→“Create”。
- 添加以下常用映射（根据盘古AI需求调整）：
  - 用户名映射：Name=username，Mapper Type=User Property，Property=username，Token Claim Name=preferred_username。
  - 用户ID映射：Name=user_id，Mapper Type=User Attribute，Attribute=id，Token Claim Name=sub。
- 确保生成的JWT令牌包含盘古AI所需的字段。

盘古AI端配置步骤

OAuth2/OpenID Connect配置
- 登录盘古AI管理后台,找到“安全认证”或“SSO集成”模块。
- 选择“Keycloak”作为认证提供商，填写以下信息：
  - 授权端点（Authorization Endpoint）：https://<KEYCLOAK_HOST>/auth/realms/<REALM_NAME>/protocol/openid-connect/auth
  - 令牌端点（Token Endpoint）：https://<KEYCLOAK_HOST>/auth/realms/<REALM_NAME>/protocol/openid-connect/token
  - 用户信息端点（Userinfo Endpoint）：https://<KEYCLOAK_HOST>/auth/realms/<REALM_NAME>/protocol/openid-connect/userinfo
  - 退出登录端点（End Session Endpoint）：https://<KEYCLOAK_HOST>/auth/realms/<REALM_NAME>/protocol/openid-connect/logout
  - 客户端ID与客户端密钥：从Keycloak客户端配置中获取。
  - Scope：通常为openid profile email（根据需求调整）。
测试连接
- 保存配置后,使用“测试连接”功能验证端点可达性及密钥有效性。
- 模拟用户登录流程,确保重定向至Keycloak登录页，认证成功后返回盘古AI并获取用户信息。

高级配置与故障排查

跨域问题处理
- 若盘古AI与Keycloak不在同一域名下,需在Keycloak的“Clients”→目标客户端→“Web Origins”中添加盘古AI的域名。
- 确保盘古AI服务器配置了正确的CORS策略。
JWT令牌验证
- 使用工具（如jwt.io）解码Keycloak生成的令牌，检查是否包含盘古AI所需的声明（Claims）。
- 若缺少字段,返回Keycloak的“Protocol Mappers”调整配置。
日志与调试
- Keycloak日志路径：<KEYCLOAK_HOME>/standalone/log/server.log。
- 盘古AI日志：查看应用服务器日志（如Tomcat的catalina.out或Docker容器日志）。
- 常见错误：
  - 无效的重定向URI：检查Keycloak客户端配置与盘古AI回调地址是否完全匹配。
  - 令牌验证失败：确认客户端密钥未泄露，且盘古AI时间与Keycloak服务器同步（NTP服务）。