Keycloak开发环境不发送Cookie问题排查求助

环境部署背景 #

• 服务器：Hetzner Ubuntu，容器化部署Keycloak，连接同服务器MySQL容器
• 两个环境：
  • 预发布（staging）：配置Nginx负载均衡器并启用HTTPS，运行正常
  • 开发（develop）：无负载均衡器，仅使用HTTP，出现Cookie相关登录错误

环境配置文件 #

开发环境Dockerfile #

FROM quay.io/keycloak/keycloak:21.0.0 as builder

ENV KC_DB=mysql

ADD ./themes/tediro /opt/keycloak/themes/tediro

RUN /opt/keycloak/bin/kc.sh build

FROM quay.io/keycloak/keycloak:21.0.0
COPY --from=builder /opt/keycloak/ /opt/keycloak/

ENV KC_HOSTNAME_STRICT=false
ENV KC_HOSTNAME_STRICT_HTTPS=false
ENV KC_HTTP_ENABLED=true
ENV KC_HOSTNAME=auth.d-tms.tediro.com
ENV KC_LOGLEVEL=ALL
ENV KC_DB=mysql
ENV KC_DB_URL=jdbc:mysql://mysql:3306/keycloak
ENV KC_DB_USERNAME=keycloak
ENV KC_DB_PASSWORD=xxx
ENV KC_ADMIN=admin
ENV KC_ADMIN_PASSWORD=xxx
ENV KC_FEATURES=admin-fine-grained-authz
ENV KC_CACHE=local

ENV PROXY_ADDRESS_FORWARDING=false

ENV JDBC_PARAMS="useSSL=false&allowPublicKeyRetrieval=true&connectTimeout=50000"
ENV JAVA_TOOLS_OPTIONS="-Djboss.as.management.blocking.timeout=30000"
ENV JAVA_OPTIONS="-Djboss.as.management.blocking.timeout=6000"

ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start-dev"]

预发布环境Dockerfile #

FROM quay.io/keycloak/keycloak:21.0.0 as builder

ENV KC_DB=mysql

ADD ./themes/tediro /opt/keycloak/themes/tediro

RUN /opt/keycloak/bin/kc.sh build

FROM quay.io/keycloak/keycloak:21.0.0
COPY --from=builder /opt/keycloak/ /opt/keycloak/

ENV KC_HOSTNAME_STRICT=false
ENV KC_HOSTNAME_STRICT_HTTPS=true
ENV KC_HTTP_ENABLED=false
ENV KC_HOSTNAME=auth.s-tms.tediro.com
ENV KC_LOGLEVEL=ALL
ENV KC_DB=mysql
ENV KC_DB_URL=jdbc:mysql://mysql:3306/keycloak
ENV KC_DB_USERNAME=keycloak
ENV KC_DB_PASSWORD=xxx
ENV KC_ADMIN=admin
ENV KC_ADMIN_PASSWORD=xxx
ENV KC_FEATURES=admin-fine-grained-authz
ENV KC_CACHE=local
ENV KC_PROXY=edge

ENV PROXY_ADDRESS_FORWARDING=true

ENV JDBC_PARAMS="useSSL=true&allowPublicKeyRetrieval=true&connectTimeout=50000"
ENV JAVA_TOOLS_OPTIONS="-Djboss.as.management.blocking.timeout=30000"
ENV JAVA_OPTIONS="-Djboss.as.management.blocking.timeout=6000"

ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start"]

问题现象 #

• 开发环境中，应用通过keycloak-js调用keycloak.login()打开Keycloak托管的登录页面，页面正常设置AUTH_SESSION_ID_LEGACY和KC_RESTART两个Cookie
• 点击登录按钮时，上述两个Cookie未被浏览器发送给Keycloak，触发错误提示：Cookie not found. Please make sure cookies are enabled in your browser.
• 已排除浏览器设置问题，所有测试环境和用户端均复现；初步检查Cookie的Secure/SameSite选项配置无明显异常

可能原因及解决方案 #

1. Cookie Secure属性强制生效 #

尽管开发环境使用HTTP，但Keycloak可能默认给会话Cookie添加Secure属性，导致浏览器在HTTP环境下不会发送这类Cookie（Secure属性要求仅在HTTPS连接中传递Cookie）。

• 解决方案：在开发环境Dockerfile中添加环境变量KC_SPI_COOKIE_DEFAULT_SECURE=false，强制关闭Cookie的Secure属性要求；或者在启动命令中追加参数--spi-cookie-default-secure=false。

2. Hostname配置与实际访问地址不匹配 #

开发环境设置了KC_HOSTNAME=auth.d-tms.tediro.com，如果实际访问Keycloak使用的是IP地址或其他域名，会导致Cookie的Domain属性不匹配，浏览器拒绝发送Cookie。

• 解决方案：确保访问开发环境Keycloak的域名与KC_HOSTNAME完全一致；若使用IP访问，需删除KC_HOSTNAME配置，或结合已设置的KC_HOSTNAME_STRICT=false，让Keycloak自动适配访问地址。

3. 启动模式差异导致的配置偏差 #

开发环境使用start-dev启动，预发布环境使用start启动，两种模式的默认配置存在差异，可能影响Cookie的生成逻辑。

• 解决方案：尝试将开发环境的启动命令改为start，同时保留HTTP相关配置（KC_HTTP_ENABLED=true、KC_HOSTNAME_STRICT_HTTPS=false），验证问题是否解决。

4. 代理配置残留影响 #

开发环境设置了PROXY_ADDRESS_FORWARDING=false，但如果存在其他代理相关配置（如预发布环境的KC_PROXY=edge）残留，会让Keycloak错误判断运行环境，导致Cookie的Path或Domain配置异常。

• 解决方案：确保开发环境未设置KC_PROXY环境变量，避免Keycloak进入代理模式。

5. SameSite属性配置不当 #

若应用与Keycloak不在同一域名下，Cookie的SameSite属性设置可能导致浏览器在跨域请求时不发送Cookie。HTTP环境下无法使用SameSite=None（需配合Secure属性），因此需调整为Lax。

• 解决方案：在开发环境Dockerfile中添加环境变量KC_SPI_COOKIE_DEFAULT_SAME_SITE=Lax，统一设置Cookie的SameSite属性为宽松模式。

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