Drupal对接Keycloak 18登录点击按钮报参数缺失如何解决

问题现象 #

• 已完成Keycloak侧client id、client secret、realm参数配置，使用Drupal官方Keycloak模块实现登录、用户创建对接
• 访问本地登录地址http://localhost/drupal/user/login，点击「Login Keycloak」按钮后，站点抛出通用错误提示：The website encountered an unexpected error. Please try again later.
• 从系统日志中定位到具体报错信息：

Symfony\Component\Routing\Exception\MissingMandatoryParametersException: Some mandatory parameters are missing ("openid_connect_client") to generate a URL for route "openid_connect.redirect_controller_redirect". in Drupal\Core\Routing\UrlGenerator->doGenerate() (line 181 of C:\xampp\htdocs\drupal\core\lib\Drupal\Core\Routing\UrlGenerator.php).

排查解决步骤 #

• 校验依赖模块启用状态
  Drupal Keycloak模块依赖OpenID Connect核心模块运行，先进入后台扩展列表，确认openid_connect核心模块、Keycloak集成子模块都处于正常启用状态，不存在半安装、禁用情况。若缺失依赖，先完成模块启用，操作后清空全站缓存。
• 核对客户端配置完整性
  进入OpenID Connect配置页/admin/config/services/openid-connect，找到Keycloak客户端配置项逐一检查：
  • 客户端机器名（Machine name）不得为空，不得包含特殊字符，建议保留默认值keycloak，不要随意修改
  • 所有标注必填的配置项（client id、client secret、realm信息、服务端点地址）均填写完整，无漏填
  • 模块侧配置的重定向回调地址，与Keycloak服务端客户端配置的合法重定向URI完全一致，本地环境默认回调地址格式为http://localhost/drupal/openid-connect/keycloak
• 修复路由传参异常
  如果登录按钮是自定义模板/自定义代码输出的，检查跳转链接生成逻辑，生成openid_connect.redirect_controller_redirect路由的链接时，必须传入openid_connect_client参数，参数值为Keycloak客户端配置的机器名，正确的路由生成代码示例：

  $login_url = Url::fromRoute('openid_connect.redirect_controller_redirect', [
    'openid_connect_client' => 'keycloak'
  ]);
  

  如果是模块默认输出的登录按钮触发该报错，一般是配置保存异常导致客户端记录丢失，直接删除现有Keycloak客户端配置，重新填写保存后再测试。
• 排查版本兼容问题
  确认当前使用的Keycloak模块版本，与Drupal核心版本、OpenID Connect模块版本互相兼容，跨大版本的模块组合容易出现参数传递逻辑不匹配问题。若近期更新过核心或相关模块，可回滚到适配当前核心版本的稳定版再测试。
• 清理缓存验证结果
  完成上述调整后，依次清理Drupal全站路由缓存、渲染缓存，清空外部缓存服务（Redis、Memcached等）存储的数据，再清除本地浏览器缓存与站点Cookie，重新访问登录页测试跳转。

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