feat: add saml-auth plugin

[AlinsRan]

Summary

This PR proposes a new saml-auth plugin for Apache APISIX to support SAML 2.0 authentication at the gateway layer.

The plugin acts as a SAML Service Provider (SP) and integrates with external Identity Providers (IdP) such as Keycloak, Okta, and Azure Active Directory. It allows APISIX to authenticate end users before a request reaches upstream services, while preserving the authenticated identity in ctx.external_user for downstream authorization plugins.

Motivation

APISIX already supports several authentication mechanisms such as key-based auth, JWT, OIDC, and CAS. However, many enterprises still rely on SAML-based identity systems for workforce SSO and federated login.

Without native SAML support at the gateway layer, operators currently have to:

• implement SAML handling in each upstream service,
• deploy an additional SAML-aware proxy in front of APISIX, or
• migrate existing enterprise IdP integrations to another protocol.

This creates unnecessary operational complexity and makes policy enforcement inconsistent across services.

The saml-auth plugin fills this gap by allowing APISIX to terminate the SAML authentication flow directly.

What this plugin provides

The plugin supports:

• HTTP-Redirect binding (default)
• HTTP-POST binding
• Single Sign-On (SSO)
• Single Logout (SLO)
• Session key rotation through secret_fallbacks
• Encrypted-at-rest sensitive fields for sp_private_key, secret, and secret_fallbacks

After a successful login, the authenticated user information is stored in ctx.external_user, so other plugins (for example, acl) can make authorization decisions based on SAML-authenticated user attributes.

Design overview

At request time, the plugin checks whether a valid SAML session already exists.

• If a valid session exists, the request continues and user attributes are exposed through ctx.external_user.
• If no valid session exists, APISIX redirects the client to the configured IdP.
• After the IdP authenticates the user, it sends a signed SAML response back to the configured callback URI.
• The plugin validates the SAML response, establishes a session, and allows the request to proceed.
• Logout requests can be initiated through the configured SLO endpoint, and the plugin supports completing the SAML logout flow with the IdP.

To improve operational robustness, the plugin also handles the lua-resty-saml dependency gracefully at runtime and returns a clear 503 when the library is unavailable.

Example use case

