使用Keycloak作为IdP对接Django OIDC时出现oidc_states缺失问题

DevOps 小满

2026-10-1

问题根因澄清

oidc_states 字段并非需要Keycloak返回的回调参数，它是mozilla-django-oidc库在触发跳转到Keycloak登录页之前，自动写入当前用户Django session的校验值，用于后续回调时和请求携带的state参数做比对，防范CSRF攻击。你遇到的报错本质是回调请求对应的Django session中没有写入这个字段，和Keycloak的配置没有直接关系。

排查解决步骤

校验Django Session配置
确认Session存储服务正常：如果使用默认数据库Session，检查是否已执行python manage.py migrate创建session表；如果使用缓存类Session，确认Redis/Memcached等存储服务运行正常。
检查Cookie相关配置：如果当前Django服务使用HTTP协议访问，需确保SESSION_COOKIE_SECURE配置为False，否则浏览器不会存储Session Cookie，从Keycloak跳转回Django后会生成新的空白Session，自然不存在oidc_states字段。同时确认SESSION_COOKIE_DOMAIN、SESSION_COOKIE_PATH配置与站点域名、路径匹配，不会导致Cookie丢失。
校验mozilla-django-oidc库配置
确认未通过OIDC_CALLBACK_CLASS覆盖默认视图，或者自定义的跳转登录逻辑调用了库自带的state生成、Session写入逻辑，没有漏掉oidc_states写入步骤。
确认OIDC_STATE_SIZE配置未被修改为0或负数，该配置控制state值长度，设置异常会跳过state生成逻辑。
校验反向代理/跨域配置
如果Django前部署了Nginx等反向代理，需确认代理配置正确转发了Cookie请求头和Host头，示例Nginx配置项如下：
```
proxy_set_header Host $host;
proxy_set_header Cookie $http_cookie;
proxy_pass http://你的Django服务地址;
```
如果是前后端分离架构，前端调用登录接口时需开启withCredentials: true配置，否则请求不会携带Session Cookie，无法种下带oidc_states的会话。
快速定位方案
在跳转Keycloak前的登录视图和回调视图中分别打印request.session.session_key和request.session.get('oidc_states')，如果两次打印的session_key不一致，即可确认是Session Cookie丢失导致的问题。