How to configure persistent session cookies (Max-Age/Expires) in APISIX?

[overide]

We are encountering an issue in which session cookies generated by APISIX are sent without explicit Max-Age or Expires attributes in the Set-Cookie header. As a result, client browsers treat them strictly as session-scoped cookies.

While modern client browsers with session restore retain these cookies across restarts, browsers running on certain remote Windows Server environments purge them immediately upon closure, forcing users to re-authenticate on every restart.

I'm using apisix:3.17.0 and OIDC Plugin - https://apisix.apache.org/docs/apisix/plugins/openid-connect/

Current Configuration

We configured the session timeout settings expecting persistent cookies to be written, but the cookies are still generated without an expiration timestamp:

idling_timeout: 0
rolling_timeout: 0
absolute_timeout: 2592000 # 30 days

Expected Behavior

The Set-Cookie header should include a Max-Age or Expires attribute reflecting the configured duration so that the browser treats the cookie as persistent across sessions.

Actual Behavior

The Set-Cookie header omits the expiration attributes, causing the cookie to be discarded whenever the browser process terminates in strict/remote environments.

Questions

1. Is there an additional configuration or flag needed to enforce persistent cookies rather than session cookies?
2. Does the underlying session handler require specific properties (such as setting cookie persistence directly) to propagate Max-Age into the response header?

[jmrplens]

There is no flag you are missing. On 3.17.0 the openid-connect plugin cannot emit a persistent cookie at all, and your three timeouts are not the knob for it.

Why the timeouts do not do it

idling_timeout, rolling_timeout and absolute_timeout govern how long the session is considered valid, which is enforced server side when the cookie comes back. They say nothing about how long the browser keeps it. In lua-resty-session 4.1.5, the version APISIX 3.17.0 pins in its rockspec, Expires and Max-Age are written in exactly one place:

local remember_flags
if remember then
  local max_age = self.remember_rolling_timeout
  ...
  remember_flags = fmt("; Expires=%s; Max-Age=%d", expires, max_age)
end

That is the whole of it. The attributes only ever appear on the "remember me" cookie, which is a separate cookie with its own name and its own timeouts. The ordinary session cookie is a session cookie by design and never carries an expiry.

Why you cannot turn it on

The plugin's session schema is a closed whitelist, additionalProperties = false, and it has no persistence key. I tried every 4.x name on a clean 3.17.0 and the Admin API rejects all of them:

$ curl -X PUT .../apisix/admin/routes/2 -d '{... "session": {"secret": "...", "remember": true}}'
{"error_msg":"failed to check the configuration of plugin openid-connect err: property \"session\" validation failed: additional properties forbidden, found remember"}

Same for cookie_persistent, remember_rolling_timeout, cookie_max_age and persistent. Your current config is accepted exactly as you wrote it, and the cookie still comes out without an expiry:

Set-Cookie: session=AQAA7qy3...; Path=/; SameSite=Lax; HttpOnly

That is APISIX 3.17.0 with absolute_timeout: 2592000 configured, so this reproduces your report.

This gap is known, incidentally. Issue #13177 asked for the lua-resty-session 4.x options and listed "remember/persistent session settings" among the ones missing from the schema. The fix, PR #13178, merged on 2026-06-10, is what gave you the flat idling_timeout / rolling_timeout / absolute_timeout keys you are using, but it added the timeouts and the cookie_* attributes only. The word remember does not appear anywhere in that diff, so persistence was named in the request and simply not covered.

What works today

Rewrite the header on the way out. This is tested on 3.17.0 and produces exactly what you want:

"serverless-post-function": {
  "phase": "header_filter",
  "functions": ["return function(conf, ctx)\n  local ck = ngx.header[\"Set-Cookie\"]\n  if not ck then return end\n  local max_age = 2592000\n  local function fix(c)\n    if c:find(\"^session=\") and not c:lower():find(\"max%-age\") then\n      return c .. \"; Max-Age=\" .. max_age .. \"; Expires=\" .. ngx.cookie_time(ngx.time() + max_age)\n    end\n    return c\n  end\n  if type(ck) == \"table\" then\n    local out = {}\n    for i, c in ipairs(ck) do out[i] = fix(c) end\n    ngx.header[\"Set-Cookie\"] = out\n  else\n    ngx.header[\"Set-Cookie\"] = fix(ck)\n  end\nend"]
}

Result on the same route:

Set-Cookie: session=AQAApltx...; Path=/; SameSite=Lax; HttpOnly; Max-Age=2592000; Expires=Mon, 05-Oct-26 08:07:44 GMT

Three things to keep in mind. Match the max_age to your absolute_timeout so the browser does not hold a cookie the gateway will reject anyway, which in your case is the same 2592000. Keep the ^session= guard and the Max-Age check so you only touch the session cookie and never double-append. And be deliberate about it: a persistent auth cookie on shared or kiosk machines survives the browser closing, which is the whole point here but is also the reason the library does not do it by default.

