SAML Configuration

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: /

    A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes).

  • idp_sso_url

    string required

    A string representing a URL, such as https://example.com/path/to/resource?q=search.

  • 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: /

    A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes).

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

  • 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

  • session_response_headers

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

  • 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

    An integer representing a port number between 0 and 65535, inclusive.

  • redis

    record required
    • host

      string default: 127.0.0.1

      A string representing a host name, such as example.com.

    • port

      integer default: 6379 between: 0 65535

      An integer representing a port number between 0 and 65535, inclusive.

    • connect_timeout

      integer default: 2000 between: 0 2147483646

      An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

    • send_timeout

      integer default: 2000 between: 0 2147483646

      An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

    • read_timeout

      integer default: 2000 between: 0 2147483646

      An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

    • username

      string referenceable

      Username to use for Redis connections. If undefined, ACL authentication won’t be performed. This requires Redis v6.0.0+. To be compatible with Redis v5.x.y, you can set it to default.

    • password

      string referenceable encrypted

      Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.

    • sentinel_username

      string referenceable

      Sentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won’t be performed. This requires Redis v6.2.0+.

    • sentinel_password

      string referenceable encrypted

      Sentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.

    • database

      integer default: 0

      Database to use for the Redis connection when using the redis strategy

    • keepalive_pool_size

      integer default: 256 between: 1 2147483646

      The size limit for every cosocket connection pool associated with every remote server, per worker process. If neither keepalive_pool_size nor keepalive_backlog is specified, no pool is created. If keepalive_pool_size isn’t specified but keepalive_backlog is specified, then the pool uses the default value. Try to increase (e.g. 512) this value if latency is high or throughput is low.

    • keepalive_backlog

      integer between: 0 2147483646

      Limits the total number of opened connections for a pool. If the connection pool is full, connection queues above the limit go into the backlog queue. If the backlog queue is full, subsequent connect operations fail and return nil. Queued operations (subject to set timeouts) resume once the number of connections in the pool is less than keepalive_pool_size. If latency is high or throughput is low, try increasing this value. Empirically, this value is larger than keepalive_pool_size.

    • sentinel_master

      string

      Sentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.

    • sentinel_role

      string Must be one of: master, slave, any

      Sentinel role to use for Redis connections when the redis strategy is defined. Defining this value implies using Redis Sentinel.

    • sentinel_nodes

      array of type record len_min: 1

      Sentinel node addresses to use for Redis connections when the redis strategy is defined. Defining this field implies using a Redis Sentinel. The minimum length of the array is 1 element.

      • host

        string required default: 127.0.0.1

        A string representing a host name, such as example.com.

      • port

        integer default: 6379 between: 0 65535

        An integer representing a port number between 0 and 65535, inclusive.

    • cluster_nodes

      array of type record len_min: 1

      Cluster addresses to use for Redis connections when the redis strategy is defined. Defining this field implies using a Redis Cluster. The minimum length of the array is 1 element.

      • ip

        string required default: 127.0.0.1

        A string representing a host name, such as example.com.

      • port

        integer default: 6379 between: 0 65535

        An integer representing a port number between 0 and 65535, inclusive.

    • ssl

      boolean default: false

      If set to true, uses SSL to connect to Redis.

    • ssl_verify

      boolean default: false

      If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure lua_ssl_trusted_certificate in kong.conf to specify the CA (or server) certificate used by your Redis server. You may also need to configure lua_ssl_verify_depth accordingly.

    • server_name

      string

      A string representing an SNI (server name indication) value for TLS.

    • cluster_max_redirections

      integer default: 5

      Maximum retry attempts for redirection.

    • connection_is_proxied

      boolean default: false

      If the connection to Redis is proxied (e.g. Envoy), set it true. Set the host and port to point to the proxy address.

    • prefix

      string

      The Redis session key prefix.

    • socket

      string

      The Redis unix socket path.

• session_cookie_lifetime

  number
  Deprecation notice: openid-connect: config.session_cookie_lifetime is deprecated, please use config.session_rolling_timeout instead. This field is planned to be removed in version 4.0.

• session_cookie_idletime

  number
  Deprecation notice: openid-connect: config.session_cookie_idletime is deprecated, please use config.session_idling_timeout instead. This field is planned to be removed in version 4.0.

• session_cookie_samesite

  string
  Deprecation notice: openid-connect: config.session_cookie_samesite is deprecated, please use config.session_cookie_same_site instead. This field is planned to be removed in version 4.0.

• session_cookie_httponly

  boolean
  Deprecation notice: openid-connect: config.session_cookie_httponly is deprecated, please use config.session_cookie_http_only instead. This field is planned to be removed in version 4.0.

