Openresty集成Keycloak遇OpenID Connect会话状态缺失错误求助

Hey there, let's break down this error and walk through actionable fixes for your OpenResty reverse proxy with Keycloak authentication setup. This error typically pops up when the lua-resty-openidc module can't locate the session state that should exist when Keycloak redirects back to your application's callback endpoint. Here's how to diagnose and resolve it:

1. Validate Redirect URI Consistency (Keycloak + OpenResty) #

The most common culprit is a mismatch between the redirect URI configured in Keycloak and your OpenResty settings:

• In your Keycloak client configuration, double-check the Valid Redirect URIs field. It must exactly match the redirect_uri value in your OpenResty config—including protocol (http/https), domain, port, and path (no extra slashes or typos allowed).
• Ensure your OpenResty callback location explicitly sets the correct redirect URI. Example:

  location /auth/callback {
      access_by_lua_block {
          local opts = {
              redirect_uri = "https://your-production-domain.com/auth/callback",
              -- other Keycloak opts (issuer, client_id, client_secret)
          }
          local res, err = require("resty.openidc").authenticate(opts)
          if err then
              ngx.status = 500
              ngx.say(err)
              ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
          end
      }
  }
  

2. Check Session Storage Configuration #

By default, lua-resty-openidc stores session state in client-side cookies, but this can fail if:

• Cookie settings are misconfigured: Verify your OpenResty config isn't blocking or modifying cookies (e.g., no conflicting proxy_cookie_path rules). If using HTTPS, ensure cookies have the Secure flag enabled (the module does this by default for HTTPS, but double-check if you've overridden it).
• Distributed OpenResty setup: If you're running multiple OpenResty instances, the default cookie-based storage won't work across nodes. Switch to a shared session store like Redis:

  http {
      lua_shared_dict openidc 10m;
  
      server {
          # ... other server configs
          access_by_lua_block {
              local opts = {
                  redirect_uri = "https://your-domain.com/auth/callback",
                  session_store = "redis",
                  session_store_opts = {
                      redis_host = "your-redis-host",
                      redis_port = 6379,
                      redis_db = 0
                  },
                  -- other Keycloak opts
              }
              local res, err = require("resty.openidc").authenticate(opts)
              -- error handling
          }
      }
  }
  

3. Confirm Request Parameters Are Preserved #

When Keycloak redirects back to your callback, it sends code and state parameters. If these are lost or modified, the module can't retrieve the session state:

• Add temporary logging to verify the parameters are reaching your callback endpoint:

  location /auth/callback {
      access_log /var/log/nginx/openidc_callback.log combined;
      access_by_lua_block {
          ngx.log(ngx.INFO, "Callback params received: ", require("cjson").encode(ngx.req.get_uri_args()))
          -- authenticate logic here
      }
  }
  

• Check if any rewrite rules, WAF modules (like mod_security), or proxy settings are filtering these parameters.

4. Fix Cross-Domain Cookie Issues #

If your OpenResty app and Keycloak are on different domains, browser cookie policies might block session state cookies:

• Configure the SameSite cookie attribute to None (must be paired with Secure for HTTPS):

  local opts = {
      -- other opts
      cookie_opts = {
          secure = true,
          samesite = "None"
      }
  }
  

5. Rule Out Client-Side Cache #

Old or corrupted cookies in your browser can cause state mismatches:

• Clear your browser's cookies and cache, or test in incognito/private browsing mode to eliminate client-side issues.

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