SAML Configuration

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:

• name or plugin

  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.

• instance_name

  string

  An optional custom name to identify an instance of the plugin, for example saml_my-service.

  The instance name shows up in Kong Manager and in Konnect, so it's useful when running the same plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance via the Kong Admin API.

  An instance name must be unique within the following context:

  • Within a workspace for Kong Gateway Enterprise
  • Within a control plane or control plane group for Konnect
  • Globally for Kong Gateway (OSS)

• service.name or service.id

  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.

• route.name or route.id

  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.

• enabled

  boolean default: true

  Whether this plugin will be applied.

• config

  record required
  • assertion_consumer_path

    string required starts_with: /

    The relative path the SAML IdP provider uses when responding with an authentication response.

  • idp_sso_url

    string required

    The Single Sign-On URL exposed by the IdP provider. This is where SAML requests are posted. The IdP provides this information.

  • idp_certificate

    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.

  • response_encryption_key

    string referenceable encrypted

    The private encryption key required to decrypt encrypted assertions.

  • request_signing_key

    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.

  • request_signing_certificate

    string referenceable encrypted

    The certificate for signing requests.

  • request_signature_algorithm

    string default: SHA256 Must be one of: SHA256, SHA384, SHA512

    The signature algorithm for signing Authn requests. Options available are:

    • SHA256
    • SHA384
    • SHA512

  • request_digest_algorithm

    string default: SHA256 Must be one of: SHA256, SHA1

    The digest algorithm for Authn requests:

    • SHA256
    • SHA1

  • response_signature_algorithm

    string default: SHA256 Must be one of: SHA256, SHA384, SHA512

    The algorithm for validating signatures in SAML responses. Options available are:

    • SHA256
    • SHA384
    • SHA512

  • response_digest_algorithm

    string default: SHA256 Must be one of: SHA256, SHA1

    The algorithm for verifying digest in SAML responses:

    • SHA256
    • SHA1

  • issuer

    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.

  • nameid_format

    string default: EmailAddress Must be one of: Unspecified, EmailAddress, Persistent, Transient

    The requested NameId format. Options available are:

    • Unspecified
    • EmailAddress
    • Persistent
    • Transient

  • validate_assertion_signature

    boolean default: true

    Enable signature validation for SAML responses.

  • anonymous

    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.

  • session_secret

    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.

  • session_audience

    string default: default

    The session audience, for example “my-application”

  • session_cookie_name

    string default: session

    The session cookie name.

  • session_remember

    boolean default: false

    Enables or disables persistent sessions

  • session_remember_cookie_name

    string default: remember

    Persistent session cookie name

  • session_remember_rolling_timeout

    number default: 604800

    Persistent session rolling timeout in seconds.

  • session_remember_absolute_timeout

    number default: 2592000

    Persistent session absolute timeout in seconds.

  • session_idling_timeout

    number default: 900

    The session cookie idle time in seconds.

  • session_rolling_timeout

    number default: 3600

    The session cookie absolute timeout in seconds. Specifies how long the session can be used until it is no longer valid.

  • session_absolute_timeout

    number default: 86400

    The session cookie absolute timeout in seconds. Specifies how long the session can be used until it is no longer valid.

  • session_cookie_path

    string default: / starts_with: /

    The session cookie path flag.

  • session_cookie_domain

    string

    The session cookie domain flag.

  • session_cookie_same_site

    string default: Lax Must be one of: Strict, Lax, None, Default

    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 aren’t 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. If SameSite=None is set, the cookie secure attribute must also be set or the cookie will be blocked.
    • Default: Do not explicitly specify a Same-Site attribute.

  • session_cookie_http_only

    boolean default: true

    Forbids JavaScript from accessing the cookie, for example, through the Document.cookie property.

  • session_cookie_secure

    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.

  • session_request_headers

    set of type string Must be one of: id, audience, subject, timeout, idling-timeout, rolling-timeout, absolute-timeout

    List of information to include (as headers) in the request to upstream. Accepted values are: id, audience, subject, timeout, idling-timeout, rolling-timeout, and absolute-timeout. For example, { “id”, “timeout” } will set both Session-Id and Session-Timeout in the request headers.

  • session_response_headers

    set of type string Must be one of: id, audience, subject, timeout, idling-timeout, rolling-timeout, absolute-timeout

    List of information to include (as headers) in the response to downstream. Accepted values are: id, audience, subject, timeout, idling-timeout, rolling-timeout, and absolute-timeout. For example: { “id”, “timeout” } will inject both Session-Id and Session-Timeout in the response headers.

  • session_storage

    string default: cookie Must be one of: cookie, memcache, memcached, 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

  • session_store_metadata

    boolean default: false

    Configures whether or not session metadata should be stored. This includes information about the active sessions for the specific_audience belonging to a specific subject.

  • session_enforce_same_subject

    boolean default: false

    When set to true, audiences are forced to share the same subject.

  • session_hash_subject

    boolean default: false

    When set to true, the value of subject is hashed before being stored. Only applies when session_store_metadata is enabled.

  • session_hash_storage_key

    boolean default: false

    When set to true, the storage key (session ID) is hashed for extra security. Hashing the storage key means it is impossible to decrypt data from the storage without a cookie.

  • session_memcached_prefix

    string

    The memcached session key prefix.

  • session_memcached_socket

    string

    The memcached unix socket path.

  • session_memcached_host

    string default: 127.0.0.1

    The memcached host.

  • session_memcached_port

    integer default: 11211 between: 0 65535

    The memcached port.

  • session_redis_prefix

    string

    The Redis session key prefix.

  • session_redis_socket

    string

    The Redis unix socket path.

  • session_redis_host

    string default: 127.0.0.1

    The Redis host IP.

  • session_redis_port

    integer default: 6379 between: 0 65535

    The Redis port.

  • session_redis_username

    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.

  • session_redis_password

    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

  • session_redis_connect_timeout

    integer

    The Redis connection timeout in milliseconds.

  • session_redis_read_timeout

    integer

    The Redis read timeout in milliseconds.

  • session_redis_send_timeout

    integer

    The Redis send timeout in milliseconds.

  • session_redis_ssl

    boolean default: false

    Use SSL/TLS for the Redis connection.

  • session_redis_ssl_verify

    boolean default: false

    Verify the Redis server certificate.

  • session_redis_server_name

    string

    The SNI used for connecting to the Redis server.

  • session_redis_cluster_nodes

    array of type record

    The Redis cluster node host. Takes an array of host records, with either ip or host, and port values.

    • ip

      string required default: 127.0.0.1

    • port

      integer default: 6379 between: 0 65535

  • session_redis_cluster_max_redirections

    integer

    The Redis cluster maximum redirects.

• session_cookie_lifetime

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_idletime

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_samesite

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_httponly

  boolean
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_memcache_prefix

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_memcache_socket

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_memcache_host

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_memcache_port

  integer
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_redis_cluster_maxredirections

  integer
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_renew

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_maxsize

  integer
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_strategy

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_compressor

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_auth_ttl

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..