SAML Auth Configuration

Parameters

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

• sp_issuer — string · required

  The unique identifier the service provider (SP) uses when communicating with the identity provider (IdP) in the SAML authentication process.

• idp_uri — string · required

  The URL of the identity provider (IdP) where the service provider (SP) sends authentication requests to initiate the SAML authentication process.

• idp_cert — string · required

  The X.509 certificate provided by the identity provider (IdP), used by the service provider (SP) to verify the authenticity and integrity of SAML assertions and responses.

• login_callback_uri — string · required

  The endpoint on the service provider (SP) where the identity provider (IdP) will send the SAML response after a user successfully authenticates.

  The login callback URI should be a sub-path of the route URI. For example, if the route uri is /anything/*, the login callback URI can be /anything/login_callback.

• logout_uri — string · required

  The URI path to trigger the SAML logout process.

  The logout URI should be a sub-path of the route URI. For example, if the route uri is /anything/*, the logout URI can be /anything/logout.

• logout_callback_uri — string · required

  The endpoint on the service provider (SP) that receives the SAML logout response from the identity provider (IdP) after the logout process is completed.

  The logout callback URI should be a sub-path of the route URI. For example, if the route uri is /anything/*, the logout callback URI can be /anything/logout_callback.

• logout_redirect_uri — string · required

  The URI where the user is redirected after the logout process is completed, usually back to the Service Provider's (SP) application or a specified landing page.

  The logout redirect URI should be a sub-path of the route URI. For example, if the route uri is /anything/*, the logout redirect URI can be /anything/logout_ok.

• sp_cert — string · required

  The X.509 certificate used by the service provider (SP) to sign SAML requests and assertions, ensuring secure communication with the identity provider (IdP).

• sp_private_key — string · required

  The private key corresponding to the Service Provider's (SP) certificate sp_cert, used to sign SAML requests and decrypt SAML assertions.

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

• secret — string · required

  Valid values: 8 to 32 characters

  A cryptographic secret used to derive encryption keys for securing SAML session data and tokens. The secret should be a strong, random string for security. This ensures that sensitive authentication information is encrypted and tamper-resistant.

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

  Available in API7 Enterprise from version 3.9.3 and APISIX from version 3.17.0.

• auth_protocol_binding_method — string · optional · default: HTTP-Redirect

  Valid values: HTTP-Redirect or HTTP-POST

  Binding method for the authentication protocol. Available in API7 Enterprise from version 3.9.3 and APISIX from version 3.17.0.

  When the binding method is HTTP-Redirect, the plugin uses browser redirects via GET requests. The plugin does not explicitly configure cookie attributes for this binding; cookies follow the defaults of the browser or underlying HTTP stack (for example, SameSite typically defaults to Lax, and the Secure attribute may be omitted depending on the environment).

  When the binding method is HTTP-POST, the plugin sends SAML messages via POST requests. Cookies are explicitly configured with SameSite=None and the Secure attribute enabled to support cross-origin authentication over HTTPS.

• secret_fallbacks — array[string] · optional

  An array of alternative secrets used during key rotation.

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

  Available in API7 Enterprise from version 3.9.3 and APISIX from version 3.17.0.