Skip to content

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

Open
jens-skribble wants to merge 2 commits 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 2 commits into
apache:masterfrom
jens-skribble:feat/openid-connect-session-secret-fallbacks

Conversation

@jens-skribble

@jens-skribble jens-skribble commented Jul 16, 2026

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.

Fixes: 13718

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
…ct-session-secret-fallbacks

Resolves the `encrypt_fields` conflict with the PAR and DPoP support merged
in apache#13649: keep `dpop.private_key` from master and `session.secret_fallbacks`
from this branch, so all six encrypted fields are preserved.

Generated-by: Claude (Anthropic) via Claude Code
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.

feat: openid-connect - support session.secret key rotation

1 participant