• session_memcache_prefix

  string
  Deprecation notice: openid-connect: config.session_memcache_prefix is deprecated, please use config.session_memcached_prefix instead. This field is planned to be removed in version 4.0.

• session_memcache_socket

  string
  Deprecation notice: openid-connect: config.session_memcache_socket is deprecated, please use config.session_memcached_socket instead. This field is planned to be removed in version 4.0.

• session_memcache_host

  string
  Deprecation notice: openid-connect: config.session_memcache_host is deprecated, please use config.session_memcached_host instead. This field is planned to be removed in version 4.0.

• session_memcache_port

  integer
  Deprecation notice: openid-connect: config.session_memcache_port is deprecated, please use config.session_memcached_port instead. This field is planned to be removed in version 4.0.

• session_cookie_renew

  number
  Deprecation notice: openid-connect: config.session_cookie_renew option does not exist anymore. This field is planned to be removed in version 4.0.

• session_cookie_maxsize

  integer
  Deprecation notice: openid-connect: config.session_cookie_maxsize option does not exist anymore. This field is planned to be removed in version 4.0.

• session_strategy

  string
  Deprecation notice: openid-connect: config.session_strategy option does not exist anymore. This field is planned to be removed in version 4.0.

• session_compressor

  string
  Deprecation notice: openid-connect: config.session_compressor option does not exist anymore. This field is planned to be removed in version 4.0.

• session_auth_ttl

  number
  Deprecation notice: openid-connect: config.session_auth_ttl option does not exist anymore. This field is planned to be removed in version 4.0.

• session_redis_prefix

  string
  Deprecation notice: saml: config.session_redis_prefix is deprecated, please use config.redis.prefix instead. This field is planned to be removed in version 4.0.

• session_redis_socket

  string
  Deprecation notice: saml: config.session_redis_socket is deprecated, please use config.redis.socket instead. This field is planned to be removed in version 4.0.

• session_redis_host

  string
  Deprecation notice: saml: config.session_redis_host is deprecated, please use config.redis.host instead. This field is planned to be removed in version 4.0.

• session_redis_port

  integer
  Deprecation notice: saml: config.session_redis_port is deprecated, please use config.redis.port instead. This field is planned to be removed in version 4.0.

• session_redis_username

  string
  Deprecation notice: saml: config.redis_host is deprecated, please use config.redis.host instead. This field is planned to be removed in version 4.0.

• session_redis_password

  string
  Deprecation notice: saml: config.session_redis_password is deprecated, please use config.redis.password instead. This field is planned to be removed in version 4.0.

• session_redis_connect_timeout

  integer
  Deprecation notice: saml: config.session_redis_connect_timeout is deprecated, please use config.redis.connect_timeout instead. This field is planned to be removed in version 4.0.

• session_redis_read_timeout

  integer
  Deprecation notice: saml: config.session_redis_read_timeout is deprecated, please use config.redis.read_timeout instead. This field is planned to be removed in version 4.0.

• session_redis_send_timeout

  integer
  Deprecation notice: saml: config.session_redis_send_timeout is deprecated, please use config.redis.send_timeout instead. This field is planned to be removed in version 4.0.

• session_redis_ssl

  boolean
  Deprecation notice: saml: config.session_redis_ssl is deprecated, please use config.redis.ssl instead. This field is planned to be removed in version 4.0.

• session_redis_ssl_verify

  boolean
  Deprecation notice: saml: config.session_redis_ssl_verify is deprecated, please use config.redis.ssl_verify instead. This field is planned to be removed in version 4.0.

• session_redis_server_name

  string
  Deprecation notice: saml: config.session_redis_server_name is deprecated, please use config.redis.server_name instead. This field is planned to be removed in version 4.0.

• session_redis_cluster_nodes

  array of type record
  Deprecation notice: saml: config.session_redis_cluster_nodes is deprecated, please use config.redis.cluster_nodes instead. This field is planned to be removed in version 4.0.

  • ip

    string required default: 127.0.0.1

    A string representing a host name, such as example.com.

  • port

    integer default: 6379 between: 0 65535

    An integer representing a port number between 0 and 65535, inclusive.

• session_redis_cluster_max_redirections

  integer
  Deprecation notice: saml: config.session_redis_cluster_max_redirections is deprecated, please use config.redis.cluster_max_redirections instead. This field is planned to be removed in version 4.0.

• session_redis_cluster_maxredirections

  integer
  Deprecation notice: saml: config.session_redis_cluster_maxredirections is deprecated, please use config.redis.cluster_max_redirections instead. This field is planned to be removed in version 4.0.