feat(openid-connect): update session config to support lua-resty-session, fixes deprecated session.cookie.lifetime

[francescodedomenico]

Description

APISIX bundles lua-resty-session 4.1.5, but the openid-connect plugin's session schema still exposed the legacy session.cookie.lifetime property from the 3.x API. Since lua-resty-openidc passes the session configuration as-is to resty.session.start(), only properties recognized by the 4.x library actually take effect.

This PR removes the deprecated session.cookie.lifetime and replaces it with the full set of flat configuration keys that lua-resty-session 4.x supports.

Why does it matter

With this update we have full control of the oidc sticky session, allowing apisix users to

• declare multiple OIDC plugins in the same apisix configuration, with different client-ids, and properties
• to make such sticky sessions to be forwarded only for selected paths using the cookie_path parameter

New session properties

Category	Properties
Cookie	cookie_name, cookie_prefix, cookie_path, cookie_domain, cookie_http_only, cookie_secure, cookie_priority, cookie_same_site, cookie_same_party, cookie_partitioned
Timeouts	idling_timeout (default 900s), rolling_timeout (default 3600s), absolute_timeout (default 86400s)
Remember / persistent sessions	remember, remember_cookie_name, remember_rolling_timeout, remember_absolute_timeout, remember_safety
Other	audience, subject, enforce_same_subject, stale_ttl, touch_threshold, compression_threshold, hash_storage_key, hash_subject, store_metadata

Migration from session.cookie.lifetime

The old session.cookie.lifetime (default 3600s) mapped loosely to a single cookie expiry. In lua-resty-session 4.x this is replaced by three independent timeouts that give much finer-grained control:

Old property	New equivalent(s)	Default
session.cookie.lifetime	idling_timeout — invalidate after inactivity	900s
	rolling_timeout — force renewal after duration	3600s
	absolute_timeout — hard session max lifetime	86400s

Breaking change

Please note that even if I am mentioning this as a breaking change, the session.cookie.lifetime is already ignored by the resty.session plugin in APISIX main branch and 3.15 release, possibly happening on older versions as well

session.cookie.lifetime is no longer accepted. Existing configurations using this property will be rejected by schema validation (additionalProperties = false). Users should migrate to idling_timeout, rolling_timeout, and/or absolute_timeout.

Files changed

• apisix/plugins/openid-connect.lua — replaced session schema with lua-resty-session 4.x properties
• docs/en/latest/plugins/openid-connect.md — updated English documentation
• docs/zh/latest/plugins/openid-connect.md — updated Chinese documentation
• t/plugin/openid-connect10.t — 14 new schema validation tests covering valid configs, invalid enum/type values, deprecated property rejection, and unknown property rejection

Which issue(s) this PR fixes:

Fixes #13177

Checklist

• I have explained the need for this PR and the problem it solves
• I have explained the changes or the new features added to this PR
• I have added tests corresponding to this change
• I have updated the documentation to reflect this change
• I have verified that this change is backward compatible (If not, please discuss on the APISIX mailing list first)

[Baoyuantop]

Hi @francescodedomenico, thank you for your contribution, but we need to evaluate whether it’s necessary to expose all the underlying library’s configurations. I’ll discuss this with the other maintainers. I look forward to hearing others’ thoughts.

[kovasaurus]

I would like to chip into this discussion.

Prior to lua-resty-session 4.x we could use the nginx variables to setup the various features from lua-resty-session which were not exposed directly through openid-connect plugin in Apisix. After 4.x version, due to dependency chain of openid-connect apisix plugin -> lua-resty-openidc -> lua-resty-session it is only possible to configure those features by configuration which is sent from openid-connect plugin.

Effectively, the limited schema capabilities are now blocking us from using the features that exist in lua-resty-session.
This PR from OP addresses the cookie configuration, but I have additional example.

lua-resty-session supports Redis with sentinel configuration -> https://github.com/bungle/lua-resty-session/blob/master/README.md#redis-sentinels-configuration

I have tried to play around with it for a bit, and I've managed to create custom docker image from apisix:3.16.0 with lua-resty-redis-connector installed, adjusted the schema for openid-connect to support sentinel properties and were able to successfully connect to Redis sentinel. The setup is still being tested but so far looks good.

[Baoyuantop]

Hi @francescodedomenico, another issue with the current PR is that the session.cookie.lifetime configuration option has been removed outright, without providing a migration path or backward compatibility. This constitutes a breaking change. As for the additional configurations in lua-resty-session, I think we can make them available by setting additionalProperties instead of cramming them all into the current schema.

[francescodedomenico]

hello @Baoyuantop

...without providing a migration path or backward compatibility. This constitutes a breaking change.

I did add a migration note in the PR, the closest valid alternative for session.cookie.lifetime is the absolute_timeout parameter (gathered from the lifetime description of the 3.10 resty session).

I think it would be more maintainable if we continue to support 1:1 mapping rather than keeping a deprecated parameter and to map it internally. However if you tell me where I am supposed to also add the migration notes I will add them in a docs: commit.

As for the additional configurations in lua-resty-session, I think we can make them available by setting additionalProperties instead of cramming them all into the current schema.

I do agree that many parameters could be added in an session.cookie.additionalProperties field and describe the field as being mapped against the resty session configuration.

However I would like to suggest to at least expose the:

• cookie-name
• cookie-path

These two are a game changer for the user, we can have multiple oidc sessions, avoid "session" cookie conflict and have specific sessions being forwarded only to specific cookie-path.

Let me know, thank you.

Edit: fixed my answers being inglobated in quotes