feat: add saml-auth plugin#13346
Open
AlinsRan wants to merge 15 commits into
Open
Conversation
The saml-auth plugin enables SAML 2.0 authentication for API routes. It integrates with external Identity Providers (IdP) such as Keycloak, Okta, and Azure Active Directory. The plugin supports: - HTTP-Redirect and HTTP-POST SAML binding methods - Single Sign-On (SSO) and Single Logout (SLO) - Session key rotation via secret_fallbacks - Encrypted storage of private keys and secrets Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
dosubot
Bot
added
size:XL
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
shreemaan-abhishek
previously approved these changes
May 13, 2026
There was a problem hiding this comment.
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.luawith schema +rewritephase logic usinglua-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.
- Add saml-auth to t/admin/plugins.t expected plugin list - Fix response_body_like regex for required field error messages to tolerate quoted field names (e.g. "sp_issuer" vs sp_issuer) - Fix preprocessor to also check error_log_like when deciding whether to set no_error_log so TEST 8 no longer conflicts Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add additionalProperties=false to schema to reject unknown fields - Rename unused schema_type param to _ in check_schema - Change debug=false in saml_lib.init to avoid leaking sensitive data - Check saml:authenticate() return value and handle errors gracefully - Add TEST 9 to cover normal rewrite flow with mocked saml library Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This change is not needed and deviates from APISIX plugin conventions. It would also require downstream EE sync changes unnecessarily. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Change core.log.error to core.log.warn for missing lua-resty-saml so TEST 8 passes no_error_log "[error]" check while still matching error_log_like pattern (nginx writes warn to error.log) - Provide required lrucache ctx fields (conf_type/conf_id/conf_version) in TEST 9 to fix nil concatenation crash in plugin_ctx_key_and_ver Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The saml-auth plugin requires lua-resty-saml but it was missing from the rockspec dependencies. Add lua-resty-saml = 0.2.5 to match the version used in the enterprise edition. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
lua-resty-saml bundles xmlsec1 which requires libxml2 and libxslt at build time and libxml2 at runtime. Add the missing system dependencies to the debian-dev Docker image. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
lua-resty-saml builds xmlsec1 from source which requires: - libxml2-dev / libxml2-devel: XML parsing library - libxslt-dev / libxslt-devel: XSLT processing library - libssl-dev: OpenSSL (required by xmlsec1 crypto backend) Add these to all CI environments: Ubuntu test runner, RedHat/UBI runner, and the debian-dev Docker image. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
lua-resty-saml rockspec passes OPENSSL_DIR to its make build step via build_variables. APISIX's make deps configured OPENSSL_LIBDIR and OPENSSL_INCDIR but never OPENSSL_DIR, causing luarocks to pass an empty OPENSSL_DIR to make. With an empty OPENSSL_DIR, the ?= default in lua-resty-saml's Makefile is overridden (command-line assignment takes precedence), so xmlsec1's configure receives --with-openssl=/ which fails with 'not found: //include/openssl/opensslv.h'. Fix: add OPENSSL_DIR to the luarocks config alongside OPENSSL_LIBDIR and OPENSSL_INCDIR so lua-resty-saml finds the OpenResty OpenSSL. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
lua-resty-saml compilation requires: - libxslt-dev / libxslt-devel: needed for xmlsec/transforms.h - libxml2-dev / libxml2-devel: needed for libxml2 headers - zlib-dev / zlib1g-dev: needed for saml.c zlib.h include Add these to all build environments: install-dependencies.sh (apt/yum paths) and the debian-dev Docker build stage. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The linux_apisix_current_luarocks CI path calls 'luarocks install' directly (bypassing 'make deps'), so the OPENSSL_DIR luarocks variable was never set, causing lua-resty-saml's xmlsec1 build to fail with 'not found: //include/openssl/opensslv.h'. Add OPENSSL_DIR alongside the existing OPENSSL_LIBDIR/INCDIR config. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
saml-authplugin enables SAML 2.0 authentication for API routes, acting as a SAML Service Provider (SP) that integrates with external Identity Providers (IdP) such as Keycloak, Okta, and Azure Active Directory.Changes
apisix/plugins/saml-auth.lua— Plugin implementation (priority: 2598, phase: rewrite)apisix-master-0.rockspec— Addedlua-resty-saml = 0.2.5dependencyconf/config.yaml.example— Registered plugin at priority 2598 (between openid-connect 2599 and cas-auth 2597)apisix/cli/config.lua— Added plugin to default plugin listt/plugin/saml-auth.t— Schema validation testsdocs/en/latest/plugins/saml-auth.md— English documentationdocs/zh/latest/plugins/saml-auth.md— Chinese documentationPlugin Features
secret_fallbackssp_private_key,secret, andsecret_fallbacksctx.external_userfor downstream authorization plugins (e.g.,acl)