升级Pac4j从5.7.6到5.7.7后遇UnknownHostException求助

问题分析 #

从5.7.6升级到5.7.7后出现java.net.UnknownHostException: keycloak.localhost，说明新版本可能对OIDC配置中的域名验证逻辑做了调整，默认限制了localhost子域名的使用，而旧版本允许这类测试域名。异常出现在OidcConfiguration.internalInit和OidcAuthenticator.validate方法中，进一步确认是Pac4j内部的域名校验或解析逻辑变更导致。

解决方案 #

1. 显式开启localhost子域名支持 #

检查OidcConfiguration的配置项，5.7.7版本可能收紧了域名验证规则，尝试手动开启localhost支持：

oidcConfig.setAllowLocalhost(true);

该配置会放宽对localhost及子域名的限制，适配测试环境的自定义子域名场景。

2. 验证Docker环境的DNS解析 #

确保Docker容器内部能正常解析keycloak.localhost：

• 在容器内执行ping keycloak.localhost，确认是否能解析到正确IP
• 如果使用Docker Compose，可直接用容器名访问（如http://keycloak/realms/gixx/.well-known/openid-configuration），避免依赖自定义子域名解析
• 若必须保留子域名，可在容器的/etc/hosts中添加映射：127.0.0.1 keycloak.localhost，或通过Docker的extra_hosts配置注入该映射

3. 排查版本变更细节 #

查看Pac4j 5.7.7的版本变更记录，确认是否有OIDC相关依赖升级或域名校验逻辑的改动，针对性调整配置。

4. 反馈兼容性问题 #

如果以上方法无效，说明这是版本升级引入的兼容性问题，可向Pac4j官方提交issue，提供以下信息：

• 5.7.6正常、5.7.7异常的复现步骤
• keycloak.localhost测试域名的使用场景
• 完整的异常栈信息

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