Skip to main content
API7.ai Logo

Parameters​

See plugin common configurations for configuration options available to all plugins.

  • sp_issuer

    string

    required

    The service provider (SP) entity ID. Configure the same value as the SAML client ID at the identity provider (IdP).

  • idp_uri

    string

    required

    The identity provider (IdP) SAML endpoint where the plugin sends authentication and logout requests.

  • idp_cert

    string

    required

    The identity provider (IdP) X.509 signing certificate in PEM format. The plugin uses it to verify signed SAML responses.

  • login_callback_uri

    string

    required

    The URI path where the identity provider (IdP) sends the SAML response after authentication.

    Configure a path matched by the protected route. For example, use /anything/login_callback when the route URI is /anything/*.

  • logout_uri

    string

    required

    The URI path to trigger the SAML logout process.

    Configure a path matched by the protected route. For example, use /anything/logout when the route URI is /anything/*.

  • logout_callback_uri

    string

    required

    The URI path where the identity provider (IdP) sends the SAML logout response.

    Configure a path matched by the protected route. For example, use /anything/logout_callback when the route URI is /anything/*.

  • logout_redirect_uri

    string

    required

    The URI where the plugin redirects the browser after single logout completes.

    Use a public route if the user should remain logged out. Redirecting to a path protected by the same plugin starts a new authentication flow.

  • sp_cert

    string

    required

    The service provider (SP) X.509 certificate in PEM format. The identity provider (IdP) uses it to verify requests signed by the plugin.

  • sp_private_key

    string

    required

    The private key corresponding to sp_cert, in PEM format. The plugin uses it to sign authentication and logout requests.

    The value is encrypted with AES before being stored in the database.

  • secret

    string

    required

    vaild vaule:

    8 to 32 characters

    A cryptographic secret used to derive encryption keys for SAML session data. Configure the same value on every gateway node so sessions remain valid across nodes and reloads.

    The value is encrypted with AES before being stored in the database.

    Introduced in API7 Enterprise 3.9.3 and APISIX 3.17.0.

  • auth_protocol_binding_method

    string

    default: HTTP-Redirect

    vaild vaule:

    HTTP-Redirect or HTTP-POST

    The SAML binding method used for authentication requests. Introduced in API7 Enterprise 3.9.3 and APISIX 3.17.0.

    If set to HTTP-Redirect, the plugin sends the authentication request through a browser redirect.

    If set to HTTP-POST, the plugin sends the authentication request in an HTML form and sets the session cookie attributes to SameSite=None and Secure. Use HTTPS with this binding.

  • secret_fallbacks

    array[string]

    Previous session secrets accepted during key rotation. Configure the new value in secret and retain the immediately preceding value here until older sessions expire.

    The value is encrypted with AES before being stored in the database.

    Introduced in API7 Enterprise 3.9.3 and APISIX 3.17.0.

  • idp_issuers

    array[string]

    Issuers accepted on a login response. Every assertion in the response must name one of them.

    If unset, any issuer whose assertions are signed by the idp_cert certificate is accepted. An empty list accepts no issuer.

    Introduced in API7 Enterprise 3.9.21 and APISIX 3.19.0. Not available in API7 Enterprise 3.10.7.

  • sp_acs_url

    string

    vaild vaule:

    an absolute URL starting with http:// or https://

    The absolute external URL of the assertion consumer service, where the identity provider (IdP) delivers the login response. It is the public URL of login_callback_uri.

    The plugin announces this URL to the IdP in the authentication request. The Recipient of the assertion, and the Destination of the response if present, must match it.

    If unset, the URL is built from the scheme and host of the callback request, taking the Forwarded, X-Forwarded-Proto, and X-Forwarded-Host headers into account. Set it when the gateway runs behind a proxy that terminates TLS without setting X-Forwarded-Proto, rewrites the host, or does not normalize the forwarded headers.

    Introduced in API7 Enterprise 3.9.21 and APISIX 3.19.0. Not available in API7 Enterprise 3.10.7.

  • sp_audiences

    array[string]

    Audiences this service provider (SP) accepts. An assertion that carries an AudienceRestriction must name one of them. An assertion without an AudienceRestriction is not restricted.

    If unset, the only accepted audience is the value of sp_issuer.

    Introduced in API7 Enterprise 3.9.21 and APISIX 3.19.0. Not available in API7 Enterprise 3.10.7.

  • clock_skew

    number

    default: 60

    vaild vaule:

    greater than or equal to 0

    Seconds of clock difference tolerated against the identity provider (IdP) when checking the NotBefore and NotOnOrAfter conditions of an assertion.

    Introduced in API7 Enterprise 3.9.21 and APISIX 3.19.0. Not available in API7 Enterprise 3.10.7.

  • replay_dict

    string

    Name of a lua_shared_dict in which the gateway records accepted assertions. An assertion already recorded in this dictionary is rejected while its record remains valid. If unset, assertions are not recorded.

    The gateway declares the plugin-saml-auth-replay shared dictionary (10m) for this purpose. Its size can be changed under nginx_config.http.lua_shared_dict in the gateway configuration file.

    The record is kept per gateway instance and is not shared between instances.

    If the dictionary is full, the login can still succeed without recording its assertion. Monitor warnings and size the dictionary for the expected login volume; this is not a cluster-wide guarantee against replay.

    Introduced in API7 Enterprise 3.9.21 and APISIX 3.19.0. Not available in API7 Enterprise 3.10.7.

  • replay_ttl

    number

    default: 600

    vaild vaule:

    greater than or equal to 1

    Seconds to record an assertion with no expiry in its conditions or usable subject confirmations. Otherwise, the record lasts until the assertion can no longer be accepted, plus clock_skew. Retention is capped at one day or replay_ttl, whichever is longer.

    Takes effect only when replay_dict is set.

    Introduced in API7 Enterprise 3.9.21 and APISIX 3.19.0. Not available in API7 Enterprise 3.10.7.