Skip to content

feat(openid-connect): support session.secret_fallbacks for key rotation#13702

Open
jens-skribble wants to merge 1 commit into
apache:masterfrom
jens-skribble:feat/openid-connect-session-secret-fallbacks
Open

feat(openid-connect): support session.secret_fallbacks for key rotation#13702
jens-skribble wants to merge 1 commit into
apache:masterfrom
jens-skribble:feat/openid-connect-session-secret-fallbacks

Conversation

@jens-skribble

Copy link
Copy Markdown

Description

The openid-connect plugin stores its session in a cookie sealed with a key derived from session.secret. Because the plugin exposes only a single session.secret (and the session schema sets additionalProperties = false), the secret cannot be rotated without breaking active sessions:

  • Rotating session.secret invalidates every live cookie at once, forcing all users to re-authenticate.
  • In a high-availability deployment where instances are updated one by one, there is a window in which an instance carrying the new secret cannot decrypt a cookie issued by an instance still using the old one, so requests fail depending on which instance they land on.

lua-resty-session 4.x (already used by this plugin) supports graceful key rotation via secret_fallbacks: cookies sealed with any secret listed in secret_fallbacks still decrypt, while new cookies are sealed with the primary secret. This PR exposes that option:

  • Add session.secret_fallbacks (array of strings, each minLength 16) to the session schema.
  • Add session.secret_fallbacks to encrypt_fields so the values are encrypted at rest when data encryption is enabled (the nested-array path is handled by plugin.lua's process_encrypt_field).
  • Document the pre-seed -> flip -> retire rotation procedure in the plugin docs.

build_session_opts already forwards the session table verbatim to resty.session.start(), so no runtime change is required beyond allowing the field through validation.

This mirrors the secret + secret_fallbacks pattern already shipped in the saml-auth, dingtalk-auth, and feishu-auth plugins.

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 (the field is optional; existing configs with only session.secret are unaffected, covered by a test case)

The openid-connect plugin stores its session in a cookie sealed with a key
derived from `session.secret`. Rotating that single secret invalidates every
live cookie at once, forcing all users to re-authenticate. In an HA deployment
updated instance-by-instance it also creates a window where an instance carrying
the new secret cannot decrypt a cookie issued by an instance still using the old
one.

lua-resty-session 4.x already supports graceful key rotation via
`secret_fallbacks`: cookies sealed with any fallback secret still decrypt, while
new cookies are sealed with the primary `secret`. The `session` schema's
`additionalProperties = false` prevented passing it through.

This exposes `session.secret_fallbacks` explicitly (mirroring the pattern already
used by saml-auth), adds it to `encrypt_fields`, and documents the
pre-seed -> flip -> retire rotation procedure. `build_session_opts` already
forwards the session table verbatim to lua-resty-session, so no runtime change is
needed.

Generated-by: Claude (Anthropic) via Claude Code
@dosubot dosubot Bot added size:L This PR changes 100-499 lines, ignoring generated files. enhancement New feature or request labels Jul 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant