feat(cas-auth): sign request URI cookie and tighten cookie attributes

[shreemaan-abhishek]

Description

This change updates the cas-auth plugin so that the CAS_REQUEST_URI cookie — which the plugin uses to remember where the user was headed before being bounced to the CAS IdP — is signed with HMAC-SHA256 and verified on the IdP callback using a constant-time comparison.

After successful CAS ticket validation, the recovered redirect target is also validated as a same-origin path before being applied; if the cookie is missing, malformed, fails signature verification, or carries something that is not a relative path, the plugin falls back to / instead of using the cookie value verbatim.

A new required cookie object is added to the plugin schema:

• cookie.secret (string, required, minLength 32) — HMAC-signing key. Must match across all APISIX nodes so cookies issued on one node remain verifiable on another. Encrypted at rest via schema.encrypt_fields.
• cookie.secure (boolean, default true) — whether to set the Secure attribute on issued cookies. Set to false only for deployments where the protected route is not served over HTTPS.
• cookie.samesite (string, default "Lax", enum "Lax"/"None") — value for the SameSite cookie attribute. "Strict" is intentionally not exposed because it suppresses the cookie on the IdP→SP top-level redirect when the IdP is on a different site. samesite="None" requires secure=true (rejected at check_schema time) because browsers refuse to store SameSite=None cookies without Secure.

HttpOnly continues to be set unconditionally on the issued cookies. t/lib/keycloak_cas.lua is updated so existing integration tests continue to pass; new tests in t/plugin/cas-auth.t exercise the schema constraints, the safe-redirect predicate, and the HMAC sign/verify roundtrip including tampering, wrong-secret, and malformed-cookie cases.

Breaking change

This PR is not backward compatible for existing cas-auth plugin configurations. A new field cookie.secret is added as a required field of the schema, and a route that has cas-auth enabled without it will fail check_schema and be rejected at admin-API time.

Why it has to be required: the cookie integrity guarantee this PR introduces depends on every issued cookie being signed and every received cookie being verified. Making the secret optional would mean some deployments sign and some do not — the verification path could not assume a signature exists, the safe-redirect fallback could not distinguish "unsigned cookie" from "tampered cookie", and the protection would be defeated in exactly the deployments that did not opt in. Requiring the secret keeps the invariant "every cookie issued by this plugin is signed" simple and enforceable.

Migration for existing configurations: add a cookie.secret of at least 32 characters to every route whose plugins contains cas-auth. The same value must be configured on every APISIX node in the deployment so that cookies issued on one node remain verifiable on another. Generate one with e.g. openssl rand -base64 48.

Before:

{
  "plugins": {
    "cas-auth": {
      "idp_uri": "https://cas.example.com",
      "cas_callback_uri": "/cas/callback",
      "logout_uri": "/cas/logout"
    }
  }
}

After:

{
  "plugins": {
    "cas-auth": {
      "idp_uri": "https://cas.example.com",
      "cas_callback_uri": "/cas/callback",
      "logout_uri": "/cas/logout",
      "cookie": {
        "secret": "<32+ char random string>"
      }
    }
  }
}

cookie.secure and cookie.samesite are optional and default to true and "Lax" respectively, which match the previous unconditional behavior introduced earlier in this PR.

Operational impact: during a rolling upgrade, any node already running the new code will reject old-format configs from etcd until they are updated. Recommended order: update all cas-auth route configurations to include cookie.secret first, then roll out the new APISIX binary.

Which issue(s) this PR fixes:

N/A

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)

[membphis]

This is a breakchange
This point must be clearly stated in the PR description.

[shreemaan-abhishek]

@membphis it is mentioned at the end of the PR description that it is not backward compatible.

[membphis]

@membphis it is mentioned at the end of the PR description that it is not backward compatible.

only this is not enough, pls write some detail doc about the not backward compatible

[shreemaan-abhishek]

@membphis updated the PR description with a Breaking change section that:

• Calls out the incompatibility explicitly at the top
• Explains why cookie.secret is required rather than optional (the integrity invariant only holds if every issued cookie is signed; making it optional would defeat the guarantee for unconfigured routes)
• Provides a concrete before/after JSON migration example
• Notes the rolling-upgrade operational impact (update configs first, then roll out the binary)

Happy to add anything else if there's a specific deployment concern you want covered.