A company uses Keycloak as its enterprise IdP and wants all requests to /internal/* to require SAML login before they reach upstream services.

With this plugin, APISIX can:

1. redirect unauthenticated users to Keycloak,
2. validate the SAML assertion returned by Keycloak,
3. establish the gateway-side session, and
4. pass the authenticated identity to downstream authorization logic.

Example configuration

The following example protects a route with the saml-auth plugin:

curl "http://127.0.0.1:9180/apisix/admin/routes/1" \
  -H "X-API-KEY: $ADMIN_API_KEY" \
  -X PUT \
  -d '{
    "uri": "/internal/*",
    "plugins": {
      "saml-auth": {
        "sp_issuer": "https://sp.example.com",
        "idp_uri": "https://keycloak.example.com/realms/myrealm/protocol/saml",
        "idp_cert": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
        "login_callback_uri": "https://sp.example.com/login/callback",
        "logout_uri": "https://sp.example.com/logout",
        "logout_callback_uri": "https://sp.example.com/logout/callback",
        "logout_redirect_uri": "https://sp.example.com/logout/done",
        "sp_cert": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
        "sp_private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----",
        "auth_protocol_binding_method": "HTTP-Redirect",
        "secret": "my-session-secret",
        "secret_fallbacks": ["my-previous-secret"]
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "127.0.0.1:1980": 1
      }
    }
  }'

Schema highlights

Required fields:

• sp_issuer
• idp_uri
• idp_cert
• login_callback_uri
• logout_uri
• logout_callback_uri
• logout_redirect_uri
• sp_cert
• sp_private_key

Required fields:

• secret: must be identical on all APISIX nodes; used for resty.session key derivation. Without a stable secret, each worker generates a random key at startup, breaking session verification across workers and after reloads.

Optional fields:

• auth_protocol_binding_method (HTTP-Redirect or HTTP-POST)
• secret_fallbacks

Dependency and build notes

This plugin depends on lua-resty-saml.

Because lua-resty-saml builds native xmlsec bindings, this PR also updates the relevant build and CI paths to install the required development dependencies such as:

• OpenSSL development headers
• libxml2 development headers
• libxslt development headers
• zlib development headers

Files changed

Core plugin and registration:

• apisix/plugins/saml-auth.lua
• apisix/cli/config.lua
• conf/config.yaml.example
• apisix-master-0.rockspec
• t/admin/plugins.t

Tests:

• t/plugin/saml-auth.t

Documentation:

• docs/en/latest/plugins/saml-auth.md
• docs/zh/latest/plugins/saml-auth.md
• docs/en/latest/config.json
• docs/zh/latest/config.json

Build / CI support:

• Makefile
• ci/linux-install-openresty.sh
• ci/redhat-ci.sh
• docker/debian-dev/Dockerfile
• utils/install-dependencies.sh
• utils/linux-install-luarocks.sh

Backward compatibility

This PR adds a new plugin and does not change the behavior of existing routes unless the plugin is explicitly enabled.

Checklist

• I have explained the need for this PR and the problem it solves
• I have explained the changes or the new features added in this PR
• I have added or updated tests corresponding to this change
• I have updated the documentation to reflect this change
• I have verified that this change is backward compatible

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new saml-auth APISIX plugin to enable SAML 2.0 authentication (SP-initiated) for protected routes, along with registration, docs, and basic schema tests.

Changes:

• Introduces apisix/plugins/saml-auth.lua with schema + rewrite phase logic using lua-resty-saml
• Registers the plugin in default/config plugin lists and docs navigation
• Adds docs (EN/ZH) and a test file covering schema validation + missing dependency behavior

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
apisix/plugins/saml-auth.lua	Implements the saml-auth plugin schema and rewrite handler (loads/initializes lua-resty-saml, sets ctx.external_user).
conf/config.yaml.example	Adds saml-auth to the example plugin list at priority 2598.
apisix/cli/config.lua	Adds saml-auth to the default enabled plugin list.
t/plugin/saml-auth.t	Adds schema validation tests and missing lua-resty-saml graceful-failure tests.
docs/en/latest/plugins/saml-auth.md	Adds English plugin documentation and configuration reference.
docs/zh/latest/plugins/saml-auth.md	Adds Chinese plugin documentation and configuration reference.
docs/en/latest/config.json	Adds plugins/saml-auth to the English docs sidebar/config.
docs/zh/latest/config.json	Adds plugins/saml-auth to the Chinese docs sidebar/config.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[membphis]

Review notes from merge-risk check:

Dependency usage check: lua-resty-saml

This PR adds lua-resty-saml = 0.2.5. The object lifecycle is mostly aligned with api7/lua-resty-saml and API7 EE usage: initialize resty_saml once, create/cache a SAML object per APISIX plugin config, then call saml:authenticate() per request.

One concrete inconsistency still needs attention: upstream lua-resty-saml tests configure a stable session_config.secret, and lua-resty-saml passes opts.secret to resty.session. In this PR, secret is optional, which means resty.session can fall back to process-local random keying material. That is not safe for APISIX multi-worker / reload behavior; see P1 below.

[P1] secret is optional, which can make SAML sessions fail across workers/reloads

• Problem: saml-auth marks secret as optional, but the underlying lua-resty-saml session uses it as the resty.session encryption/key-derivation secret.
• Why this blocks merge: when secret is absent, lua-resty-session may use random process-local keying material. The worker that handles the ACS callback may be unable to read the saml_state cookie created by the worker that initiated login; reloads have the same problem.
• Impact: SAML login can fail intermittently in normal multi-worker deployments, or after worker reload/restart.
• Trigger: enable saml-auth without configuring secret.
• Evidence: apisix/plugins/saml-auth.lua makes secret optional and passes conf into resty_saml.new; lua-resty-saml builds session_config.secret = opts.secret; lua-resty-session derives IKM from secret when present, otherwise defaults to random keying material. APISIX openid-connect already requires session.secret for non-bearer interactive login for the same class of reason.
• Suggested fix: make secret required for saml-auth, require a stronger minimum length, document that all APISIX nodes must share the same value, and add schema coverage.

[P1] Runtime image misses libxslt, so default plugin loading can fail

• Problem: lua-resty-saml links saml.so with -lxslt, but the final Debian runtime image only installs libxml2, not the runtime libxslt package.
• Why this blocks merge: saml-auth is added to the default plugin list and directly requires resty.saml at module load time. If libxslt is missing, the gateway/container can fail during plugin load/startup.
• Impact: official/minimal runtime images may fail to start after this PR, even when users do not configure the new plugin on any route.
• Trigger: start APISIX with the default plugin list in a runtime image that lacks libxslt1.1.
• Evidence: lua-resty-saml Makefile links -lxslt; this PR's docker/debian-dev/Dockerfile final stage installs libxml2 but not libxslt1.1; apisix/plugins/saml-auth.lua uses top-level require("resty.saml").
• Suggested fix: install the runtime libxslt package in the final image and verify all dynamic runtime deps of saml.so are present. If graceful missing-dependency behavior is intended, keep pcall(require, ...) and align the PR description/tests with that behavior.

[membphis]

Follow-up after the latest update:

The two previous P1 code blockers look fixed now:

• secret is required by the plugin schema and covered by schema tests.
• The Debian runtime image installs libxslt1.1, so the lua-resty-saml native module should have the required runtime library.

One small docs mismatch still needs to be fixed before merge:

[P2] Chinese docs still mark secret as optional

• Problem: docs/zh/latest/plugins/saml-auth.md still shows secret as 必填 = 否, while the plugin schema now requires secret and the English docs show it as required.
• Why this blocks merge: Chinese users following the docs can omit secret, but the Admin API will reject the config. The row also misses the important note that the value must be identical on all APISIX nodes for session verification across workers/reloads.
• Evidence: apisix/plugins/saml-auth.lua includes "secret" in the required list; docs/en/latest/plugins/saml-auth.md marks secret as True; docs/zh/latest/plugins/saml-auth.md still marks it as 否.
• Suggested fix: change the Chinese secret row to 必填 = 是 and mirror the English description that the value must be identical on all APISIX nodes.

[membphis]

need to update the chinese doc too

docs/zh/latest/plugins/saml-auth.md, secret is a requied field