Skip to content

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

Description

@jens-skribble

Description

Problem

The openid-connect plugin seals its session cookie with a key derived from session.secret. The session schema exposes only a single secret and sets additionalProperties = false, so there is no way to rotate that secret gracefully. Any rotation is a hard cutover with two concrete failure modes:

  • Replacing session.secret invalidates every live cookie at once, forcing all users to re-authenticate.
  • In an HA deployment updated instance-by-instance, there is a window where an instance carrying the new secret cannot decrypt a cookie issued by an instance still on the old secret, so requests fail depending on which instance they hit.

Proposed enhancement

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. Exposing this in the session schema would allow a safe pre-seed → flip → retire rotation:

  • Add session.secret_fallbacks (array of strings, minLength 16) to the session schema.
  • Add it to encrypt_fields so values are encrypted at rest when data encryption is enabled.
  • Document the rotation procedure in the plugin docs.

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

Precedent

The secret + secret_fallbacks pattern is already shipped in the saml-auth, dingtalk-auth, and feishu-auth plugins, including having secret_fallbacks in their encrypt_fields. This request brings openid-connect in line with those.

The change is optional and backward compatible: existing configs with only session.secret are unaffected.

I've opened a PR implementing this: #13702

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    Status
    📋 Backlog

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions