# SAML Auth Configuration

The `saml-auth` plugin provides SAML 2.0 single sign-on and single logout for APISIX and API7 Gateway routes using identity providers such as Keycloak.<!-- --> <!-- -->Configuration covers plugin parameters.

## Parameters[​](#parameters "Direct link to Parameters")

See plugin [common configurations](https://docs.api7.ai/apisix/reference/plugin-common-configurations.md) 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`

  ***

  Binding that the service provider requests for the identity provider's authentication response. The plugin includes this value as `ProtocolBinding` in the SAML `AuthnRequest`. The initial authentication request is always sent to the identity provider with an HTTP redirect and a `SAMLRequest` query parameter; selecting `HTTP-POST` does not replace it with a submitted form. Introduced in API7 Enterprise 3.9.3 and APISIX 3.17.0.

  With `HTTP-Redirect`, the identity provider returns the authentication response to the callback with a GET request. The plugin does not explicitly configure session cookie attributes for this binding.

  With `HTTP-POST`, the identity provider returns the authentication response to the callback with a POST request. The plugin sets the session cookie attributes to `SameSite=None` and `Secure` to support the cross-site POST. 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 3.10.8, and in APISIX 3.19.0.

* 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 3.10.8, and in APISIX 3.19.0.

* 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 3.10.8, and in APISIX 3.19.0.

* 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 3.10.8, and in APISIX 3.19.0.

* 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 3.10.8, and in APISIX 3.19.0.

* 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 3.10.8, and in APISIX 3.19.0.
