You are browsing documentation for an outdated plugin version.
Configuration
This plugin is compatible with DB-less mode.
Compatible protocols
The SAML plugin is compatible with the following protocols:
grpc
, grpcs
, http
, https
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
-
string required
The name of the plugin, in this case
saml
.- If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is
name
. - If using the KongPlugin object in Kubernetes, the field is
plugin
.
- If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is
-
string
The name or ID of the service the plugin targets. Set one of these parameters if adding the plugin to a service through the top-level
/plugins
endpoint. Not required if using/services/{serviceName|Id}/plugins
. -
string
The name or ID of the route the plugin targets. Set one of these parameters if adding the plugin to a route through the top-level
/plugins
endpoint. Not required if using/routes/{routeName|Id}/plugins
. -
boolean default:
true
Whether this plugin will be applied.
-
record required
-
string required starts_with:
/
The relative path the SAML IdP provider uses when responding with an authentication response.
-
string required
The Single Sign-On URL exposed by the IdP provider. This is where SAML requests are posted. The IdP provides this information.
-
string referenceable encrypted
The public certificate provided by the IdP. This is used to validate responses from the IdP.
Only include the contents of the certificate. Do not include the header (
BEGIN CERTIFICATE
) and footer (END CERTIFICATE
) lines.
-
string referenceable encrypted
The private encryption key required to decrypt encrypted assertions.
-
string referenceable encrypted
The private key for signing requests. If this parameter is set, requests sent to the IdP are signed. The
request_signing_certificate
parameter must be set as well.
-
string referenceable encrypted
The certificate for signing requests.
-
string default:
SHA256
Must be one of:SHA256
,SHA384
,SHA512
The signature algorithm for signing Authn requests. Options available are:
SHA256
SHA384
SHA512
-
string default:
SHA256
Must be one of:SHA256
,SHA1
The digest algorithm for Authn requests:
SHA256
SHA1
-
string default:
SHA256
Must be one of:SHA256
,SHA384
,SHA512
The algorithm for validating signatures in SAML responses. Options available are:
SHA256
SHA384
SHA512
-
string default:
SHA256
Must be one of:SHA256
,SHA1
The algorithm for verifying digest in SAML responses:
SHA256
SHA1
-
string required
The unique identifier of the IdP application. Formatted as a URL containing information about the IdP so the SP can validate that the SAML assertions it receives are issued from the correct IdP.
-
string default:
EmailAddress
Must be one of:Unspecified
,EmailAddress
,Persistent
,Transient
The requested
NameId
format. Options available are:Unspecified
EmailAddress
Persistent
Transient
-
boolean default:
true
Enable signature validation for SAML responses.
-
string
An optional string (consumer UUID or username) value to use as an “anonymous” consumer. If not set, a Kong Consumer must exist for the SAML IdP user credentials, mapping the username format to the Kong Consumer username.
-
string required referenceable encrypted matches:
^[0-9a-zA-Z/_+]+$
len_min:32
len_max:32
The session secret. This must be a random string of 32 characters from the base64 alphabet (letters, numbers,
/
,_
and+
). It is used as the secret key for encrypting session data as well as state information that is sent to the IdP in the authentication exchange.
-
string default:
session
The session cookie name.
-
number default:
3600
The session cookie lifetime in seconds.
-
number
The session cookie idle time in seconds.
-
number default:
600
The session cookie renew time in seconds.
-
string default:
/
starts_with:/
The session cookie path flag.
-
string
The session cookie domain flag.
-
string default:
Lax
Must be one of:Strict
,Lax
,None
,off
Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks:
-
Strict
: Cookies will only be sent in a first-party context and not be sent along with requests initiated by third party websites. -
Lax
: Cookies are not sent on normal cross-site subrequests, like loading images or frames into a third party site, but are sent when a user is navigating to the origin site, like when they are following a link. -
None
: Cookies will be sent in all contexts, including responses to both first-party and cross-origin requests. IfSameSite=None
is set, the cookie secure attribute must also be set or the cookie will be blocked. -
off
: Do not set the Same-Site flag.
-
-
boolean default:
true
Forbids JavaScript from accessing the cookie, for example, through the
Document.cookie
property.
-
boolean
The cookie is only sent to the server when a request is made with the https:scheme (except on localhost), and therefore is more resistant to man-in-the-middle attacks.
-
number required default:
5400
-
integer default:
4000
The maximum size of each cookie in bytes.
-
string default:
default
Must be one of:default
,regenerate
The session strategy:
-
default
: reuses session identifiers over modifications (but can be problematic with single-page applications with a lot of concurrent asynchronous requests) -
regenerate
: generates a new session identifier on each modification and does not use expiry for signature verification. This is useful in single-page applications or SPAs.
-
-
string default:
none
Must be one of:none
,zlib
The session strategy:
-
none
: no compression. -
zlib
: use Zlib to compress cookie data.
-
-
string default:
cookie
Must be one of:cookie
,memcache
,redis
The session storage for session data:
-
cookie
: stores session data with the session cookie. The session cannot be invalidated or revoked without changing the session secret, but is stateless, and doesn’t require a database. -
memcached
: stores session data in memcached -
redis
: stores session data in Redis
-
-
string default:
sessions
The memcached session key prefix.
-
string
The memcached unix socket path.
-
string default:
127.0.0.1
The memcached host.
-
integer default:
11211
between:0
65535
The memcached port.
-
string default:
sessions
The Redis session key prefix.
-
string
The Redis unix socket path.
-
string default:
127.0.0.1
The Redis host IP.
-
integer default:
6379
between:0
65535
The Redis port.
-
string referenceable
Redis username if the
redis
session storage is defined and ACL authentication is desired.If undefined, ACL authentication will not be performed.This requires Redis v6.0.0+. The username cannot be set to
default
.
-
string referenceable encrypted
Password to use for Redis connection when the
redis
session storage is defined. If undefined, no auth commands are sent to Redis. This value is pulled from
-
integer
The Redis connection timeout in milliseconds.
-
integer
The Redis read timeout in milliseconds.
-
integer
The Redis send timeout in milliseconds.
-
boolean default:
false
Use SSL/TLS for the Redis connection.
-
boolean default:
false
Verify the Redis server certificate.
-
string
The SNI used for connecting to the Redis server.
-
array of type
record
-
integer
The Redis cluster’s maximum redirects.
-