FastAPI集成Keycloak认证（v20.0）URL配置报错求助

错误原因分析 #

• 带http://前缀时报错MissingSchema: Invalid URL 'None': No scheme supplied：核心原因是Keycloak路径配置错误。Keycloak 17+版本（含20.0）采用Quarkus重构后，默认路径不再包含/auth，若你的server_url带了/auth，库内部拼接OIDC配置路径时会出错，生成无效URL。
• 去掉前缀时报错requests.exceptions.InvalidSchema: No connection adapters were found for：requests库需要明确的协议头（http/https）才能建立连接，不带前缀的URL无法被识别。

解决方案 #

1. 修正Server URL格式
   Keycloak 20.0版本的正确server_url需包含完整协议头，且末尾不带/auth，示例代码如下：

   from fastapi_keycloak import FastAPIKeycloak, OIDCUser
   
   app = FastAPI()
   idp = FastAPIKeycloak(
       server_url="https://auth.some-domain.com/",  # 保留协议头，移除末尾的/auth
       client_id="some-client",
       client_secret="some-client-secret",
       admin_client_secret="admin-cli-secret",
       realm="some-realm-name",
       callback_uri="http://localhost:8081/callback"
   )
   idp.add_swagger_config(app)
   

2. 验证OIDC配置有效性
   手动访问https://auth.some-domain.com/realms/some-realm-name/.well-known/openid-configuration，若能返回JSON格式的OIDC配置，说明server_url和realm配置正确；若返回404，需确认Keycloak部署路径是否有自定义修改。

3. 排查其他配置项

   • 确认Keycloak服务可被应用所在网络访问，无防火墙或代理拦截
   • 检查Keycloak客户端的Valid Redirect URIs是否包含你的callback_uri（http://localhost:8081/callback）
   • 确保admin_client_secret对应Keycloak中admin-cli客户端的密钥，且该客户端已开启服务账号权限

额外提示 #

若修正路径后仍有问题，可尝试升级fastapi-keycloak到最新版本，确保与Keycloak 20.0的兼容性。

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