apache / apache/apisix

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

Open
#13,718 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Lua
Stars
17.1k
Forks
2.9k
Avg merge
3d 16h
Merged PRs (30d)
63

Description

### 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: https://github.com/apache/apisix/pull/13702

Contributor guide

Open the contributing guide

Research direction

Start with the openid-connect session schema, its encrypt_fields configuration, and build_session_opts; compare them with the corresponding secret_fallbacks handling in the saml-auth, dingtalk-auth, and feishu-auth plugins. Check the linked pull request for work already underway. Done means the schema accepts encrypted fallback secrets and the plugin documentation describes rotation without requiring runtime changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
lua
Domain
api, backend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.