Skip to content
|
Plugin Hub
github-edit-pageEdit this page
report-issueReport an issue
header icon

SAML Configuration

By Kong Inc.
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.

  • 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.

    • 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. If SameSite=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.

    • session_auth_ttl

      number required default: 5400
    • integer default: 4000

      The maximum size of each cookie in bytes.

    • session_strategy

      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.

    • session_compressor

      string default: none Must be one of: none, zlib

      The session strategy:

      • none: no compression.
      • zlib: use Zlib to compress cookie data.

    • session_storage

      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

    • session_memcache_prefix

      string default: sessions

      The memcached session key prefix.

    • session_memcache_socket

      string

      The memcached unix socket path.

    • session_memcache_host

      string default: 127.0.0.1

      The memcached host.

    • session_memcache_port

      integer default: 11211 between: 0 65535

      The memcached port.

    • session_redis_prefix

      string default: sessions

      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_maxredirections

      integer

      The Redis cluster’s maximum redirects.