[bzp2010]

This is an intentional design choice in lua-resty-session. It differs significantly from your understanding of the Max-Age header for cookies.

Session cookies are always valid only for the duration of the browser session and are cleared when the browser is closed; their concept is similar to a short-term access_token.
It also provides a separate "remember" cookie, which is used for session restoration, that's a concept similar to a long-term refresh_token. Whenever the browser restarts, the server uses this cookie and the session data stored on the server to regenerate and send the session cookie.

Currently, neither APISIX’s OpenID Connect nor lua-resty-session utilizes the "remember" feature. Therefore, the mechanism described above will not take effect.

Manually modifying the session cookie's expiration time is neither supported nor recommended. We do not endorse this informal method, and you must resolve any unexpected issues on your own.

---

APISIX acts as the Service Provider (SP) in the authentication process. It can use a short-term cookie mechanism exclusively, refreshing the cookie with every request. Once the short-term cookie expires, the user is redirected directly to the Identity Provider (IDP).

We expect the IDP to provide a session persistence mechanism with a longer validity period. For example, sessions on Google OAuth rarely expire with regular use. The IDP can silently complete authentication and code generation, then redirect back to APISIX, which will also silently handle token exchange and reverse proxying.
As a result, users will only experience a few redirects before gaining access to the system.

One example is the Keycloak Admin Console, which does exactly that.

[jmrplens]

Thanks, that settles the intent, and it lines up with what the code does: the remember cookie exists in lua-resty-session and nothing in the plugin wires it, which is why no schema key turns it on.

I withdraw the header rewrite for anyone reading later. It works, but you have said it is not supported, and there is a supported way to get what was asked for.

One thing worth adding though, because it decides whether the silent re-authentication actually happens: with Keycloak's default realm settings it does not. Measured on APISIX 3.17.0 with Keycloak 26, cookies after a successful login through the plugin:

cookie	Remember Me off	Remember Me on and ticked
KEYCLOAK_IDENTITY	session	persistent, 30 days
KEYCLOAK_SESSION	persistent	persistent, 30 days
KEYCLOAK_REMEMBER_ME	absent	persistent, 1 year
APISIX session	session	session

Then dropping every cookie with no expiry, which is what the browsers in the original report do on close:

• Remember Me off: only KEYCLOAK_SESSION survives and the next request lands on the login form. KEYCLOAK_IDENTITY is what proves the SSO session, and it is a session cookie, so there is nothing to re-authenticate silently against.
• Remember Me on: KEYCLOAK_IDENTITY survives, the next request goes to the IdP and back into the upstream with no form. That is exactly the behaviour you describe.

So for the original report the knob is on the IdP, not on APISIX: enable Remember Me on the realm, set ssoSessionIdleTimeoutRememberMe and ssoSessionMaxLifespanRememberMe to the window you want, and the user ticks the box once. APISIX keeps its short lived cookie exactly as designed.

[overide]

Thanks for the clarification, @bzp2010 @jmrplens

A quick follow-up on absolute_timeout: To align with our IdP's 30-day refresh token validity, I plan to set absolute_timeout to 30 days so the gateway can silently refresh tokens without dropping sessions.

Is this recommended? Since access tokens expire in 10 minutes while the gateway session lasts 30 days, does APISIX track the access token's expiry and trigger a refresh under the hood?

[jmrplens]

Both parts are measurable, so I set it up: APISIX 3.17.0 with Keycloak 26, access token lifetime cut to 60 seconds, and the plugin configured with set_access_token_header so I could read what actually reaches the upstream.

Yes, it renews on its own. renew_access_token_on_expiry defaults to true in the plugin schema, and it does what it says. The exp of the access token injected upstream, one request every 75 seconds against a 60 second lifetime:

request	http	access token exp
just logged in	200	1788784691
+75s	200	1788784766
+150s	200	1788784841
+225s	200	1788784916

A fresh token every time, with no user interaction. So you do not need a short absolute_timeout for token hygiene: the gateway is already rotating the access token behind the request.

What decides the real ceiling is the IdP, not absolute_timeout. I capped the Keycloak SSO session at 120 seconds and left everything else alone:

	direct	following redirects	login form
within the cap	200	200	no
past the cap	302	200	yes

Once the IdP session is over the refresh fails, APISIX redirects, and the user gets the form. So an absolute_timeout of 30 days is coherent only if the refresh token and the IdP session really live 30 days as well. Whichever expires first wins, and a gateway session that outlives it just means the redirect happens at the next request instead of at the timeout.

Two details worth knowing. access_token_expires_leeway defaults to 0, so renewal happens after expiry rather than before it, and a few tens of seconds there avoids handing the upstream a token that dies in flight. And the session cookie is still browser scoped, which is where this thread started: a 30 day server side session only survives a browser restart if the IdP keeps its own persistent cookie.