如何在Rocket.Chat及JSF定制CRM中配置Keycloak SSO认证？

我帮你梳理一下完整的配置步骤，结合你遇到的问题，重点关注容易踩坑的细节：

一、Keycloak 端核心配置 #

先确保Keycloak这边的基础配置正确，这是后续集成的关键：

• 创建专属Realm：
  在Keycloak后台新建一个独立Realm（比如rocketchat-realm），不要用默认的master，避免权限混乱。

• 配置Rocket.Chat Client：

  1. 进入Realm -> Clients -> Create，填写Client ID为rocketchat，Client Protocol选择openid-connect，点击Save。
  2. 在Settings标签页：
     • Access Type设为confidential（因为Rocket.Chat是服务器端应用）；
     • Valid Redirect URIs必须填写Rocket.Chat的OAuth回调地址：http(s)://你的Rocket.Chat域名/_oauth/keycloak/callback；
     • Web Origins填写允许跨域的域名，比如http(s)://你的Rocket.Chat域名,http(s)://你的JSF CRM域名（测试阶段可以用*，生产环境建议指定具体域名）；
     • 其他保持默认，点击Save。
  3. 切换到Credentials标签页，复制Secret值，后面Rocket.Chat配置会用到。

• 配置用户信息映射（Client Scope）：
  Rocket.Chat需要从Keycloak获取用户名、邮箱等信息来创建用户，所以得确保这些字段能正确传递：

  1. 进入Realm -> Client Scopes -> Create，新建一个rocketchat-scope；
  2. 切换到Mappers标签页，添加几个Mapper：
     • 类型选User Property，Name填email，User Property填email，Token Claim Name填email，勾选Add to ID token和Add to access token；
     • 同理添加username（映射到username或preferred_username）、full name（映射到firstName+lastName组合，或者直接用name字段）；
  3. 回到Rocket.Chat的Client配置，在Client Scopes标签页，把rocketchat-scope添加到Default Client Scopes里。

• 准备测试用户：
  在Realm -> Users里创建一个测试用户，确保填写了Email、Username、First Name/Last Name，并设置好密码，启用该用户。

二、Rocket.Chat 端配置 #

接下来在Rocket.Chat后台完成OAuth集成：

• 启用Keycloak OAuth Provider：
  登录Rocket.Chat Admin面板，进入Settings -> OAuth，找到Keycloak选项，将Enabled设为True。

• 填写核心配置项：
  对应Keycloak的信息填写：

  • Client ID：rocketchat（和Keycloak里的一致）；
  • Client Secret：刚才复制的Keycloak Client Secret；
  • Server URL：http(s)://你的Keycloak域名/auth/realms/rocketchat-realm（注意路径要包含Realm名称）；
  • Token Path：/protocol/openid-connect/token；
  • Identity Path：/protocol/openid-connect/userinfo；
  • Authorization Path：/protocol/openid-connect/auth；
  • Scope：openid email profile（或者你创建的rocketchat-scope）；
  • Login Style：可选Popup或Redirect，根据你的需求选择。

• 用户数据映射配置：
  在OAuth设置的User Data Mapping区域，确保：

  • Username Field：preferred_username（或你在Keycloak里映射的用户名字段）；
  • Email Field：email；
  • Name Field：name（或full_name，根据你的Mapper配置）。

• 关键全局配置：
  进入Settings -> General，确认Site URL填写正确的Rocket.Chat域名（必须和Keycloak里的Redirect URI一致，包括http/https和端口）。

三、JSF CRM 集成要点 #

因为你的CRM是JSF开发的，要实现和Rocket.Chat的SSO，需要共享Keycloak身份源：

• 集成Keycloak Java Adapter：
  在JSF项目中引入Keycloak Java Adapter依赖（Maven/Gradle），并配置keycloak.json文件：

  {
    "realm": "rocketchat-realm",
    "auth-server-url": "http(s)://你的Keycloak域名/auth/",
    "ssl-required": "external",
    "resource": "crm-client",
    "credentials": {
      "secret": "你的CRM Client Secret"
    },
    "confidential-port": 0
  }
  

  同时在web.xml中配置Keycloak的过滤器，保护CRM的资源。

• SSO 配置：
  确保Keycloak中CRM Client的Valid Redirect URIs和Web Origins包含Rocket.Chat的域名，这样用户登录CRM后，访问Rocket.Chat会自动识别Keycloak会话，实现单点登录。

• 用户数据同步：
  CRM和Rocket.Chat都从Keycloak获取用户信息，无需各自维护用户数据库，确保两者的用户字段映射一致即可。

四、常见问题排查 #

如果之前的配置无效，可以从这些方向排查：

• 检查Redirect URI一致性：
  Rocket.Chat的回调地址必须和Keycloak Client里的Valid Redirect URIs完全匹配，包括协议（http/https）、域名、端口，比如http://localhost:3000/_oauth/keycloak/callback不能写成http://localhost/_oauth/keycloak/callback。

• 查看日志定位错误：

  • Keycloak日志：在Realm -> Events里查看认证请求的错误信息，比如invalid redirect_uri、missing scope；
  • Rocket.Chat日志：在Admin面板 -> Logs -> System里搜索oauth或keycloak相关的错误，比如无法获取Token、用户字段映射失败。

• SSL证书问题：
  如果使用HTTPS，确保Rocket.Chat信任Keycloak的SSL证书，或者测试时可以临时在Rocket.Chat中禁用证书验证（生产环境不建议）：
  在Rocket.Chat的环境变量中添加OAUTH_KEYCLOAK_INSECURE=true，或者在Admin面板的OAuth设置里找到Insecure选项设为True。

• Scope权限检查：
  确保请求的Scope包含openid（必须），以及email、profile等必要字段，否则Keycloak不会返回对应的用户信息。

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