diff --git a/src/pages/plugins/Form.vue b/src/pages/plugins/Form.vue index d27caa6..314066d 100644 --- a/src/pages/plugins/Form.vue +++ b/src/pages/plugins/Form.vue @@ -79,7 +79,6 @@ import EntityForm from '@/components/EntityForm/EntityForm.vue' import FormPageMixin from '@/components/EntityForm/mixins/FormPage' import { capitalize, uuidRegEx, redirectOnResponseStatus, isObjectEmpty } from '@/components/EntityForm/helpers' import { pluginMeta } from './PluginMeta' -import PluginConfig from './PluginConfig' import customSchemas from '@/schemas/CustomSchemas' import typedefs from '@/schemas/typedefs' import { ArrayStringFieldSchema } from '@/components/EntityForm/fields' @@ -563,9 +562,8 @@ export default { } if (parent === 'config') { - const definition = PluginConfig[this.plugin]?.find(config => config.name === key) - if (definition?.description) { - output[field].help = marked.parse(definition.description, { mangle: false, headerIds: false }) + if (schema[key]?.description) { + output[field].help = marked.parse(schema[key].description, { mangle: false, headerIds: false }) } } diff --git a/src/pages/plugins/PluginConfig.json b/src/pages/plugins/PluginConfig.json deleted file mode 100644 index ae20683..0000000 --- a/src/pages/plugins/PluginConfig.json +++ /dev/null @@ -1,9345 +0,0 @@ -{ - "__!!NOTICE": "THIS FILE IS AUTO-GENERATED; DO NOT EDIT", - "acl": [ - { - "name": "whitelist", - "required": "semi", - "default": null, - "value_in_examples": "group1, group2", - "description": "Comma separated list of arbitrary group names that are allowed to consume the Service or the Route (or API). One of `config.whitelist` or `config.blacklist` must be specified.\n", - "maximum_version": "2.0.x" - }, - { - "name": "blacklist", - "required": "semi", - "default": null, - "description": "Comma separated list of arbitrary group names that are not allowed to consume the Service or the Route (or API). One of `config.whitelist` or `config.blacklist` must be specified.\n", - "maximum_version": "2.0.x" - }, - { - "name": "allow", - "required": "semi", - "default": null, - "value_in_examples": [ - "group1", - "group2" - ], - "datatype": "array of string elements", - "description": "Arbitrary group names that are allowed to consume the Service or Route. One of `config.allow` or `config.deny` must be specified.\n", - "minimum_version": "2.1.x" - }, - { - "name": "deny", - "required": "semi", - "default": null, - "datatype": "array of string elements", - "description": "Arbitrary group names that are not allowed to consume the Service or Route. One of `config.allow` or `config.deny` must be specified.\n", - "minimum_version": "2.1.x" - }, - { - "name": "hide_groups_header", - "required": true, - "default": false, - "value_in_examples": true, - "datatype": "boolean", - "description": "Flag that if enabled (`true`), prevents the `X-Consumer-Groups` header to be sent in the request to the Upstream service.\n" - } - ], - "acme": [ - { - "name": "account_email", - "required": "yes", - "default": null, - "value_in_examples": "example@example.com", - "encrypted": true, - "datatype": "string", - "referenceable": true, - "description": "The account identifier. Can be reused in a different plugin instance.\n" - }, - { - "name": "api_uri", - "required": false, - "default": "` https://acme-v02.api.letsencrypt.org/directory`", - "datatype": "string", - "description": "The ACMEv2 API endpoint to use. You can specify the\n[Let's Encrypt staging environment](https://letsencrypt.org/docs/staging-environment/) for testing. Kong doesn't automatically delete staging certificates. If you use the same domain in test and production environments, you need to manually delete those certificates after testing.\n" - }, - { - "name": "cert_type", - "required": false, - "default": "`rsa`", - "datatype": "string", - "description": "The certificate type to create. The possible values are `\"rsa\"` for RSA certificate or `\"ecc\"` for EC certificate.\n" - }, - { - "name": "domains", - "required": false, - "default": "`[]`", - "datatype": "array of string elements", - "description": "The list of domains to create certificates for. To match subdomains under `example.com`, use `*.example.com`.\nRegex pattern is not supported.\n\nThis parameter is only used to match domains, not to specify the Common Name\nor Subject Alternative Name to create certificates. Each domain must have its own certificate.\nThe ACME plugin checks this configuration before checking any certificate in `storage` when serving the certificate of a request.\n\nIf this field is left empty, all top-level domains (TLDs) are allowed.\n" - }, - { - "name": "allow_any_domain", - "minimum_version": "3.0.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "If set to `true`, the plugin allows all domains and ignores any values in the `domains` list.\n" - }, - { - "name": "fail_backoff_minutes", - "minimum_version": "2.1.x", - "required": false, - "default": 5, - "datatype": "number", - "description": "Minutes to wait for each domain that fails to create a certificate. This applies to both a\nnew certificate and a renewal certificate.\n" - }, - { - "name": "renew_threshold_days", - "required": false, - "default": "`14`", - "datatype": "number", - "description": "Days remaining to renew the certificate before it expires.\n" - }, - { - "name": "storage", - "required": false, - "default": "`shm`", - "datatype": "string", - "description": "The backend storage type to use. The possible values are `\"kong\"`, `\"shm\"`, `\"redis\"`, `\"consul\"`, or `\"vault\"`. In DB-less mode, `\"kong\"` storage is unavailable. Note that `\"shm\"` storage does not persist during Kong restarts and does not work for Kong running on different machines, so consider using one of `\"kong\"`, `\"redis\"`, `\"consul\"`, or `\"vault\"` in production. Please refer to the Hybrid Mode sections below as well.\n" - }, - { - "name": "storage_config", - "required": false, - "default": null, - "datatype": "record", - "description": "Storage configs for each backend storage. See [Storage configuration considerations](#storage-config)\nfor information on its default values.\n" - }, - { - "name": "tos_accepted", - "required": false, - "default": "`false`", - "datatype": "boolean", - "description": "If you are using Let's Encrypt, you must set this to `true` to agree the [Terms of Service](https://letsencrypt.org/repository/).\n" - }, - { - "name": "eab_kid", - "minimum_version": "2.4.x", - "required": false, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "External account binding (EAB) key id. You usually don't need to set this unless it is explicitly required by the CA.\n" - }, - { - "name": "eab_hmac_key", - "minimum_version": "2.4.x", - "required": false, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "External account binding (EAB) base64-encoded URL string of the HMAC key. You usually don't need to set this unless it is explicitly required by the CA.\n" - }, - { - "name": "rsa_key_size", - "minimum_version": "2.8.x", - "required": false, - "datatype": "number", - "default": 4096, - "description": "RSA private key size for the certificate. The possible values are 2048, 3072, or 4096.\n" - } - ], - "application-registration": [ - { - "name": "auto_approve", - "required": true, - "default": "`false`", - "value_in_examples": false, - "datatype": "boolean", - "description": "If enabled, all new Service Contracts requests are automatically\napproved. See [Enable automatic registration approval](#enable-automatic-registration-approval). Otherwise, Dev Portal admins must manually approve requests.\n" - }, - { - "name": "description", - "required": false, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "Unique description displayed in information about a Service in the Developer Portal.\n" - }, - { - "name": "display_name", - "required": true, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "Unique display name used for a Service in the Developer Portal.\n" - }, - { - "name": "show_issuer", - "required": true, - "default": "`false`", - "value_in_examples": false, - "datatype": "boolean", - "description": "Displays the **Issuer URL** in the **Service Details** dialog.\n" - } - ], - "aws-lambda": [ - { - "name": "aws_key", - "required": "semi", - "value_in_examples": "", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "The AWS key credential to be used when invoking the function. The `aws_key` value is required\nif `aws_secret` is defined. If `aws_key` and `aws_secret` are not set, the plugin uses an\nIAM role inherited from the instance running Kong to authenticate. Can be symmetrically encrypted\nif using Kong Gateway and [data encryption](/gateway/latest/kong-production/db-encryption/)\nis configured.\n" - }, - { - "name": "aws_secret", - "required": "semi", - "value_in_examples": "", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "The AWS secret credential to be used when invoking the function. The `aws_secret` value is required\nif `aws_key` is defined. If `aws_key` and `aws_secret` are not set, the plugin uses an\nIAM role inherited from the instance running Kong to authenticate. Can be symmetrically encrypted\nif using Kong Gateway and [data encryption](/gateway/latest/kong-production/db-encryption/)\nis configured.\n" - }, - { - "name": "aws_region", - "maximum_version": "2.5.x", - "required": true, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "The AWS region where the Lambda function is located. The plugin does not\nattempt to validate the supplied region name. If an invalid region name\nis provided, the plugin responds with an HTTP `500 Internal Server Error`\nat runtime and logs a DNS resolution failure. Either `aws_region` or `host`\nmust be provided.\n" - }, - { - "name": "aws_region", - "minimum_version": "2.6.x", - "maximum_version": "2.8.x", - "required": false, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "The AWS region where the Lambda function is located. The plugin does not\nattempt to validate the supplied region name. If an invalid region name\nis provided, the plugin responds with an HTTP `500 Internal Server Error`\nat runtime and logs a DNS resolution failure.\n\nThe plugin will automatically\ndetect the AWS region on runtime via `AWS_REGION` or `AWS_DEFAULT_REGION` environment\nvariables when neither `aws_region` nor `host` is specified in plugin configuration.\nUsing environment variables enables regionally distributed Kong cluster nodes\nto connect to the closest AWS region. If `aws_region`, `host` and environment\nvariables have not been specified, the plugin responds with an HTTP\n`500 Internal Server Error` at run-time.\n" - }, - { - "name": "aws_region", - "minimum_version": "3.0.x", - "required": "semi", - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "The AWS region where the Lambda function is located. The plugin does not\nattempt to validate the supplied region name.\n\nThe plugin has two methods of detecting the AWS region: the `aws_region`\nparameter, or one of the `AWS_REGION` or `AWS_DEFAULT_REGION` environment\nvariables. One of these must be set.\n\nIf `region` is not specified in plugin configuration, the plugin\nautomatically detects the AWS region on runtime via one of the environment\nvariables.\nUsing environment variables enables regionally distributed Kong cluster nodes\nto connect to the closest AWS region.\n\nThe AWS region is required for AWS SigV4.\nIf `aws_region` or the `AWS_REGION` or `AWS_DEFAULT_REGION` environment\nvariables have not been specified, or an invalid region name has been provided,\nthe plugin responds with an HTTP `500 Internal Server Error` at runtime.\n" - }, - { - "name": "aws_assume_role_arn", - "minimum_version": "2.8.x", - "required": false, - "default": null, - "value_in_examples": "", - "datatype": "string", - "referenceable": true, - "description": "The target AWS IAM role ARN used to invoke the Lambda function. Typically this is\nused for a cross-account Lambda function invocation.\n" - }, - { - "name": "aws_role_session_name", - "minimum_version": "2.8.x", - "required": false, - "default": "`kong`", - "value_in_examples": "", - "datatype": "string", - "description": "The identifier of the assumed role session. It is used for uniquely identifying\na session when the same target role is assumed by different principals or\nfor different reasons. The role session name is also used in the ARN of the assumed role principle.\n" - }, - { - "name": "host", - "minimum_version": "2.1.x", - "maximum_version": "2.5.x", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "The host where the Lambda function is located. This value can point to a\nlocal Lambda server, allowing for easier debugging.\n\nEither `aws_region` or `host` must be provided.\n" - }, - { - "name": "host", - "minimum_version": "3.0.x", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "The host where the Lambda function is located. This value can point to a\nlocal Lambda server, allowing for easier debugging.\n\nTo set a region, use the `aws_region` parameter.\n" - }, - { - "name": "function_name", - "required": true, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "The AWS Lambda function name to invoke. This may contain\nthe function name only (`my-function`), the full ARN\n(arn:aws:lambda:us-west-2:123456789012:function:my-function) or a\npartial ARN (123456789012:function:my-function). You can also append a version\nnumber or alias to any of the formats.\n" - }, - { - "name": "qualifier", - "required": false, - "default": null, - "datatype": "string", - "description": "The [`Qualifier`](http://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html#API_Invoke_RequestSyntax) to use when invoking the function.\n" - }, - { - "name": "invocation_type", - "required": true, - "default": "`RequestResponse`", - "datatype": "string", - "description": "The [`InvocationType`](http://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html#API_Invoke_RequestSyntax) to use when invoking the function. Available types are `RequestResponse`, `Event`, `DryRun`.\n" - }, - { - "name": "log_type", - "required": true, - "default": "`Tail`", - "datatype": "string", - "description": "The [`LogType`](http://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html#API_Invoke_RequestSyntax) to use when invoking the function. By default, `None` and `Tail` are supported.\n" - }, - { - "name": "timeout", - "required": true, - "default": "`60000`", - "datatype": "number", - "description": "An optional timeout in milliseconds when invoking the function." - }, - { - "name": "port", - "required": false, - "default": "`443`", - "datatype": "integer", - "description": "The TCP port that the plugin uses to connect to the server.\n" - }, - { - "name": "keepalive", - "required": true, - "default": "`60000`", - "datatype": "number", - "description": "An optional value in milliseconds that defines how long an idle connection lives before being closed.\n" - }, - { - "name": "unhandled_status", - "required": false, - "default": "`200`, `202`, or `204`", - "datatype": "integer", - "description": "The response status code to use (instead of the default `200`, `202`, or `204`) in the case of an\n[`Unhandled` Function Error](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html#API_Invoke_ResponseSyntax).\n" - }, - { - "name": "forward_request_body", - "required": false, - "default": "`false`", - "datatype": "boolean", - "description": "An optional value that defines whether the request body is sent in the `request_body` field of the JSON-encoded request.\nIf the body arguments can be parsed, they are sent in the separate `request_body_args` field of the request.\nThe body arguments can be parsed for `application/json`, `application/x-www-form-urlencoded`, and `multipart/form-data` content types.\n" - }, - { - "name": "forward_request_headers", - "required": false, - "default": "`false`", - "datatype": "boolean", - "description": "An optional value that defines whether the original HTTP request headers are\nsent as a map in the `request_headers` field of the JSON-encoded request.\n" - }, - { - "name": "forward_request_method", - "required": false, - "default": "`false`", - "datatype": "boolean", - "description": "An optional value that defines whether the original HTTP request method verb is\nsent in the `request_method` field of the JSON-encoded request.\n" - }, - { - "name": "forward_request_uri", - "required": false, - "default": "`false`", - "datatype": "boolean", - "description": "An optional value that defines whether the original HTTP request URI is sent in\nthe `request_uri` field of the JSON-encoded request. Request URI arguments (if any) are sent in\nthe separate `request_uri_args` field of the JSON body.\n" - }, - { - "name": "is_proxy_integration", - "required": false, - "default": "`false`", - "datatype": "boolean", - "description": "An optional value that defines whether the response format to receive from the Lambda to\n[this format](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-output-format).\n" - }, - { - "name": "awsgateway_compatible", - "required": false, - "default": "`false`", - "datatype": "boolean", - "description": "An optional value that defines whether the plugin should wrap requests into the Amazon API gateway.\n" - }, - { - "name": "proxy_url", - "required": "semi", - "default": null, - "datatype": "string", - "value_in_examples": "http://my-proxy-server:3128", - "description": "An optional value that defines whether the plugin should connect through\nthe given proxy server URL. Include the request scheme in the URL, which\nmust be `http`. For example: `http://my-proxy-server:3128`.\n\nKong Gateway uses HTTP tunneling via the [CONNECT HTTP](https://httpwg.org/specs/rfc7231.html#CONNECT)\nmethod so that no details of the AWS Lambda request are leaked to the proxy server.\n" - }, - { - "name": "proxy_scheme", - "maximum_version": "2.8.x", - "required": "semi", - "default": null, - "datatype": "string", - "description": "\n{:.important}\n> As of Kong Gateway 2.8.0.0, this parameter is deprecated.\n>

\n> If running Kong Gateway 2.7.x or earlier, the\n`proxy_scheme` value is required if `proxy_url` is defined. In 2.8.x or\nlater versions, `proxy_scheme` is not required.\n\nAn optional value that defines which HTTP scheme to use for connecting through the proxy server. The\nsupported schemes are `http` and `https`.\n" - }, - { - "name": "skip_large_bodies", - "required": false, - "default": "`true`", - "datatype": "boolean", - "description": "An optional value that defines whether Kong should send large\nbodies that are buffered to disk. Note that enabling this option will have an impact\non system memory depending on the number of requests simultaneously in flight at any given point in time\nand on the maximum size of each request. Also this option blocks all requests being handled by the\nnginx workers. That could be tens of thousands of other transactions that are not being processed. For small I/O\noperations, such a delay would generally not be problematic. In cases where the body size is in the order of MB,\nsuch a delay would cause notable interruptions in request processing. Given all of the potential\ndownsides resulting from enabling this option, consider increasing the\n[client_body_buffer_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size)\nvalue instead.\n" - }, - { - "name": "base64_encode_body", - "minimum_version": "2.2.x", - "required": false, - "default": "`true`", - "datatype": "boolean", - "description": "An optional value that Base64-encodes the request body.\n" - }, - { - "name": "aws_imds_protocol_version", - "minimum_version": "2.8.x", - "required": true, - "default": "`v1`", - "datatype": "string", - "description": "Identifier to select the IMDS protocol version to use, either\n`v1` or `v2`. If `v2` is selected, an additional session\ntoken is requested from the EC2 metadata service by the plugin\nto secure the retrieval of the EC2 instance role. Note that\nif Kong Gateway is running inside a container on an\nEC2 instance, the EC2 instance metadata must be configured\naccordingly. \n\nRefer to the Considerations section in the\n[Retrieve Instance Metadata section of the EC2 manual](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html)\nfor details.\n" - } - ], - "azure-functions": [ - { - "name": "functionname", - "required": true, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "Name of the Azure function to invoke." - }, - { - "name": "appname", - "required": true, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "The Azure app name." - }, - { - "name": "hostdomain", - "required": true, - "default": "azurewebsites.net", - "value_in_examples": "azurewebsites.net", - "datatype": "string", - "description": "The domain where the function resides." - }, - { - "name": "routeprefix", - "required": false, - "default": "/api", - "value_in_examples": null, - "datatype": "string", - "description": "Route prefix to use." - }, - { - "name": "apikey", - "required": false, - "default": null, - "value_in_examples": "", - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "The apikey to access the Azure resources. If provided, it is injected as the `x-functions-key` header.\n" - }, - { - "name": "clientid", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "The `clientid` to access the Azure resources. If provided, it is injected as the `x-functions-clientid` header.\n" - }, - { - "name": "https_verify", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "Set to `true` to authenticate the Azure Functions server." - }, - { - "name": "https", - "required": false, - "default": true, - "value_in_examples": null, - "datatype": "boolean", - "description": "Use of HTTPS to connect with the Azure Functions server." - }, - { - "name": "timeout", - "required": false, - "default": 600000, - "value_in_examples": null, - "datatype": "number", - "description": "Timeout in milliseconds before closing a connection to the Azure Functions server." - }, - { - "name": "keepalive", - "required": false, - "default": 60000, - "value_in_examples": null, - "datatype": "number", - "description": "Time in milliseconds during which an idle connection to the Azure Functions server lives before being closed." - } - ], - "basic-auth": [ - { - "name": "hide_credentials", - "required": true, - "value_in_examples": true, - "datatype": "boolean", - "default": "`false`", - "description": "An optional boolean value telling the plugin to show or hide the credential from the upstream service. If `true`, the plugin will strip the credential from the request (i.e. the `Authorization` header) before proxying it.\n" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (Consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request will fail with an authentication failure `4xx`. Please note that this value must refer to the Consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails.\nIf empty (default), the request will fail with an authentication failure `4xx`. Note that this value\nmust refer to the consumer `id` attribute that is internal to Kong, and **not** its `custom_id`.\n", - "maximum_version": "3.0.x" - } - ], - "bot-detection": [ - { - "name": "whitelist", - "required": false, - "default": null, - "description": "A comma separated array of regular expressions that should be whitelisted. The regular expressions will be checked against the `User-Agent` header.\n", - "maximum_version": "2.0.x" - }, - { - "name": "blacklist", - "required": false, - "default": null, - "description": "A comma separated array of regular expressions that should be blacklisted. The regular expressions will be checked against the `User-Agent` header.\n", - "maximum_version": "2.0.x" - }, - { - "name": "allow", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "An array of regular expressions that should be allowed. The regular expressions will be checked against the `User-Agent` header.\n", - "minimum_version": "2.1.x" - }, - { - "name": "deny", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "An array of regular expressions that should be denied. The regular expressions will be checked against the `User-Agent` header.\n", - "minimum_version": "2.1.x" - } - ], - "canary": [ - { - "name": "start", - "maximum_version": "3.1.x", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "number", - "description": "Future time in seconds since epoch, when the canary release will start.\nIgnored when `percentage` is set, or when using `allow` or `deny` in `hash`.\n" - }, - { - "name": "start", - "minimum_version": "3.2.x", - "default": "current timestamp", - "value_in_examples": null, - "datatype": "number", - "description": "Future time in seconds since epoch, when the canary release will start.\nIgnored when `percentage` is set, or when using `allow` or `deny` in `hash`.\n\nIf no value is set for the `start` field, it defaults to the \ntimestamp of the moment that the plugin instance is created.\n" - }, - { - "name": "duration", - "required": null, - "default": 3600, - "value_in_examples": null, - "datatype": "number", - "description": "The duration of the transition in seconds. Ignored when `percentage` is set, or\nwhen using `allow` or `deny` in `hash`.\n" - }, - { - "name": "percentage", - "required": "semi", - "default": null, - "value_in_examples": 50, - "datatype": "number", - "description": "Fixed percentage of traffic to be routed to new target, if given overrides `start` and `duration`. The\nvalue must be between 0 and 100.\n" - }, - { - "name": "steps", - "required": null, - "default": 1000, - "value_in_examples": null, - "datatype": "number", - "description": "Number of steps the release should be broken into.\n" - }, - { - "name": "upstream_host", - "required": "semi", - "default": null, - "value_in_examples": "example.com", - "datatype": "string", - "description": "The target hostname where traffic will be routed. Required if `upstream_uri` and `upstream_port` are not set.\n" - }, - { - "name": "upstream_fallback", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "Whether the plugin will fall back to the original upstream if the Canary Upstream doesn't have at least one healthy target. (`upstream_host` must point to a valid Kong Upstream entity.)\n" - }, - { - "name": "upstream_port", - "required": "semi", - "default": null, - "value_in_examples": 80, - "datatype": "integer", - "description": "The target port where traffic will be routed. Required if `upstream_uri` and `upstream_host` are not set.\nMust be a value between 0 and 65535.\n" - }, - { - "name": "upstream_uri", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "The Upstream URI where traffic will be routed. Required if `upstream_port` and `upstream_host` are not set.\n" - }, - { - "name": "hash", - "required": null, - "default": "consumer", - "value_in_examples": null, - "datatype": "string", - "description": "Entity to be used for hashing. Options: `consumer`, `ip`, `header`, `allow`, `deny`, or `none`.\nWhen using `consumer` or `ip`, make sure to properly set the settings for trusted IPs\n(see the `trusted_ips` and `real_ip_header` settings in the Kong configuration file.)\n" - }, - { - "name": "groups", - "required": null, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "An array of strings with the group names that are allowed or denied. Set `hash` to either `allow` (the listed groups\ngo into the canary) or `deny` (the listed groups will NOT go into the canary.)\n" - }, - { - "name": "hash_header", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Header name whose value will be used as hash input. Required if `config.hash` is set to `header`.\n" - }, - { - "name": "canary_by_header_name", - "minimum_version": "2.8.x", - "required": null, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Header name that, when present on a request, overrides the configured canary\nfunctionality.\n\n* If the configured header is present with the value `always`, the request will\nalways go to the canary upstream.\n* If the header is present with the value `never`, the request will never go to the\ncanary upstream.\n\nFor all other values, the configured canary rules will be applied.\n" - } - ], - "correlation-id": [ - { - "name": "header_name", - "required": false, - "default": "Kong-Request-ID", - "value_in_examples": "Kong-Request-ID", - "datatype": "string", - "description": "The HTTP header name to use for the correlation ID.\n" - }, - { - "name": "generator", - "required": false, - "default": "uuid#counter", - "value_in_examples": "uuid#counter", - "datatype": "string", - "description": "The generator to use for the correlation ID. Accepted values are `uuid`, `uuid#counter`, and `tracker`. See [Generators](#generators).\n" - }, - { - "name": "echo_downstream", - "required": false, - "default": false, - "value_in_examples": false, - "datatype": "boolean", - "description": "Whether to echo the header back to downstream (the client).\n" - } - ], - "cors": [ - { - "name": "origins", - "required": false, - "default": null, - "value_in_examples": [ - "http://mockbin.com" - ], - "datatype": "array of string elements", - "description": "List of allowed domains for the `Access-Control-Allow-Origin` header. If you want to allow all origins, add `*` as a single value to this configuration field. The accepted values can either be flat strings or PCRE regexes.\n" - }, - { - "name": "methods", - "required": false, - "default": "`GET, HEAD, PUT, PATCH, POST, DELETE, OPTIONS, TRACE, CONNECT`", - "value_in_examples": [ - "GET", - "POST" - ], - "datatype": "array of string elements", - "description": "Value for the `Access-Control-Allow-Methods` header. Available options include `GET`, `HEAD`, `PUT`, `PATCH`, `POST`, `DELETE`, `OPTIONS`, `TRACE`, `CONNECT`. By default, all options are allowed." - }, - { - "name": "headers", - "required": false, - "default": "Value of the `Access-Control-Request-Headers` request header", - "value_in_examples": [ - "Accept", - "Accept-Version", - "Content-Length", - "Content-MD5", - "Content-Type", - "Date", - "X-Auth-Token" - ], - "datatype": "array of string elements", - "description": "Value for the `Access-Control-Allow-Headers` header.\n" - }, - { - "name": "exposed_headers", - "required": false, - "default": null, - "value_in_examples": [ - "X-Auth-Token" - ], - "datatype": "array of string elements", - "description": "Value for the `Access-Control-Expose-Headers` header. If not specified, no custom headers are exposed.\n" - }, - { - "name": "credentials", - "required": true, - "default": "`false`", - "value_in_examples": true, - "datatype": "boolean", - "description": "Flag to determine whether the `Access-Control-Allow-Credentials` header should be sent with `true` as the value.\n" - }, - { - "name": "max_age", - "required": false, - "default": null, - "value_in_examples": 3600, - "datatype": "number", - "description": "Indicates how long the results of the preflight request can be cached, in `seconds`.\n" - }, - { - "name": "preflight_continue", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "A boolean value that instructs the plugin to proxy the `OPTIONS` preflight request to the Upstream service." - } - ], - "datadog": [ - { - "name": "host", - "required": false, - "default": "localhost", - "value_in_examples": "127.0.0.1", - "datatype": "string", - "description": "The IP address or hostname to send data to." - }, - { - "name": "port", - "required": false, - "default": 8125, - "value_in_examples": 8125, - "datatype": "integer", - "description": "The port to send data to on the upstream server." - }, - { - "name": "metrics", - "required": true, - "default": null, - "datatype": "array of record elements", - "description": "List of metrics to be logged. Available values are described at [Metrics](#metrics).\nBy default, the plugin logs all available metrics. If you specify an array of metrics,\nonly the listed metrics are logged.\n" - }, - { - "name": "prefix", - "required": false, - "default": "kong", - "datatype": "string", - "description": "String to be attached as a prefix to a metric's name." - }, - { - "name": "service_name_tag", - "minimum_version": "2.7.x", - "required": false, - "default": "name", - "datatype": "string", - "description": "String to be attached as the name of the service." - }, - { - "name": "status_tag", - "minimum_version": "2.7.x", - "required": false, - "default": "status", - "datatype": "string", - "description": "String to be attached as the tag of the HTTP status." - }, - { - "name": "consumer_tag", - "minimum_version": "2.7.x", - "required": false, - "default": "consumer", - "datatype": "string", - "description": "String to be attached as tag of the consumer." - }, - { - "name": "flush_timeout", - "required": true, - "default": "`2`", - "value_in_examples": 2, - "datatype": "number", - "description": "Optional time in seconds. If `queue_size` > 1, this is the max idle time before sending a log with less than `queue_size` records.\n", - "minimum_version": "3.1.x" - }, - { - "name": "retry_count", - "required": true, - "default": 10, - "value_in_examples": 10, - "datatype": "integer", - "description": "Number of times to retry when sending data to the upstream server.", - "minimum_version": "3.1.x" - }, - { - "name": "queue_size", - "required": true, - "default": 1, - "datatype": "integer", - "description": "Maximum number of log entries to be sent on each message to the upstream server.", - "minimum_version": "3.1.x" - } - ], - "degraphql": [ - { - "name": "graphql_server_path", - "required": true, - "default": "/graphql", - "datatype": "string", - "description": "The path to the GraphQL server.", - "minimum_version": "3.0.x" - } - ], - "exit-transformer": [ - { - "name": "functions", - "required": true, - "value_in_examples": [ - "@example/my_function.lua" - ], - "value_in_examples_serialized": [ - "|\n local responses = {\n [\"Invalid authentication credentials\"] = {\n message = \"Invalid API key\",\n },\n }\n\n return function(status, body, headers)\n if not body or not body.message then\n return status, body, headers\n end\n\n local response = responses[body.message]\n\n body.message = response.message or body.message\n status = response.status or status\n headers = response.headers or headers\n\n return status, body, headers\n end\n" - ], - "datatype": "array of string elements", - "description": "Array of functions used to transform any Kong proxy exit response." - }, - { - "name": "handle_unknown", - "default": "`false`", - "required": false, - "datatype": "boolean", - "description": "Allow transform to apply to unmatched Service, Route, or Workspace (404) responses." - }, - { - "name": "handle_unexpected", - "default": "`false`", - "required": false, - "datatype": "boolean", - "description": "Allow transform to apply to unexpected request (400) responses." - } - ], - "file-log": [ - { - "name": "path", - "required": true, - "default": null, - "value_in_examples": "/tmp/file.log", - "datatype": "string", - "description": "The file path of the output log file. The plugin creates the log file if it doesn't exist yet. Make sure Kong has write permissions to this file.\n" - }, - { - "name": "reopen", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Determines whether the log file is closed and reopened on every request. If the file\nis not reopened, and has been removed/rotated, the plugin keeps writing to the\nstale file descriptor, and hence loses information.\n" - }, - { - "name": "custom_fields_by_lua", - "minimum_version": "2.4.x", - "required": false, - "default": null, - "datatype": "map", - "description": "A list of key-value pairs, where the key is the name of a log field and\nthe value is a chunk of Lua code, whose return value sets or replaces\nthe log field value. Requires Kong 2.4.x or above.\n" - } - ], - "forward-proxy": [ - { - "name": "http_proxy_host", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": "example.com", - "datatype": "string", - "description": "The HTTP hostname or IP address of the forward proxy to which to connect.\nRequired if `http_proxy_port` is set.\n\nAt least one of `http_proxy_host` or `https_proxy_host` must be specified.\n\nIf `http_proxy_host` isn't set, the plugin falls back to the value\nconfigured in `https_proxy_host`.\n" - }, - { - "name": "http_proxy_port", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": 80, - "datatype": "string", - "description": "The TCP port of the HTTP forward proxy to which to connect.\nRequired if `http_proxy_host` is set.\n\nAt least one of `http_proxy_port` or `https_proxy_port` must be specified.\n\nIf `http_proxy_port` isn't set, the plugin falls back to the value\nconfigured in `https_proxy_port`.\n" - }, - { - "name": "https_proxy_host", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "The HTTPS hostname or IP address of the forward proxy to which to connect.\nRequired if `https_proxy_port` is set.\n\nAt least one of `http_proxy_host` or `https_proxy_host` must be specified.\n\nIf `https_proxy_host` isn't set, the plugin falls back to the value\nconfigured in `http_proxy_host`.\n" - }, - { - "name": "https_proxy_port", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "The TCP port of the HTTPS forward proxy to which to connect.\nRequired if `https_proxy_host` is set.\n\nAt least one of `http_proxy_port` or `https_proxy_port` must be specified.\n\nIf `https_proxy_port` isn't set, the plugin falls back to the value\nconfigured in `http_proxy_port`.\n" - }, - { - "name": "proxy_host", - "maximum_version": "2.8.x", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "\n{:.important}\n> This parameter is deprecated as of Kong Gateway 2.8.0.0 and\nis planned to be removed in a future release.\n>
\n> Use `http_proxy_host` or `https_proxy_host` instead.\n\nThe hostname or IP address of the forward proxy to which to connect.\n" - }, - { - "name": "proxy_port", - "maximum_version": "2.8.x", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "\n{:.important}\n> This parameter is deprecated as of Kong Gateway 2.8.0.0 and\nis planned to be removed in a future release.\n>
\n> Use `http_proxy_host` or `https_proxy_host` instead.\n\nThe TCP port of the forward proxy to which to connect.\n" - }, - { - "name": "proxy_scheme", - "required": false, - "default": "http", - "value_in_examples": "http", - "datatype": "string", - "description": "The proxy scheme to use when connecting. Only `http` is supported.\n" - }, - { - "name": "auth_username", - "minimum_version": "2.7.x", - "required": false, - "default": null, - "value_in_examples": "example_user", - "datatype": "string", - "referenceable": true, - "description": "The username to authenticate with, if the forward proxy is protected\nby basic authentication.\n" - }, - { - "name": "auth_password", - "minimum_version": "2.7.x", - "required": false, - "default": null, - "value_in_examples": "example_pass", - "datatype": "string", - "referenceable": true, - "description": "The password to authenticate with, if the forward proxy is protected\nby basic authentication.\n" - }, - { - "name": "https_verify", - "required": false, - "default": false, - "value_in_examples": false, - "datatype": "boolean", - "description": "Whether the server certificate will be verified according to the CA certificates\nspecified in\n[lua_ssl_trusted_certificate](https://www.nginx.com/resources/wiki/modules/lua/#lua-ssl-trusted-certificate).\n" - }, - { - "name": "x_headers", - "required": false, - "default": "append", - "value_in_examples": "transparent", - "datatype": "string", - "description": "How the plugin handles the following headers:\n`X-Real-IP`, `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Forwarded-Port`.\n\nThe field should be set to one of the following values:\n - `append`: Append information from this hop to the headers.\n - `transparent`: Leave headers unchanged, as if not using a proxy.\n - `delete`: Remove all headers including those that should be added for this hop, as if you are the originating client.\n\nAll options respect the trusted IP setting and will ignore last hop headers if they are not from clients with trusted IPs.\n" - } - ], - "graphql-proxy-cache-advanced": [ - { - "name": "vary_headers", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Relevant headers considered for the cache key. If undefined, none of the headers are taken into consideration.\n" - }, - { - "name": "cache_ttl", - "required": null, - "default": 300, - "value_in_examples": null, - "datatype": "integer", - "description": "TTL in seconds of cache entities. Must be a value greater than 0.\n" - }, - { - "name": "strategy", - "required": true, - "default": "memory", - "value_in_examples": "memory", - "datatype": "string", - "description": "The backing data store in which to hold cached entities. Accepted value is `memory`.\n" - }, - { - "name": "memory.dictionary_name", - "required": true, - "default": "kong_db_cache", - "value_in_examples": null, - "datatype": "string", - "description": "The name of the shared dictionary in which to hold cache entities when the memory strategy is selected. Note\nthat this dictionary currently must be defined manually in the Kong Nginx template.\n" - } - ], - "graphql-rate-limiting-advanced": [ - { - "name": "cost_strategy", - "required": true, - "default": "default", - "value_in_examples": null, - "datatype": "string", - "description": "Strategy to use to evaluate query costs. Either `default` or\n`node_quantifier`. See [default](/hub/kong-inc/graphql-rate-limiting-advanced/#default) and\n[node_quantifier](/hub/kong-inc/graphql-rate-limiting-advanced/#node_quantifier) respectively.\n" - }, - { - "name": "max_cost", - "required": false, - "default": 0, - "value_in_examples": null, - "datatype": "number", - "description": "A defined maximum cost per query. 0 means unlimited.\n" - }, - { - "name": "score_factor", - "required": false, - "default": 1, - "value_in_examples": null, - "datatype": "number", - "description": "A scoring factor to multiply (or divide) the cost. The `score_factor` must always be greater than 0.\n" - }, - { - "name": "limit", - "required": true, - "default": null, - "value_in_examples": [ - "5" - ], - "datatype": "array of number elements", - "description": "One or more requests-per-window limits to apply.\n" - }, - { - "name": "window_size", - "required": true, - "default": null, - "value_in_examples": [ - "30" - ], - "datatype": "array of number elements", - "description": "One or more window sizes to apply a limit to (defined in seconds).\n" - }, - { - "name": "identifier", - "required": true, - "default": "consumer", - "value_in_examples": null, - "datatype": "string", - "description": "How to define the rate limit key. Can be `ip`, `credential`, `consumer`.\n" - }, - { - "name": "dictionary_name", - "required": true, - "default": "kong_rate_limiting_counters", - "value_in_examples": null, - "datatype": "string", - "description": "The shared dictionary where counters will be stored until the next sync cycle.\n" - }, - { - "name": "sync_rate", - "required": true, - "default": null, - "value_in_examples": -1, - "datatype": "number", - "description": "How often to sync counter data to the central data store. A value of 0\nresults in synchronous behavior; a value of -1 ignores sync behavior\nentirely and only stores counters in node memory. A value greater than\n0 syncs the counters in that many number of seconds.\n" - }, - { - "name": "namespace", - "required": "semi", - "default": "random_auto_generated_string", - "value_in_examples": "example_namespace", - "datatype": "string", - "description": "The rate limiting library namespace to use for this plugin instance. Counter\ndata and sync configuration is shared in a namespace.\n\n{:.important}\n> **Important**: If managing Kong Gateway with **declarative configuration** or running\nKong Gateway in **DB-less mode**, set the `namespace` explicitly in your declarative configuration.\n>

\n> If not set, you will run into the following issues:\n* In DB-less mode, this field will be regenerated automatically on every configuration change.\n* If applying declarative configuration with decK, decK will automatically fail the update and require a \n`namespace` value.\n" - }, - { - "name": "strategy", - "required": null, - "default": "cluster", - "value_in_examples": "cluster", - "datatype": "string", - "description": "The rate-limiting strategy to use for retrieving and incrementing the\nlimits. Available values are:\n- `cluster`: Counters are stored in the Kong datastore and shared across\nthe nodes.\n- `redis`: Counters are stored on a Redis server and shared\nacross the nodes.\n\nIn DB-less and hybrid modes, the `cluster` config strategy is not\nsupported.\n\n{:.important}\n> There is no local storage strategy. However, you can achieve local\nrate limiting by using a placeholder `strategy` value (either `cluster` or `redis`)\nand a `sync_rate` of `-1`. This setting stores counters in-memory on the\nnode.\n

If using `redis` as the placeholder value, you must fill in all\nadditional `redis` configuration parameters with placeholder values.\n\nFor details on which strategy should be used, refer to the\n[implementation considerations](/hub/kong-inc/rate-limiting/#implementation-considerations).\n" - }, - { - "name": "redis.host", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Host to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.port", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "integer", - "description": "Port to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.ssl", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "If set to true, then uses SSL to connect to Redis.\n", - "minimum_version": "2.2.x" - }, - { - "name": "redis.ssl_verify", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "If set to true, then verifies the validity of the server SSL certificate. Note that you need to configure the\n[lua_ssl_trusted_certificate](/gateway/latest/reference/configuration/#lua_ssl_trusted_certificate)\nto specify the CA (or server) certificate used by your redis server. You may also need to configure\n[lua_ssl_verify_depth](/gateway/latest/reference/configuration/#lua_ssl_verify_depth) accordingly.\n", - "minimum_version": "2.2.x" - }, - { - "name": "redis.server_name", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Specifies the server name for the new TLS extension Server Name Indication (SNI) when connecting over SSL.\n", - "minimum_version": "2.2.x" - }, - { - "name": "redis.timeout", - "required": "semi", - "default": 2000, - "value_in_examples": null, - "datatype": "number", - "description": "Connection timeout (in milliseconds) to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.username", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Username to use for Redis connection when the `redis` strategy is defined and ACL authentication is desired.\nIf undefined, ACL authentication will not be performed.\n\n This requires Redis v6.0.0+. The username **cannot** be set to `default`.\n", - "minimum_version": "2.8.x" - }, - { - "name": "redis.password", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Password to use for Redis connection when the `redis` strategy is defined.\nIf undefined, no AUTH commands are sent to Redis.\n" - }, - { - "name": "redis.database", - "required": "semi", - "default": 0, - "value_in_examples": null, - "datatype": "integer", - "description": "Database to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.sentinel_master", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Sentinel master to use for Redis connection when the `redis` strategy is defined. Defining this value implies using Redis Sentinel.\n" - }, - { - "name": "redis.sentinel_username", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Sentinel username to authenticate with a Redis Sentinel instance.\nIf undefined, ACL authentication will not be performed. This requires Redis v6.2.0+.\n", - "minimum_version": "2.8.x" - }, - { - "name": "redis.sentinel_password", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Sentinel password to authenticate with a Redis Sentinel instance.\nIf undefined, no AUTH commands are sent to Redis Sentinels.\n" - }, - { - "name": "redis.sentinel_role", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Sentinel role to use for Redis connection when the `redis` strategy is defined. Defining this value implies using Redis Sentinel.\n" - }, - { - "name": "redis.sentinel_addresses", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Sentinel addresses to use for Redis connection when the `redis` strategy is defined. Defining this value implies using Redis Sentinel.\n" - }, - { - "name": "redis.cluster_addresses", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Cluster addresses to use for Redis connection when the `redis` strategy is defined. Defining this value implies using Redis cluster.\n" - }, - { - "name": "redis.keepalive_backlog", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "integer", - "description": "If specified, limits the total number of opened connections for a pool. If the\nconnection pool is full, all connection queues beyond the maximum limit go into\nthe backlog queue. Once the backlog queue is full, subsequent connect operations\nwill fail and return `nil`. Queued connect operations resume once the number of\nconnections in the pool is less than `keepalive_pool_size`. Note that queued\nconnect operations are subject to set timeouts.\n", - "minimum_version": "2.5.x" - }, - { - "name": "redis.keepalive_pool", - "required": false, - "default": "generated from string template", - "value_in_examples": null, - "datatype": "string", - "description": "The custom name of the connection pool. If not specified, the connection pool\nname is generated from the string template `\":\"` or `\"\"`.\n", - "minimum_version": "2.5.x" - }, - { - "name": "redis.keepalive_pool_size", - "required": false, - "default": 30, - "value_in_examples": null, - "datatype": "integer", - "description": "The size limit for every cosocket connection pool associated with every remote\nserver, per worker process. If no `keepalive_pool_size` is specified and no `keepalive_backlog`\nis specified, no pool is created. If no `keepalive_pool_size` is specified and `keepalive_backlog`\nis specified, then the pool uses the default value `30`.\n", - "minimum_version": "2.5.x" - }, - { - "name": "window_type", - "required": true, - "default": "sliding", - "value_in_examples": null, - "datatype": "string", - "description": "Sets the time window to either `sliding` or `fixed`.\n" - }, - { - "name": "hide_client_headers", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "Optionally hide informative response headers. Available options: `true` or `false`.\n" - } - ], - "grpc-gateway": [ - { - "name": "proto", - "required": false, - "default": null, - "value_in_examples": "path/to/hello.proto", - "datatype": "string", - "description": "Describes the gRPC types and methods.\n[HTTP configuration](https://github.com/googleapis/googleapis/blob/fc37c47e70b83c1cc5cc1616c9a307c4303fe789/google/api/http.proto)\nmust be defined in the file.\n" - } - ], - "grpc-web": [ - { - "name": "proto", - "required": false, - "default": null, - "value_in_examples": "path/to/hello.proto", - "datatype": "string", - "description": "If present, describes the gRPC types and methods.\nRequired to support payload transcoding. When absent, the\nweb client must use application/grpw-web+proto content.\n" - }, - { - "name": "pass_stripped_path", - "minimum_version": "2.2.x", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "boolean", - "description": "If set to `true` causes the plugin to pass the stripped request path to the upstream gRPC service (see the `strip_path` Route attribute)." - }, - { - "name": "allow_origin_header", - "minimum_version": "2.5.x", - "required": false, - "datatype": "string", - "default": "*", - "value_in_examples": null, - "description": "The value of the `Access-Control-Allow-Origin` header in the response to\nthe gRPC-Web client. The default of `*` is appropriate for requests without\ncredentials. In other cases, specify the allowed origins of the client code.\nFor more information, see [MDN Web Docs - Access-Control-Allow-Origin](https://developer.mozilla.org/docs/Web/HTTP/Headers/Access-Control-Allow-Origin).\n" - } - ], - "hmac-auth": [ - { - "name": "hide_credentials", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "An optional boolean value telling the plugin to show or hide the credential from the upstream service. If `true`, the plugin strips the credential from the request (i.e. the `Authorization` header) before proxying it.\n" - }, - { - "name": "clock_skew", - "required": false, - "default": "`300`", - "datatype": "number", - "description": "[Clock Skew](https://tools.ietf.org/html/draft-cavage-http-signatures-00#section-3.4) in seconds to prevent replay attacks.\n" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (Consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request will fail with an authentication failure `4xx`. Please note that this value must refer to the Consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails.\nIf empty (default), the request will fail with an authentication failure `4xx`. Note that this value\nmust refer to the consumer `id` attribute that is internal to Kong Gateway, and **not** its `custom_id`.\n", - "maximum_version": "3.0.x" - }, - { - "name": "validate_request_body", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "A boolean value telling the plugin to enable body validation." - }, - { - "name": "enforce_headers", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "A list of headers that the client should at least use for HTTP signature creation." - }, - { - "name": "algorithms", - "required": false, - "default": "`hmac-sha1`,
`hmac-sha256`,
`hmac-sha384`,
`hmac-sha512`", - "datatype": "array of string elements", - "description": "A list of HMAC digest algorithms that the user wants to support. Allowed values are `hmac-sha1`, `hmac-sha256`, `hmac-sha384`, and `hmac-sha512`\n" - } - ], - "http-log": [ - { - "name": "http_endpoint", - "required": true, - "default": null, - "value_in_examples": "http://mockbin.org/bin/:id", - "datatype": "string", - "encrypted": true, - "description": "The HTTP URL endpoint (including the protocol to use) to which the data is sent.\n\nIf the `http_endpoint` contains a username and password (for example,\n`http://bob:password@example.com/logs`), then Kong Gateway automatically includes\na basic-auth `Authorization` header in the log requests.\n" - }, - { - "name": "method", - "required": false, - "default": "`POST`", - "value_in_examples": "POST", - "datatype": "string", - "description": "An optional method used to send data to the HTTP server. Supported values are\n`POST` (default), `PUT`, and `PATCH`.\n" - }, - { - "name": "content_type", - "required": false, - "default": "`application/json`", - "value_in_examples": null, - "datatype": "string", - "description": "Indicates the type of data sent. The only available option is `application/json`.\n" - }, - { - "name": "timeout", - "required": false, - "default": "`10000`", - "value_in_examples": 1000, - "datatype": "number", - "description": "An optional timeout in milliseconds when sending data to the upstream server." - }, - { - "name": "keepalive", - "required": false, - "default": "`60000`", - "value_in_examples": 1000, - "datatype": "number", - "description": "An optional value in milliseconds that defines how long an idle connection will live before being closed." - }, - { - "name": "flush_timeout", - "required": false, - "default": "`2`", - "value_in_examples": 2, - "datatype": "number", - "description": "Optional time in seconds. If `queue_size` > 1, this is the max idle time before sending a log with less than `queue_size` records. \n" - }, - { - "name": "retry_count", - "required": false, - "default": 10, - "value_in_examples": 15, - "datatype": "integer", - "description": "Number of times to retry when sending data to the upstream server." - }, - { - "name": "queue_size", - "required": false, - "default": 1, - "datatype": "integer", - "description": "Maximum number of log entries to be sent on each message to the upstream server." - }, - { - "name": "headers", - "required": false, - "default": "empty table", - "datatype": "table", - "description": "\nAn optional table of headers added to the HTTP message to the upstream server.\nThe table contains arrays of values, indexed by the header name (multiple values per header).\n\nThe following headers are not allowed: `Host`, `Content-Length`, `Content-Type`.\n", - "minimum_version": "2.3.x", - "maximum_version": "2.8.x" - }, - { - "name": "headers", - "required": false, - "default": "empty table", - "datatype": "table", - "description": "An optional table of headers included in the HTTP message to the\nupstream server. Values are indexed by header name, and each header name\naccepts a single string.\n\nThe following headers are not allowed: `Host`, `Content-Length`, `Content-Type`.\n\n> **Note:** Before version 3.0.0, the values were arrays of strings (multiple values per header name).\n", - "minimum_version": "3.0.x" - }, - { - "name": "custom_fields_by_lua", - "required": false, - "default": null, - "datatype": "map", - "description": "A list of key-value pairs, where the key is the name of a log field and\nthe value is a chunk of Lua code, whose return value sets or replaces\nthe log field value.\n", - "minimum_version": "2.4.x" - } - ], - "ip-restriction": [ - { - "name": "whitelist", - "required": "semi", - "default": null, - "value_in_examples": "54.13.21.1, 143.1.0.0/24", - "description": "Comma-separated list of IPs or CIDR ranges to whitelist. One of `config.whitelist` or `config.blacklist` must be specified.\n", - "maximum_version": "2.0.x" - }, - { - "name": "blacklist", - "required": "semi", - "default": null, - "description": "Comma-separated list of IPs or CIDR ranges to blacklist. One of `config.whitelist` or `config.blacklist` must be specified.\n", - "maximum_version": "2.0.0" - }, - { - "name": "allow", - "required": "semi", - "default": null, - "value_in_examples": [ - "54.13.21.1", - "143.1.0.0/24" - ], - "datatype": "array of string elements", - "description": "List of IPs or CIDR ranges to allow. One of `config.allow` or `config.deny` must be specified.\n\nNote: We have deprecated the usage of `whitelist` and `blacklist` in favor of `allow` and `deny`. \n", - "minimum_version": "2.1.x", - "maximum_version": "2.8.x" - }, - { - "name": "deny", - "required": "semi", - "default": null, - "datatype": "array of string elements", - "description": "List of IPs or CIDR ranges to deny. One of `config.allow` or `config.deny` must be specified.\n\nNote: We have deprecated the usage of `whitelist` and `blacklist` in favor of `allow` and `deny`. \n", - "minimum_version": "2.1.x", - "maximum_version": "2.8.x" - }, - { - "name": "allow", - "required": "semi", - "default": null, - "value_in_examples": [ - "54.13.21.1", - "143.1.0.0/24" - ], - "datatype": "array of string elements", - "description": "List of IPs or CIDR ranges to allow. One of `config.allow` or `config.deny` must be specified.\n", - "minimum_version": "3.0.x" - }, - { - "name": "deny", - "required": "semi", - "default": null, - "datatype": "array of string elements", - "description": "List of IPs or CIDR ranges to deny. One of `config.allow` or `config.deny` must be specified.\n", - "minimum_version": "3.0.x" - }, - { - "name": "status", - "required": false, - "default": 403, - "datatype": "integer", - "description": "The HTTP status of the requests that will be rejected by the plugin.\n", - "minimum_version": "2.7.x" - }, - { - "name": "message", - "required": false, - "default": "Your IP address is not allowed", - "datatype": "string", - "description": "The message to send as a response body to rejected requests.\n", - "minimum_version": "2.7.x" - } - ], - "jq": [ - { - "name": "request_jq_program", - "required": "semi", - "datatype": "string", - "description": "The jq program to run on the request body. For example, `.[0] | { \"X-Foo\": .foo }`.\nEither `request_jq_program` or `response_jq_plugin` **must** be included in the configuration.\n" - }, - { - "name": "request_jq_program_options", - "required": false, - "datatype": "record", - "description": "Boolean option flags to modify the run behavior of the jq program run on the request body.\n- `compact_output`: Returns output in a compact form without additional spacing,\n and with each JSON object on a single line. Defaults to `true`. Set to `false` for \"pretty\" output.\n- `raw_output`: Outputs as raw strings, not JSON quoted. Default is `false`.\n- `join_output`: Similar to `raw_output` but does not output newline separators. Default is `false`.\n- `ascii_output`: jq usually outputs non-ASCII Unicode codepoints as UTF-8, even if the input specified\n them as escape sequences (like `\\u03bc`). Using this option, you can force jq to produce pure ASCII\n output, replacing every non-ASCII character with the equivalent escape sequence. Default is `false`.\n- `sort_keys`: Outputs the fields of each object with the keys in sorted order. Default is `false`.\n" - }, - { - "name": "request_if_media_type", - "required": false, - "datatype": "array of strings", - "default": [ - "application/json" - ], - "description": "A list of media type strings. The media type included in the `Content-Type` request header **must**\nmatch one of the media types on this list for the program to run.\n" - }, - { - "name": "response_jq_program", - "required": "semi", - "datatype": "string", - "description": "The jq program to run on the response body. For example, `.[0] | { \"X-Foo\": .foo }`.\nEither `request_jq_program` or `response_jq_plugin` **must** be included in configuration.\n" - }, - { - "name": "response_jq_program_options", - "required": false, - "datatype": "record", - "description": "Boolean option flags to modify the run behavior of the jq program run on the response body.\n- `compact_output`: Returns output in a compact form without additional spacing,\n and with each JSON object on a single line. Defaults to `true`. Set to `false` for \"pretty\" output.\n- `raw_output`: Outputs as raw strings, not JSON quoted. Default is `false`.\n- `join_output`: Similar to `raw_output` but does not output newline separators. Default is `false`.\n- `ascii_output`: jq usually outputs non-ASCII Unicode codepoints as UTF-8, even if the input specified\n them as escape sequences (like `\\u03bc`). Using this option, you can force jq to produce pure ASCII\n output, replacing every non-ASCII character with the equivalent escape sequence. Default is `false`.\n- `sort_keys`: Outputs the fields of each object with the keys in sorted order. Default is `false`.\n" - }, - { - "name": "response_if_media_type", - "required": false, - "datatype": "array of strings", - "default": [ - "application/json" - ], - "description": "A list of media type strings. The media type included in the `Content-Type` response header **must**\nmatch one of the media types on this list for the program to run.\n" - }, - { - "name": "response_if_status_code", - "required": false, - "datatype": "array of integers", - "default": [ - 200 - ], - "description": "A list of HTTP response status codes. The response status code **must**\nmatch one of the response status codes on this list for the program to run.\n" - } - ], - "jwe-decrypt": [ - { - "name": "lookup_token_name", - "required": false, - "default": "Authorization", - "datatype": "string", - "description": "The name of the header to look for the JWE token.\n" - }, - { - "name": "forward_token_name", - "required": false, - "default": "Authorization", - "datatype": "string", - "description": "The name of the header that is used to set the decrypted value.\n" - }, - { - "name": "strict", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Defines how the plugin behaves in cases where no token was found in the request. When using `strict` mode, the request requires a token to be present and subsequently raise an error if none could be found.\n" - }, - { - "name": "key-sets", - "required": true, - "datatype": "array of string elements", - "description": "Denote the name or names of all Key Sets that should be inspected when trying to find a suitable key to decrypt the JWE token.\n" - } - ], - "jwt-signer": [ - { - "name": "realm", - "required": false, - "default": null, - "datatype": "string", - "description": "When authentication or authorization fails, or there is an unexpected\nerror, the plugin sends an `WWW-Authenticate` header with the `realm`\nattribute value.\n" - }, - { - "name": "enable_hs_signatures", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Tokens signed with HMAC algorithms such as `HS256`, `HS384`, or `HS512` are not\naccepted by default. If you need to accept such tokens for verification,\nenable this setting.\n" - }, - { - "name": "enable_instrumentation", - "required": false, - "default": false, - "datatype": "boolean", - "description": "When you are experiencing problems in production and don't want to change\nthe logging level on Kong nodes, which requires a reload, use this\nparameter to enable instrumentation for the request. The parameter writes\nlog entries with some added information using `ngx.CRIT` (CRITICAL) level.\n" - }, - { - "name": "access_token_issuer", - "required": false, - "default": "kong", - "datatype": "string", - "description": "The `iss` claim of a signed or re-signed access token is set to this value.\nOriginal `iss` claim of the incoming token (possibly introspected) is\nstored in `original_iss` claim of the newly signed access token.\n" - }, - { - "name": "access_token_keyset", - "required": false, - "default": "kong", - "datatype": "string", - "description": "The name of the keyset containing signing keys.\n" - }, - { - "name": "access_token_jwks_uri", - "required": false, - "default": null, - "datatype": "string", - "description": "If you want to use `config.verify_access_token_signature`, you must specify\nthe URI where the plugin can fetch the public keys (JWKS) to verify the\nsignature of the access token. If you don't specify a URI and you pass a\nJWT token to the plugin, then the plugin responds with\n`401 Unauthorized`.\n" - }, - { - "name": "access_token_request_header", - "required": false, - "default": "Authorization", - "datatype": "string", - "description": "This parameter tells the name of the header where to look for the access token.\nBy default, the plugin searches it from `Authorization: Bearer ` header\n(the value being magic key `authorization:bearer`). If you don't want to\ndo anything with `access token`, then you can set this to `null` or `\"\"` (empty string).\nAny header can be used to pass the access token to the plugin. Two predefined\nvalues are `authorization:bearer` and `authorization:basic`.\n" - }, - { - "name": "access_token_leeway", - "required": false, - "default": 0, - "datatype": "number", - "description": "Adjusts clock skew between the token issuer and Kong. The value\nis added to the token's `exp` claim before checking token expiry against\nKong servers' current time in seconds. You can disable access token\n`expiry` verification altogether with `config.verify_access_token_expiry`.\n" - }, - { - "name": "access_token_scopes_required", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Specify the required values (or scopes) that are checked by a\nclaim specified by `config.access_token_scopes_claim`. For example,\n`[ \"employee demo-service\", \"superadmin\" ]` can be given as\n`\"employee demo-service,superadmin\"` (form post) would mean that the claim\nneeds to have values `\"employee\"` and `\"demo-service\"` **OR** that the claim\nneeds to have the value of `\"superadmin\"` to be successfully authorized for\nthe upstream access. If required scopes are\nnot found in access token, the plugin responds with `403 Forbidden`.\n" - }, - { - "name": "access_token_scopes_claim", - "required": false, - "default": [ - "scope" - ], - "datatype": "array of string elements", - "description": "Specify the claim in an access token to verify against values of\n`config.access_token_scopes_required`. This supports nested claims. For\nexample, with Keycloak you could use `[ \"realm_access\", \"roles\" ]`, which can\nbe given as `realm_access,roles` (form post).\nIf the claim is not found in the access token, and you have specified\n`config.access_token_scopes_required`,\nthe plugin responds with `403 Forbidden`.\n" - }, - { - "name": "access_token_consumer_claim", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "When you set a value for this parameter, the plugin tries to map an arbitrary\nclaim specified with this configuration parameter (for example, `sub` or `username`) in\nan access token to Kong consumer entity. Kong consumers have an `id`, a `username`,\nand a `custom_id`. The `config.access_token_consumer_by` parameter\ntells the plugin which of these Kong consumer properties can be used for mapping.\nIf this parameter is enabled but the mapping fails, such as when there's\na non-existent Kong consumer, the plugin responds with `403 Forbidden`.\nKong [consumer mapping](#consumer-mapping) is useful when you want to communicate this information\nto other plugins such as [ACL](/hub/kong-inc/acl/) or [rate limiting](/hub/kong-inc/rate-limiting/).\nThe JWT Signer plugin also sets a couple of standard Kong\nupstream consumer headers.\n" - }, - { - "name": "access_token_consumer_by", - "required": false, - "default": [ - "username", - "custom_id" - ], - "datatype": "array of string elements", - "description": "When the plugin tries to apply an access token to a Kong consumer mapping,\nit tries to find a matching Kong consumer from properties defined using\nthis configuration parameter. The parameter can take an array of\nvalues. Valid values are `id`, `username`, and `custom_id`.\n" - }, - { - "name": "access_token_upstream_header", - "required": false, - "default": "Authorization:bearer", - "datatype": "string", - "description": "Removes the `config.access_token_request_header` from the request after reading its\nvalue. With `config.access_token_upstream_header`, you can specify the upstream header where the plugin adds the Kong signed token. If you don't specify a value, such as use `null` or `\"\"` (empty string), the plugin does not even try to sign or re-sign the token.\n" - }, - { - "name": "access_token_upstream_leeway", - "required": false, - "default": 0, - "datatype": "number", - "description": "If you want to add or perhaps subtract (using a negative value) expiry\ntime (in seconds) of the original access token, you can specify a value that is added to\nthe original access token's `exp` claim.\n" - }, - { - "name": "access_token_introspection_endpoint", - "required": false, - "default": null, - "datatype": "string", - "description": "When you use `opaque` access tokens and you want to turn on access token\nintrospection, you need to specify the OAuth 2.0 introspection endpoint URI\nwith this configuration parameter. Otherwise, the plugin does not try\nintrospection and returns `401 Unauthorized` instead.\n" - }, - { - "name": "access_token_introspection_authorization", - "required": false, - "default": null, - "datatype": "string", - "description": "If the introspection endpoint requires client authentication (client being\nthe JWT Signer plugin), you can specify the `Authorization` header's value with this\nconfiguration parameter. For example, if you use client credentials, enter\nthe value of `\"Basic base64encode('client_id:client_secret')\"`\nto this configuration parameter. You are responsible for providing the full string\nof the header and doing all of the necessary encodings (such as base64)\nrequired on a given endpoint.\n" - }, - { - "name": "access_token_introspection_body_args", - "required": false, - "default": null, - "datatype": "string", - "description": "If you need to pass additional body arguments to an introspection endpoint\nwhen the plugin introspects the opaque access token, use this config parameter\nto specify them. You should URL encode the value. For example: `resource=` or `a=1&b=&c`.\n" - }, - { - "name": "access_token_introspection_hint", - "required": false, - "default": "access_token", - "datatype": "string", - "description": "If you need to give `hint` parameter when introspecting an access token,\nuse this parameter to specify the value. By default, the plugin\nsends `hint=access_token`.\n" - }, - { - "name": "access_token_introspection_jwt_claim", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "If your introspection endpoint returns an access token in one of the keys\n(or claims) within the introspection results (`JSON`), the plugin can use that value\ninstead of the introspection results when doing expiry verification and\nsigning of the new token issued by Kong. For example, if you specify\n`[ \"token_string\" ]`, which can be given as `\"token_string\"` (form post)\nto this configuration parameter, the plugin looks for key `token_string`\nin JSON of the introspection results and uses that as an access token instead\nof using introspection JSON directly. If the key cannot be found, the\nplugin responds with `401 Unauthorized`. Also if the key is found\nbut cannot be decoded as JWT, it also responds with `401 Unauthorized`.\n" - }, - { - "name": "access_token_introspection_scopes_required", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Specify the required values (or scopes) that are checked by an\nintrospection claim/property specified by `config.access_token_introspection_scopes_claim`.\nFor example, `[ \"employee demo-service\", \"superadmin\" ]` can be given as `\"employee demo-service,superadmin\"`\n(form post) would mean that the claim needs to have values `\"employee\"` and `\"demo-service\"` **OR**\nthat the claim needs to have value of `\"superadmin\"` to be successfully authorized for the upstream\naccess. If required scopes are not found in access token introspection results (`JSON`),\nthe plugin responds with `403 Forbidden`.\n" - }, - { - "name": "access_token_introspection_scopes_claim", - "required": true, - "default": [ - "scope" - ], - "datatype": "array of string elements", - "description": "Specify the claim/property in access token introspection results\n(`JSON`) to be verified against values of `config.access_token_introspection_scopes_required`.\nThis supports nested claims. For example, with Keycloak you could use `[ \"realm_access\", \"roles\" ]`,\nwhich can be given as `realm_access,roles` (form post). If the claim is not found in access\ntoken introspection results, and you have specified `config.access_token_introspection_scopes_required`,\nthe plugin responds with `403 Forbidden`.\n" - }, - { - "name": "access_token_introspection_consumer_claim", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "When you set a value for this parameter, the plugin tries to map an arbitrary\nclaim specified with this configuration parameter (such as `sub` or `username`)\nin access token introspection results to the Kong consumer entity. Kong consumers\nhave an `id`, a `username`, and a `custom_id`. The\n`config.access_token_introspection_consumer_by` parameter tells the plugin which of these\nKong consumer properties can be used for mapping. If this parameter is enabled\nbut the mapping fails, such as when there's\na non-existent Kong consumer, the plugin responds\nwith `403 Forbidden`. Kong [consumer mapping](#consumer-mapping) is useful when you want to\ncommunicate this information to other plugins such as [ACL](/hub/kong-inc/acl/)\nor [rate limiting](/hub/kong-inc/rate-limiting/). The JWT Signer plugin also\nsets a couple of standard Kong upstream consumer headers.\n" - }, - { - "name": "access_token_introspection_consumer_by", - "required": false, - "default": [ - "username", - "custom_id" - ], - "datatype": "array of string elements", - "description": "When the plugin tries to do access token introspection results to Kong consumer mapping, it tries to\nfind a matching Kong consumer from properties defined using this configuration parameter. The parameter\ncan take an array of values. Valid values are `id`, `username`, and `custom_id`.\n" - }, - { - "name": "access_token_introspection_leeway", - "required": false, - "default": 0, - "datatype": "number", - "description": "Adjusts clock skew between the token issuer introspection results\nand Kong. The value is added to introspection results (`JSON`) `exp` claim/property before\nchecking token expiry against Kong servers current time in seconds. You\ncan disable access token introspection `expiry` verification altogether\nwith `config.verify_access_token_introspection_expiry`.\n" - }, - { - "name": "access_token_introspection_timeout", - "required": false, - "default": null, - "datatype": "number", - "description": "Timeout in milliseconds for an introspection request.\nThe plugin tries to introspect twice if the first request\nfails for some reason. If both requests timeout, then the plugin runs two times the\n`config.access_token_introspection_timeout` on access token introspection.\n" - }, - { - "name": "access_token_signing_algorithm", - "required": true, - "default": "RS256", - "datatype": "string", - "description": "When this plugin sets the upstream header as specified with `config.access_token_upstream_header`,\nit also re-signs the original access token using the private keys of the JWT Signer plugin.\nSpecify the algorithm that is used to sign the token. Currently\nsupported values:\n- `\"HS256\"`\n- `\"HS384\"`\n- `\"HS512\"`\n- `\"RS256\"`\n- `\"RS512\"`\n- `\"ES256\"`\n- `\"ES384\"`\n- `\"ES512\"`\n- `\"PS256\"`\n- `\"PS384\"`\n- `\"PS512\"`\n- `\"EdDSA\"`\n\nThe `config.access_token_issuer`\nspecifies which `keyset` is used to sign the new token issued by Kong using\nthe specified signing algorithm.\n" - }, - { - "name": "access_token_optional", - "required": false, - "default": false, - "datatype": "boolean", - "description": "If an access token is not provided or no `config.access_token_request_header` is specified,\nthe plugin cannot verify the access token. In that case, the plugin normally responds\nwith `401 Unauthorized` (client didn't send a token) or `500 Unexpected` (a configuration error).\nUse this parameter to allow the request to proceed even when there is no token to check.\nIf the token is provided, then this parameter has no effect (look other parameters to enable and\ndisable checks in that case).\n" - }, - { - "name": "verify_access_token_signature", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Quickly turn access token signature verification off and on as needed.\n" - }, - { - "name": "verify_access_token_expiry", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Quickly turn access token expiry verification off and on as needed.\n" - }, - { - "name": "verify_access_token_scopes", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Quickly turn off and on the access token\nrequired scopes verification, specified with `config.access_token_scopes_required`.\n" - }, - { - "name": "verify_access_token_introspection_expiry", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Quickly turn access token introspection expiry verification off and on as needed.\n" - }, - { - "name": "verify_access_token_introspection_scopes", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Quickly turn off and on the access token\nintrospection scopes verification, specified with\n`config.access_token_introspection_scopes_required`.\n" - }, - { - "name": "cache_access_token_introspection", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Whether to cache access token introspection results.\n" - }, - { - "name": "trust_access_token_introspection", - "required": false, - "default": true, - "datatype": "boolean", - "description": "When you provide a opaque access token that the plugin introspects, and you do expiry\nand scopes verification on introspection results, you probably don't want to do another\nround of checks on the payload before the plugin signs a new token. Or that you don't\nwant to do checks to a JWT token provided with introspection JSON specified with\n`config.access_token_introspection_jwt_claim`. Use this parameter to enable and\ndisable further checks on a payload before the new token is signed. If you set this\nto `true`, the expiry or scopes are not checked on a payload.\n" - }, - { - "name": "enable_access_token_introspection", - "required": false, - "default": true, - "datatype": "boolean", - "description": "If you don't want to support opaque access tokens, change this\nconfiguration parameter to `false` to disable introspection.\n" - }, - { - "name": "channel_token_issuer", - "required": false, - "default": "kong", - "datatype": "string", - "description": "The `iss` claim of the re-signed channel token is set to this value, which\nis `kong` by default. The original `iss` claim of the incoming token\n(possibly introspected) is stored in the `original_iss` claim of\nthe newly signed channel token.\n" - }, - { - "name": "channel_token_keyset", - "required": false, - "default": "kong", - "datatype": "string", - "description": "The name of the keyset containing signing keys.\n" - }, - { - "name": "channel_token_jwks_uri", - "required": false, - "default": null, - "datatype": "string", - "description": "If you want to use `config.verify_channel_token_signature`, you must specify the URI where\nthe plugin can fetch the public keys (JWKS) to verify the signature of the channel token.\nIf you don't specify a URI and you pass a JWT token to the plugin, then the plugin responds\nwith `401 Unauthorized`.\n" - }, - { - "name": "channel_token_request_header", - "required": false, - "default": null, - "datatype": "string", - "description": "This parameter tells the name of the header where to look for the channel token.\nBy default, the plugin doesn't look for the channel token. If you don't want to\ndo anything with the channel token, then you can set this to `null` or `\"\"`\n(empty string). Any header can be used to pass the channel\ntoken to this plugin. Two predefined values are `authorization:bearer`\nand `authorization:basic`.\n" - }, - { - "name": "channel_token_leeway", - "required": false, - "default": 0, - "datatype": "number", - "description": "Adjusts clock skew between the token issuer and Kong. The value\nwill be added to token's `exp` claim before checking token expiry against Kong servers current\ntime in seconds. You can disable channel token `expiry` verification altogether with\n`config.verify_channel_token_expiry`.\n" - }, - { - "name": "channel_token_scopes_required", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Specify the required values (or scopes) that are checked by a claim\nspecified by `config.channel_token_scopes_claim`. For example, if `[ \"employee demo-service\", \"superadmin\" ]`\nwas given as `\"employee demo-service,superadmin\"` (form post), the claim needs\nto have values `\"employee\"` and `\"demo-service\"`, **OR** that the claim needs to have the value of\n`\"superadmin\"` to be successfully authorized for the upstream access. If required scopes are not\nfound in the channel token, the plugin responds with `403 Forbidden`.\n" - }, - { - "name": "channel_token_scopes_claim", - "required": false, - "default": [ - "scope" - ], - "datatype": "array of string elements", - "description": "Specify the claim in a channel token to verify against values of\n`config.channel_token_scopes_required`. This supports nested claims. With Keycloak, you could\nuse `[ \"realm_access\", \"roles\" ]`, which can be given as `realm_access,roles` (form post).\nIf the claim is not found in the channel token, and you have specified `config.channel_token_scopes_required`,\nthe plugin responds with `403 Forbidden`.\n" - }, - { - "name": "channel_token_consumer_claim", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "When you set a value for this parameter, the plugin tries to map an arbitrary claim specified with\nthis configuration parameter (such as `sub` or `username`) in a channel token to a Kong consumer entity. Kong\nconsumers have an `id`, a `username`, and a `custom_id`. The `config.channel_token_consumer_by` parameter\ntells the plugin which Kong consumer properties can be used for mapping. If this\nparameter is enabled but the mapping fails, such as when there's\na non-existent Kong consumer, the plugin responds\nwith `403 Forbidden`. Kong [consumer mapping](#consumer-mapping) is useful\nwhen you want to communicate this information\nto other plugins such as [ACL](/hub/kong-inc/acl/) or [rate limiting](/hub/kong-inc/rate-limiting/).\nThe JWT Signer plugin also sets a couple of standard Kong upstream consumer headers.\n" - }, - { - "name": "channel_token_consumer_by", - "required": false, - "default": [ - "username", - "custom_id" - ], - "datatype": "array of string elements", - "description": "When the plugin tries to do channel token to Kong consumer mapping, it tries\nto find a matching Kong consumer from properties defined using this configuration parameter.\nThe parameter can take an array of valid values: `id`, `username`, and `custom_id`.\n" - }, - { - "name": "channel_token_upstream_header", - "required": false, - "default": null, - "datatype": "string", - "description": "This plugin removes the `config.channel_token_request_header` from the request\nafter reading its value.\nWith `config.channel_token_upstream_header`, you can specify the upstream header where the plugin\nadds the Kong-signed token. If you don't specify a value (so `null` or `\"\"` empty string),\nthe plugin does not attempt to re-sign the token.\n" - }, - { - "name": "channel_token_upstream_leeway", - "required": false, - "default": 0, - "datatype": "number", - "description": "If you want to add or perhaps subtract (using negative value) expiry time of the original channel token,\nyou can specify a value that is added to the original channel token's `exp` claim.\n" - }, - { - "name": "channel_token_introspection_endpoint", - "required": false, - "default": null, - "datatype": "string", - "description": "When using `opaque` channel tokens, and you want to turn on channel token introspection, you need to\nspecify the OAuth 2.0 introspection endpoint URI with this configuration parameter.\nOtherwise the plugin will not try introspection, and instead returns `401 Unauthorized`\nwhen using opaque channel tokens.\n" - }, - { - "name": "channel_token_introspection_authorization", - "required": false, - "default": null, - "datatype": "string", - "description": "If the introspection endpoint requires client authentication (client being this plugin), you can specify\nthe `Authorization` header's value with this configuration parameter. If you use client credentials,\nyou should enter the value of `\"Basic base64encode('client_id:client_secret')\"` to this configuration parameter.\nYou are responsible for providing the full string of the header and doing\nall the necessary encodings (such as base64) required on a given endpoint.\n" - }, - { - "name": "channel_token_introspection_body_args", - "required": false, - "default": null, - "datatype": "string", - "description": "If you need to pass additional body arguments to introspection endpoint when the plugin introspects the\nopaque channel token, you can use this config parameter to specify them. You should URL encode the value.\nFor example: `resource=` or `a=1&b=&c`.\n" - }, - { - "name": "channel_token_introspection_hint", - "required": false, - "default": null, - "datatype": "string", - "description": "If you need to give `hint` parameter when introspecting a channel token, you can use this parameter to\nspecify the value of such parameter. By default, a `hint` isn't sent with channel token introspection.\n" - }, - { - "name": "channel_token_introspection_jwt_claim", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "If your introspection endpoint returns a channel token in one of the keys (or claims) in the introspection\nresults (`JSON`), the plugin can use that value instead of the introspection results when doing expiry verification\nand signing of the new token issued by Kong. For example, if you specify `[ \"token_string\" ]`, which can be given as\n`\"token_string\"` (form post) to this configuration parameter, the plugin looks for key `token_string`\nin JSON of the introspection results and uses that as a channel token instead of using introspection JSON\ndirectly. If the key cannot be found, the plugin responds with `401 Unauthorized`. Also if the key\nis found but cannot be decoded as JWT, the plugin responds with `401 Unauthorized`.\n" - }, - { - "name": "channel_token_introspection_scopes_required", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Use this parameter to specify the required values (or scopes) that are checked by an introspection\nclaim/property specified by `config.channel_token_introspection_scopes_claim`.\nFor example, `[ \"employee demo-service\", \"superadmin\" ]`, which can be given as `\"employee demo-service,superadmin\"`\n(form post) would mean that the claim needs to have the values `\"employee\"` and `\"demo-service\"` **OR** that the\nclaim needs to have the value of `\"superadmin\"` to be successfully authorized for the upstream access.\nIf required scopes are not found in channel token introspection results (`JSON`), the plugin\nresponds with `403 Forbidden`.\n" - }, - { - "name": "channel_token_introspection_scopes_claim", - "required": false, - "default": [ - "scope" - ], - "datatype": "array of string elements", - "description": "Use this parameter to specify the claim/property in channel token introspection results (`JSON`)\nto be verified against values of `config.channel_token_introspection_scopes_required`. This supports\nnested claims. For example, with Keycloak you could use `[ \"realm_access\", \"roles\" ]`, which can be given as\n`realm_access,roles` (form post). If the claim is not found in channel token introspection results,\nand you have specified `config.channel_token_introspection_scopes_required`, the plugin responds\nwith `403 Forbidden`.\n" - }, - { - "name": "channel_token_introspection_consumer_claim", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "When you set a value for this parameter, the plugin tries to map an arbitrary claim specified with\nthis configuration parameter (such as `sub` or `username`) in channel token introspection results to\nKong consumer entity. Kong consumers have an `id`, a `username` and a `custom_id`. The\n`config.channel_token_introspection_consumer_by` parameter tells the plugin which of these\nKong consumer properties can be used for mapping. If this parameter is enabled\nbut the mapping fails, such as when there's\na non-existent Kong consumer, the plugin responds with `403 Forbidden`. Kong\n[consumer mapping](#consumer-mapping)\nis useful when you want to communicate this information to other plugins such as\n[ACL](/hub/kong-inc/acl/) or [rate limiting](/hub/kong-inc/rate-limiting/). The\nJWT Signer plugin also sets a couple of standard\nKong upstream consumer headers.\n" - }, - { - "name": "channel_token_introspection_consumer_by", - "required": false, - "default": [ - "username", - "custom_id" - ], - "datatype": "array of string elements", - "description": "When the plugin tries to do channel token introspection results to Kong consumer mapping, it tries to\nfind a matching Kong consumer from properties defined using this configuration parameter. The parameter\ncan take an array of values. Valid values are `id`, `username` and `custom_id`.\n" - }, - { - "name": "channel_token_introspection_leeway", - "required": false, - "default": 0, - "datatype": "number", - "description": "You can use this parameter to adjust clock skew between the token issuer introspection results and Kong.\nThe value will be added to introspection results (`JSON`) `exp` claim/property before checking token expiry\nagainst Kong servers current time (in seconds). You can disable channel token introspection `expiry`\nverification altogether with `config.verify_channel_token_introspection_expiry`.\n" - }, - { - "name": "access_token_introspection_timeout", - "required": false, - "default": null, - "datatype": "number", - "description": "Timeout in milliseconds for an introspection request. The plugin tries to introspect twice if the first request\nfails for some reason. If both requests timeout, then the plugin runs two times the\n`config.access_token_introspection_timeout` on channel token introspection.\n" - }, - { - "name": "channel_token_signing_algorithm", - "required": true, - "default": "RS256", - "datatype": "string", - "description": "When this plugin sets the upstream header as specified with `config.channel_token_upstream_header`,\nit also re-signs the original channel token using private keys of this plugin.\nSpecify the algorithm that is used to sign the token. Currently\nsupported values:\n- `\"HS256\"`\n- `\"HS384\"`\n- `\"HS512\"`\n- `\"RS256\"`\n- `\"RS512\"`\n- `\"ES256\"`\n- `\"ES384\"`\n- `\"ES512\"`\n- `\"PS256\"`\n- `\"PS384\"`\n- `\"PS512\"`\n- `\"EdDSA\"`\n\nThe `config.channel_token_issuer` specifies which `keyset`\nis used to sign the new token issued by Kong using the specified signing algorithm.\n" - }, - { - "name": "channel_token_optional", - "required": false, - "default": false, - "datatype": "boolean", - "description": "If a channel token is not provided or no `config.channel_token_request_header` is specified,\nthe plugin cannot verify the channel token. In that case, the plugin normally responds\nwith `401 Unauthorized` (client didn't send a token) or `500 Unexpected` (a configuration error).\nEnable this parameter to allow the request to proceed even when there is no channel token\nto check. If the channel token is provided, then this parameter has no effect\n(look other parameters to enable and disable checks in that case).\n" - }, - { - "name": "verify_channel_token_signature", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Quickly turn on/off the channel token signature verification.\n" - }, - { - "name": "verify_channel_token_expiry", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Quickly turn on/off the channel token expiry verification.\n" - }, - { - "name": "verify_channel_token_scopes", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Quickly turn on/off the channel token required scopes\nverification specified with `config.channel_token_scopes_required`.\n" - }, - { - "name": "verify_channel_token_introspection_expiry", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Quickly turn on/off the channel token introspection expiry\nverification.\n" - }, - { - "name": "verify_channel_token_introspection_scopes", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Quickly turn on/off the channel token introspection scopes\nverification specified with `config.channel_token_introspection_scopes_required`.\n" - }, - { - "name": "cache_channel_token_introspection", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Whether to cache channel token introspection results.\n" - }, - { - "name": "trust_channel_token_introspection", - "required": false, - "default": true, - "datatype": "boolean", - "description": "When you provide an opaque channel token that the plugin introspects, and you do expiry\nand scopes verification on introspection results, you probably don't want to do another\nround of checks on the payload before the plugin signs a new token. Or you don't\nwant to do checks to a JWT token provided with introspection JSON specified with\n`config.channel_token_introspection_jwt_claim`. Use this parameter to enable or\ndisable further checks on a payload before the new token is signed. If you set this\nto `true` (default), the expiry or scopes are not checked on a payload.\n" - }, - { - "name": "enable_channel_token_introspection", - "required": false, - "default": true, - "datatype": "boolean", - "description": "If you don't want to support opaque channel tokens, disable introspection by\nchanging this configuration parameter to `false`.\n" - } - ], - "jwt": [ - { - "name": "uri_param_names", - "required": false, - "default": "`jwt`", - "datatype": "set of string elements", - "description": "A list of querystring parameters that Kong will inspect to retrieve JWTs." - }, - { - "name": "cookie_names", - "required": false, - "default": null, - "datatype": "set of string elements", - "description": "A list of cookie names that Kong will inspect to retrieve JWTs." - }, - { - "name": "header_names", - "required": false, - "default": "`authorization`", - "datatype": "set of string elements", - "description": "A list of HTTP header names that Kong will inspect to retrieve JWTs." - }, - { - "name": "claims_to_verify", - "required": false, - "default": null, - "datatype": "set of string elements", - "description": "A list of registered claims (according to [RFC 7519](https://tools.ietf.org/html/rfc7519)) that Kong can verify as well. Accepted values: one of `exp` or `nbf`.\n" - }, - { - "name": "key_claim_name", - "required": false, - "default": "`iss`", - "datatype": "string", - "description": "The name of the claim in which the `key` identifying the secret **must** be passed. Starting with version `0.13.1`, the plugin will attempt to read this claim from the JWT payload and the header, in that order.\n" - }, - { - "name": "secret_is_base64", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "If true, the plugin assumes the credential's `secret` to be base64 encoded. You will need to create a base64-encoded secret for your Consumer, and sign your JWT with the original secret.\n" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request will fail with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails.\nIf empty (default), the request will fail with an authentication failure `4xx`. Note that this value\nmust refer to the consumer `id` attribute that is internal to Kong Gateway, and **not** its `custom_id`.\n", - "maximum_version": "3.0.x" - }, - { - "name": "run_on_preflight", - "required": true, - "default": "`true`", - "datatype": "boolean", - "description": "A boolean value that indicates whether the plugin should run (and try to authenticate) on `OPTIONS` preflight requests. If set to `false`, then `OPTIONS` requests will always be allowed.\n" - }, - { - "name": "maximum_expiration", - "required": false, - "default": 0, - "datatype": "number", - "description": "A value between 0 and 31536000 (365 days) limiting the lifetime of the JWT to `maximum_expiration` seconds in the future. Any JWT that has a longer lifetime is rejected (HTTP 403). If this value is specified, `exp` must be specified as well in the `claims_to_verify` property. The default value of `0` represents an indefinite period. Potential clock skew should be considered when configuring this setting.\n" - } - ], - "kafka-log": [ - { - "name": "bootstrap_servers", - "required": true, - "value_in_examples": { - "BOOTSTRAP_SERVERS": null - }, - "urlencode_in_examples": true, - "default": null, - "datatype": "set of record elements", - "description": "Set of bootstrap brokers in a `{host: host, port: port}` list format.\n" - }, - { - "name": "topic", - "required": true, - "value_in_examples": { - "TOPIC": null - }, - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "description": "The Kafka topic to publish to.\n" - }, - { - "name": "authentication.strategy", - "minimum_version": "2.6.x", - "required": false, - "value_in_examples": "sasl", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "description": "The authentication strategy for the plugin, the only option for the value is `sasl`.\n" - }, - { - "name": "authentication.mechanism", - "minimum_version": "2.6.x", - "maximum_version": "2.7.x", - "required": false, - "value_in_examples": "PLAIN", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "description": "The SASL authentication mechanism.\n\nSupported options: `PLAIN` or `SCRAM-SHA-256`.\n" - }, - { - "name": "authentication.mechanism", - "minimum_version": "2.8.x", - "required": false, - "value_in_examples": "PLAIN", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "description": "The SASL authentication mechanism.\n\nSupported options: `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`.\n" - }, - { - "name": "authentication.user", - "minimum_version": "2.6.x", - "required": false, - "value_in_examples": "admin", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "Username for SASL authentication.\n" - }, - { - "name": "authentication.password", - "minimum_version": "2.6.x", - "required": false, - "value_in_examples": "admin-secret", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "Password for SASL authentication.\n" - }, - { - "name": "authentication.tokenauth", - "minimum_version": "2.6.x", - "required": false, - "value_in_examples": false, - "default": false, - "datatype": "boolean", - "description": "Enable this to indicate `DelegationToken` authentication\n" - }, - { - "name": "security.ssl", - "minimum_version": "2.6.x", - "required": false, - "value_in_examples": false, - "default": false, - "datatype": "boolean", - "description": "Enables TLS.\n" - }, - { - "name": "security.certificate_id", - "minimum_version": "2.6.x", - "required": false, - "urlencode_in_examples": true, - "value_in_examples": "nil", - "default": null, - "datatype": "string", - "description": "UUID of certificate entity for mTLS authentication.\n" - }, - { - "name": "timeout", - "required": false, - "default": "`10000`", - "value_in_examples": 10000, - "datatype": "integer", - "description": "Socket timeout in milliseconds.\n" - }, - { - "name": "keepalive", - "required": false, - "default": "`60000`", - "value_in_examples": 60000, - "datatype": "integer", - "description": "Keepalive timeout in milliseconds.\n" - }, - { - "name": "cluster_name", - "minimum_version": "2.8.x", - "required": false, - "default": "``", - "value_in_examples": null, - "datatype": "string", - "description": "An identifier for the Kafka cluster. By default, this field generates a\nrandom string. You can also set your own custom cluster identifier.\n\nIf more than one Kafka plugin is configured without a `cluster_name`\n(that is, if the default autogenerated value is removed),\nthese plugins will use the same producer, and by extension, the same\ncluster. Logs will be sent to the leader of the cluster.\n" - }, - { - "name": "producer_request_acks", - "required": false, - "default": "`1`", - "value_in_examples": -1, - "datatype": "integer", - "description": "The number of acknowledgments the producer requires the leader to have received before\nconsidering a request complete. Allowed values: 0 for no acknowledgments; 1 for only the\nleader; and -1 for the full ISR (In-Sync Replica set).\n" - }, - { - "name": "producer_request_timeout", - "required": false, - "default": "`2000`", - "value_in_examples": 2000, - "datatype": "integer", - "description": "Time to wait for a Produce response in milliseconds\n" - }, - { - "name": "producer_request_limits_messages_per_request", - "required": false, - "default": "`200`", - "value_in_examples": 200, - "datatype": "integer", - "description": "Maximum number of messages to include into a single Produce request.\n" - }, - { - "name": "producer_request_limits_bytes_per_request", - "required": false, - "default": "`1048576`", - "value_in_examples": 1048576, - "datatype": "integer", - "description": "Maximum size of a Produce request in bytes.\n" - }, - { - "name": "producer_request_retries_max_attempts", - "required": false, - "default": "`10`", - "value_in_examples": 10, - "datatype": "integer", - "description": "Maximum number of retry attempts per single Produce request.\n" - }, - { - "name": "producer_request_retries_backoff_timeout", - "required": false, - "default": "`100`", - "datatype": "integer", - "description": "Backoff interval between retry attempts in milliseconds.\n" - }, - { - "name": "producer_async", - "required": false, - "default": "`true`", - "datatype": "boolean", - "description": "Flag to enable asynchronous mode.\n" - }, - { - "name": "producer_async_flush_timeout", - "required": false, - "default": "`1000`", - "datatype": "integer", - "description": "Maximum time interval in milliseconds between buffer flushes in asynchronous mode.\n" - }, - { - "name": "producer_async_buffering_limits_messages_in_memory", - "required": false, - "default": "`50000`", - "datatype": "integer", - "description": "Maximum number of messages that can be buffered in memory in asynchronous mode.\n" - }, - { - "name": "api_version", - "maximum_version": "2.5.x", - "required": false, - "default": "`0`", - "value_in_examples": 0, - "datatype": "integer", - "description": "API version of a Produce request. Allowed values: `0`, `1`, or `2`.\n" - } - ], - "kafka-upstream": [ - { - "name": "bootstrap_servers", - "required": true, - "value_in_examples": { - "BOOTSTRAP_SERVERS": null - }, - "urlencode_in_examples": true, - "default": null, - "datatype": "set of record elements", - "description": "Set of bootstrap brokers in a `{host: host, port: port}` list format.\n" - }, - { - "name": "topic", - "required": true, - "value_in_examples": { - "TOPIC": null - }, - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "description": "The Kafka topic to publish to.\n" - }, - { - "name": "authentication.strategy", - "minimum_version": "2.6.x", - "required": false, - "value_in_examples": "sasl", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "description": "The authentication strategy for the plugin, the only option for the value is `sasl`.\n" - }, - { - "name": "authentication.mechanism", - "minimum_version": "2.6.x", - "maximum_version": "2.7.x", - "required": false, - "value_in_examples": "PLAIN", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "description": "The SASL authentication mechanism.\n\nSupported options: `PLAIN` or `SCRAM-SHA-256`.\n" - }, - { - "name": "authentication.mechanism", - "minimum_version": "2.8.x", - "required": false, - "value_in_examples": "PLAIN", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "description": "The SASL authentication mechanism.\n\nSupported options: `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`.\n" - }, - { - "name": "authentication.user", - "minimum_version": "2.6.x", - "required": false, - "value_in_examples": "admin", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "Username for SASL authentication.\n" - }, - { - "name": "authentication.password", - "minimum_version": "2.6.x", - "required": false, - "value_in_examples": "admin-secret", - "urlencode_in_examples": true, - "default": null, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "Password for SASL authentication.\n" - }, - { - "name": "authentication.tokenauth", - "minimum_version": "2.6.x", - "required": false, - "value_in_examples": false, - "default": false, - "datatype": "boolean", - "description": "Enable this to indicate `DelegationToken` authentication.\n" - }, - { - "name": "security.ssl", - "minimum_version": "2.6.x", - "required": false, - "value_in_examples": false, - "default": false, - "datatype": "boolean", - "description": "Enables TLS.\n" - }, - { - "name": "security.certificate_id", - "minimum_version": "2.6.x", - "required": false, - "urlencode_in_examples": true, - "value_in_examples": "nil", - "default": null, - "datatype": "string", - "description": "UUID of certificate entity for mTLS authentication.\n" - }, - { - "name": "timeout", - "required": false, - "default": "`10000`", - "value_in_examples": 10000, - "datatype": "integer", - "description": "Socket timeout in milliseconds.\n" - }, - { - "name": "keepalive", - "required": false, - "default": "`60000`", - "value_in_examples": 60000, - "datatype": "integer", - "description": "Keepalive timeout in milliseconds.\n" - }, - { - "name": "forward_method", - "required": "semi", - "default": "`false`", - "datatype": "boolean", - "description": "Include the request method in the message. At least one of these must be true:\n`forward_method`, `forward_uri`, `forward_headers`, `forward_body`.\n" - }, - { - "name": "forward_uri", - "required": "semi", - "default": "`false`", - "datatype": "boolean", - "description": "Include the request URI and URI arguments (as in, query arguments) in the message.\nAt least one of these must be true: `forward_method`, `forward_uri`, `forward_headers`,\n`forward_body`.\n" - }, - { - "name": "forward_headers", - "required": "semi", - "default": "`false`", - "datatype": "boolean", - "description": "Include the request headers in the message. At least one of these must be true:\n`forward_method`, `forward_uri`, `forward_headers`, `forward_body`.\n" - }, - { - "name": "forward_body", - "required": "semi", - "default": "`true`", - "datatype": "boolean", - "description": "Include the request body in the message. At least one of these must be true:\n`forward_method`, `forward_uri`, `forward_headers`, `forward_body`.\n" - }, - { - "name": "cluster_name", - "minimum_version": "2.8.x", - "required": false, - "default": "``", - "value_in_examples": null, - "datatype": "string", - "description": "An identifier for the Kafka cluster. By default, this field generates a\nrandom string. You can also set your own custom cluster identifier.\n\nIf more than one Kafka plugin is configured without a `cluster_name`\n(that is, if the default autogenerated value is removed),\nthese plugins will use the same producer, and by extension, the same\ncluster. Logs will be sent to the leader of the cluster.\n" - }, - { - "name": "producer_request_acks", - "required": false, - "default": "`1`", - "value_in_examples": -1, - "datatype": "integer", - "description": "The number of acknowledgments the producer requires the leader to have received before\nconsidering a request complete. Allowed values: 0 for no acknowledgments; 1 for only the\nleader; and -1 for the full ISR (In-Sync Replica set).\n" - }, - { - "name": "producer_request_timeout", - "required": false, - "default": "`2000`", - "value_in_examples": 2000, - "datatype": "integer", - "description": "Time to wait for a Produce response in milliseconds.\n" - }, - { - "name": "producer_request_limits_messages_per_request", - "required": false, - "default": "`200`", - "value_in_examples": 200, - "datatype": "integer", - "description": "Maximum number of messages to include into a single Produce request.\n" - }, - { - "name": "producer_request_limits_bytes_per_request", - "required": false, - "default": "`1048576`", - "value_in_examples": 1048576, - "datatype": "integer", - "description": "Maximum size of a Produce request in bytes.\n" - }, - { - "name": "producer_request_retries_max_attempts", - "required": false, - "default": "`10`", - "value_in_examples": 10, - "datatype": "integer", - "description": "Maximum number of retry attempts per single Produce request.\n" - }, - { - "name": "producer_request_retries_backoff_timeout", - "required": false, - "default": "`100`", - "datatype": "integer", - "description": "Backoff interval between retry attempts in milliseconds.\n" - }, - { - "name": "producer_async", - "required": false, - "default": "`true`", - "datatype": "boolean", - "description": "Flag to enable asynchronous mode.\n" - }, - { - "name": "producer_async_flush_timeout", - "required": false, - "default": "`1000`", - "datatype": "integer", - "description": "Maximum time interval in milliseconds between buffer flushes in asynchronous mode.\n" - }, - { - "name": "producer_async_buffering_limits_messages_in_memory", - "required": false, - "default": "`50000`", - "datatype": "integer", - "description": "Maximum number of messages that can be buffered in memory in asynchronous mode.\n" - } - ], - "key-auth-enc": [ - { - "name": "key_names", - "required": true, - "default": "`apikey`", - "value_in_examples": [ - "apikey" - ], - "datatype": "array of strings", - "description": "Describes an array of parameter names where the plugin will look for a key. The client must send the\nauthentication key in one of those key names, and the plugin will try to read the credential from a\nheader, request body, or query string parameter with the same name.\n\nKey names may only contain [a-z], [A-Z], [0-9], [_] underscore, and [-] hyphen.\n" - }, - { - "name": "key_in_body", - "required": false, - "default": "`false`", - "datatype": "boolean", - "description": "If enabled, the plugin reads the request body (if said request has one and its MIME type is supported) and tries to find the key in it. Supported MIME types: `application/www-form-urlencoded`, `application/json`, and `multipart/form-data`.\n" - }, - { - "name": "key_in_header", - "required": false, - "default": "`true`", - "datatype": "boolean", - "description": "If enabled (default), the plugin reads the request header and tries to find the key in it.\n" - }, - { - "name": "key_in_query", - "required": false, - "default": "`true`", - "datatype": "boolean", - "description": "If enabled (default), the plugin reads the query parameter in the request and tries to find the key in it.\n" - }, - { - "name": "hide_credentials", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "An optional boolean value telling the plugin to show or hide the credential from the upstream service. If `true`,\nthe plugin strips the credential from the request (i.e., the header, query string, or request body containing the key) before proxying it.\n" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request will fail with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails.\nIf empty (default), the request will fail with an authentication failure `4xx`. Note that this value\nmust refer to the consumer `id` attribute that is internal to Kong Gateway, and **not** its `custom_id`.\n", - "maximum_version": "3.0.x" - }, - { - "name": "run_on_preflight", - "required": false, - "default": "`true`", - "datatype": "boolean", - "description": "A boolean value that indicates whether the plugin should run (and try to authenticate) on `OPTIONS` preflight requests.\nIf set to `false`, then `OPTIONS` requests are always allowed.\n" - } - ], - "key-auth": [ - { - "name": "key_names", - "required": true, - "default": "[`apikey`]", - "value_in_examples": [ - "apikey" - ], - "datatype": "array of strings", - "description": "Describes an array of parameter names where the plugin will look for a key. The client must send the\nauthentication key in one of those key names, and the plugin will try to read the credential from a\nheader, request body, or query string parameter with the same name.\n
**Note**: The key names may only contain [a-z], [A-Z], [0-9], [_] underscore, and [-] hyphen.\n" - }, - { - "name": "key_in_body", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "If enabled, the plugin reads the request body (if said request has one and its MIME type is supported) and tries to find the key in it. Supported MIME types: `application/www-form-urlencoded`, `application/json`, and `multipart/form-data`.\n" - }, - { - "name": "key_in_header", - "minimum_version": "2.3.x", - "required": true, - "default": "`true`", - "datatype": "boolean", - "description": "If enabled (default), the plugin reads the request header and tries to find the key in it.\n" - }, - { - "name": "key_in_query", - "minimum_version": "2.3.x", - "required": true, - "default": "`true`", - "datatype": "boolean", - "description": "If enabled (default), the plugin reads the query parameter in the request and tries to find the key in it.\n" - }, - { - "name": "hide_credentials", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "An optional boolean value telling the plugin to show or hide the credential from the upstream service. If `true`,\nthe plugin strips the credential from the request (i.e., the header, query string, or request body containing the key) before proxying it.\n" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request will fail with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails.\nIf empty (default), the request will fail with an authentication failure `4xx`. Note that this value\nmust refer to the consumer `id` attribute that is internal to Kong Gateway, and **not** its `custom_id`.\nFor more information, see [Anonymous Access](/gateway/latest/kong-plugins/authentication/reference/#anonymous-access).\n", - "maximum_version": "3.0.x" - }, - { - "name": "run_on_preflight", - "required": true, - "default": "`true`", - "datatype": "boolean", - "description": "A boolean value that indicates whether the plugin should run (and try to authenticate) on `OPTIONS` preflight requests.\nIf set to `false`, then `OPTIONS` requests are always allowed.\n" - } - ], - "ldap-auth-advanced": [ - { - "name": "ldap_host", - "required": true, - "default": null, - "value_in_examples": "ldap.example.com", - "datatype": "string", - "description": "Host on which the LDAP server is running.\n" - }, - { - "name": "ldap_port", - "required": true, - "default": 389, - "value_in_examples": 389, - "datatype": "number", - "description": "TCP port where the LDAP server is listening. 389 is the default\nport for non-SSL LDAP and AD. 636 is the port required for SSL LDAP and AD. If `ldaps` is\nconfigured, you must use port 636.\n" - }, - { - "name": "ldap_password", - "required": null, - "default": null, - "value_in_examples": null, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "The password to the LDAP server.\n" - }, - { - "name": "start_tls", - "required": true, - "default": "`false`", - "value_in_examples": true, - "datatype": "boolean", - "description": "Set it to `true` to issue StartTLS (Transport Layer Security) extended operation\nover `ldap` connection. If the `start_tls` setting is enabled, ensure the `ldaps`\nsetting is disabled.\n" - }, - { - "name": "ldaps", - "required": true, - "default": "`false`", - "value_in_examples": null, - "datatype": "boolean", - "description": "Set it to `true` to use `ldaps`, a secure protocol (that can be configured\nto TLS) to connect to the LDAP server. When `ldaps` is\nconfigured, you must use port 636. If the `ldap` setting is enabled, ensure the\n`start_tls` setting is disabled.\n" - }, - { - "name": "base_dn", - "required": true, - "default": null, - "value_in_examples": "dc=example,dc=com", - "datatype": "string", - "description": "Base DN as the starting point for the search; e.g., \"dc=example,dc=com\".\n" - }, - { - "name": "verify_ldap_host", - "required": true, - "default": "`false`", - "value_in_examples": false, - "datatype": "boolean", - "description": "Set to `true` to authenticate LDAP server. The server certificate will be verified according to the CA certificates specified by the `lua_ssl_trusted_certificate` directive.\n" - }, - { - "name": "attribute", - "required": true, - "default": null, - "value_in_examples": "cn", - "datatype": "string", - "description": "Attribute to be used to search the user; e.g., \"cn\".\n" - }, - { - "name": "cache_ttl", - "required": true, - "default": "`60`", - "value_in_examples": 60, - "datatype": "number", - "description": "Cache expiry time in seconds.\n" - }, - { - "name": "timeout", - "required": false, - "default": "`10000`", - "value_in_examples": null, - "datatype": "number", - "description": "An optional timeout in milliseconds when waiting for connection with LDAP server.\n" - }, - { - "name": "keepalive", - "required": false, - "default": "`60000`", - "value_in_examples": null, - "datatype": "number", - "description": "An optional value in milliseconds that defines how long an idle connection to LDAP server will live before being closed.\n" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request will fail with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails.\nIf empty (default), the request will fail with an authentication failure `4xx`. Note that this value\nmust refer to the consumer `id` attribute that is internal to Kong Gateway, and **not** its `custom_id`.\n", - "maximum_version": "3.0.x" - }, - { - "name": "header_type", - "required": false, - "default": "`ldap`", - "value_in_examples": "ldap", - "datatype": "string", - "description": "An optional string to use as part of the Authorization header. By default, a valid Authorization header looks like this:\n`Authorization: ldap base64(username:password)`. If `header_type` is set to \"basic\", then the Authorization header would be\n`Authorization: basic base64(username:password)`. Note that `header_type` can take any string, not just `\"ldap\"` and `\"basic\"`.\n" - }, - { - "name": "consumer_optional", - "required": false, - "default": "`false`", - "value_in_examples": null, - "datatype": "boolean", - "description": "Whether consumer mapping is optional. If `consumer_optional=true`, the plugin will not attempt to associate a consumer with the\nLDAP authenticated user. If `consumer_optional=false`, LDAP authenticated users can still access upstream resources.\n\nTo prevent access from LDAP users that are not associated with consumers, set `consumer_optional=false`, set the `anonymous` field to an\nexisting `consumer_id`, then use the [Request Termination plugin](/hub/kong-inc/request-termination/) to deny any requests from the anonymous consumer.\n" - }, - { - "name": "consumer_by", - "required": false, - "default": "`[ \"username\", \"custom_id\" ]`", - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Whether to authenticate consumers based on `username`, `custom_id`, or both.\n" - }, - { - "name": "hide_credentials", - "required": true, - "default": "`false`", - "value_in_examples": null, - "datatype": "boolean", - "description": "An optional boolean value telling the plugin to hide the credential to the upstream server. It will be removed by Kong before proxying the request.\n" - }, - { - "name": "bind_dn", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "The DN to bind to. Used to perform LDAP search of user. This `bind_dn`\nshould have permissions to search for the user being authenticated.\n" - }, - { - "name": "group_base_dn", - "required": null, - "default": "matches `conf.base_dn`", - "value_in_examples": null, - "datatype": "string", - "description": "Sets a distinguished name (DN) for the entry where LDAP searches for groups begin. This field is case-insensitive.\n" - }, - { - "name": "group_name_attribute", - "required": null, - "default": "matches `conf.attribute`", - "value_in_examples": null, - "datatype": "string", - "description": "Sets the attribute holding the name of a group, typically\ncalled `name` (in Active Directory) or `cn` (in OpenLDAP). This\nfield is case-insensitive.\n" - }, - { - "name": "group_member_attribute", - "required": null, - "default": "`memberOf`", - "value_in_examples": null, - "datatype": "string", - "description": "Sets the attribute holding the members of the LDAP group. This field is case-sensitive.\n" - }, - { - "name": "log_search_results", - "required": false, - "default": "`false`", - "value_in_examples": null, - "datatype": "boolean", - "description": "Displays all the LDAP search results received from the LDAP\nserver for debugging purposes. Not recommended to be enabled in\na production environment.\n", - "minimum_version": "2.3.x" - }, - { - "name": "groups_required", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The groups required to be present in the LDAP search result for successful authorization. This config parameter works in both **AND** / **OR** cases.\n- When `[\"group1 group2\"]` are in the same array indices, both `group1` AND `group2` need to be present in the LDAP search result.\n- When `[\"group1\", \"group2\"]` are in different array indices, either `group1` OR `group2` need to be present in the LDAP search result.\n", - "minimum_version": "3.0.x" - } - ], - "ldap-auth": [ - { - "name": "hide_credentials", - "required": true, - "default": "`false`", - "value_in_examples": true, - "datatype": "boolean", - "description": "An optional boolean value telling the plugin to hide the credential to the upstream server. It will be removed by Kong before proxying the request." - }, - { - "name": "ldap_host", - "required": true, - "default": null, - "value_in_examples": "ldap.example.com", - "datatype": "string", - "description": "Host on which the LDAP server is running." - }, - { - "name": "ldap_port", - "minimum_version": "2.5.x", - "required": true, - "default": 389, - "value_in_examples": 389, - "datatype": "number", - "description": "TCP port where the LDAP server is listening. 389 is the default\nport for non-SSL LDAP and AD. 636 is the port required for SSL LDAP and AD. If `ldaps` is\nconfigured, you must use port 636.\n" - }, - { - "name": "start_tls", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Set it to `true` to issue StartTLS (Transport Layer Security) extended operation over `ldap`\nconnection. If the `start_tls` setting is enabled, ensure the `ldaps`\nsetting is disabled.\n" - }, - { - "name": "ldaps", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Set to `true` to connect using the LDAPS protocol (LDAP over TLS). When `ldaps` is\nconfigured, you must use port 636. If the `ldap` setting is enabled, ensure the\n`start_tls` setting is disabled.\n" - }, - { - "name": "base_dn", - "required": true, - "default": null, - "value_in_examples": "dc=example,dc=com", - "datatype": "string", - "description": "Base DN as the starting point for the search; e.g., \"dc=example,dc=com\"." - }, - { - "name": "verify_ldap_host", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Set to `true` to authenticate LDAP server. The server certificate will be verified according to the CA certificates specified by the `lua_ssl_trusted_certificate` directive.\n" - }, - { - "name": "attribute", - "required": true, - "default": null, - "value_in_examples": "cn", - "datatype": "string", - "description": "Attribute to be used to search the user; e.g., \"cn\"." - }, - { - "name": "cache_ttl", - "required": true, - "default": "`60`", - "datatype": "number", - "description": "Cache expiry time in seconds." - }, - { - "name": "timeout", - "required": false, - "default": "`10000`", - "datatype": "number", - "description": "An optional timeout in milliseconds when waiting for connection with LDAP server." - }, - { - "name": "keepalive", - "required": false, - "default": "`60000`", - "datatype": "number", - "description": "An optional value in milliseconds that defines how long an idle connection to LDAP server will live before being closed.\n" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request fails with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails.\nIf empty (default), the request fails with an authentication failure `4xx`. Note that this value\nmust refer to the consumer `id` attribute that is internal to Kong Gateway, and **not** its `custom_id`.\n", - "maximum_version": "3.0.x" - }, - { - "name": "header_type", - "required": false, - "default": "`ldap`", - "value_in_examples": "ldap", - "datatype": "string", - "description": "An optional string to use as part of the Authorization header. By default, a valid Authorization header looks like this: `Authorization: ldap base64(username:password)`. If `header_type` is set to \"basic\", then the Authorization header would be `Authorization: basic base64(username:password)`. Note that `header_type` can take any string, not just `\"ldap\"` and `\"basic\"`.\n" - } - ], - "loggly": [ - { - "name": "host", - "required": false, - "default": "`logs-01.loggly.com`", - "datatype": "string", - "description": "The IP address or hostname of Loggly server." - }, - { - "name": "port", - "required": false, - "default": "`514`", - "datatype": "integer", - "description": "The UDP port to send data to on the Loggly server." - }, - { - "name": "key", - "required": true, - "default": null, - "value_in_examples": "YOUR_LOGGLY_SERVICE_TOKEN", - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "Loggly [customer token](https://www.loggly.com/docs/customer-token-authentication-token/).\n" - }, - { - "name": "tags", - "required": false, - "default": "`kong`", - "datatype": "set of string elements", - "description": "An optional list of [tags](https://www.loggly.com/docs/tags/) to support segmentation and filtering of logs.\n" - }, - { - "name": "timeout", - "required": false, - "default": "`10000`", - "datatype": "number", - "description": "An optional timeout in milliseconds when sending data to the Loggly server." - }, - { - "name": "successful_severity", - "required": false, - "default": "`info`", - "datatype": "string", - "description": "An optional logging severity assigned to all the successful requests with a response\nstatus code 400. Available options: `debug`, `info`, `notice`, `warning`, `err`,\n`crit`, `alert`, `emerg`.\n" - }, - { - "name": "client_errors_severity", - "required": false, - "default": "`info`", - "datatype": "string", - "description": "An optional logging severity assigned to all the failed requests with a response\nstatus code 400 or higher but less than 500. Available options: `debug`, `info`,\n`notice`, `warning`, `err`, `crit`, `alert`, `emerg`.\n" - }, - { - "name": "server_errors_severity", - "required": false, - "default": "`info`", - "datatype": "string", - "description": "An optional logging severity assigned to all the failed requests with response status\ncode 500 or higher. Available options: `debug`, `info`, `notice`, `warning`, `err`,\n`crit`, `alert`, `emerg`.\n" - }, - { - "name": "log_level", - "required": false, - "default": "`info`", - "datatype": "string", - "description": "An optional logging severity, any request with equal or higher severity will be\nlogged to Loggly. Available options: `debug`, `info`, `notice`, `warning`, `err`,\n`crit`, `alert`, `emerg`.\n" - }, - { - "name": "custom_fields_by_lua", - "required": false, - "default": null, - "datatype": "map", - "description": "A list of key-value pairs, where the key is the name of a log field and\nthe value is a chunk of Lua code, whose return value sets or replaces\nthe log field value.\n" - } - ], - "mocking": [ - { - "name": "api_specification_filename", - "required": "semi", - "default": null, - "datatype": "string", - "value_in_examples": null, - "description": "The path and name of the specification file loaded into Kong Gateway's database. You cannot\nuse this option for DB-less or hybrid mode.\n" - }, - { - "name": "api_specification", - "required": "semi", - "default": null, - "datatype": "string", - "value_in_examples": "", - "description": "The contents of the specification file. You must use this option for hybrid or DB-less mode.\nWith this configuration option, you can include the full specification as part of the configuration,\ninstead of referring to a separate file with `api_specification_filename` that lives next to the Kong Gateway.\nIn Kong Manager, you can copy and paste the contents of the spec directly into\nthe `Config.Api Specification` text field.\n" - }, - { - "name": "random_delay", - "required": false, - "default": false, - "datatype": "boolean", - "value_in_examples": true, - "description": "Enables a random delay in the mocked response. Introduces delays to simulate\nreal-time response times by APIs.\n" - }, - { - "name": "max_delay_time", - "required": "semi", - "default": 1, - "datatype": "number", - "value_in_examples": 1, - "description": "The maximum value in seconds of delay time. Set this value when `random_delay` is enabled\nand you want to adjust the default. The value must be greater than the\n`min_delay_time`.\n" - }, - { - "name": "min_delay_time", - "required": "semi", - "default": 0.001, - "datatype": "number", - "value_in_examples": 0.001, - "description": "The minimum value in seconds of delay time. Set this value when `random_delay` is enabled\nand you want to adjust the default. The value must be less than the\n`max_delay_time`.\n" - }, - { - "name": "random_examples", - "required": false, - "default": false, - "datatype": "boolean", - "value_in_examples": true, - "description": "Randomly selects one example and returns it. This parameter requires the spec to have multiple examples configured.\n", - "minimum_version": "2.7.x" - }, - { - "name": "included_status_codes", - "required": false, - "default": null, - "datatype": "array of integers", - "description": "A global list of the HTTP status codes that can only be selected and returned.\n", - "minimum_version": "3.1.x" - }, - { - "name": "random_status_code", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Determines whether to randomly select an HTTP status code from the responses of the corresponding API method.\nThe default value is `false`, which means the minimum HTTP status code is always selected and returned.\n", - "minimum_version": "3.1.x" - } - ], - "mtls-auth": [ - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request fails with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an \"anonymous\" consumer if authentication fails.\nIf the request is left empty (which it is by default), it fails with an authentication failure of either\n`HTTP 495` if the client presented a certificate that is not acceptable, or `HTTP 496` if the client failed\nto present certificate as requested. Please note that this value must refer to the consumer `id`\nattribute, which is internal to Kong, and **not** its `custom_id`.\n", - "maximum_version": "3.0.x" - }, - { - "name": "consumer_by", - "required": false, - "default": "`[ \"username\", \"custom_id\" ]`", - "datatype": "array of string elements", - "description": "Whether to match the subject name of the client-supplied certificate against consumer's `username` and/or `custom_id` attribute. If set to `[]` (the empty array), then auto-matching is disabled.\n" - }, - { - "name": "ca_certificates", - "required": true, - "value_in_examples": [ - "fdac360e-7b19-4ade-a553-6dd22937c82f" - ], - "datatype": "array of string elements", - "description": "List of CA Certificates strings to use as Certificate Authorities (CA) when validating a client certificate.\nAt least one is required but you can specify as many as needed. The value of this array is comprised\nof primary keys (`id`).\n" - }, - { - "name": "skip_consumer_lookup", - "default": "`false`", - "required": true, - "datatype": "boolean", - "description": "Skip consumer lookup once certificate is trusted against the configured CA list.\n" - }, - { - "name": "authenticated_group_by", - "default": "`CN`", - "required": false, - "datatype": "string", - "description": "Certificate property to use as the authenticated group. Valid values are `CN` (Common Name) or\n`DN` (Distinguished Name). Once `skip_consumer_lookup` is applied, any client with a\nvalid certificate can access the Service/API. To restrict usage to only some of the authenticated users,\nalso add the ACL plugin (not covered here) and create allowed or denied groups of users.\n" - }, - { - "name": "revocation_check_mode", - "default": "`IGNORE_CA_ERROR`", - "required": false, - "datatype": "string", - "description": ">**Known Issue:** The default value `IGNORE_CA_ERROR` has a known issue in versions 1.5.0.0 and later.\nAs a workaround, manually set the value to `SKIP`.\n\nControls client certificate revocation check behavior. Valid values are `SKIP`, `IGNORE_CA_ERROR`, or `STRICT`.\nIf set to `SKIP`, no revocation check is performed. If set to `IGNORE_CA_ERROR`, the plugin respects\nthe revocation status when either OCSP or CRL URL is set, and doesn't fail on network issues. If set to `STRICT`,\nthe plugin only treats the certificate as valid when it's able to verify the revocation status, and a missing\nOCSP or CRL URL in the certificate or a failure to connect to the server results in a revoked status.\nIf both OCSP and CRL URL are set, the plugin always checks OCSP first, and only checks the CRL URL if\nit can't communicate with the OCSP server.\n" - }, - { - "name": "http_timeout", - "default": "30000", - "datatype": "number", - "description": "HTTP timeout threshold in milliseconds when communicating with the OCSP server or downloading CRL.\n" - }, - { - "name": "cert_cache_ttl", - "default": "60000", - "datatype": "number", - "description": "The length of time in milliseconds between refreshes of the revocation check status cache.\n" - }, - { - "name": "cache_ttl", - "default": "60", - "required": true, - "datatype": "number", - "description": "Cache expiry time in seconds.\n" - }, - { - "name": "http_proxy_host", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": "example", - "datatype": "string", - "description": "The HTTP hostname or IP address of a proxy. Use this setting with\n`http_proxy_port` to access a certificate revocation list\n(CRL) or an OCSP server.\n\nRequired if `http_proxy_port` is set.\n" - }, - { - "name": "http_proxy_port", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": 80, - "datatype": "string", - "description": "The TCP port of the HTTP proxy.\n\nRequired if `http_proxy_host` is set.\n" - }, - { - "name": "https_proxy_host", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "The HTTPS hostname or IP address of a proxy. Use this setting with\n`https_proxy_port` to access a certificate revocation list\n(CRL) or an OCSP server.\n\nRequired if `https_proxy_port` is set.\n" - }, - { - "name": "https_proxy_port", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "The TCP port of the HTTPS proxy.\n\nRequired if `https_proxy_host` is set.\n" - }, - { - "name": "send_ca_dn", - "minimum_version": "3.1.x", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "Sends the distinguished names (DN) of the configured CA list in the TLS handshake message.\n" - }, - { - "name": "allow_partial_chain", - "minimum_version": "3.1.x", - "required": true, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "Allow certificate verification with only an intermediate certificate.\nWhen this is enabled, you don't need to upload the full chain to Kong Certificates.\n" - } - ], - "oas-validation": [ - { - "name": "api_spec", - "required": true, - "datatype": "string", - "value_in_examples": "{your API specification}", - "description": "The API specification defined using either Swagger or the OpenAPI. This can be either a JSON or YAML based file. If using a YAML file, the spec needs to be URL encoded to preserve the YAML format.\n" - }, - { - "name": "validate_request_uri_params", - "required": false, - "datatype": "boolean", - "default": true, - "description": "If set to true, validates URI parameters in the request against the API specification.\n" - }, - { - "name": "validate_request_header_params", - "required": false, - "datatype": "boolean", - "default": true, - "description": "If set to true, validates HTTP header parameters against the API specification.\n" - }, - { - "name": "validate_request_query_params", - "required": false, - "datatype": "boolean", - "default": true, - "description": "If set to true, validates query parameters against the API specification.\n" - }, - { - "name": "validate_request_body", - "required": false, - "datatype": "boolean", - "default": true, - "description": "If set to true, validates the request body content against the API specification.\n" - }, - { - "name": "notify_only_request_validation_failure", - "required": false, - "datatype": "boolean", - "default": false, - "description": "If set to true, notifications via event hooks are enabled, but request based validation failures don't affect the request flow.\n" - }, - { - "name": "validate_response_body", - "required": false, - "datatype": "boolean", - "default": false, - "description": "If set to true, validates the response from the upstream services against the API specification. If validation fails, it results in an `HTTP 406 Not Acceptable` status code.\n" - }, - { - "name": "notify_only_response_body_validation_failure", - "required": false, - "datatype": "boolean", - "default": false, - "description": "If set to true, notifications via event hooks are enabled, but response validation failures don't affect the response flow.\n" - }, - { - "name": "header_parameter_check", - "required": true, - "datatype": "boolean", - "default": false, - "description": "If set to true, checks if HTTP header parameters in the request exist in the API specification.\n" - }, - { - "name": "query_parameter_check", - "required": true, - "datatype": "boolean", - "default": false, - "description": "If set to true, checks if query parameters in the request exist in the API specification.\n" - }, - { - "name": "allowed_header_parameters", - "required": false, - "datatype": "string", - "default": "`Host,Content-Type,User-Agent,Accept,Content-Length`", - "description": "List of header parameters in the request that will be ignored when performing HTTP header validation. These are additional headers added to an API request beyond those defined in the API specification.\n\nFor example, you might include the HTTP header `User-Agent`, which lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent.\n" - }, - { - "name": "verbose_response", - "required": false, - "datatype": "boolean", - "default": false, - "value_in_examples": true, - "description": "If set to true, returns a detailed error message for invalid requests & responses. This is useful while testing.\n" - } - ], - "oauth2-introspection": [ - { - "name": "introspection_url", - "required": true, - "default": null, - "value_in_examples": "https://example-url.com", - "datatype": "string", - "description": "The full URL to the third-party introspection endpoint.\n\nIf the introspection endpoint is `https`, [`lua_ssl_trusted_certificate`](/gateway/latest/reference/configuration/#lua_ssl_trusted_certificate)\nmust be set in `kong.conf` to ensure the plugin can connect\nto the endpoint. The CA bundle file location depends on your OS. See the\n[configuration reference](/gateway/latest/reference/configuration/#lua_ssl_trusted_certificate) for a list.\n\nStarting with Kong v2.2, users can set `lua_ssl_trusted_certificate=system`\nto automatically use the CA bundle from the OS.\n" - }, - { - "name": "authorization_value", - "required": true, - "default": null, - "value_in_examples": "Basic MG9hNWlpbjpPcGVuU2VzYW1l", - "datatype": "string", - "description": "The value to set as the `Authorization` header when querying the introspection endpoint. This depends on the OAuth 2.0 server, but usually is the `client_id` and `client_secret` as a Base64-encoded Basic Auth string (`Basic MG9hNWl...`).\n" - }, - { - "name": "token_type_hint", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "The `token_type_hint` value to associate to introspection requests.\n" - }, - { - "name": "ttl", - "required": false, - "default": 30, - "value_in_examples": null, - "datatype": "number", - "description": "The TTL in seconds for the introspection response. Set to 0 to disable the expiration.\n" - }, - { - "name": "hide_credentials", - "required": true, - "default": null, - "value_in_examples": null, - "datatype": "boolean", - "description": "An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request.\n" - }, - { - "name": "timeout", - "required": false, - "default": 10000, - "value_in_examples": null, - "datatype": "integer", - "description": "An optional timeout in milliseconds when sending data to the upstream server.\n" - }, - { - "name": "keepalive", - "required": false, - "default": 60000, - "value_in_examples": null, - "datatype": "integer", - "description": "An optional value in milliseconds that defines how long an idle connection lives before being closed.\n" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request fails with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails. If empty (default), the request fails with an authentication failure `4xx`.\n", - "maximum_version": "3.0.x" - }, - { - "name": "run_on_preflight", - "required": false, - "default": true, - "value_in_examples": null, - "datatype": "boolean", - "description": "A boolean value that indicates whether the plugin should run (and try to authenticate) on `OPTIONS` preflight requests. If set to `false`, then `OPTIONS` requests will always be allowed.\n" - }, - { - "name": "consumer_by", - "required": true, - "default": "CONSUMER_BY_DEFAULT", - "value_in_examples": "username", - "datatype": "string", - "description": "A string indicating whether to associate OAuth2 `username` or `client_id`\nwith the consumer's username. OAuth2 `username` is mapped to a consumer's\n`username` field, while an OAuth2 `client_id` maps to a consumer's\n`custom_id`.\n" - }, - { - "name": "introspect_request", - "required": true, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "A boolean indicating whether to forward information about the current\ndownstream request to the introspect endpoint. If true, headers\n`X-Request-Path` and `X-Request-Http-Method` will be inserted into the\nintrospect request.\n" - }, - { - "name": "custom_introspection_headers", - "required": true, - "default": null, - "value_in_examples": null, - "datatype": "map of string keys and string values", - "description": "A list of custom headers to be added in the introspection request.\n" - }, - { - "name": "custom_claims_forward", - "required": true, - "default": null, - "value_in_examples": null, - "datatype": "set of string elements", - "description": "A list of custom claims to be forwarded from the introspection response\nto the upstream request. Claims are forwarded in headers with prefix\n`X-Credential-{claim-name}`.\n" - } - ], - "oauth2": [ - { - "name": "scopes", - "required": "semi", - "default": null, - "value_in_examples": [ - "email", - "phone", - "address" - ], - "datatype": "array of string elements", - "description": "Describes an array of scope names that will be available to the end user. If `mandatory_scope` is\nset to `true`, then `scopes` are required.\n" - }, - { - "name": "mandatory_scope", - "required": true, - "default": "`false`", - "value_in_examples": true, - "datatype": "boolean", - "description": "An optional boolean value telling the plugin to require at least one `scope` to be authorized by the end user." - }, - { - "name": "provision_key", - "required": true, - "default": "`true`", - "value_in_examples": "", - "datatype": "string", - "encrypted": true, - "description": "The unique key the plugin has generated when it has been added to the Service.\n" - }, - { - "name": "token_expiration", - "required": true, - "default": "`7200`", - "datatype": "number", - "description": "An optional integer value telling the plugin how many seconds a token should last, after which the client will\nneed to refresh the token. Set to `0` to disable the expiration.\n" - }, - { - "name": "enable_authorization_code", - "required": true, - "default": "`false`", - "value_in_examples": true, - "datatype": "boolean", - "description": "An optional boolean value to enable the three-legged Authorization Code flow ([RFC 6742 Section 4.1](https://tools.ietf.org/html/rfc6749#section-4.1)).\n" - }, - { - "name": "enable_client_credentials", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "An optional boolean value to enable the Client Credentials Grant flow ([RFC 6742 Section 4.4](https://tools.ietf.org/html/rfc6749#section-4.4)).\n" - }, - { - "name": "enable_implicit_grant", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "An optional boolean value to enable the Implicit Grant flow which allows to provision a token as a result of the authorization process ([RFC 6742 Section 4.2](https://tools.ietf.org/html/rfc6749#section-4.2)).\n" - }, - { - "name": "enable_password_grant", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "An optional boolean value to enable the Resource Owner Password Credentials Grant flow ([RFC 6742 Section 4.3](https://tools.ietf.org/html/rfc6749#section-4.3)).\n" - }, - { - "name": "auth_header_name", - "required": false, - "default": "`authorization`", - "datatype": "string", - "description": "The name of the header that is supposed to carry the access token. Default: `authorization`.\n" - }, - { - "name": "hide_credentials", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "An optional boolean value telling the plugin to show or hide the credential from the upstream service.\nIf `true`, the plugin will strip the credential from the request (the header containing the client credentials)\nbefore proxying it.\n" - }, - { - "name": "accept_http_if_already_terminated", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Accepts HTTPs requests that have already been terminated by a proxy or load balancer and the\n`x-forwarded-proto: https` header has been added to the request. Only enable this option\nif the Kong server cannot be publicly accessed and the only entry point is such proxy or load balancer.\n" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request fails with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails.\nIf empty (default), the request fails with an authentication failure `4xx`. Note that this value\nmust refer to the consumer `id` attribute that is internal to Kong Gateway, and **not** its `custom_id`.\n", - "maximum_version": "3.0.x" - }, - { - "name": "global_credentials", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "An optional boolean value that allows using the same OAuth credentials generated by the plugin with\nany other Service whose OAuth 2.0 plugin configuration also has `config.global_credentials=true`.\n" - }, - { - "name": "refresh_token_ttl", - "required": true, - "default": "`1209600`", - "datatype": "number", - "description": "An optional integer value telling the plugin how many seconds a token/refresh token pair is valid for,\nand can be used to generate a new access token. Default value is 2 weeks. Set to `0` to keep the token/refresh\ntoken pair valid indefinitely.\n" - }, - { - "name": "reuse_refresh_token", - "required": true, - "default": false, - "datatype": "boolean", - "description": "An optional boolean value that indicates whether an OAuth refresh token is\nreused when refreshing an access token.\n" - }, - { - "name": "pkce", - "required": false, - "default": "`lax`", - "datatype": "string", - "description": "Specifies a mode of how the Proof Key for Code Exchange (PKCE) should be\nhandled by the plugin. The possible modes are `none`, `lax`, and `strict`.\nThe `strict` mode enforces PKCE on both authorization and token endpoints for\nall the clients. The `lax` mode enforces PKCE for public clients, but it does\nnot enforce it for confidential clients. The `none` mode does not enforce PKCE\non any client. In any case, if a client asks for PKCE on authorization\nendpoint, the PKCE is also enforced on token endpoint.\n" - } - ], - "opa": [ - { - "name": "opa_protocol", - "required": false, - "datatype": "string", - "default": "`http`", - "description": "The protocol to use when talking to Open Policy Agent (OPA) server. Allowed protocols are `http` and `https`.\n" - }, - { - "name": "opa_host", - "required": false, - "value_in_examples": "localhost", - "datatype": "string", - "default": "`localhost`", - "description": "The DNS name or IP address of the OPA server.\n" - }, - { - "name": "opa_port", - "required": false, - "value_in_examples": 8181, - "datatype": "integer", - "default": "`8181`", - "description": "The port of the OPA server.\n" - }, - { - "name": "opa_path", - "required": true, - "value_in_examples": "", - "datatype": "string", - "description": "The HTTP path to use when making a request to the OPA server. This is usually the path to the policy and rule to evaluate, prefixed with `/v1/data/`. For example,\nif you want to evaluate the `allow` rule inside `example.kong` package, then the path would be `/v1/data/example/kong/allowBoolean`.\n" - }, - { - "name": "include_service_in_opa_input", - "required": false, - "datatype": "boolean", - "default": false, - "description": "If set to true, the Kong Gateway Service object in use for the current request is included as input to OPA.\n" - }, - { - "name": "include_route_in_opa_input", - "required": false, - "datatype": "boolean", - "default": false, - "description": "If set to true, the Kong Gateway Route object in use for the current request is included as input to OPA.\n" - }, - { - "name": "include_consumer_in_opa_input", - "required": false, - "datatype": "boolean", - "default": false, - "description": "If set to true, the Kong Gateway Consumer object in use for the current request (if any) is included as input to OPA.\n" - }, - { - "name": "include_body_in_opa_input", - "required": false, - "datatype": "boolean", - "default": false, - "description": "If set to true, the current requests' request body is included as input to OPA.\n" - }, - { - "name": "include_parsed_json_body_in_opa_input", - "required": false, - "datatype": "boolean", - "default": false, - "description": "If set to true and the `Content-Type` header of the current request is `application/json`, the request body will be JSON decoded and the decoded struct is included as input to OPA.\n" - }, - { - "name": "include_uri_captures_in_opa_input", - "required": false, - "datatype": "boolean", - "default": false, - "minimum_version": "3.0.x", - "description": "If set to true, the [regex capture groups](https://docs.konghq.com/gateway/latest/reference/proxy/#using-regex-in-paths) captured on the Kong Gateway Route's path field in the current request (if any) are included as input to OPA.\n" - }, - { - "name": "ssl_verify", - "required": true, - "datatype": "boolean", - "default": true, - "description": "If set to true, the OPA certificate will be verified according to the CA certificates specified in [lua_ssl_trusted_certificate](/gateway/latest/reference/configuration/#lua_ssl_trusted_certificate).\n", - "minimum_version": "3.0.x" - } - ], - "openid-connect": [ - { - "group": "Authentication Grants", - "description": "Parameters for enabling only grants/credentials that you want to use." - }, - { - "name": "auth_methods", - "required": false, - "default": [ - "password", - "client_credentials", - "authorization_code", - "bearer", - "introspection", - "userinfo", - "kong_oauth2", - "refresh_token", - "session" - ], - "value_in_examples": [ - "authorization_code", - "session" - ], - "datatype": "array of string elements", - "description": "Types of credentials/grants to enable:\n- `password`: OAuth legacy password grant\n- `client_credentials`: OAuth client credentials grant\n- `authorization_code`: authorization code flow\n- `bearer`: JWT access token verification\n- `introspection`: OAuth introspection\n- `userinfo`: OpenID Connect user info endpoint authentication\n- `kong_oauth2`: Kong OAuth plugin issued tokens verification\n- `refresh_token`: OAuth refresh token grant\n- `session`: session cookie authentication\n" - }, - { - "group": "Anonymous Access", - "description": "Parameter for allowing anonymous access. This parameter is disabled by default." - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID or username) value that functions as an “anonymous” consumer if authentication fails. If empty (default null), requests that fail authentication will return a `4xx` HTTP status code. This value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails.\nIf empty (default), the request will fail with an authentication failure `4xx`. Note that this value\nmust refer to the consumer `id` attribute that is internal to Kong Gateway, and **not** its `custom_id`.\n", - "maximum_version": "3.0.x" - }, - { - "group": "General Settings", - "description": "Parameters for settings that affect different grants and flows." - }, - { - "name": "preserve_query_args", - "required": false, - "default": false, - "datatype": "boolean", - "description": "With this parameter, you can preserve request query arguments even when doing authorization code flow.\n> When this parameter is used with the `config.login_action=redirect` parameter, the browser location\n> will change and display the original query arguments. Otherwise, the upstream request\n> is modified to include the original query arguments, and the browser will not display\n> them in the location field.\n" - }, - { - "name": "refresh_tokens", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Specifies whether the plugin should try to refresh (soon to be) expired access tokens if the\nplugin has a `refresh_token` available.\n" - }, - { - "name": "hide_credentials", - "required": true, - "default": true, - "datatype": "boolean", - "description": "Remove the credentials used for authentication from the request.\n> If multiple credentials are sent with the same request, the plugin will\n> remove those that were used for successful authentication.\n" - }, - { - "name": "search_user_info", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Specify whether to use the user info endpoint to get additional claims for consumer mapping,\ncredential mapping, authenticated groups, and upstream and downstream headers.\n> This requires an extra round-trip and can add latency, but the plugin can also cache\n> user info requests (see: `config.cache_user_info`).\n" - }, - { - "group": "Discovery", - "description": "Parameters for auto-configuring most of the settings and providing the means for key rotation." - }, - { - "name": "issuer", - "required": true, - "default": null, - "value_in_examples": "", - "datatype": "url", - "description": "The discovery endpoint (or the issuer identifier).\n> When using Kong with the database, the discovery information and the JWKS\n> are cached to the Kong configuration database.\n" - }, - { - "name": "rediscovery_lifetime", - "required": false, - "default": 30, - "datatype": "integer", - "description": "Specifies how long (in seconds) the plugin waits between discovery attempts. Discovery is still triggered on an as-needed basis.\n> The re-discovery usually happens when the plugin cannot find a key for verifying\n> the signature. For example, if a token is presented for which Kong does not have a\n> JWK cached, it will poll the discovery endpoint for new JWK data. If that discovery\n> attempt does not yield a JWK that can validate the token, Kong will wait the specified\n> number of seconds before retrying the discovery.\n" - }, - { - "group": "Client" - }, - { - "name": "client_id", - "required": false, - "value_in_examples": [ - "" - ], - "default": null, - "datatype": "array of string elements (the plugin supports multiple clients)", - "encrypted": true, - "referenceable": true, - "description": "The client id(s) that the plugin uses when it calls authenticated endpoints on the identity provider.\nOther settings that are associated with the client are:\n- `config.client_secret`\n- `config.client_auth`\n- `config.client_jwk`\n- `config.client_alg`\n- `config.redirect_uri`\n- `config.login_redirect_uri`\n- `config.logout_redirect_uri`\n- `config.unauthorized_redirect_uri`\n- `config.forbidden_redirect_uri`\n- `config.unexpected_redirect_uri`\n\nUse the same array index when configuring related settings for the client.\n" - }, - { - "name": "client_arg", - "required": false, - "default": null, - "datatype": "string", - "description": "The client to use for this request (the selection is made with a request parameter with the same name).\nFor example, setting this value to `Client`, and sending the request header `Client: 1` will cause the plugin\nto use the first client (see: `config.client_id`) from the client array.\n" - }, - { - "group": "Client Authentication", - "description": "Parameters for configuring how the client should authenticate with the identity provider." - }, - { - "name": "client_auth", - "required": false, - "default": "(discovered or \"client_secret_basic\")", - "datatype": "array of string elements (one for each client)", - "description": "The authentication method used by the client (plugin) when calling the endpoints:\n- `client_secret_basic`: send `client_id` and `client_secret` in `Authorization: Basic` header\n- `client_secret_post`: send `client_id` and `client_secret` as part of the body\n- `client_secret_jwt`: send client assertion signed with the `client_secret` as part of the body\n- `private_key_jwt`: send client assertion signed with the `private key` as part of the body\n- `none`: do not authenticate\n\n\n> Private keys can be stored in a database, and they are by the default automatically generated\n> in the database. It is also possible to specify private keys with `config.client_jwk` directly\n> in the plugin configuration.\n" - }, - { - "name": "client_secret", - "required": false, - "value_in_examples": [ - "" - ], - "default": null, - "datatype": "array of string elements (one for each client)", - "encrypted": true, - "referenceable": true, - "description": "The client secret.\n> Specify one if using `client_secret_*` authentication with the client on\n> the identity provider endpoints.\n" - }, - { - "name": "client_jwk", - "required": false, - "default": "(plugin managed)", - "datatype": "array of JWK records (one for each client)", - "description": "The JWK used for the `private_key_jwt` authentication.\n" - }, - { - "name": "client_alg", - "required": false, - "default": "(client_secret_jwt: \"HS256\", private_key_jwt: \"RS256\")", - "datatype": "array of string elements (one for each client)", - "description": "The algorithm to use for `client_secret_jwt` (only `HS***`) or `private_key_jwt` authentication:\n- `HS256`: HMAC using SHA-256\n- `HS384`: HMAC using SHA-384\n- `HS512`: HMAC using SHA-512\n- `RS256`: RSASSA-PKCS1-v1_5 using SHA-256\n- `RS512`: RSASSA-PKCS1-v1_5 using SHA-512\n- `ES256`: ECDSA using P-256 and SHA-256\n- `ES384`: ECDSA using P-384 and SHA-384\n- `ES512`: ECDSA using P-521 and SHA-512\n- `PS256`: RSASSA-PSS using SHA-256 and MGF1 with SHA-256\n- `PS384`: RSASSA-PSS using SHA-384 and MGF1 with SHA-384\n- `PS512`: RSASSA-PSS using SHA-512 and MGF1 with SHA-512\n- `EdDSA`: EdDSA with Ed25519\n" - }, - { - "group": "JWT Access Token Authentication", - "description": "Parameters for specifying the location of the bearer token, and introspection options." - }, - { - "name": "bearer_token_param_type", - "required": false, - "default": [ - "header", - "query", - "body" - ], - "datatype": "array of string elements", - "description": "Where to look for the bearer token:\n- `header`: search the HTTP headers\n- `query`: search the URL's query string\n- `body`: search the HTTP request body\n- `cookie`: search the HTTP request cookies specified with `config.bearer_token_cookie_name`\n" - }, - { - "name": "bearer_token_cookie_name", - "required": false, - "default": null, - "datatype": "string", - "description": "The name of the cookie in which the bearer token is passed." - }, - { - "name": "introspect_jwt_tokens", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Specifies whether to introspect the JWT access tokens (can be used to check for revocations)." - }, - { - "group": "Client Credentials Grant", - "description": "Parameters specifying the location of client credentials." - }, - { - "name": "client_credentials_param_type", - "required": false, - "default": [ - "header", - "query", - "body" - ], - "datatype": "array of string elements", - "description": "Where to look for the client credentials:\n- `header`: search the HTTP headers\n- `query`: search the URL's query string\n- `body`: search from the HTTP request body\n" - }, - { - "group": "Password Grant", - "description": "Parameters for where to look for the username and password." - }, - { - "name": "password_param_type", - "required": false, - "default": [ - "header", - "query", - "body" - ], - "datatype": "array of string elements", - "description": "Where to look for the username and password:\n- `header`: search the HTTP headers\n- `query`: search the URL's query string\n- `body`: search the HTTP request body\n" - }, - { - "group": "Refresh Token Grant", - "description": "Parameters for where to look for the refresh token (rarely used as the refresh tokens are in many cases bound to the client)." - }, - { - "name": "refresh_token_param_type", - "required": false, - "default": [ - "header", - "query", - "body" - ], - "datatype": "array of string elements", - "description": "Where to look for the refresh token:\n- `header`: search the HTTP headers\n- `query`: search the URL's query string\n- `body`: search the HTTP request body\n" - }, - { - "name": "refresh_token_param_name", - "required": false, - "default": null, - "datatype": "string", - "description": "The name of the parameter used to pass the refresh token." - }, - { - "group": "ID Token", - "description": "Parameters for where to look for the id token (rarely sent as part of the request)." - }, - { - "name": "id_token_param_type", - "required": false, - "default": [ - "header", - "query", - "body" - ], - "datatype": "array of string elements", - "description": "Where to look for the id token:\n- `header`: search the HTTP headers\n- `query`: search the URL's query string\n- `body`: search the HTTP request body\n" - }, - { - "name": "id_token_param_name", - "required": false, - "default": null, - "datatype": "string", - "description": "The name of the parameter used to pass the id token." - }, - { - "group": "Consumer Mapping", - "description": "Parameters for mapping external identity provider managed identities to Kong managed ones." - }, - { - "name": "admin_claim", - "minimum_version": "2.7.x", - "required": false, - "default": null, - "datatype": "string", - "description": "The claim used for admin mapping for Kong Manager. Required if mapping IdP claims to Kong Manager admins." - }, - { - "name": "consumer_claim", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The claim used for consumer mapping." - }, - { - "name": "consumer_by", - "required": false, - "default": [ - "username", - "custom_id" - ], - "datatype": "array of string elements", - "description": "Consumer fields used for mapping:\n- `id`: try to find the matching Consumer by `id`\n- `username`: try to find the matching Consumer by `username`\n- `custom_id`: try to find the matching Consumer by `custom_id`\n" - }, - { - "name": "by_username_ignore_case", - "minimum_version": "2.6.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "If `consumer_by` is set to `username`, specify whether `username` can match consumers case-insensitively." - }, - { - "name": "consumer_optional", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Do not terminate the request if consumer mapping fails." - }, - { - "group": "Credential Mapping", - "description": "Parameters for mapping external identity provider managed identities to a Kong credential (virtual in this case)." - }, - { - "name": "credential_claim", - "required": false, - "default": [ - "sub" - ], - "datatype": "array of string elements", - "description": "The claim used to derive virtual credentials (e.g. to be consumed by the rate-limiting plugin), in case the consumer mapping is not used." - }, - { - "group": "Issuer Verification" - }, - { - "name": "issuers_allowed", - "minimum_version": "2.2.x", - "required": false, - "default": "(discovered issuer)", - "datatype": "array of string elements", - "description": "The issuers allowed to be present in the tokens (`iss` claim)." - }, - { - "group": "Authorization" - }, - { - "name": "authenticated_groups_claim", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The claim that contains authenticated groups. This setting can be used together\nwith ACL plugin, but it also enables IdP managed groups with other applications\nand integrations (for example, Kong Manager and Dev Portal). The OpenID Connect\nplugin itself does not do anything other than set the context value.\n" - }, - { - "name": "scopes_required", - "required": false, - "default": "(discovered issuer)", - "datatype": "array of string elements", - "description": "The scopes (`scopes_claim` claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both **AND** / **OR** cases.\n- When `[\"scope1 scope2\"]` are in the same array indices, both `scope1` AND `scope2` need to be present in access token (or introspection results).\n- When `[\"scope1\", \"scope2\"]` are in different array indices, either `scope1` OR `scope2` need to be present in access token (or introspection results).\n" - }, - { - "name": "scopes_claim", - "required": false, - "default": [ - "scope" - ], - "datatype": "array of string elements", - "description": "The claim that contains the scopes." - }, - { - "name": "audience_required", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The audiences (`audience_claim` claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both **AND** / **OR** cases.\n- When `[\"audience1 audience2\"]` are in the same array indices, both `audience1` AND `audience2` need to be present in access token (or introspection results).\n- When `[\"audience1\", \"audience2\"]` are in different array indices, either `audience1` OR `audience2` need to be present in access token (or introspection results).\n" - }, - { - "name": "audience_claim", - "required": false, - "default": [ - "aud" - ], - "datatype": "array of string elements", - "description": "The claim that contains the audience." - }, - { - "name": "groups_required", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The groups (`groups_claim` claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both **AND** / **OR** cases.\n- When `[\"group1 group2\"]` are in the same array indices, both `group1` AND `group2` need to be present in access token (or introspection results).\n- When `[\"group1\", \"group2\"]` are in different array indices, either `group1` OR `group2` need to be present in access token (or introspection results).\n" - }, - { - "name": "groups_claim", - "required": false, - "default": [ - "groups" - ], - "datatype": "array of string elements", - "description": "The claim that contains the groups." - }, - { - "name": "roles_required", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The roles (`roles_claim` claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both **AND** / **OR** cases.\n- When `[\"role1 role2\"]` are in the same array indices, both `role1` AND `role2` need to be present in access token (or introspection results).\n- When `[\"role1\", \"role2\"]` are in different array indices, either `role1` OR `role2` need to be present in access token (or introspection results).\n" - }, - { - "name": "roles_claim", - "required": false, - "default": [ - "roles" - ], - "datatype": "array of string elements", - "description": "The claim that contains the roles." - }, - { - "group": "Claims Verification", - "description": "Parameters for verification rules for standard claims." - }, - { - "name": "verify_claims", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Verify tokens for standard claims." - }, - { - "name": "leeway", - "required": false, - "default": 0, - "datatype": "integer", - "description": "Allow some leeway on the ttl / expiry verification." - }, - { - "name": "domains", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The allowed values for the `hd` claim." - }, - { - "name": "max_age", - "required": false, - "default": null, - "datatype": "integer", - "description": "The maximum age (in seconds) compared to the `auth_time` claim." - }, - { - "name": "jwt_session_claim", - "required": false, - "default": "\"sid\"", - "datatype": "string", - "description": "The claim to match against the JWT session cookie." - }, - { - "name": "jwt_session_cookie", - "required": false, - "default": null, - "datatype": "string", - "description": "The name of the JWT session cookie." - }, - { - "group": "Signature Verification" - }, - { - "name": "verify_signature", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Verify signature of tokens." - }, - { - "name": "enable_hs_signatures", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Enable shared secret, for example, HS256, signatures (when disabled they will not be accepted)." - }, - { - "name": "ignore_signature", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Skip the token signature verification on certain grants:\n- `password`: OAuth password grant\n- `client_credentials`: OAuth client credentials grant\n- `authorization_code`: authorization code flow\n- `refresh_token`: OAuth refresh token grant\n- `session`: session cookie authentication\n- `introspection`: OAuth introspection\n- `userinfo`: OpenID Connect user info endpoint authentication\n" - }, - { - "name": "extra_jwks_uris", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "JWKS URIs whose public keys are trusted (in addition to the keys found with the discovery)." - }, - { - "group": "Authorization Code Flow Verification" - }, - { - "name": "verify_nonce", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Verify nonce on authorization code flow." - }, - { - "group": "Introspection Verification" - }, - { - "name": "introspection_check_active", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Check that the introspection response has an `active` claim with a value of `true`." - }, - { - "group": "Configuration Verification" - }, - { - "name": "verify_parameters", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Verify plugin configuration against discovery." - }, - { - "group": "Upstream Headers", - "description": "Parameters for the headers for the upstream service request." - }, - { - "name": "upstream_headers_claims", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The upstream header claims." - }, - { - "name": "upstream_headers_names", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The upstream header names for the claim values." - }, - { - "name": "upstream_access_token_header", - "required": false, - "default": "authorization:bearer", - "datatype": "string", - "description": "The upstream access token header." - }, - { - "name": "upstream_access_token_jwk_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The upstream access token JWK header." - }, - { - "name": "upstream_id_token_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The upstream id token header." - }, - { - "name": "upstream_id_token_jwk_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The upstream id token JWK header." - }, - { - "name": "upstream_refresh_token_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The upstream refresh token header." - }, - { - "name": "upstream_user_info_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The upstream user info header." - }, - { - "name": "upstream_user_info_jwt_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The upstream user info JWT header (in case the user info returns a JWT response)." - }, - { - "name": "upstream_introspection_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The upstream introspection header." - }, - { - "name": "upstream_introspection_jwt_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The upstream introspection header (in case the introspection returns a JWT response)." - }, - { - "name": "upstream_session_id_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The upstream session id header." - }, - { - "group": "Downstream Headers", - "description": "Parameters for the headers for the downstream response." - }, - { - "name": "downstream_headers_claims", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The downstream header claims." - }, - { - "name": "downstream_headers_names", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The downstream header names for the claim values." - }, - { - "name": "downstream_access_token_header", - "required": false, - "default": "authorization:bearer", - "datatype": "string", - "description": "The downstream access token header." - }, - { - "name": "downstream_access_token_jwk_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The downstream access token JWK header." - }, - { - "name": "downstream_id_token_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The downstream id token header." - }, - { - "name": "downstream_id_token_jwk_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The downstream id token JWK header." - }, - { - "name": "downstream_refresh_token_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The downstream refresh token header." - }, - { - "name": "downstream_user_info_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The downstream user info header." - }, - { - "name": "downstream_user_info_jwt_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The downstream user info JWT header (in case the user info returns a JWT response)." - }, - { - "name": "downstream_introspection_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The downstream introspection header." - }, - { - "name": "downstream_introspection_jwt_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The downstream introspection header (in case the introspection returns a JWT response)." - }, - { - "name": "downstream_session_id_header", - "required": false, - "default": null, - "datatype": "string", - "description": "The downstream session id header." - }, - { - "group": "Cross-Origin Resource Sharing (CORS)" - }, - { - "name": "run_on_preflight", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Specifies whether to run this plugin on pre-flight (`OPTIONS`) requests." - }, - { - "group": "Login", - "description": "Parameters for what action the plugin completes after a successful login." - }, - { - "name": "login_methods", - "required": false, - "default": [ - "authorization_code" - ], - "datatype": "array of string elements", - "description": "Enable login functionality with specified grants:\n- `password`: enable for OAuth password grant\n- `client_credentials`: enable OAuth client credentials grant\n- `authorization_code`: enable for authorization code flow\n- `bearer`: enable for JWT access token authentication\n- `introspection`: enable for OAuth introspection authentication\n- `userinfo`: enable for OpenID Connect user info endpoint authentication\n- `kong_oauth2`: enable for Kong OAuth Plugin authentication\n- `refresh_token`: enable for OAuth refresh token grant\n- `session`: enable for session cookie authentication\n" - }, - { - "name": "login_action", - "required": false, - "default": "\"upstream\"", - "datatype": "string", - "description": "What to do after successful login:\n- `upstream`: proxy request to upstream service\n- `response`: terminate request with a response\n- `redirect`: redirect to a different location\n" - }, - { - "name": "login_tokens", - "required": false, - "default": [ - "id_token" - ], - "datatype": "array of string elements", - "description": "What tokens to include in `response` body or `redirect` query string or fragment:\n- `id_token`: include id token\n- `access_token`: include access token\n- `refresh_token`: include refresh token\n- `tokens`: include the full token endpoint response\n- `introspection`: include introspection response\n" - }, - { - "name": "login_redirect_mode", - "required": false, - "default": "\"fragment\"", - "datatype": "string", - "description": "Where to place `login_tokens` when using `redirect` `login_action`:\n- `query`: place tokens in query string\n- `fragment`: place tokens in url fragment (not readable by servers)\n" - }, - { - "name": "login_redirect_uri", - "required": false, - "default": null, - "datatype": "array of urls (one for each client)", - "description": "Where to redirect the client when `login_action` is set to `redirect`.\n> Tip: Leave this empty and the plugin will redirect the client to the URL that originally initiated the\n> flow with possible query args preserved from the original request when `config.preserve_query_args`\n> is enabled.\n" - }, - { - "group": "Logout", - "description": "Parameters for triggering logout with the plugin and the actions to take on logout." - }, - { - "name": "logout_query_arg", - "required": false, - "default": null, - "datatype": "string", - "description": "The request query argument that activates the logout." - }, - { - "name": "logout_post_arg", - "required": false, - "default": null, - "datatype": "string", - "description": "The request body argument that activates the logout." - }, - { - "name": "logout_uri_suffix", - "required": false, - "default": null, - "datatype": "string", - "description": "The request URI suffix that activates the logout." - }, - { - "name": "logout_methods", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The request methods that can activate the logout:\n- `POST`: HTTP POST method\n- `GET`: HTTP GET method\n- `DELETE`: HTTP DELETE method\n" - }, - { - "name": "logout_revoke", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Revoke tokens as part of the logout." - }, - { - "name": "logout_revoke_access_token", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Revoke the access token as part of the logout." - }, - { - "name": "logout_revoke_refresh_token", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Revoke the refresh token as part of the logout." - }, - { - "name": "logout_redirect_uri", - "required": false, - "default": null, - "datatype": "array of urls (one for each client)", - "description": "Where to redirect the client after the logout." - }, - { - "group": "Unauthorized", - "description": "Parameters for how to handle unauthorized requests." - }, - { - "name": "unauthorized_redirect_uri", - "required": false, - "default": null, - "datatype": "array of urls (one for each client)", - "description": "Where to redirect the client on unauthorized requests." - }, - { - "name": "unauthorized_error_message", - "required": false, - "default": "\"Forbidden\"", - "datatype": "string", - "description": "The error message for the unauthorized requests (when not using the redirection)." - }, - { - "group": "Forbidden", - "description": "Parameters for how to handle forbidden requests." - }, - { - "name": "forbidden_redirect_uri", - "required": false, - "default": null, - "datatype": "array of urls (one for each client)", - "description": "Where to redirect the client on forbidden requests." - }, - { - "name": "forbidden_error_message", - "required": false, - "default": "\"Forbidden\"", - "datatype": "string", - "description": "The error message for the forbidden requests (when not using the redirection)." - }, - { - "name": "forbidden_destroy_session", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Destroy any active session for the forbidden requests." - }, - { - "group": "Errors", - "description": "Parameters for how to handle unexpected errors." - }, - { - "name": "unexpected_redirect_uri", - "required": false, - "default": null, - "datatype": "array of urls (one for each client)", - "description": "Where to redirect the client when unexpected errors happen with the requests." - }, - { - "name": "display_errors", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Display errors on failure responses." - }, - { - "group": "Authorization Cookie", - "description": "Parameters used during authorization code flow for verification and preserving settings." - }, - { - "name": "authorization_cookie_name", - "required": false, - "default": "\"authorization\"", - "datatype": "string", - "description": "The authorization cookie name." - }, - { - "name": "authorization_cookie_lifetime", - "maximum_version": "3.1.x", - "required": false, - "default": 600, - "datatype": "integer", - "description": "The authorization cookie lifetime in seconds." - }, - { - "name": "authorization_rolling_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 600, - "datatype": "integer", - "description": "The authorization cookie rolling timeout in seconds.\nSpecifies how long the authorization cookie can be used until it needs to be renewed.\n" - }, - { - "name": "authorization_cookie_path", - "required": false, - "default": "\"/\"", - "datatype": "string", - "description": "The authorization cookie Path flag." - }, - { - "name": "authorization_cookie_domain", - "required": false, - "default": null, - "datatype": "string", - "description": "The authorization cookie Domain flag." - }, - { - "name": "authorization_cookie_samesite", - "maximum_version": "3.1.x", - "required": false, - "default": "\"off\"", - "datatype": "string", - "description": "Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks:\n- `Strict`: Cookies will only be sent in a first-party context and not be sent along with requests initiated by third party websites.\n- `Lax`: Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating to the origin site (for instance, when following a link).\n- `None`: Cookies will be sent in all contexts, for example in 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).\n- `off`: Do not set the SameSite flag.\n" - }, - { - "name": "authorization_cookie_same_site", - "minimum_version": "3.2.x", - "required": false, - "default": "\"Default\"", - "datatype": "string", - "description": "Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks:\n- `Strict`: Cookies will only be sent in a first-party context and not be sent along with requests initiated by third party websites.\n- `Lax`: Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating to the origin site (for instance, when following a link).\n- `None`: Cookies will be sent in all contexts, for example in 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).\n- `Default`: Do not explicitly specify a SameSite attribute.\n" - }, - { - "name": "authorization_cookie_httponly", - "maximum_version": "3.1.x", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Forbids JavaScript from accessing the cookie, for example, through the `Document.cookie` property.\n" - }, - { - "name": "authorization_cookie_http_only", - "minimum_version": "3.2.x", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Forbids JavaScript from accessing the cookie, for example, through the `Document.cookie` property." - }, - { - "name": "authorization_cookie_secure", - "required": false, - "default": "(from the request scheme)", - "datatype": "boolean", - "description": "Cookie is only sent to the server when a request is made with the https: scheme (except on localhost),\nand therefore is more resistant to man-in-the-middle attacks.\n" - }, - { - "group": "Session Cookie", - "description": "Parameters used with the session cookie authentication." - }, - { - "name": "session_cookie_name", - "required": false, - "default": "\"session\"", - "datatype": "string", - "description": "The session cookie name." - }, - { - "name": "session_cookie_lifetime", - "maximum_version": "3.1.x", - "required": false, - "default": 3600, - "datatype": "integer", - "description": "The session cookie lifetime in seconds." - }, - { - "name": "session_rolling_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 3600, - "datatype": "integer", - "description": "The session cookie rolling timeout in seconds.\nSpecifies how long the session can be used until it needs to be renewed.\n" - }, - { - "name": "session_absolute_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 86400, - "datatype": "integer", - "description": "The session cookie absolute timeout in seconds.\nSpecifies how long the session can be used until it is no longer valid.\n" - }, - { - "name": "session_cookie_idletime", - "maximum_version": "3.1.x", - "required": false, - "default": null, - "datatype": "integer", - "description": "The session cookie idle time in seconds." - }, - { - "name": "session_idling_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 900, - "datatype": "integer", - "description": "The session cookie idle time in seconds." - }, - { - "name": "session_cookie_renew", - "maximum_version": "3.1.x", - "required": false, - "default": 600, - "datatype": "integer", - "description": "The number of seconds prior to the `session_cookie_lifetime` that the session cookie will be renewed." - }, - { - "name": "session_cookie_path", - "required": false, - "default": "\"/\"", - "datatype": "string", - "description": "The session cookie Path flag." - }, - { - "name": "session_cookie_domain", - "required": false, - "default": null, - "datatype": "string", - "description": "The session cookie Domain flag." - }, - { - "name": "session_cookie_samesite", - "maximum_version": "3.1.x", - "required": false, - "default": "\"Lax\"", - "datatype": "string", - "description": "Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks:\n- `Strict`: Cookies will only be sent in a first-party context and not be sent along with requests initiated by third party websites.\n- `Lax`: Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating to the origin site (for example, when following a link).\n- `None`: Cookies will be sent in all contexts, for example in 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)\n- `off`: Do not set the SameSite flag.\n" - }, - { - "name": "session_cookie_same_site", - "minimum_version": "3.2.x", - "required": false, - "default": "\"Lax\"", - "datatype": "string", - "description": "Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks:\n- `Strict`: Cookies will only be sent in a first-party context and aren't sent along with requests initiated by third party websites.\n- `Lax`: Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating to the origin site (for example, when following a link).\n- `None`: Cookies will be sent in all contexts, for example in 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.\n- `Default`: Do not explicitly specify a `SameSite` attribute.\n" - }, - { - "name": "session_cookie_httponly", - "maximum_version": "3.1.x", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Forbids JavaScript from accessing the cookie, for example, through the `Document.cookie` property.\n" - }, - { - "name": "session_cookie_http_only", - "minimum_version": "3.2.x", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Forbids JavaScript from accessing the cookie, for example, through the `Document.cookie` property." - }, - { - "name": "session_cookie_secure", - "required": false, - "default": "(from the request scheme)", - "datatype": "boolean", - "description": "Cookie is only sent to the server when a request is made with the https: scheme (except on localhost),\nand therefore is more resistant to man-in-the-middle attacks.\n" - }, - { - "name": "session_cookie_maxsize", - "maximum_version": "3.1.x", - "required": false, - "default": 4000, - "datatype": "integer", - "description": "The maximum size of each cookie chunk in bytes." - }, - { - "group": "Session Settings" - }, - { - "name": "session_secret", - "required": false, - "default": "(with database, or traditional mode, the value is auto-generated and stored along the issuer discovery information in the database)", - "datatype": "string", - "encrypted": true, - "value_in_examples": "", - "referenceable": true, - "description": "The session secret.\n" - }, - { - "name": "disable_session", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Disable issuing the session cookie with the specified grants:\n- `password`: do not start a session with the password grant\n- `client_credentials`: do not start a session with the client credentials grant\n- `authorization_code`: do not start a session after authorization code flow\n- `bearer`: do not start session with JWT access token authentication\n- `introspection`: do not start session with introspection authentication\n- `userinfo`: do not start session with user info authentication\n- `kong_oauth2`: do not start session with Kong OAuth authentication\n- `refresh_token` do not start session with refresh token grant\n- `session`: do not renew the session with session cookie authentication\n" - }, - { - "name": "session_strategy", - "maximum_version": "3.1.x", - "required": false, - "default": "\"default\"", - "datatype": "string", - "description": "The session strategy:\n- `default`: reuses session identifiers over modifications (but can be problematic with single-page applications with a lot of concurrent asynchronous requests)\n- `regenerate`: generates a new session identifier on each modification and does not use expiry for signature verification (useful in single-page applications or SPAs)\n" - }, - { - "name": "session_compressor", - "maximum_version": "3.1.x", - "required": false, - "default": "\"none\"", - "datatype": "string", - "description": "The session strategy:\n- `none`: no compression\n- `zlib`: use zlib to compress cookie data\n" - }, - { - "name": "session_audience", - "minimum_version": "3.2.x", - "required": false, - "default": "\"default\"", - "datatype": "string", - "description": "The session audience, which is the intended target application. For example `\"my-application\"`." - }, - { - "name": "session_remember", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Enables or disables persistent sessions." - }, - { - "name": "session_remember_cookie_name", - "minimum_version": "3.2.x", - "required": false, - "default": "\"remember\"", - "datatype": "string", - "description": "Persistent session cookie name. Use with the `remember` configuration parameter." - }, - { - "name": "session_remember_rolling_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 604800, - "datatype": "integer", - "description": "The persistent session rolling timeout window, in seconds." - }, - { - "name": "session_remember_absolute_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 2592000, - "datatype": "integer", - "description": "The persistent session absolute timeout limit, in seconds." - }, - { - "name": "session_request_headers", - "minimum_version": "3.2.x", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "List of information to include, as headers, in the request to the upstream. \nAccepted values are: `id`, `audience`, `subject`, `timeout`, `idling-timeout`, `rolling-timeout`, and\n`absolute-timeout`.\nFor example, `{ \"id\", \"timeout\" }` sets both `Session-Id` and `Session-Timeout` in the request headers.\n" - }, - { - "name": "session_response_headers", - "minimum_version": "3.2.x", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "List of information to include, as headers, in the response to the downstream. \nAccepted values are: `id`, `audience`, `subject`, `timeout`, `idling-timeout`, `rolling-timeout`, and\n`absolute-timeout`.\nFor example: `{ \"id\", \"timeout\" }` injects both `Session-Id` and `Session-Timeout` in the response headers.\n" - }, - { - "name": "session_store_metadata", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Configures whether or not session metadata should be stored.\nThis metadata includes information about the active sessions for a specific audience\nbelonging to a specific subject.\n" - }, - { - "name": "session_enforce_same_subject", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "When set to `true`, audiences are forced to share the same subject." - }, - { - "name": "session_hash_subject", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "When set to `true`, the value of subject is hashed before being stored.\nOnly applies when `session_store_metadata` is enabled.\n" - }, - { - "name": "session_hash_storage_key", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "When set to `true`, the storage key (session ID) is hashed for extra security.\nHashing the storage key means it is impossible to decrypt data from the storage\nwithout a cookie.\n" - }, - { - "name": "session_storage", - "required": false, - "default": "\"cookie\"", - "datatype": "string", - "description": "The session storage for session data:\n- `cookie`: stores session data with the session cookie (the session cannot be invalidated or revoked without changing session secret, but is stateless, and doesn't require a database)\n- `memcache`: stores session data in memcached\n- `redis`: stores session data in Redis\n" - }, - { - "name": "reverify", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Specifies whether to always verify tokens stored in the session." - }, - { - "group": "Session Settings for Memcached" - }, - { - "name": "session_memcache_prefix", - "maximum_version": "3.1.x", - "required": false, - "default": "\"sessions\"", - "datatype": "string", - "description": "The memcached session key prefix." - }, - { - "name": "session_memcached_prefix", - "minimum_version": "3.2.x", - "required": false, - "default": "\"sessions\"", - "datatype": "string", - "description": "The memcached session key prefix." - }, - { - "name": "session_memcache_socket", - "maximum_version": "3.1.x", - "required": false, - "default": null, - "datatype": "string", - "description": "The memcached unix socket path." - }, - { - "name": "session_memcached_socket", - "minimum_version": "3.2.x", - "required": false, - "default": null, - "datatype": "string", - "description": "The memcached unix socket path." - }, - { - "name": "session_memcache_host", - "maximum_version": "3.1.x", - "required": false, - "default": "\"127.0.0.1\"", - "datatype": "string", - "description": "The memcached host." - }, - { - "name": "session_memcached_host", - "minimum_version": "3.2.x", - "required": false, - "default": "\"127.0.0.1\"", - "datatype": "string", - "description": "The memcached host." - }, - { - "name": "session_memcache_port", - "maximum_version": "3.1.x", - "required": false, - "default": 11211, - "datatype": "integer", - "description": "The memcached port." - }, - { - "name": "session_memcached_port", - "minimum_version": "3.2.x", - "required": false, - "default": 11211, - "datatype": "integer", - "description": "The memcached port." - }, - { - "group": "Session Settings for Redis" - }, - { - "name": "session_redis_prefix", - "required": false, - "default": "\"sessions\"", - "datatype": "string", - "description": "The Redis session key prefix." - }, - { - "name": "session_redis_socket", - "required": false, - "default": null, - "datatype": "string", - "description": "The Redis unix socket path." - }, - { - "name": "session_redis_host", - "required": false, - "default": "\"127.0.0.1\"", - "datatype": "string", - "description": "The Redis host" - }, - { - "name": "session_redis_port", - "required": false, - "default": 6379, - "datatype": "integer", - "description": "The Redis port." - }, - { - "name": "session_redis_username", - "minimum_version": "2.8.x", - "required": false, - "default": null, - "datatype": "string", - "referenceable": true, - "description": "Username to use for Redis connection when the `redis` session storage is defined and ACL authentication is desired.\nIf undefined, ACL authentication will not be performed.\n\nThis requires Redis v6.0.0+. The username **cannot** be set to `default`.\n" - }, - { - "name": "session_redis_password", - "minimum_version": "2.8.x", - "required": false, - "default": "(from kong)", - "encrypted": true, - "datatype": "string", - "referenceable": true, - "description": "Password to use for Redis connection when the `redis` session storage is defined.\nIf undefined, no AUTH commands are sent to Redis.\n" - }, - { - "name": "session_redis_auth", - "maximum_version": "2.8.x", - "required": false, - "default": "(from kong)", - "encrypted": true, - "datatype": "string", - "description": "Password to use for Redis connection when the `redis` session storage is defined.\nIf undefined, no AUTH commands are sent to Redis.\n\n{:.important}\n> In Kong Gateway 2.8.x, this field is deprecated and replaced with `session_redis_password`.\n> The`session_redis_auth` field will continue to work in a backwards compatible way,\n> but it is recommended to use the replacement field.\n>\n> Starting from Kong Gateway 3.0.0.0, this field has been removed.\n" - }, - { - "name": "session_redis_connect_timeout", - "required": false, - "default": "(from kong)", - "datatype": "integer", - "description": "The Redis connection timeout in milliseconds." - }, - { - "name": "session_redis_read_timeout", - "required": false, - "default": "(from kong)", - "datatype": "integer", - "description": "The Redis read timeout in milliseconds." - }, - { - "name": "session_redis_send_timeout", - "required": false, - "default": "(from kong)", - "datatype": "integer", - "description": "The Redis send timeout in milliseconds." - }, - { - "name": "session_redis_ssl", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Use SSL/TLS for Redis connection." - }, - { - "name": "session_redis_ssl_verify", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Verify Redis server certificate." - }, - { - "name": "session_redis_server_name", - "required": false, - "default": null, - "datatype": "string", - "description": "The SNI used for connecting the Redis server." - }, - { - "name": "session_redis_cluster_nodes", - "maximum_version": "2.5.x", - "required": false, - "default": null, - "datatype": "array of host records", - "description": "The Redis cluster node host. Takes an array of host records, with\n`ip` and `port` values.\n" - }, - { - "name": "session_redis_cluster_nodes", - "minimum_version": "2.6.x", - "required": false, - "default": null, - "datatype": "array of host records", - "description": "The Redis cluster node host. Takes an array of host records, with\neither `ip` or `host`, and `port` values.\n" - }, - { - "name": "session_redis_cluster_maxredirections", - "maximum_version": "3.1.x", - "required": false, - "default": null, - "datatype": "integer", - "description": "The Redis cluster maximum redirects." - }, - { - "name": "session_redis_cluster_max_redirections", - "minimum_version": "3.2.x", - "required": false, - "default": null, - "datatype": "integer", - "description": "The Redis cluster maximum redirects." - }, - { - "group": "Endpoints", - "description": "Parameters normally not needed as the endpoints are discovered." - }, - { - "name": "authorization_endpoint", - "required": false, - "default": "(discovered uri)", - "datatype": "url", - "description": "The authorization endpoint." - }, - { - "name": "token_endpoint", - "required": false, - "default": "(discovered uri)", - "datatype": "url", - "description": "The token endpoint." - }, - { - "name": "introspection_endpoint", - "required": false, - "default": "(discovered uri)", - "datatype": "url", - "description": "The introspection endpoint." - }, - { - "name": "revocation_endpoint", - "required": false, - "default": "(discovered uri)", - "datatype": "url", - "description": "The revocation endpoint." - }, - { - "name": "userinfo_endpoint", - "minimum_version": "2.2.x", - "required": false, - "default": "(discovered uri)", - "datatype": "url", - "description": "The user info endpoint." - }, - { - "name": "end_session_endpoint", - "required": false, - "default": "(discovered uri)", - "datatype": "url", - "description": "The end session endpoint." - }, - { - "name": "token_exchange_endpoint", - "required": false, - "default": "(discovered uri)", - "datatype": "url", - "description": "The token exchange endpoint." - }, - { - "group": "Endpoint Authentication", - "description": "Parameters normally not needed as the client authentication can be specified for the client." - }, - { - "name": "token_endpoint_auth_method", - "required": false, - "default": "(see: config.client_auth)", - "datatype": "string", - "description": "The token endpoint authentication method:\n- `client_secret_basic`: send `client_id` and `client_secret` in `Authorization: Basic` header\n- `client_secret_post`: send `client_id` and `client_secret` as part of the body\n- `client_secret_jwt`: send client assertion signed with the `client_secret` as part of the body\n- `private_key_jwt`: send client assertion signed with the `private key` as part of the body\n- `none`: do not authenticate\n" - }, - { - "name": "introspection_endpoint_auth_method", - "required": false, - "default": "(see: config.client_auth)", - "datatype": "string", - "description": "The introspection endpoint authentication method:\n- `client_secret_basic`: send `client_id` and `client_secret` in `Authorization: Basic` header\n- `client_secret_post`: send `client_id` and `client_secret` as part of the body\n- `client_secret_jwt`: send client assertion signed with the `client_secret` as part of the body\n- `private_key_jwt`: send client assertion signed with the `private key` as part of the body\n- `none`: do not authenticate\n" - }, - { - "name": "revocation_endpoint_auth_method", - "required": false, - "default": "(see: config.client_auth)", - "datatype": "string", - "description": "The revocation endpoint authentication method:\n- `client_secret_basic`: send `client_id` and `client_secret` in `Authorization: Basic` header\n- `client_secret_post`: send `client_id` and `client_secret` as part of the body\n- `client_secret_jwt`: send client assertion signed with the `client_secret` as part of the body\n- `private_key_jwt`: send client assertion signed with the `private key` as part of the body\n- `none`: do not authenticate\n" - }, - { - "group": "Discovery Endpoint Arguments" - }, - { - "name": "discovery_headers_names", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra header names passed to the discovery endpoint." - }, - { - "name": "discovery_headers_values", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra header values passed to the discovery endpoint." - }, - { - "group": "Authorization Endpoint Arguments" - }, - { - "name": "response_mode", - "required": false, - "default": "\"query\"", - "datatype": "string", - "value_in_examples": "form_post", - "description": "The response mode passed to the authorization endpoint:\n- `query`: Instructs the identity provider to pass parameters in query string\n- `form_post`: Instructs the identity provider to pass parameters in request body\n- `fragment`: Instructs the identity provider to pass parameters in uri fragment (rarely useful as the plugin itself cannot read it)\n" - }, - { - "name": "response_type", - "required": false, - "default": [ - "code" - ], - "datatype": "array of string elements", - "description": "The response type passed to the authorization endpoint." - }, - { - "name": "scopes", - "required": false, - "default": [ - "openid" - ], - "datatype": "array of string elements", - "description": "The scopes passed to the authorization and token endpoints." - }, - { - "name": "audience", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "The audience passed to the authorization endpoint." - }, - { - "name": "redirect_uri", - "required": false, - "default": "(request uri)", - "datatype": "array of urls (one for each client)", - "description": "The redirect URI passed to the authorization and token endpoints." - }, - { - "name": "authorization_query_args_names", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra query argument names passed to the authorization endpoint." - }, - { - "name": "authorization_query_args_values", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra query argument values passed to the authorization endpoint." - }, - { - "name": "authorization_query_args_client", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra query arguments passed from the client to the authorization endpoint." - }, - { - "group": "Token Endpoint Arguments" - }, - { - "name": "token_headers_names", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra header names passed to the token endpoint." - }, - { - "name": "token_headers_values", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra header values passed to the token endpoint." - }, - { - "name": "token_headers_client", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra headers passed from the client to the token endpoint." - }, - { - "name": "token_post_args_names", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra post argument names passed to the token endpoint." - }, - { - "name": "token_post_args_values", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra post argument values passed to the token endpoint." - }, - { - "name": "token_post_args_client", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Pass extra arguments from the client to the OpenID-Connect plugin. If arguments exist, the client can pass them using:\n- Request Body\n- Query parameters\n\nThis parameter can be used with `scope` values, like this:\n\n`config.token_post_args_client=scope`\n\nIn this case, the token would take the `scope` value from the query parameter or from the request body and send it to the token endpoint.\n" - }, - { - "group": "Token Endpoint Response Headers", - "description": "Parameters for an uncommon use case of sending certain token endpoint headers to the downstream client." - }, - { - "name": "token_headers_replay", - "default": null, - "datatype": "array of string elements", - "description": "The names of token endpoint response headers to forward to the downstream client." - }, - { - "name": "token_headers_prefix", - "default": null, - "datatype": "string", - "description": "Add a prefix to the token endpoint response headers before forwarding them to the downstream client." - }, - { - "name": "token_headers_grants", - "default": null, - "datatype": "array of string elements", - "description": "Enable the sending of the token endpoint response headers only with certain grants:\n- `password`: with OAuth password grant\n- `client_credentials`: with OAuth client credentials grant\n- `authorization_code`: with authorization code flow\n- `refresh_token` with refresh token grant\n" - }, - { - "group": "Introspection Endpoint Arguments" - }, - { - "name": "introspection_hint", - "required": false, - "default": "\"access_token\"", - "datatype": "string", - "description": "Introspection hint parameter value passed to the introspection endpoint." - }, - { - "name": "introspection_accept", - "required": false, - "default": "\"application/json\"", - "datatype": "string", - "description": "The value of `Accept` header for introspection requests:\n- `application/json`: introspection response as JSON\n- `application/token-introspection+jwt`: introspection response as JWT (from the current IETF draft document)\n- `application/jwt`: introspection response as JWT (from the obsolete IETF draft document)\n" - }, - { - "name": "introspection_headers_names", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra header names passed to the introspection endpoint." - }, - { - "name": "introspection_headers_values", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra header values passed to the introspection endpoint." - }, - { - "name": "introspection_headers_client", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra headers passed from the client to the introspection endpoint." - }, - { - "name": "introspection_post_args_names", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra post argument names passed to the introspection endpoint." - }, - { - "name": "introspection_post_args_values", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra post argument values passed to the introspection endpoint." - }, - { - "name": "introspection_post_args_client", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra post arguments passed from the client to the introspection endpoint." - }, - { - "group": "User Info Endpoint Arguments" - }, - { - "name": "userinfo_accept", - "required": false, - "default": "\"application/json\"", - "datatype": "string", - "description": "The value of `Accept` header for user info requests:\n- `application/json`: user info response as JSON\n- `application/jwt`: user info response as JWT (from the obsolete IETF draft document)\n" - }, - { - "name": "userinfo_headers_names", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra header names passed to the user info endpoint." - }, - { - "name": "userinfo_headers_values", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra header values passed to the user info endpoint." - }, - { - "name": "userinfo_headers_client", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra headers passed from the client to the user info endpoint." - }, - { - "name": "userinfo_query_args_names", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra query argument names passed to the user info endpoint." - }, - { - "name": "userinfo_query_args_values", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra query argument values passed to the user info endpoint." - }, - { - "name": "userinfo_query_args_client", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Extra query arguments passed from the client to the user info endpoint." - }, - { - "group": "HTTP Client", - "description": "Parameters for generic settings for the HTTP client when the plugin needs to interact with the identity provider." - }, - { - "name": "keepalive", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Use keepalive with the HTTP client." - }, - { - "name": "ssl_verify", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Verify identity provider server certificate." - }, - { - "name": "timeout", - "required": false, - "default": 10000, - "datatype": "integer", - "description": "Network IO timeout in milliseconds." - }, - { - "name": "http_version", - "required": false, - "default": 1.1, - "datatype": "number", - "description": "The HTTP version used for the requests by this plugin:\n- `1.1`: HTTP 1.1 (the default)\n- `1.0`: HTTP 1.0\n" - }, - { - "group": "HTTP Client Proxy Settings", - "description": "Parameters only needed if the HTTP(S) requests to identity provider need to go through a proxy server." - }, - { - "name": "http_proxy", - "required": false, - "default": null, - "datatype": "url", - "description": "The HTTP proxy" - }, - { - "name": "http_proxy_authorization", - "required": false, - "default": null, - "datatype": "string", - "description": "The HTTP proxy authorization." - }, - { - "name": "https_proxy", - "required": false, - "default": null, - "datatype": "url", - "description": "The HTTPS proxy" - }, - { - "name": "https_proxy_authorization", - "required": false, - "default": null, - "datatype": "string", - "description": "The HTTPS proxy authorization." - }, - { - "name": "no_proxy", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "Do not use proxy with these hosts." - }, - { - "group": "Cache TTLs", - "description": "These do not apply to the discovery cache." - }, - { - "name": "cache_ttl", - "required": false, - "default": 3600, - "datatype": "integer", - "description": "The default cache ttl in seconds that is used in case the cached object does not specify the expiry." - }, - { - "name": "cache_ttl_max", - "required": false, - "default": null, - "datatype": "integer", - "description": "The maximum cache ttl in seconds (enforced)." - }, - { - "name": "cache_ttl_min", - "required": false, - "default": null, - "datatype": "integer", - "description": "The minimum cache ttl in seconds (enforced)." - }, - { - "name": "cache_ttl_neg", - "required": false, - "default": "(derived from Kong configuration)", - "datatype": "integer", - "description": "The negative cache ttl in seconds." - }, - { - "name": "cache_ttl_resurrect", - "required": false, - "default": "(derived from Kong configuration)", - "datatype": "integer", - "description": "The resurrection ttl in seconds." - }, - { - "group": "Cache Settings for the Endpoints" - }, - { - "name": "cache_tokens", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Cache the token endpoint requests." - }, - { - "name": "cache_tokens_salt", - "required": false, - "default": "(auto generated)", - "datatype": "string", - "description": "Salt used for generating the cache key that us used for caching the token\nendpoint requests.\n> If you use multiple plugin instances of the OpenID Connect\n> plugin and want to share token endpoint caches between the plugin\n> instances, set the salt to the same value on each plugin instance.\n" - }, - { - "name": "cache_introspection", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Cache the introspection endpoint requests." - }, - { - "name": "cache_token_exchange", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Cache the token exchange endpoint requests." - }, - { - "name": "cache_user_info", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Cache the user info requests." - }, - { - "name": "resolve_distributed_claims", - "minimum_version": "2.8.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Distributed claims are represented by the `_claim_names` and `_claim_sources` members\nof the JSON object containing the claims.\nIf this parameter is set to `true`, the plugin explicitly resolves these distributed claims.\n" - } - ], - "opentelemetry": [ - { - "name": "endpoint", - "required": true, - "value_in_examples": "http://opentelemetry.collector:4318/v1/traces", - "datatype": "string", - "description": "The full HTTP(S) endpoint that Kong Gateway should send OpenTelemetry spans to.\nThe endpoint must be a [OTLP/HTTP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md#otlphttp) endpoint.\n" - }, - { - "name": "headers", - "maximum_version": "3.0.x", - "required": false, - "datatype": "map", - "value_in_examples": [ - "X-Auth-Token:secret-token" - ], - "description": "The custom headers to be added in the HTTP request sent to the OTLP server.\nThis setting is useful for adding the authentication headers (token)\nfor the APM backend.\n" - }, - { - "name": "headers", - "minimum_version": "3.1.x", - "referenceable": true, - "required": false, - "datatype": "map", - "value_in_examples": [ - "X-Auth-Token:secret-token" - ], - "description": "The custom headers to be added in the HTTP request sent to the OTLP server.\nThis setting is useful for adding the authentication headers (token)\nfor the APM backend.\n" - }, - { - "name": "resource_attributes", - "required": false, - "datatype": "map", - "description": "The attributes specified on this property are added to the OpenTelemetry resource object.\nKong follows the OpenTelemetry specification for [Semantic Attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#service).\n\nThe following attributes are automatically added to the resource object:\n- `service.name`: The name of the service. This is `kong` by default.\n- `service.version`: The version of Kong Gateway.\n- `service.instance.id`: The node id of Kong Gateway.\n\nThe default values for the above attributes can be overridden by specifying them in this property. For example,\nto override the default value of `service.name` to `my-service`, you can specify `{ \"service.name\": \"my-service\" }`.\n" - }, - { - "name": "batch_span_count", - "required": true, - "default": 200, - "datatype": "number", - "description": "The number of spans to be sent in a single batch.\n" - }, - { - "name": "batch_flush_delay", - "required": true, - "default": 3, - "datatype": "number", - "description": "The delay, in seconds, between two consecutive batches.\n" - }, - { - "name": "connect_timeout", - "default": 1000, - "datatype": "number", - "description": "The timeout, in milliseconds, for the OTLP server connection.\n" - }, - { - "name": "send_timeout", - "default": 5000, - "datatype": "number", - "description": "The timeout, in milliseconds, for sending spans to the OTLP server.\n" - }, - { - "name": "read_timeout", - "default": 5000, - "datatype": "number", - "description": "The timeout, in milliseconds, for reading the response from the OTLP server.\n" - } - ], - "openwhisk": [ - { - "name": "host", - "required": true, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "Host of the OpenWhisk server." - }, - { - "name": "port", - "required": true, - "default": "`443`", - "datatype": "integer", - "description": "Port of the OpenWhisk server." - }, - { - "name": "path", - "required": true, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "The path to `Action` resource.\n" - }, - { - "name": "action", - "required": true, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "Name of the `Action` to be invoked by the plugin.\n" - }, - { - "name": "service_token", - "required": false, - "default": null, - "value_in_examples": "", - "datatype": "string", - "description": "The service token to access Openwhisk resources." - }, - { - "name": "https_verify", - "required": false, - "default": "`false`", - "datatype": "boolean", - "description": "Set to `true` to authenticate Openwhisk server.\n" - }, - { - "name": "https", - "required": false, - "default": "`true`", - "datatype": "boolean", - "description": "Option to use HTTPS to connect with the OpenWhisk server." - }, - { - "name": "result", - "required": false, - "default": "`true`", - "datatype": "boolean", - "description": "Return only the result of the invoked `Action`.\n" - }, - { - "name": "timeout", - "required": false, - "default": "`60000`", - "datatype": "integer", - "description": "Timeout in milliseconds before closing a connection to OpenWhisk server." - }, - { - "name": "keepalive", - "required": false, - "default": "`60000`", - "datatype": "integer", - "description": "Time in milliseconds for which an idle connection to OpenWhisk server lives before being closed." - } - ], - "prometheus": [ - { - "name": "per_consumer", - "required": false, - "datatype": "boolean", - "default": "`false`", - "description": "A boolean value that determines if per-consumer metrics should be\ncollected.\nIf enabled, the `kong_http_requests_total` and `kong_bandwidth_bytes`\nmetrics fill in the consumer label when available.\n" - }, - { - "name": "status_code_metrics", - "required": false, - "datatype": "boolean", - "default": "`false`", - "description": "A boolean value that determines if status code metrics should be\ncollected.\nIf enabled, `http_requests_total`, `stream_sessions_total` metrics will be exported.\n" - }, - { - "name": "latency_metrics", - "required": false, - "datatype": "boolean", - "default": "`false`", - "description": "A boolean value that determines if status code metrics should be\ncollected.\nIf enabled, `kong_latency_ms`, `upstream_latency_ms` and `request_latency_ms`\nmetrics will be exported.\n" - }, - { - "name": "bandwidth_metrics", - "required": false, - "datatype": "boolean", - "default": "`false`", - "description": "A boolean value that determines if status code metrics should be\ncollected.\nIf enabled, `bandwidth_bytes` and `stream_sessions_total` metrics will be exported.\n" - }, - { - "name": "upstream_health_metrics", - "required": false, - "datatype": "boolean", - "default": "`false`", - "description": "A boolean value that determines if status code metrics should be\ncollected.\nIf enabled, `upstream_target_health` metric will be exported.\n" - } - ], - "proxy-cache-advanced": [ - { - "name": "response_code", - "required": true, - "default": "200, 301, 404", - "value_in_examples": [ - "200" - ], - "datatype": "array of type integer", - "description": "Upstream response status code considered cacheable. The integers must be a value\nbetween 100 and 900.\n" - }, - { - "name": "request_method", - "required": true, - "default": "`[\"GET\",\"HEAD\"]`", - "value_in_examples": [ - "GET", - "HEAD" - ], - "datatype": "array of string elements", - "description": "Downstream request methods considered cacheable. Available options: `HEAD`, `GET`, `POST`, `PATCH`, `PUT`.\n" - }, - { - "name": "content_type", - "required": true, - "default": "text/plain, application/json", - "value_in_examples": [ - "text/plain", - "application/json" - ], - "datatype": "array of string elements", - "description": "Upstream response content types considered cacheable. The plugin performs an **exact match** against each specified value; for example, if the upstream is expected to respond with a `application/json; charset=utf-8` content-type, the plugin configuration must contain said value or a `Bypass` cache status is returned.\n" - }, - { - "name": "vary_headers", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Relevant headers considered for the cache key. If undefined, none of the headers are taken into consideration.\n" - }, - { - "name": "vary_query_params", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Relevant query parameters considered for the cache key. If undefined, all params are taken into consideration.\n" - }, - { - "name": "cache_ttl", - "required": null, - "default": 300, - "value_in_examples": null, - "datatype": "integer", - "description": "TTL in seconds of cache entities.\n" - }, - { - "name": "cache_control", - "required": true, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "When enabled, respect the Cache-Control behaviors defined in [RFC7234](https://tools.ietf.org/html/rfc7234#section-5.2).\n" - }, - { - "name": "storage_ttl", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "integer", - "description": "Number of seconds to keep resources in the storage backend. This value is independent\nof `cache_ttl` or resource TTLs defined by Cache-Control behaviors.\n" - }, - { - "name": "strategy", - "required": true, - "default": null, - "value_in_examples": "memory", - "datatype": "string", - "description": "The backing data store in which to hold cache entities. Accepted values are: `memory` and `redis`.\n" - }, - { - "name": "memory.dictionary_name", - "required": true, - "default": "kong_db_cache", - "value_in_examples": null, - "datatype": "string", - "description": "The name of the shared dictionary in which to hold cache entities when the memory strategy is selected. Note that this dictionary currently must be defined manually in the Kong Nginx template.\n" - }, - { - "name": "redis.host", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Host to use for Redis connection when the redis strategy is defined.\n" - }, - { - "name": "redis.port", - "required": "semi", - "default": 6379, - "value_in_examples": null, - "datatype": "integer", - "description": "Port to use for Redis connections when the `redis` strategy is defined. Must be a\nvalue between 0 and 65535. Default: 6379.\n" - }, - { - "name": "redis.ssl", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "If set to `true`, then uses SSL to connect to Redis.\n\n**Note:** This parameter is only available for Kong Gateway versions\n2.2.x and later.\n" - }, - { - "name": "redis.ssl_verify", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "If set to `true`, then verifies the validity of the server SSL certificate. Note that you need to configure the\n[lua_ssl_trusted_certificate](/gateway/latest/reference/configuration/#lua_ssl_trusted_certificate)\nto specify the CA (or server) certificate used by your Redis server. You may also need to configure\n[lua_ssl_verify_depth](/gateway/latest/reference/configuration/#lua_ssl_verify_depth) accordingly.\n\n**Note:** This parameter is only available for Kong Gateway versions\n2.2.x and later.\n" - }, - { - "name": "redis.server_name", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Specifies the server name for the new TLS extension Server Name Indication (SNI) when connecting over SSL.\n\n**Note:** This parameter is only available for Kong Gateway versions\n2.2.x and later.\n" - }, - { - "name": "redis.timeout", - "required": "semi", - "default": 2000, - "value_in_examples": null, - "datatype": "number", - "description": "Connection timeout to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.password", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Password to use for Redis connection when the `redis` strategy is defined.\nIf undefined, no AUTH commands are sent to Redis.\n" - }, - { - "name": "redis.database", - "required": "semi", - "default": 0, - "value_in_examples": null, - "datatype": "integer", - "description": "Database to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.sentinel_master", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Sentinel master to use for Redis connection when the `redis` strategy is defined. Defining this value implies using Redis Sentinel.\n" - }, - { - "name": "redis.sentinel_username", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Sentinel username to authenticate with a Redis Sentinel instance.\nIf undefined, ACL authentication will not be performed. This requires Redis v6.2.0+.\n" - }, - { - "name": "redis.sentinel_password", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Sentinel password to authenticate with a Redis Sentinel instance.\nIf undefined, no AUTH commands are sent to Redis Sentinels.\n" - }, - { - "name": "redis.sentinel_role", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Sentinel role to use for Redis connections when the `redis` strategy is defined. Defining this value\nimplies using Redis Sentinel. Available options: `master`, `slave`, `any`.\n" - }, - { - "name": "redis.sentinel_addresses", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Sentinel addresses to use for Redis connections when the `redis` strategy is defined.\nDefining this value implies using Redis Sentinel. Each string element must\nbe a hostname. The minimum length of the array is 1 element.\n" - }, - { - "name": "redis.cluster_addresses", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Cluster addresses to use for Redis connection when the `redis` strategy is defined.\nDefining this value implies using Redis cluster. Each string element must\nbe a hostname. The minimum length of the array is 1 element.\n" - }, - { - "name": "redis.keepalive_backlog", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "integer", - "description": "If specified, limits the total number of opened connections for a pool. If the\nconnection pool is full, all connection queues beyond the maximum limit go into\nthe backlog queue. Once the backlog queue is full, subsequent connect operations\nwill fail and return `nil`. Queued connect operations resume once the number of\nconnections in the pool is less than `keepalive_pool_size`. Note that queued\nconnect operations are subject to set timeouts.\n" - }, - { - "name": "redis.keepalive_pool", - "required": false, - "default": "generated from string template", - "value_in_examples": null, - "datatype": "string", - "description": "The custom name of the connection pool. If not specified, the connection pool\nname is generated from the string template `\":\"` or `\"\"`.\n" - }, - { - "name": "redis.keepalive_pool_size", - "required": false, - "default": 30, - "value_in_examples": null, - "datatype": "integer", - "description": "The size limit for every cosocket connection pool associated with every remote\nserver, per worker process. If no `keepalive_pool_size` is specified and no `keepalive_backlog`\nis specified, no pool is created. If no `keepalive_pool_size` is specified and `keepalive_backlog`\nis specified, then the pool uses the default value `30`.\n" - }, - { - "name": "bypass_on_err", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "Unhandled errors while trying to retrieve a cache entry (such as redis down) are resolved with `Bypass`, with the request going upstream.\n" - } - ], - "proxy-cache": [ - { - "name": "response_code", - "required": null, - "default": "200, 301, 404", - "value_in_examples": [ - "200" - ], - "datatype": "array integer elements", - "description": "Upstream response status code considered cacheable.\n" - }, - { - "name": "request_method", - "required": null, - "default": "`[\"GET\",\"HEAD\"]`", - "value_in_examples": [ - "GET", - "HEAD" - ], - "datatype": "array of string elements", - "description": "Downstream request methods considered cacheable.\n" - }, - { - "name": "content_type", - "required": null, - "default": "`[\"text/plain\", \"application/json\"]`", - "value_in_examples": [ - "text/plain", - "application/json" - ], - "datatype": "array of string elements", - "description": "Upstream response content types considered cacheable. The plugin performs an **exact match** against each specified value; for example, if the upstream is expected to respond with a `application/json; charset=utf-8` content-type, the plugin configuration must contain said value or a `Bypass` cache status is returned.\n" - }, - { - "name": "vary_headers", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Relevant headers considered for the cache key. If undefined, none of the headers are taken into consideration.\n" - }, - { - "name": "vary_query_params", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Relevant query parameters considered for the cache key. If undefined, all params are taken into consideration.\n" - }, - { - "name": "cache_ttl", - "required": null, - "default": 300, - "value_in_examples": 300, - "datatype": "integer", - "description": "TTL, in seconds, of cache entities.\n" - }, - { - "name": "cache_control", - "required": null, - "default": "`false`", - "value_in_examples": null, - "datatype": "boolean", - "description": "When enabled, respect the Cache-Control behaviors defined in [RFC7234](https://tools.ietf.org/html/rfc7234#section-5.2).\n" - }, - { - "name": "storage_ttl", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "integer", - "description": "Number of seconds to keep resources in the storage backend. This value is independent of `cache_ttl` or resource TTLs defined by Cache-Control behaviors.\n" - }, - { - "name": "strategy", - "required": true, - "default": null, - "value_in_examples": "memory", - "datatype": "string", - "description": "The backing data store in which to hold cache entities. The only accepted value is `memory`.\n" - }, - { - "name": "memory.dictionary_name", - "required": null, - "default": "`kong_db_cache`", - "value_in_examples": null, - "datatype": "string", - "description": "The name of the shared dictionary in which to hold cache entities when the memory strategy is selected. Note that this dictionary currently must be defined manually in the Kong Nginx template.\n" - } - ], - "rate-limiting-advanced": [ - { - "name": "limit", - "required": true, - "default": null, - "value_in_examples": [ - "5" - ], - "datatype": "array of number elements", - "description": "One or more requests-per-window limits to apply. There must be a matching\nnumber of window limits and sizes specified.\n" - }, - { - "name": "window_size", - "required": true, - "default": null, - "value_in_examples": [ - "30" - ], - "datatype": "array of number elements", - "description": "One or more window sizes to apply a limit to (defined in seconds). There\nmust be a matching number of window limits and sizes specified.\n" - }, - { - "name": "identifier", - "required": true, - "default": "consumer", - "value_in_examples": "consumer", - "datatype": "string", - "description": "The type of identifier used to generate the rate limit key.\nDefines the scope used to increment the rate limiting counters.\nCan be `ip`, `credential`, `consumer`, `service`, `header`, or `path`.\n" - }, - { - "name": "path", - "required": "semi", - "datatype": "string", - "description": "Request path to use as the rate limit key when `config.identifier` is\nconfigured with the value `path`. Ignored when `config.identifier` has any other value.\n" - }, - { - "name": "header_name", - "required": "semi", - "datatype": "string", - "description": "Header name to use as the rate limit key when `config.identifier` is\nconfigured with the value `header`. Ignored when `config.identifier` is not `header`.\n" - }, - { - "name": "dictionary_name", - "required": true, - "default": "kong_rate_limiting_counters", - "value_in_examples": null, - "datatype": "string", - "description": "The shared dictionary where counters are stored. When the plugin is\nconfigured to synchronize counter data externally (that is \n`config.strategy` is `cluster` or `redis` and `config.sync_rate` isn't\n`-1`), this dictionary serves as a buffer to populate counters in the\ndata store on each synchronization cycle.\n" - }, - { - "name": "sync_rate", - "required": true, - "default": null, - "value_in_examples": -1, - "datatype": "number", - "description": "How often to sync counter data to the central data store. A value of 0\nresults in synchronous behavior; a value of -1 ignores sync behavior\nentirely and only stores counters in node memory. A value greater than\n0 will sync the counters in the specified number of seconds. The minimum\nallowed interval is 0.02 seconds (20ms).\n" - }, - { - "name": "namespace", - "required": "semi", - "default": "random_auto_generated_string", - "value_in_examples": "example_namespace", - "datatype": "string", - "description": "The rate limiting library namespace to use for this plugin instance. Counter\ndata and sync configuration is isolated in each namespace.\n\n{:.important}\n> **Important**: If managing Kong Gateway with **declarative configuration** or running\nKong Gateway in **DB-less mode**, set the `namespace` explicitly in your declarative configuration.\n>

\n> If not set, you will run into the following issues:\n* In DB-less mode, this field will be regenerated automatically on every configuration change.\n* If applying declarative configuration with decK, decK will automatically fail the update and require a \n`namespace` value.\n" - }, - { - "name": "strategy", - "maximum_version": "2.8.x", - "required": true, - "default": "cluster", - "value_in_examples": "local", - "datatype": "string", - "description": "The rate-limiting strategy to use for retrieving and incrementing the\nlimits. Available values are:\n- `cluster`: Counters are stored in the Kong datastore and shared across\n the nodes.\n- `redis`: Counters are stored on a Redis server and shared\n across the nodes.\n- `local`: Counters are stored locally in-memory on the node (same effect\n as setting `sync_rate` to `-1`).\n\nIn DB-less, hybrid mode, and Konnect, the `cluster` config strategy\nis not supported.\n\nFor details on which strategy should be used, refer to the\n[implementation considerations](/hub/kong-inc/rate-limiting/#implementation-considerations).\n" - }, - { - "name": "strategy", - "minimum_version": "3.0.x", - "required": true, - "default": "local", - "value_in_examples": "local", - "datatype": "string", - "description": "The rate-limiting strategy to use for retrieving and incrementing the\nlimits. Available values are:\n- `local`: Counters are stored locally in-memory on the node (same effect\n as setting `sync_rate` to `-1`).\n- `cluster`: Counters are stored in the Kong datastore and shared across\n the nodes.\n- `redis`: Counters are stored on a Redis server and shared\n across the nodes.\n\nIn DB-less, hybrid mode, and Konnect, the `cluster` config strategy\nis not supported. \n\nFrom `3.0.0.0` onwards, Kong disallows\nthe plugin enablement if the strategy is `cluster` and `sync_rate` is `-1`\nwith DB-less or hybrid mode. From `3.2.0.0` onward, please\nuse a different strategy or set `sync_rate` to `-1`.\n\nFor details on which strategy should be used, refer to the\n[implementation considerations](/hub/kong-inc/rate-limiting/#implementation-considerations).\n" - }, - { - "name": "hide_client_headers", - "required": false, - "default": false, - "value_in_examples": false, - "datatype": "boolean", - "description": "Optionally hide informative response headers that would otherwise\nprovide information about the current status of limits and counters as\ndescribed in the paragraph [Headers sent to the client](#headers-sent-to-the-client).\nAvailable options: `true` or `false`.\n" - }, - { - "name": "redis.host", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Host to use for Redis connection when the `redis` strategy is defined.\nThis parameter accepts a hostname or an IP address as a value.\n" - }, - { - "name": "redis.port", - "required": "semi", - "default": 6379, - "value_in_examples": null, - "datatype": "integer", - "description": "Specifies the Redis server port when using the `redis` strategy. Must be a\nvalue between 0 and 65535. Default: 6379.\n" - }, - { - "name": "redis.ssl", - "minimum_version": "2.2.x", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "If set to true, then uses SSL to connect to Redis.\n" - }, - { - "name": "redis.ssl_verify", - "minimum_version": "2.2.x", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "If set to true, then verifies the validity of the server SSL certificate. Note that you need to configure the\n[lua_ssl_trusted_certificate](/gateway/latest/reference/configuration/#lua_ssl_trusted_certificate)\nto specify the CA (or server) certificate used by your redis server. You may also need to configure\n[lua_ssl_verify_depth](/gateway/latest/reference/configuration/#lua_ssl_verify_depth) accordingly.\n" - }, - { - "name": "redis.server_name", - "minimum_version": "2.2.x", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Specifies the server name for the new TLS extension Server Name Indication (SNI) when connecting over SSL.\n" - }, - { - "name": "redis.timeout", - "maximum_version": "2.4.x", - "required": "semi", - "default": 2000, - "value_in_examples": null, - "datatype": "number", - "description": "Connection timeout (in milliseconds) to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.timeout", - "minimum_version": "2.5.x", - "required": "semi", - "default": 2000, - "value_in_examples": null, - "datatype": "number", - "description": "Connection timeout (in milliseconds) to use for Redis connection when the `redis` strategy is defined.\nThis field is deprecated and replaced with `redis.connect_timeout`, `redis.send_timeout`, and `redis.read_timeout`.\nThe `redis.timeout` field will continue to work in a backwards compatible way, but it is recommended to use the replacement fields.\nIf set to something other than the default, a deprecation warning will be logged in the log file, stating the field's deprecation\nand planned removal in v3.x.x.\n" - }, - { - "name": "redis.connect_timeout", - "minimum_version": "2.5.x", - "required": "semi", - "default": 2000, - "datatype": "number", - "description": "Connection timeout to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.send_timeout", - "minimum_version": "2.5.x", - "required": "semi", - "default": 2000, - "datatype": "number", - "description": "Send timeout to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.read_timeout", - "minimum_version": "2.5.x", - "required": "semi", - "default": 2000, - "datatype": "number", - "description": "Read timeout to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.username", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Username to use for Redis connection when the `redis` strategy is defined and ACL authentication is desired.\nIf undefined, ACL authentication will not be performed.\n\nThis requires Redis v6.0.0+. The username **cannot** be set to `default`.\n" - }, - { - "name": "redis.password", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Password to use for Redis connection when the `redis` strategy is defined.\nIf undefined, no AUTH commands are sent to Redis.\n" - }, - { - "name": "redis.database", - "required": "semi", - "default": 0, - "value_in_examples": null, - "datatype": "integer", - "description": "Database to use for Redis connection when the `redis` strategy is defined.\n" - }, - { - "name": "redis.sentinel_master", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Sentinel master to use for Redis connections when the `redis` strategy is defined.\nDefining this value implies using Redis Sentinel.\n" - }, - { - "name": "redis.sentinel_username", - "minimum_version": "2.8.x", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Sentinel username to authenticate with a Redis Sentinel instance.\nIf undefined, ACL authentication will not be performed. This requires Redis v6.2.0+.\n" - }, - { - "name": "redis.sentinel_password", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "referenceable": true, - "description": "Sentinel password to authenticate with a Redis Sentinel instance.\nIf undefined, no AUTH commands are sent to Redis Sentinels.\n" - }, - { - "name": "redis.sentinel_role", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Sentinel role to use for Redis connections when the `redis` strategy is defined.\nDefining this value implies using Redis Sentinel. Available options: `master`, `slave`, `any`.\n" - }, - { - "name": "redis.sentinel_addresses", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Sentinel addresses to use for Redis connections when the `redis` strategy is defined.\nDefining this value implies using Redis Sentinel. Each string element must\nconsist of a hostname (or IP address) and port. The minimum length of the array is 1 element.\n" - }, - { - "name": "redis.cluster_addresses", - "required": "semi", - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Cluster addresses to use for Redis connections when the `redis` strategy is defined.\nDefining this value implies using Redis cluster. Each string element must\nconsist of a hostname (or IP address) and port. The minimum length of the array is 1 element.\n" - }, - { - "name": "redis.keepalive_backlog", - "minimum_version": "2.5.x", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "integer", - "description": "If specified, limits the total number of opened connections for a pool. If the\nconnection pool is full, all connection queues beyond the maximum limit go into\nthe backlog queue. Once the backlog queue is full, subsequent connect operations\nwill fail and return `nil`. Queued connect operations resume once the number of\nconnections in the pool is less than `keepalive_pool_size`. Note that queued\nconnect operations are subject to set timeouts.\n" - }, - { - "name": "redis.keepalive_pool", - "minimum_version": "2.5.x", - "required": false, - "default": "generated from string template", - "value_in_examples": null, - "datatype": "string", - "description": "The custom name of the connection pool. If not specified, the connection pool\nname is generated from the string template `\":\"` or `\"\"`.\n" - }, - { - "name": "redis.keepalive_pool_size", - "minimum_version": "2.5.x", - "required": false, - "default": 30, - "value_in_examples": null, - "datatype": "integer", - "description": "The size limit for every cosocket connection pool associated with every remote\nserver, per worker process. If no `keepalive_pool_size` is specified and no `keepalive_backlog`\nis specified, no pool is created. If no `keepalive_pool_size` is specified and `keepalive_backlog`\nis specified, then the pool uses the default value `30`.\n" - }, - { - "name": "window_type", - "required": true, - "default": "sliding", - "value_in_examples": null, - "datatype": "string", - "description": "Sets the time window type to either `sliding` (default) or `fixed`.\nSliding windows apply the rate limiting logic while taking into account\nprevious hit rates (from the window that immediately precedes the current)\nusing a dynamic weight.\nFixed windows consist of buckets that are statically assigned to a\ndefinitive time range, each request is mapped to only one fixed window\nbased on its timestamp and will affect only that window's counters.\nFor more information refer to the\n[Enterprise Rate Limiting Library Overview](/gateway/latest/reference/rate-limiting/#overview).\n" - }, - { - "name": "retry_after_jitter_max", - "required": true, - "default": 0, - "value_in_examples": null, - "datatype": "number", - "description": "The upper bound of a jitter (random delay) in seconds to be added to the `Retry-After`\nheader of denied requests (status = `429`) in order to prevent all the clients\nfrom coming back at the same time. The lower bound of the jitter is `0`; in this case,\nthe `Retry-After` header is equal to the `RateLimit-Reset` header.\n" - }, - { - "name": "enforce_consumer_groups", - "minimum_version": "2.7.x", - "required": false, - "default": false, - "value_in_examples": true, - "datatype": "boolean", - "description": "Set to `true` to enable `consumer_groups`, which allows the settings\nfrom one of the allowed consumer groups to override the given plugin\nconfiguration.\n" - }, - { - "name": "consumer_groups", - "minimum_version": "2.7.x", - "required": "semi", - "default": null, - "value_in_examples": [ - "group1", - "group2" - ], - "datatype": "array of string elements", - "description": "List of consumer groups allowed to override the rate limiting\nsettings for the given Route or Service. Required if\n`enforce_consumer_groups` is set to `true`.\n\nFlipping `enforce_consumer_groups` from `true` to `false` disables the\ngroup override, but does not clear the list of consumer groups.\nYou can then flip `enforce_consumer_groups` to `true` to re-enforce the\ngroups.\n" - }, - { - "name": "disable_penalty", - "minimum_version": "3.1.x", - "required": false, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "If set to `true`, this doesn't count denied requests (status = `429`). If set to `false`, all requests, including denied ones, are counted. This parameter only affects the `sliding` window_type.\n" - }, - { - "name": "error_code", - "minimum_version": "3.1.x", - "required": false, - "default": 429, - "datatype": "number", - "description": "Set a custom error code to return when the rate limit is exceeded.\n" - }, - { - "name": "error_message", - "minimum_version": "3.1.x", - "required": false, - "default": "rate limit exceeded", - "datatype": "string", - "description": "Set a custom error message to return when the rate limit is exceeded.\n" - } - ], - "rate-limiting": [ - { - "name": "second", - "required": "semi", - "value_in_examples": 5, - "datatype": "number", - "description": "The number of HTTP requests that can be made per second." - }, - { - "name": "minute", - "required": "semi", - "datatype": "number", - "description": "The number of HTTP requests that can be made per minute." - }, - { - "name": "hour", - "required": "semi", - "value_in_examples": 10000, - "datatype": "number", - "description": "The number of HTTP requests that can be made per hour." - }, - { - "name": "day", - "required": "semi", - "datatype": "number", - "description": "The number of HTTP requests that can be made per day." - }, - { - "name": "month", - "required": "semi", - "datatype": "number", - "description": "The number of HTTP requests that can be made per month." - }, - { - "name": "year", - "required": "semi", - "datatype": "number", - "description": "The number of HTTP requests that can be made per year." - }, - { - "name": "limit_by", - "required": false, - "default": "`consumer`", - "datatype": "string", - "description": "The entity that is used when aggregating the limits. Available values are:\n- `consumer`\n- `credential`\n- `ip`\n- `service`\n- `header` (The `header_name` configuration must be provided.)\n- `path` (The `path` configuration must be provided.)\n\nIf the entity value for aggregating the limits cannot be determined, the system falls back to `ip`.\n" - }, - { - "name": "header_name", - "required": "semi", - "datatype": "string", - "description": "Header name to be used if `limit_by` is set to `header`." - }, - { - "name": "path", - "required": "semi", - "datatype": "string", - "description": "Path to be used if `limit_by` is set to `path`." - }, - { - "name": "policy", - "required": false, - "value_in_examples": "local", - "default": "`local`", - "datatype": "string", - "description": "The rate-limiting policies to use for retrieving and incrementing the\nlimits. Available values are:\n- `local`: Counters are stored locally in-memory on the node.\n- `cluster`: Counters are stored in the Kong data store and shared across\nthe nodes.\n- `redis`: Counters are stored on a Redis server and shared\nacross the nodes.\n\nIn DB-less, hybrid mode, and Konnect, the `cluster` config policy is not supported.\nFor DB-less mode or Konnect, use one of `redis` or `local`; for hybrid mode, use\n`redis`, or `local` for data planes only.\n\nFor details on which policy should be used, refer to the\n[implementation considerations](#implementation-considerations).\n" - }, - { - "name": "fault_tolerant", - "required": true, - "default": "`true`", - "datatype": "boolean", - "description": "A boolean value that determines if the requests should be proxied even if Kong has troubles connecting a third-party data store. If `true`, requests will be proxied anyway, effectively disabling the rate-limiting function until the data store is working again. If `false`, then the clients will see `500` errors.\n" - }, - { - "name": "hide_client_headers", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Optionally hide informative response headers." - }, - { - "name": "redis_host", - "required": "semi", - "datatype": "string", - "description": "When using the `redis` policy, this property specifies the address to the Redis server.\n" - }, - { - "name": "redis_port", - "required": false, - "default": "`6379`", - "datatype": "integer", - "description": "When using the `redis` policy, this property specifies the port of the Redis server. By default is `6379`.\n" - }, - { - "name": "redis_username", - "minimum_version": "2.8.x", - "required": false, - "datatype": "string", - "referenceable": true, - "description": "When using the `redis` policy, this property specifies the username to connect to the Redis server when ACL authentication is desired. \n\nThis requires Redis v6.0.0+. The username **cannot** be set to `default`.\n" - }, - { - "name": "redis_password", - "minimum_version": "2.7.x", - "required": false, - "datatype": "string", - "referenceable": true, - "description": "When using the `redis` policy, this property specifies the password to connect to the Redis server.\n" - }, - { - "name": "redis_ssl", - "minimum_version": "2.7.x", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "When using the `redis` policy, this property specifies if SSL is used to connect to the Redis server.\n" - }, - { - "name": "redis_ssl_verify", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "When using the `redis` policy with `redis_ssl` set to `true`, this property specifies it server SSL certificate is validated. Note that you need to configure the lua_ssl_trusted_certificate to specify the CA (or server) certificate used by your Redis server. You may also need to configure lua_ssl_verify_depth accordingly.\n" - }, - { - "name": "redis_server_name", - "required": false, - "datatype": "string", - "description": "When using the `redis` policy with `redis_ssl` set to `true`, this property specifies the server name for the TLS extension Server Name Indication (SNI)\n" - }, - { - "name": "redis_timeout", - "required": false, - "default": "`2000`", - "datatype": "number", - "description": "When using the `redis` policy, this property specifies the timeout in milliseconds of any command submitted to the Redis server.\n" - }, - { - "name": "redis_database", - "required": false, - "default": "`0`", - "datatype": "integer", - "description": "When using the `redis` policy, this property specifies the Redis database to use.\n" - }, - { - "name": "error_code", - "minimum_version": "3.1.x", - "required": false, - "default": 429, - "datatype": "number", - "description": "Set a custom error code to return when the rate limit is exceeded.\n" - }, - { - "name": "error_message", - "minimum_version": "3.1.x", - "required": false, - "default": "rate limit exceeded", - "datatype": "string", - "description": "Set a custom error message to return when the rate limit is exceeded.\n" - } - ], - "request-size-limiting": [ - { - "name": "allowed_payload_size", - "required": true, - "default": "`128`", - "datatype": "integer", - "value_in_examples": 128, - "description": "Allowed request payload size in megabytes. Default is `128` megabytes (128000000 bytes)." - }, - { - "name": "size_unit", - "required": true, - "default": "`megabytes`", - "datatype": "string", - "description": "Size unit can be set either in `bytes`, `kilobytes`, or `megabytes` (default). This configuration is not available in versions prior to Kong Gateway 1.3 and Kong Gateway (OSS) 2.0." - }, - { - "name": "require_content_length", - "minimum_version": "2.3.x", - "required": true, - "default": false, - "datatype": "boolean", - "value_in_examples": false, - "description": "Set to `true` to ensure a valid `Content-Length` header exists before reading the request body." - } - ], - "request-termination": [ - { - "name": "status_code", - "required": false, - "default": "`503`", - "value_in_examples": 403, - "datatype": "integer", - "description": "The response code to send. Must be an integer between 100 and 599." - }, - { - "name": "message", - "required": false, - "value_in_examples": "So long and thanks for all the fish!", - "datatype": "string", - "description": "The message to send, if using the default response generator." - }, - { - "name": "body", - "required": false, - "datatype": "string", - "description": "The raw response body to send. This is mutually exclusive with the `config.message` field." - }, - { - "name": "content_type", - "required": false, - "default": "`application/json; charset=utf-8`", - "datatype": "string", - "description": "Content type of the raw response configured with `config.body`." - }, - { - "name": "trigger", - "minimum_version": "2.6.x", - "required": false, - "default": null, - "description": "When not set, the plugin always activates. When set to a string, the plugin will activate exclusively on requests containing either a header or a query parameter that is named the string." - }, - { - "name": "echo", - "minimum_version": "2.6.x", - "required": false, - "default": false, - "description": "When set, the plugin will echo a copy of the request back to the client. The main usecase for this is debugging. It can be combined with `trigger` in order to debug requests on live systems without disturbing real traffic." - } - ], - "request-transformer-advanced": [ - { - "name": "http_method", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Changes the HTTP method for the upstream request.\n" - }, - { - "name": "remove.headers", - "required": false, - "default": null, - "value_in_examples": [ - "x-toremove", - "x-another-one" - ], - "datatype": "array of string elements", - "description": "List of header names. Unset the headers with the given name.\n" - }, - { - "name": "remove.querystring", - "required": false, - "default": null, - "value_in_examples": [ - "qs-old-name:qs-new-name", - "qs2-old-name:qs2-new-name" - ], - "datatype": "array of string elements", - "description": "List of querystring names. Remove the querystring if it is present.\n" - }, - { - "name": "remove.body", - "required": false, - "default": null, - "value_in_examples": [ - "formparam-toremove", - "formparam-another-one" - ], - "datatype": "array of string elements", - "description": "List of parameter names. Remove the parameter if and only if content-type is one of the\nfollowing: [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`]; and parameter is present.\n" - }, - { - "name": "replace.headers", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "referenceable": true, - "description": "List of headername:value pairs. If and only if the header is already set,\nreplace its old value with the new one. Ignored if the header is not already set.\n" - }, - { - "name": "replace.querystring", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "referenceable": true, - "description": "List of queryname:value pairs. If and only if the querystring name is already set,\nreplace its old value with the new one. Ignored if the header is not already set.\n" - }, - { - "name": "replace.uri", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Updates the upstream request URI with given value. This value can only\nbe used to update the path part of the URI; not the scheme, nor the hostname.\n" - }, - { - "name": "replace.body", - "required": false, - "default": null, - "value_in_examples": [ - "body-param1:new-value-1", - "body-param2:new-value-2" - ], - "datatype": "array of string elements", - "referenceable": true, - "description": "List of paramname:value pairs. If and only if content-type is one the\nfollowing: [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`];\nand the parameter is already present, replace its old value with the new one. Ignored if the parameter is not already present.\n" - }, - { - "name": "replace.json_types", - "minimum_version": "3.1.x", - "required": false, - "datatype": "array of string, boolean, or number elements", - "description": "List of JSON type names. Specify the types of the JSON values returned when replacing JSON properties.\n" - }, - { - "name": "rename.headers", - "required": false, - "default": null, - "value_in_examples": [ - "header-old-name:header-new-name", - "another-old-name:another-new-name" - ], - "datatype": "array of string elements", - "referenceable": true, - "description": "List of `headername:value` pairs. If and only if the header is already set,\nrename the header. The value is unchanged. Ignored if the header is not already set.\n" - }, - { - "name": "rename.querystring", - "required": false, - "default": null, - "value_in_examples": [ - "qs-old-name:qs-new-name", - "qs2-old-name:qs2-new-name" - ], - "datatype": "array of string elements", - "referenceable": true, - "description": "List of `queryname:value` pairs. If and only if the field name is already set,\nrename the field name. The value is unchanged. Ignored if the field name is not already set.\n" - }, - { - "name": "rename.body", - "required": false, - "default": null, - "value_in_examples": [ - "param-old:param-new", - "param2-old:param2-new" - ], - "datatype": "array of string elements", - "referenceable": true, - "description": "List of parameter `name:value` pairs. Rename the parameter name if and only if content-type is\none of the following: [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`]; and parameter is present.\n" - }, - { - "name": "add.headers", - "required": false, - "default": null, - "value_in_examples": [ - "x-new-header:value", - "x-another-header:something" - ], - "datatype": "array of string elements", - "referenceable": true, - "description": "List of `headername:value` pairs. If and only if the header is not already set,\nset a new header with the given value. Ignored if the header is already set.\n" - }, - { - "name": "add.querystring", - "required": false, - "default": null, - "value_in_examples": [ - "new-param:some_value", - "another-param:some_value" - ], - "datatype": "array of string elements", - "referenceable": true, - "description": "List of `queryname:value` pairs. If and only if the querystring name is not already set,\nset a new querystring with the given value. Ignored if the querystring name is already set.\n" - }, - { - "name": "add.body", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "referenceable": true, - "description": "List of `paramname:value` pairs. If and only if content-type is one the following: [`application/json, multipart/form-data`, `application/x-www-form-urlencoded`]; and the parameter is not present, add a new parameter with the given value to form-encoded body.\nIgnored if the parameter is already present.\n" - }, - { - "name": "add.json_types", - "minimum_version": "3.1.x", - "required": false, - "value_in_examples": [ - "new-json-key:string", - "another-json-key:boolean", - "another-json-key:number" - ], - "datatype": "array of string, boolean, or number elements", - "description": "List of JSON type names. Specify the types of the JSON values returned when adding a new JSON property.\n" - }, - { - "name": "append.headers", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "referenceable": true, - "description": "List of `headername:value` pairs. If the header is not set, set it with the given value.\nIf it is already set, a new header with the same name and the new value will be set.\n" - }, - { - "name": "append.querystring", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "referenceable": true, - "description": "List of `queryname:value` pairs. If the querystring is not set, set it with the given value.\nIf it is already set, a new querystring with the same name and the new value will be set.\n" - }, - { - "name": "append.body", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "referenceable": true, - "description": "List of `paramname:value` pairs. If the content-type is one the following: [`application/json`, `application/x-www-form-urlencoded`]; add a new parameter with the given value if the parameter is not present. Otherwise, if it is already present,\nthe two values (old and new) will be aggregated in an array.\n" - }, - { - "name": "append.json_types", - "minimum_version": "3.1.x", - "required": false, - "datatype": "array of string, boolean, or number elements", - "description": "List of JSON type names. Specify the types of the JSON values returned when appending JSON properties.\n" - }, - { - "name": "allow.body", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Set of parameter names. If and only if content-type is one the following:\n[`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`]; allow only allowed parameters in the body.\n" - }, - { - "name": "dots_in_keys", - "minimum_version": "3.1.x", - "required": false, - "datatype": "boolean", - "default": true, - "description": "Specify whether dots (for example, `customers.info.phone`) should be treated as part of a property name or used to descend into nested JSON objects. \nSee [Arrays and nested objects](#arrays-and-nested-objects).\n" - } - ], - "request-transformer": [ - { - "name": "http_method", - "required": false, - "datatype": "string", - "description": "Sets the HTTP method for the upstream request." - }, - { - "name": "remove.headers", - "required": false, - "value_in_examples": [ - "x-toremove", - "x-another-one" - ], - "datatype": "array of string elements", - "description": "List of header names. Unset the headers with the given name." - }, - { - "name": "remove.querystring", - "required": false, - "value_in_examples": [ - "qs-old-name:qs-new-name", - "qs2-old-name:qs2-new-name" - ], - "datatype": "array of string elements", - "description": "List of querystring names. Remove the querystring if it is present." - }, - { - "name": "remove.body", - "required": false, - "value_in_examples": [ - "formparam-toremove", - "formparam-another-one" - ], - "datatype": "array of string elements", - "description": "List of parameter names. Remove the parameter if and only if content-type is one the following:\n[`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and the parameter is present.\n" - }, - { - "name": "replace.uri", - "required": false, - "datatype": "string", - "description": "Updates the upstream request URI with a given value. This value can be used to update\nonly the path part of the URI, not the scheme or the hostname.\n" - }, - { - "name": "replace.body", - "required": false, - "value_in_examples": [ - "body-param1:new-value-1", - "body-param2:new-value-2" - ], - "datatype": "array of string elements", - "description": "List of `paramname:value` pairs. If and only if content-type is one the following\n[`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`] and the\nparameter is already present, replace its old value with the new one. Ignored if\nthe parameter is not already present.\n" - }, - { - "name": "replace.headers", - "required": false, - "datatype": "array of string elements", - "description": "List of `headername:value` pairs. If and only if the header is already set, replace\nits old value with the new one. Ignored if the header is not already set.\n" - }, - { - "name": "replace.querystring", - "required": false, - "datatype": "array of string elements", - "description": "List of `queryname:value pairs`. If and only if the field name is already set,\nreplace its old value with the new one. Ignored if the field name is not already set.\n" - }, - { - "name": "rename.headers", - "required": false, - "value_in_examples": [ - "header-old-name:header-new-name", - "another-old-name:another-new-name" - ], - "datatype": "array of string elements", - "description": "List of `headername:value` pairs. If and only if the header is already set, rename\nthe header. The value is unchanged. Ignored if the header is not already set.\n" - }, - { - "name": "rename.querystring", - "required": false, - "value_in_examples": [ - "qs-old-name:qs-new-name", - "qs2-old-name:qs2-new-name" - ], - "datatype": "array of string elements", - "description": "List of queryname:value pairs. If and only if the field name is already set, rename the field name.\nThe value is unchanged. Ignored if the field name is not already set.\n" - }, - { - "name": "rename.body", - "required": false, - "value_in_examples": [ - "param-old:param-new", - "param2-old:param2-new" - ], - "datatype": "array of string elements", - "description": "List of `paramname:value` pairs. Rename the parameter name if and only if\ncontent-type is one the following [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`]\nand the parameter is present.\n" - }, - { - "name": "add.headers", - "required": false, - "value_in_examples": [ - "x-new-header:value", - "x-another-header:something" - ], - "datatype": "array of string elements", - "description": "List of `headername:value` pairs. If and only if the header is not already set, set a new header\nwith the given value. Ignored if the header is already set.\n" - }, - { - "name": "add.querystring", - "required": false, - "value_in_examples": [ - "new-param:some_value", - "another-param:some_value" - ], - "datatype": "array of string elements", - "description": "List of `queryname:value` pairs. If and only if the querystring is not already set, set a new\nquerystring with the given value. Ignored if the querystring is already set.\n" - }, - { - "name": "add.body", - "required": false, - "value_in_examples": [ - "new-form-param:some_value", - "another-form-param:some_value" - ], - "datatype": "array of string elements", - "description": "List of `paramname:value` pairs. If and only if content-type is one the\nfollowing [`application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`]\nand the parameter is not present, add a new parameter with the given value to the form-encoded\nbody. Ignored if the parameter is already present.\n" - }, - { - "name": "append.headers", - "required": false, - "datatype": "array of string elements", - "description": "List of `headername:value` pairs. If the header is not set, set it with the given value.\nIf it is already set, an additional new header with the same name and the new value will be appended.\n" - }, - { - "name": "append.querystring", - "required": false, - "datatype": "array of string elements", - "description": "List of `queryname:value` pairs. If the querystring is not set, set it with the given value. If it is already set, a new querystring with the same name and the new value will be set." - }, - { - "name": "append.body", - "required": false, - "datatype": "array of string elements", - "description": "List of `paramname:value` pairs. If the content-type is one the following\n[`application/json`, `application/x-www-form-urlencoded`], add a new parameter\nwith the given value if the parameter is not present. Otherwise, if it is already present,\naggregate the two values (old and new) in an array.\n" - } - ], - "request-validator": [ - { - "name": "body_schema", - "required": "semi", - "value_in_examples": "'[{\"name\":{\"type\": \"string\", \"required\": true}}]'", - "datatype": "string", - "description": "The request body schema specification. One of `body_schema` or `parameter_schema`\nmust be specified.\n" - }, - { - "name": "allowed_content_types", - "required": true, - "default": [ - "application/json" - ], - "value_in_examples": null, - "datatype": "Set of string elements", - "description": "List of allowed content types. The value can be configured with the `charset` parameter. For example, `application/json; charset=UTF-8`.\n
**Note:** \nBody validation is only done for `application/json` and skipped for any other allowed content types. \nOnly one parameter is supported at the most. If a request is sending more than one parameter with the Content-Type header, only the first parameter is evaluated and the rest are truncated. Note that `application/json` doesn't match with `application/json; charset=UTF-8`.\nThe type, subtype, parameter names, and the value of the charset parameter are not case sensitive based on the RFC explanation.\n" - }, - { - "name": "version", - "required": true, - "default": "kong", - "value_in_examples": null, - "datatype": "string", - "description": "Which validator to use. Supported values are `kong` (default) for using Kong's own schema\nvalidator, or `draft4` for using a JSON Schema Draft 4-compliant validator.\n" - }, - { - "name": "parameter_schema", - "required": "semi", - "value_in_examples": null, - "datatype": "Array of record elements", - "description": "Array of parameter validator specifications. For details and examples, see\n[Parameter Schema Definition](#parameter-schema-definition). One of `body_schema` or `parameter_schema`\nmust be specified.\n" - }, - { - "name": "verbose_response", - "required": true, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "If enabled, the plugin returns more verbose and detailed validation errors\n(for example, the name of the required field that is missing).\n" - } - ], - "response-ratelimiting": [ - { - "name": "limits.{limit_name}", - "required": true, - "value_in_examples": "", - "datatype": "string", - "description": "This is a list of custom objects that you can set, with arbitrary names set in the `{limit_name`} placeholder, like `config.limits.sms.minute=20` if your object is called \"SMS\"." - }, - { - "name": "limits.{limit_name}.second", - "required": "semi", - "datatype": "number", - "description": "The amount of HTTP requests the developer can make per second. At least one limit must exist." - }, - { - "name": "limits.{limit_name}.minute", - "required": "semi", - "value_in_examples": 10, - "datatype": "number", - "description": "The amount of HTTP requests the developer can make per minute. At least one limit must exist." - }, - { - "name": "limits.{limit_name}.hour", - "required": "semi", - "datatype": "number", - "description": "The amount of HTTP requests the developer can make per hour. At least one limit must exist." - }, - { - "name": "limits.{limit_name}.day", - "required": "semi", - "datatype": "number", - "description": "The amount of HTTP requests the developer can make per day. At least one limit must exist." - }, - { - "name": "limits.{limit_name}.month", - "required": "semi", - "datatype": "number", - "description": "The number of HTTP requests the developer can make per month. A month is defined as a 30-day interval of time, not a calendar month. At least one limit must exist." - }, - { - "name": "limits.{limit_name}.year", - "required": "semi", - "datatype": "number", - "description": "The number of HTTP requests the developer can make per year. A year is defined as a 365-day interval of time, not a calendar year. At least one limit must exist." - }, - { - "name": "header_name", - "required": false, - "default": "`X-Kong-Limit`", - "datatype": "string", - "description": "The name of the response header used to increment the counters." - }, - { - "name": "block_on_first_violation", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "A boolean value that determines if the requests should be blocked as soon as one limit is being exceeded. This will block requests that are supposed to consume other limits too." - }, - { - "name": "limit_by", - "required": false, - "default": "`consumer`", - "datatype": "string", - "description": "The entity that will be used when aggregating the limits: `consumer`, `credential`, `ip`. If the `consumer` or the `credential` cannot be determined, the system will always fallback to `ip`." - }, - { - "name": "policy", - "required": false, - "default": "`local`", - "value_in_examples": "local", - "datatype": "string", - "description": "The rate-limiting policies to use for retrieving and incrementing the\nlimits. Available values are:\n- `local`: Counters are stored locally in-memory on the node.\n- `cluster`: Counters are stored in the Kong datastore and shared across\nthe nodes.\n- `redis`: Counters are stored on a Redis server and shared\nacross the nodes.\n\nIn DB-less, hybrid mode, and Konnect, the `cluster` config policy is not supported.\nFor DB-less mode or Konnect, use one of `redis` or `local`; for hybrid mode, use\n`redis`, or `local` for data planes only.\n\nFor details on which policy should be used, refer to the\n[implementation considerations](/hub/kong-inc/rate-limiting/#implementation-considerations).\n" - }, - { - "name": "fault_tolerant", - "required": true, - "default": "`true`", - "datatype": "boolean", - "description": "A boolean value that determines if the requests should be proxied even if Kong has troubles connecting a third-party datastore. If `true`, requests will be proxied anyway, effectively disabling the rate-limiting function until the datastore is working again. If `false`, then the clients will see `500` errors." - }, - { - "name": "hide_client_headers", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Optionally hide informative response headers." - }, - { - "name": "redis_host", - "required": "semi", - "datatype": "string", - "description": "When using the `redis` policy, this property specifies the address to the Redis server." - }, - { - "name": "redis_port", - "required": false, - "default": "`6379`", - "datatype": "integer", - "description": "When using the `redis` policy, this property specifies the port of the Redis server." - }, - { - "name": "redis_username", - "minimum_version": "2.8.x", - "required": false, - "datatype": "string", - "referenceable": true, - "description": "When using the `redis` policy, this property specifies the username to connect to the Redis server when ACL authentication is desired.\n\nThis requires Redis v6.0.0+. The username **cannot** be set to `default`.\n" - }, - { - "name": "redis_password", - "required": false, - "datatype": "string", - "referenceable": true, - "description": "When using the `redis` policy, this property specifies the password to connect to the Redis server.\n" - }, - { - "name": "redis_timeout", - "required": false, - "default": "`2000`", - "datatype": "number", - "description": "When using the `redis` policy, this property specifies the timeout in milliseconds of any command submitted to the Redis server." - }, - { - "name": "redis_database", - "required": false, - "default": "`0`", - "datatype": "number", - "description": "When using the `redis` policy, this property specifies Redis database to use." - }, - { - "name": "redis_ssl", - "minimum_version": "3.1.x", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "When using the `redis` policy, this property specifies if SSL is used to connect to the Redis server.\n" - }, - { - "name": "redis_ssl_verify", - "minimum_version": "3.1.x", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "When using the `redis` policy with `redis_ssl` set to `true`, this property specifies if the server SSL certificate is validated. Note that you need to configure the `lua_ssl_trusted_certificate` to specify the CA (or server) certificate used by your Redis server. You may also need to configure `lua_ssl_verify_depth` accordingly.\n" - }, - { - "name": "redis_server_name", - "minimum_version": "3.1.x", - "required": false, - "datatype": "string", - "description": "When using the `redis` policy with `redis_ssl` set to `true`, this property specifies the server name for the TLS extension Server Name Indication (SNI) \n" - } - ], - "response-transformer-advanced": [ - { - "name": "remove.headers", - "required": false, - "value_in_examples": [ - "x-toremove", - "x-another-one:application/json", - "x-list-of-values:v1,v2,v3", - "Set-Cookie:/JSESSIONID=.*/", - "x-another-regex://status/$/", - "x-one-more-regex:/^/begin//" - ], - "datatype": "array of string elements", - "description": "List of `headername[:value]`. If only `headername` is given, unset the header field with the given `headername`. If `headername:value` is given, unset the header field `headername` when it has a specific `value`. If `value` starts and ends with a `/` (slash character), then it is considered to be a regular expression. Note that in accordance with [RFC 7230](https://httpwg.org/specs/rfc7230.html#field.order) multiple header values with the same header name are allowed if the entire field value for that header field is defined as a comma-separated list or the header field is a `Set-Cookie` header field." - }, - { - "name": "remove.json", - "required": false, - "datatype": "array of string elements", - "value_in_examples": [ - "json-key-toremove", - "another-json-key" - ], - "description": "List of property names. Remove the property from the JSON body if it is present." - }, - { - "name": "remove.if_status", - "required": false, - "datatype": "array of string elements", - "description": "List of response status codes or status code ranges to which the transformation will apply. Empty means all response codes." - }, - { - "name": "rename.headers", - "required": false, - "datatype": "array of string elements", - "description": "List of `headername1:headername2` pairs. If a header with `headername1` exists and `headername2` is valid, rename header to `headername2`." - }, - { - "name": "rename.if_status", - "required": false, - "datatype": "array of string elements", - "description": "List of response status codes or status code ranges to which the transformation will apply. Empty means all response codes." - }, - { - "name": "replace.headers", - "required": false, - "datatype": "array of string elements", - "description": "List of `headername:value` pairs. If and only if the header is already set, replace its old value with the new one. Ignored if the header is not already set." - }, - { - "name": "replace.json", - "required": false, - "datatype": "array of string elements", - "description": "List of property `name:value` pairs. If and only if the parameter is already present, replace its old value with the new one. Ignored if the parameter is not already present." - }, - { - "name": "replace.json_types", - "required": false, - "datatype": "array of string, boolean, or number elements", - "description": "List of JSON type names. Specify the types of the JSON values returned when replacing JSON properties." - }, - { - "name": "replace.body", - "required": false, - "datatype": "string", - "description": "String with which to replace the entire response body." - }, - { - "name": "replace.if_status", - "required": false, - "datatype": "array of string elements", - "description": "List of response status codes or status code ranges to which the transformation will apply. Empty means all response codes." - }, - { - "name": "add.headers", - "required": false, - "value_in_examples": [ - "x-new-header:value", - "x-another-header:something" - ], - "datatype": "array of string elements", - "description": "List of `headername:value` pairs. If and only if the header is not already set, set a new header with the given value. Ignored if the header is already set." - }, - { - "name": "add.json", - "required": false, - "value_in_examples": [ - "new-json-key:some_value", - "another-json-key:some_value" - ], - "datatype": "array of string elements", - "description": "List of `name:value` pairs. If and only if the property is not present, add a new property with the given value to the JSON body. Ignored if the property is already present." - }, - { - "name": "add.json_types", - "required": false, - "value_in_examples": [ - "new-json-key:string", - "another-json-key:boolean", - "another-json-key:number" - ], - "datatype": "array of string, boolean, or number elements", - "description": "List of JSON type names. Specify the types of the JSON values returned when adding a new JSON property." - }, - { - "name": "add.if_status", - "required": false, - "datatype": "array of string elements", - "description": "List of response status codes or status code ranges to which the transformation will apply. Empty means all response codes." - }, - { - "name": "append.headers", - "required": false, - "value_in_examples": [ - "x-existing-header:some_value", - "x-another-header:some_value" - ], - "datatype": "array of string elements", - "description": "List of `headername:value` pairs. If the header is not set, set it with the given value. If it is already set, a new header with the same name and the new value will be set." - }, - { - "name": "append.json", - "required": false, - "datatype": "array of string elements", - "description": "List of `name:value` pairs. If the property is not present in the JSON body, add it with the given value. If it is already present, the two values (old and new) will be aggregated in an array." - }, - { - "name": "append.json_types", - "required": false, - "datatype": "array of string, boolean, or number elements", - "description": "List of JSON type names. Specify the types of the JSON values returned when appending JSON properties." - }, - { - "name": "append.if_status", - "required": false, - "datatype": null, - "description": "List of response status codes or status code ranges to which the transformation will apply. Empty means all response codes." - }, - { - "name": "allow.json", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "array of string elements", - "description": "Set of parameter names. Only allowed parameters are present in the JSON response body.\n" - }, - { - "name": "transform.functions", - "required": false, - "datatype": "array of function elements", - "description": "Set of Lua functions to perform arbitrary transforms in a response JSON body." - }, - { - "name": "transform.if_status", - "required": false, - "datatype": "array of string elements", - "description": "List of response status codes or ranges to which the arbitrary transformation applies. Leaving empty implies that the transformations apply to all response codes." - }, - { - "name": "transform.json", - "required": false, - "datatype": "array of string elements", - "description": "Apply Lua functions to a particular list of JSON property `name` or `name:value` pairs." - }, - { - "name": "dots_in_keys", - "required": false, - "datatype": "boolean", - "default": true, - "description": "Whether dots (for example, `customers.info.phone`) should be treated as part of a property name or used to descend into nested JSON objects. See [Arrays and nested objects](#arrays-and-nested-objects)." - } - ], - "response-transformer": [ - { - "name": "remove.headers", - "required": false, - "value_in_examples": [ - "x-toremove", - "x-another-one" - ], - "datatype": "array of string elements", - "description": "List of header names. Unset the header(s) with the given name." - }, - { - "name": "remove.json", - "required": false, - "value_in_examples": [ - "json-key-toremove", - "another-json-key" - ], - "datatype": "array of string elements", - "description": "List of property names. Remove the property from the JSON body if it is present." - }, - { - "name": "rename.headers", - "required": false, - "datatype": "array of string elements", - "description": "List of `original_header_name:new_header_name` pairs. If the header `original_headername` is already set, rename it to `new_headername`. Ignored if the header is not already set." - }, - { - "name": "replace.headers", - "required": false, - "datatype": "array of string elements", - "description": "List of `headername:value` pairs. If and only if the header is already set, replace its old value with the new one. Ignored if the header is not already set." - }, - { - "name": "replace.json", - "required": false, - "datatype": "array of string elements", - "description": "List of `property:value` pairs. If and only if the parameter is already present, replace its old value with the new one. Ignored if the parameter is not already present." - }, - { - "name": "replace.json_types", - "required": false, - "datatype": "array of string elements", - "description": "List of JSON type names. Specify the types of the JSON values returned when\nreplacing JSON properties. Each string\nelement can be one of: boolean, number, or string.\n" - }, - { - "name": "add.headers", - "required": false, - "value_in_examples": [ - "x-new-header:value", - "x-another-header:something" - ], - "datatype": "array of string elements", - "description": "List of `headername:value` pairs. If and only if the header is not already set, set a new header with the given value. Ignored if the header is already set." - }, - { - "name": "add.json", - "required": false, - "value_in_examples": [ - "new-json-key:some_value", - "another-json-key:some_value" - ], - "datatype": "array of string elements", - "description": "List of `property:value` pairs. If and only if the property is not present, add a new property with the given value to the JSON body. Ignored if the property is already present." - }, - { - "name": "add.json_types", - "required": false, - "value_in_examples": [ - "new-json-key:string", - "another-json-key:boolean", - "another-json-key:number" - ], - "datatype": "array of string elements", - "description": "List of JSON type names. Specify the types of the JSON values returned when adding\na new JSON property. Each string element can be one of: boolean, number, or string.\n" - }, - { - "name": "append.headers", - "required": false, - "value_in_examples": [ - "x-existing-header:some_value", - "x-another-header:some_value" - ], - "datatype": "array of string elements", - "description": "List of `headername:value` pairs. If the header is not set, set it with the given value. If it is\nalready set, a new header with the same name and the new value will be set. Each string\nelement can be one of: boolean, number, or string.\n" - }, - { - "name": "append.json", - "required": false, - "datatype": "array of string elements", - "description": "List of `property:value` pairs. If the property is not present in the JSON body, add it with the given value. If it is already present, the two values (old and new) will be aggregated in an array." - }, - { - "name": "append.json_types", - "required": false, - "datatype": "array of string elements", - "description": "List of JSON type names. Specify the types of the JSON values returned when appending\nJSON properties. Each string element can be one of: boolean, number, or string.\n" - } - ], - "route-by-header": [ - { - "name": "rules", - "required": false, - "default": {}, - "value_in_examples": null, - "description": "List of [rules](#rules)\n" - } - ], - "route-transformer-advanced": [ - { - "name": "path", - "required": "semi", - "value_in_examples": [ - "/path" - ], - "datatype": "string", - "description": "Updates the upstream request path with given value/template. This value can only be used to update the path part of the URI, not the scheme, nor the hostname. One of `config.path` or `config.host` or `config.port` must be specified.\n" - }, - { - "name": "host", - "required": "semi", - "datatype": "string", - "description": "Updates the upstream request Host with given value/template. This value can only be used to update the routing, it will not update the Host-header value. One of `config.path` or `config.host` or `config.port` must be specified.\n" - }, - { - "name": "port", - "required": "semi", - "datatype": "string", - "description": "Updates the upstream request Port with given value/template. Note that the port as set may be overridden again by DNS resolution (in case of SRV records,or an Upstream) One of `config.path` or `config.host` or `config.port` must be specified.\n" - }, - { - "name": "escape_path", - "required": false, - "datatype": "boolean", - "default": false, - "description": "If set to true, the path is escaped after being transformed.\n", - "minimum_version": "3.1.x" - } - ], - "saml": [ - { - "name": "anonymous", - "required": false, - "default": null, - "value_in_examples": "anonymous", - "datatype": "string", - "description": "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." - }, - { - "name": "assertion_consumer_path", - "required": true, - "datatype": "url", - "default": null, - "value_in_examples": "", - "description": "The relative path the SAML IdP provider uses when responding with an authentication response.\n" - }, - { - "name": "idp_sso_url", - "required": true, - "datatype": "url", - "default": null, - "value_in_examples": "", - "description": "The Single Sign-On URL exposed by the IdP provider. This is where SAML requests are posted. The IdP provides this information.\n" - }, - { - "name": "idp_certificate", - "required": true, - "datatype": "string", - "default": null, - "referenceable": true, - "description": "The public certificate provided by the IdP. This is used to validate responses from the IdP.\n\nOnly include the contents of the certificate. Do not include the header (`BEGIN CERTIFICATE`) and footer (`END CERTIFICATE`) lines.\n" - }, - { - "name": "encryption_key", - "required": false, - "datatype": "string", - "default": null, - "referenceable": true, - "description": "The private encryption key required to decrypt encrypted assertions.\n" - }, - { - "name": "request_signing_key", - "required": false, - "datatype": "string", - "default": null, - "referenceable": true, - "description": "The private key for signing requests. If this parameter is\nset, requests sent to the IdP are signed. The\n`request_signing_certificate` parameter must be set as well.\n" - }, - { - "name": "request_signing_certificate", - "required": false, - "datatype": "string", - "default": null, - "referenceable": true, - "description": "The certificate for signing requests.\n" - }, - { - "name": "request_signature_algorithm", - "required": false, - "datatype": "string", - "default": "SHA256", - "description": "The signature algorithm for signing Authn requests. Options available are:\n- `SHA256`\n- `SHA384`\n- `SHA512`\n" - }, - { - "name": "request_digest_algorithm", - "required": false, - "datatype": "string", - "default": "SHA256", - "description": "The digest algorithm for Authn requests:\n- `SHA256`\n- `SHA1`\n" - }, - { - "name": "response_signature_algorithm", - "required": false, - "datatype": "string", - "default": "SHA256", - "description": "The algorithm for validating signatures in SAML responses. Options available are:\n- `SHA256`\n- `SHA384`\n- `SHA512`\n" - }, - { - "name": "response_digest_algorithm", - "required": false, - "datatype": "string", - "default": "SHA256", - "description": "The algorithm for verifying digest in SAML responses:\n- `SHA256`\n- `SHA1`\n" - }, - { - "name": "issuer", - "required": true, - "datatype": "string", - "default": null, - "description": "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.\n" - }, - { - "name": "nameid_format", - "required": false, - "datatype": "string", - "default": "EmailAddress", - "description": "The requested `NameId` format. Options available are:\n- `Unspecified`\n- `EmailAddress`\n- `Persistent`\n- `Transient`\n" - }, - { - "name": "validate_assertion_signature", - "required": false, - "datatype": "boolean", - "default": true, - "value_in_examples": true, - "description": "Enable signature validation for SAML responses.\n" - }, - { - "group": "Session cookie", - "description": "Parameters used with session cookie authentication." - }, - { - "name": "session_cookie_name", - "required": false, - "default": "session", - "datatype": "string", - "description": "The session cookie name." - }, - { - "name": "session_cookie_lifetime", - "maximum_version": "3.1.x", - "required": false, - "default": 3600, - "datatype": "integer", - "description": "The session cookie lifetime in seconds." - }, - { - "name": "session_rolling_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 3600, - "datatype": "integer", - "description": "The session cookie rolling timeout in seconds.\nSpecifies how long the session can be used until it needs to be renewed.\n" - }, - { - "name": "session_absolute_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 86400, - "datatype": "integer", - "description": "The session cookie absolute timeout in seconds.\nSpecifies how long the session can be used until it is no longer valid.\n" - }, - { - "name": "session_cookie_idletime", - "maximum_version": "3.1.x", - "required": false, - "default": null, - "datatype": "integer", - "description": "The session cookie idle time in seconds." - }, - { - "name": "session_idling_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 900, - "datatype": "integer", - "description": "The session cookie idle time in seconds." - }, - { - "name": "session_cookie_renew", - "maximum_version": "3.1.x", - "required": false, - "default": 600, - "datatype": "integer", - "description": "The session cookie renew time in seconds." - }, - { - "name": "session_cookie_path", - "required": false, - "default": "/", - "datatype": "string", - "description": "The session cookie path flag." - }, - { - "name": "session_cookie_domain", - "required": false, - "default": null, - "datatype": "string", - "description": "The session cookie domain flag." - }, - { - "name": "session_cookie_samesite", - "maximum_version": "3.1.x", - "required": false, - "default": "Lax", - "datatype": "string", - "description": "Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks:\n- `Strict`: Cookies will only be sent in a first-party context and not be sent along with requests initiated by third party websites.\n- `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.\n- `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.\n- `off`: Do not set the Same-Site flag.\n" - }, - { - "name": "session_cookie_same_site", - "minimum_version": "3.2.x", - "required": false, - "default": "Lax", - "datatype": "string", - "description": "Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks:\n- `Strict`: Cookies will only be sent in a first-party context and aren't sent along with requests initiated by third party websites.\n- `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.\n- `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.\n- `Default`: Do not explicitly specify a Same-Site attribute.\n" - }, - { - "name": "session_cookie_httponly", - "maximum_version": "3.1.x", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Forbids JavaScript from accessing the cookie, for example, through the `Document.cookie` property." - }, - { - "name": "session_cookie_http_only", - "minimum_version": "3.2.x", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Forbids JavaScript from accessing the cookie, for example, through the `Document.cookie` property." - }, - { - "name": "session_cookie_secure", - "required": false, - "default": "(from the request scheme)", - "datatype": "boolean", - "description": "The cookie is only sent to the server when a request is made with the https:scheme (except on localhost),\nand therefore is more resistant to man-in-the-middle attacks.\n" - }, - { - "name": "session_cookie_maxsize", - "maximum_version": "3.1.x", - "required": false, - "default": 4000, - "datatype": "integer", - "description": "The maximum size of each cookie in bytes." - }, - { - "group": "Session Settings" - }, - { - "name": "session_secret", - "required": true, - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "The session secret. This must be a random string of 32\ncharacters from the base64 alphabet (letters, numbers, `/`, `_`\nand `+`). It is used as the secret key for encrypting session\ndata as well as state information that is sent to the IdP in\nthe authentication exchange.\n" - }, - { - "name": "session_strategy", - "maximum_version": "3.1.x", - "required": false, - "default": "default", - "datatype": "string", - "description": "The session strategy:\n- `default`: reuses session identifiers over modifications (but can be problematic with single-page applications with a lot of concurrent asynchronous requests)\n- `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.\n" - }, - { - "name": "session_compressor", - "maximum_version": "3.1.x", - "required": false, - "default": "none", - "datatype": "string", - "description": "The session strategy:\n- `none`: no compression.\n- `zlib`: use Zlib to compress cookie data.\n" - }, - { - "name": "session_audience", - "minimum_version": "3.2.x", - "required": false, - "default": "\"default\"", - "datatype": "string", - "description": "The session audience, for example \"my-application\"" - }, - { - "name": "session_remember", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Enables or disables persistent sessions" - }, - { - "name": "session_remember_cookie_name", - "minimum_version": "3.2.x", - "required": false, - "default": "\"remember\"", - "datatype": "string", - "description": "Persistent session cookie name" - }, - { - "name": "session_remember_rolling_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 604800, - "datatype": "integer", - "description": "Persistent session rolling timeout in seconds." - }, - { - "name": "session_remember_absolute_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 2592000, - "datatype": "integer", - "description": "Persistent session absolute timeout in seconds." - }, - { - "name": "session_request_headers", - "minimum_version": "3.2.x", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "List of information to include (as headers) in the request to upstream. \nAccepted values are: `id`, `audience`, `subject`, `timeout`, `idling-timeout`, `rolling-timeout`, and\n`absolute-timeout`.\nFor example, { \"id\", \"timeout\" } will set both `Session-Id` and `Session-Timeout` in the request headers.\n" - }, - { - "name": "session_response_headers", - "minimum_version": "3.2.x", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "List of information to include (as headers) in the response to downstream. \nAccepted values are: `id`, `audience`, `subject`, `timeout`, `idling-timeout`, `rolling-timeout`, and\n`absolute-timeout`.\nFor example: { \"id\", \"timeout\" } will inject both `Session-Id` and `Session-Timeout` in the response headers.\n" - }, - { - "name": "session_store_metadata", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Configures whether or not session metadata should be stored.\nThis includes information about the active sessions for the `specific_audience`\nbelonging to a specific subject.\n" - }, - { - "name": "session_enforce_same_subject", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "When set to `true`, audiences are forced to share the same subject." - }, - { - "name": "session_hash_subject", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "When set to `true`, the value of subject is hashed before being stored.\nOnly applies when `session_store_metadata` is enabled.\n" - }, - { - "name": "session_hash_storage_key", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "When set to `true`, the storage key (session ID) is hashed for extra security.\nHashing the storage key means it is impossible to decrypt data from the storage\nwithout a cookie.\n" - }, - { - "name": "session_storage", - "required": false, - "default": "cookie", - "datatype": "string", - "description": "The session storage for session data:\n- `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.\n- `memcached`: stores session data in memcached\n- `redis`: stores session data in Redis\n" - }, - { - "name": "reverify", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Specifies whether to always verify tokens stored in the session." - }, - { - "group": "Session Settings for Memcached" - }, - { - "name": "session_memcache_prefix", - "maximum_version": "3.1.x", - "required": false, - "default": "sessions", - "datatype": "string", - "description": "The memcached session key prefix." - }, - { - "name": "session_memcached_prefix", - "minimum_version": "3.2.x", - "required": false, - "default": "\"sessions\"", - "datatype": "string", - "description": "The memcached session key prefix." - }, - { - "name": "session_memcache_socket", - "maximum_version": "3.1.x", - "required": false, - "default": null, - "datatype": "string", - "description": "The memcached unix socket path." - }, - { - "name": "session_memcached_socket", - "minimum_version": "3.2.x", - "required": false, - "default": null, - "datatype": "string", - "description": "The memcached unix socket path." - }, - { - "name": "session_memcache_host", - "maximum_version": "3.1.x", - "required": false, - "default": "127.0.0.1", - "datatype": "string", - "description": "The memcached host." - }, - { - "name": "session_memcached_host", - "minimum_version": "3.2.x", - "required": false, - "default": "\"127.0.0.1\"", - "datatype": "string", - "description": "The memcached host." - }, - { - "name": "session_memcache_port", - "maximum_version": "3.1.x", - "required": false, - "default": 11211, - "datatype": "integer", - "description": "The memcached port." - }, - { - "name": "session_memcached_port", - "minimum_version": "3.2.x", - "required": false, - "default": 11211, - "datatype": "integer", - "description": "The memcached port." - }, - { - "group": "Session Settings for Redis" - }, - { - "name": "session_redis_prefix", - "required": false, - "default": "sessions", - "datatype": "string", - "description": "The Redis session key prefix." - }, - { - "name": "session_redis_socket", - "required": false, - "default": null, - "datatype": "string", - "description": "The Redis unix socket path." - }, - { - "name": "session_redis_host", - "required": false, - "default": "127.0.0.1", - "datatype": "string", - "description": "The Redis host IP." - }, - { - "name": "session_redis_port", - "required": false, - "default": 6379, - "datatype": "integer", - "description": "The Redis port." - }, - { - "name": "session_redis_username", - "required": false, - "default": null, - "datatype": "string", - "referenceable": true, - "description": "Redis username if the `redis` session storage is defined and ACL authentication is desired.\nIf undefined, ACL authentication will not be performed.\n\nThis requires Redis v6.0.0+. The username **cannot** be set to `default`.\n" - }, - { - "name": "session_redis_password", - "required": false, - "default": "(from kong)", - "encrypted": true, - "datatype": "string", - "referenceable": true, - "description": "Password to use for Redis connection when the `redis` session storage is defined.\nIf undefined, no auth commands are sent to Redis. This value is pulled from\n" - }, - { - "name": "session_redis_connect_timeout", - "required": false, - "default": "(from kong)", - "datatype": "integer", - "description": "The Redis connection timeout in milliseconds." - }, - { - "name": "session_redis_read_timeout", - "required": false, - "default": "(from kong)", - "datatype": "integer", - "description": "The Redis read timeout in milliseconds." - }, - { - "name": "session_redis_send_timeout", - "required": false, - "default": "(from kong)", - "datatype": "integer", - "description": "The Redis send timeout in milliseconds." - }, - { - "name": "session_redis_ssl", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Use SSL/TLS for the Redis connection." - }, - { - "name": "session_redis_ssl_verify", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Verify the Redis server certificate." - }, - { - "name": "session_redis_server_name", - "required": false, - "default": null, - "datatype": "string", - "description": "The SNI used for connecting to the Redis server." - }, - { - "name": "session_redis_cluster_nodes", - "required": false, - "default": null, - "datatype": "array of host records", - "description": "The Redis cluster node host. Takes an array of host records, with\neither `ip` or `host`, and `port` values.\n" - }, - { - "name": "session_redis_cluster_maxredirections", - "maximum_version": "3.1.x", - "required": false, - "default": null, - "datatype": "integer", - "description": "The Redis cluster's maximum redirects." - }, - { - "name": "session_redis_cluster_max_redirections", - "minimum_version": "3.2.x", - "required": false, - "default": null, - "datatype": "integer", - "description": "The Redis cluster maximum redirects." - } - ], - "serverless-functions": [ - { - "name": "functions", - "required": false, - "default": "[]", - "value_in_examples": "[]", - "datatype": "array", - "description": "*Deprecated*. Use `config.access` instead.\n\nArray of stringified Lua code to be cached and run in sequence during access phase.\n", - "maximum_version": "2.8.x" - }, - { - "name": "certificate", - "required": false, - "default": "[]", - "value_in_examples": "[]", - "datatype": "array", - "description": "Array of stringified Lua code to be cached and run in sequence during the certificate phase.\n\n*Note*: This only runs on global plugins.\n" - }, - { - "name": "rewrite", - "required": false, - "default": "[]", - "value_in_examples": "[]", - "datatype": "array", - "description": "Array of stringified Lua code to be cached and run in sequence during the rewrite phase.\n\n*Note*: This only runs on global plugins.\n" - }, - { - "name": "access", - "required": false, - "default": "[]", - "value_in_examples": "[]", - "datatype": "array", - "description": "Array of stringified Lua code to be cached and run in sequence during the access phase." - }, - { - "name": "header_filter", - "required": false, - "default": "[]", - "value_in_examples": "[]", - "datatype": "array", - "description": "Array of stringified Lua code to be cached and run in sequence during the header_filter phase." - }, - { - "name": "body_filter", - "required": false, - "default": "[]", - "value_in_examples": "[]", - "datatype": "array", - "description": "Array of stringified Lua code to be cached and run in sequence during the body_filter phase." - }, - { - "name": "log", - "required": false, - "default": "[]", - "value_in_examples": "[]", - "datatype": "array", - "description": "Array of stringified Lua code to be cached and run in sequence during the log phase." - } - ], - "session": [ - { - "name": "secret", - "required": false, - "default": "random number generated from `kong.utils.random_string`", - "value_in_examples": "opensesame", - "datatype": "string", - "encrypted": true, - "referenceable": true, - "description": "The secret that is used in keyed HMAC generation.​\n" - }, - { - "name": "audience", - "minimum_version": "3.2.x", - "required": false, - "default": "\"default\"", - "datatype": "string", - "description": "The session audience, which is the intended target application. For example `\"my-application\"`." - }, - { - "name": "remember", - "minimum_version": "3.2.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Enables or disables persistent sessions." - }, - { - "name": "remember_cookie_name", - "minimum_version": "3.2.x", - "required": false, - "default": "\"remember\"", - "datatype": "string", - "description": "Persistent session cookie name. Use with the `remember` configuration parameter." - }, - { - "name": "remember_rolling_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 604800, - "datatype": "integer", - "description": "The persistent session rolling timeout window, in seconds." - }, - { - "name": "remember_absolute_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 2592000, - "datatype": "integer", - "description": "The persistent session absolute timeout limit, in seconds." - }, - { - "name": "request_headers", - "minimum_version": "3.2.x", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "List of information to include, as headers, in the request to the upstream.\n\nAccepted values are: `id`, `audience`, `subject`, `timeout`, `idling-timeout`, `rolling-timeout`, and\n`absolute-timeout`.\n\nFor example, `{ \"id\", \"timeout\" }` sets both `Session-Id` and `Session-Timeout` in the request headers.\n" - }, - { - "name": "response_headers", - "minimum_version": "3.2.x", - "required": false, - "default": null, - "datatype": "array of string elements", - "description": "List of information to include, as headers, in the response to the downstream.\n\nAccepted values are: `id`, `audience`, `subject`, `timeout`, `idling-timeout`, `rolling-timeout`, and\n`absolute-timeout`.\n\nFor example: `{ \"id\", \"timeout\" }` injects both `Session-Id` and `Session-Timeout` in the response headers.\n" - }, - { - "name": "cookie_name", - "required": false, - "default": "`session`", - "datatype": "string", - "description": "The name of the cookie." - }, - { - "name": "cookie_lifetime", - "maximum_version": "3.1.x", - "required": false, - "default": 3600, - "datatype": "number", - "description": "The duration in seconds that the session will remain open." - }, - { - "name": "rolling_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 3600, - "datatype": "integer", - "description": "The session cookie rolling timeout, in seconds.\nSpecifies how long the session can be used until it needs to be renewed.\n" - }, - { - "name": "absolute_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 86400, - "datatype": "integer", - "description": "The session cookie absolute timeout, in seconds.\nSpecifies how long the session can be used until it is no longer valid.\n" - }, - { - "name": "cookie_idletime", - "maximum_version": "3.1.x", - "required": false, - "datatype": "number", - "description": "The cookie idle time (in seconds); if a cookie is not used for this time\nperiod, the session becomes invalid. This value is not set by default,\nmeaning idle time checks are disabled.\n" - }, - { - "name": "idling_timeout", - "minimum_version": "3.2.x", - "required": false, - "default": 900, - "datatype": "integer", - "description": "The session cookie idle time, in seconds." - }, - { - "name": "cookie_renew", - "maximum_version": "3.1.x", - "required": false, - "default": 600, - "datatype": "number", - "description": "The remaining duration in seconds of a session at which point the Plugin renews the session." - }, - { - "name": "cookie_path", - "required": false, - "default": "/", - "datatype": "string", - "description": "The resource in the host where the cookie is available." - }, - { - "name": "cookie_domain", - "required": false, - "default": "Set using Nginx variable host, but may be overridden", - "datatype": "string", - "description": "The domain with which the cookie is intended to be exchanged." - }, - { - "name": "cookie_samesite", - "maximum_version": "3.1.x", - "required": false, - "default": "Strict", - "datatype": "string", - "description": "Determines whether and how a cookie may be sent with cross-site requests. \n\n* `Strict`: The browser sends cookies only if the request originated from the website that set the cookie.\n* `Lax`: Same-site cookies are withheld on cross-domain subrequests, but are sent when a user navigates\nto the URL from an external site, for example, by following a link. \n* `None` or `off`: Disables the same-site attribute so that a cookie may be sent with cross-site requests. \n`None` requires the Secure attribute (`cookie_secure`) in latest browser versions. For more information, \nsee the [SameSite cookies docs on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite).\n" - }, - { - "name": "cookie_same_site", - "minimum_version": "3.2.x", - "required": false, - "default": "Strict", - "datatype": "string", - "description": "Determines whether and how a cookie may be sent with cross-site requests.\n\n* `Strict`: The browser sends cookies only if the request originated from the website that set the cookie.\n* `Lax`: Same-site cookies are withheld on cross-domain subrequests, but are sent when a user navigates\nto the URL from an external site, for example, by following a link. \n* `None` or `off`: Disables the same-site attribute so that a cookie may be sent with cross-site requests. \n`None` requires the Secure attribute (`cookie_secure`) in latest browser versions. For more info, see the\n[SameSite cookies docs on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite).\n" - }, - { - "name": "cookie_httponly", - "maximum_version": "3.1.x", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Applies the `HttpOnly` tag so that the cookie is sent only to a server. See the\n[Restrict access to cookies docs on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Restrict_access_to_cookies).\n" - }, - { - "name": "cookie_http_only", - "minimum_version": "3.2.x", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Applies the `HttpOnly` tag so that the cookie is sent only to a server. See the\n[Restrict access to cookies docs on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Restrict_access_to_cookies).\n" - }, - { - "name": "cookie_secure", - "required": false, - "default": true, - "datatype": "boolean", - "description": "Applies the Secure directive so that the cookie may be sent to the server only with an encrypted\nrequest over the HTTPS protocol. See the\n[Restrict access to cookies docs on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Restrict_access_to_cookies).\n" - }, - { - "name": "cookie_discard", - "maximum_version": "3.1.x", - "required": false, - "default": 10, - "datatype": "number", - "description": "The duration in seconds after which an old session’s TTL is updated that an old cookie is discarded." - }, - { - "name": "stale_ttl", - "minimum_version": "3.2.x", - "required": false, - "default": 10, - "datatype": "number", - "description": "The duration, in seconds, after which an old cookie is discarded, starting from the moment\nwhen the session becomes outdated and is replaced by a new one.\n" - }, - { - "name": "cookie_persistent", - "minimum_version": "3.1.x", - "required": false, - "default": false, - "datatype": "boolean", - "description": "Allows the browser to persist cookies even if the browser is closed.\nBy default, cookies are not persisted across browser restarts.\n" - }, - { - "name": "storage", - "required": false, - "default": "cookie", - "datatype": "string", - "description": "Determines where the session data is stored. `kong`: Stores encrypted session data into Kong's current database\nstrategy; the cookie will not contain any session data. `cookie`: Stores encrypted\nsession data within the cookie itself.\n" - }, - { - "name": "logout_methods", - "required": false, - "default": "[`\"POST\"`, `\"DELETE\"`]", - "datatype": "array of string elements", - "description": "The methods that may be used to end sessions: POST, DELETE, GET.\n" - }, - { - "name": "logout_query_arg", - "required": false, - "default": "session_logout", - "datatype": "string", - "description": "The query argument passed to logout requests." - }, - { - "name": "logout_post_arg", - "required": false, - "default": "session_logout", - "datatype": "string", - "description": "The POST argument passed to logout requests. Do not change this property." - } - ], - "statsd-advanced": [ - { - "name": "host", - "required": true, - "default": "`127.0.0.1`", - "value_in_examples": "127.0.0.1", - "datatype": "string", - "description": "The IP address or hostname of the StatsD server." - }, - { - "name": "port", - "required": true, - "default": "`8125`", - "value_in_examples": 8125, - "datatype": "integer", - "description": "The port of the StatsD server." - }, - { - "name": "metrics", - "required": true, - "default": "All metrics are logged.", - "datatype": "Array of record elements.", - "description": "List of Metrics to be logged. Available values are described under [Metrics](#metrics).\n" - }, - { - "name": "prefix", - "required": true, - "default": "`kong`", - "datatype": "string", - "description": "String to prefix to each metric's name." - }, - { - "name": "hostname_in_prefix", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Include the `hostname` in the `prefix` for each metric name." - }, - { - "name": "udp_packet_size", - "required": true, - "default": "`0` (not combined)", - "datatype": "number", - "description": "Combine UDP packet up to the size configured. If zero (0), don't combine the\nUDP packet. Must be a number between 0 and 65507 (inclusive).\n" - }, - { - "name": "use_tcp", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Use TCP instead of UDP." - }, - { - "name": "allow_status_codes", - "required": true, - "default": "All responses are passed to log metrics.", - "value_in_examples": [ - "200-205", - "400-499" - ], - "datatype": "array of string elements.", - "description": "List of status code ranges that are allowed to be logged in metrics." - }, - { - "name": "consumer_identifier_default", - "required": true, - "default": "custom_id", - "datatype": "string", - "description": "The default consumer identifier for metrics. This will take effect when a metric's consumer identifier is omitted. Allowed values are `custom_id`, `consumer_id`, `username`." - }, - { - "name": "service_identifier_default", - "required": true, - "default": "service_name_or_host", - "datatype": "string", - "description": "The default service identifier for metrics. This will take effect when a metric's service identifier is omitted. Allowed values are `service_name_or_host`, `service_id`, `service_name`, `service_host`." - }, - { - "name": "workspace_identifier_default", - "required": true, - "default": "workspace_id", - "datatype": "string", - "description": "The default workspace identifier for metrics. This will take effect when a metric's workspace identifier is omitted. Allowed values are `workspace_id`, `workspace_name`." - } - ], - "statsd": [ - { - "name": "host", - "required": true, - "default": "`127.0.0.1`", - "value_in_examples": "127.0.0.1", - "datatype": "string", - "description": "The IP address or hostname of StatsD server to send data to." - }, - { - "name": "port", - "required": true, - "default": "`8125`", - "value_in_examples": 8125, - "datatype": "integer", - "description": "The port of StatsD server to send data to." - }, - { - "name": "metrics", - "required": true, - "default": "All metrics are logged", - "datatype": "Array of record elements", - "description": "List of metrics to be logged. Available values are described under [Metrics](#metrics).\n" - }, - { - "name": "prefix", - "required": true, - "default": "`kong`", - "datatype": "string", - "description": "String to prefix to each metric's name." - }, - { - "name": "hostname_in_prefix", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Include the `hostname` in the `prefix` for each metric name.", - "minimum_version": "3.0.x" - }, - { - "name": "udp_packet_size", - "required": true, - "default": "`0` (not combined)", - "datatype": "number", - "description": "Combine UDP packet up to the size configured. If zero (0), don't combine the\nUDP packet. Must be a number between 0 and 65507 (inclusive).\n" - }, - { - "name": "use_tcp", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "Use TCP instead of UDP.", - "minimum_version": "3.0.x" - }, - { - "name": "allow_status_codes", - "required": true, - "default": "All responses are passed to log metrics", - "value_in_examples": [ - "200-205", - "400-499" - ], - "datatype": "array of string elements", - "description": "List of status code ranges that are allowed to be logged in metrics.", - "minimum_version": "3.0.x" - }, - { - "name": "consumer_identifier_default", - "required": true, - "default": "custom_id", - "datatype": "string", - "description": "The default consumer identifier of metrics. This takes effect when a metric's consumer identifier is omitted. Allowed values are `custom_id`, `consumer_id`, `username`.", - "minimum_version": "3.0.x" - }, - { - "name": "service_identifier_default", - "required": true, - "default": "service_name_or_host", - "datatype": "string", - "description": "The default service identifier of metrics. This takes effect when a metric's service identifier is omitted. Allowed values are `service_name_or_host`, `service_id`, `service_name`, `service_host`.", - "minimum_version": "3.0.x" - }, - { - "name": "workspace_identifier_default", - "required": true, - "default": "workspace_id", - "datatype": "string", - "description": "The default workspace identifier of metrics. This will take effect when a metric's workspace identifier is omitted. Allowed values are `workspace_id`, `workspace_name`.", - "minimum_version": "3.0.x" - }, - { - "name": "flush_timeout", - "required": true, - "default": "`2`", - "value_in_examples": 2, - "datatype": "number", - "description": "Optional time in seconds. If `queue_size` > 1, this is the max idle time before sending a log with less than `queue_size` records.\n", - "minimum_version": "3.1.x" - }, - { - "name": "retry_count", - "required": true, - "default": 10, - "value_in_examples": 10, - "datatype": "integer", - "description": "Number of times to retry when sending data to the upstream server.", - "minimum_version": "3.1.x" - }, - { - "name": "queue_size", - "required": true, - "default": 1, - "datatype": "integer", - "description": "Maximum number of log entries to be sent on each message to the upstream server.", - "minimum_version": "3.1.x" - }, - { - "name": "tag_style", - "required": false, - "datatype": "string", - "description": "The tag style configurations to send metrics with [tags](https://github.com/prometheus/statsd_exporter#tagging-extensions). Defaults to `nil`, which doesn't add any tags to the metrics. Allowed values are `dogstatsd`, `influxdb`, `librato`, and `signalfx`.", - "minimum_version": "3.2.x" - } - ], - "syslog": [ - { - "name": "successful_severity", - "required": false, - "default": "`info`", - "datatype": "string", - "description": "An optional logging severity assigned to all the successful requests with a response\nstatus code less then 400. Available options: `debug`, `info`, `notice`, `warning`, `err`, `crit`, `alert`, `emerg`.\n" - }, - { - "name": "client_errors_severity", - "required": false, - "default": "`info`", - "datatype": "string", - "description": "An optional logging severity assigned to all the failed requests with a\nresponse status code 400 or higher but less than 500. Available options: `debug`, `info`, `notice`,\n`warning`, `err`, `crit`, `alert`, `emerg`.\n" - }, - { - "name": "server_errors_severity", - "required": false, - "default": "`info`", - "datatype": "string", - "description": "An optional logging severity assigned to all the failed requests with a\nresponse status code 500 or higher. Available options: `debug`, `info`, `notice`, `warning`, `err`, `crit`, `alert`, `emerg`.\n" - }, - { - "name": "log_level", - "required": false, - "default": "`info`", - "datatype": "string", - "description": "An optional logging severity. Any request with equal or higher severity\nwill be logged to System log. Available options: `debug`, `info`, `notice`, `warning`, `err`, `crit`, `alert`, `emerg`.\n" - }, - { - "name": "custom_fields_by_lua", - "minimum_version": "2.4.x", - "required": false, - "default": null, - "datatype": "map", - "description": "A list of key-value pairs, where the key is the name of a log field and\nthe value is a chunk of Lua code, whose return value sets or replaces\nthe log field value.\n" - }, - { - "name": "facility", - "minimum_version": "2.5.x", - "required": false, - "default": "`user`", - "datatype": "string", - "description": "The facility is used by the operating system to decide how to handle each log message. This\noptional argument defines what must be the facility set by the plugin when logging. Available\noptions: `auth`, `authpriv`, `cron`, `daemon`, `ftp`, `kern`, `lpr`, `mail`, `news`, `syslog`,\n`user`, `uucp`, `local0`, `local1`, `local2`, `local3`, `local4`, `local5`, `local6`, `local7`.\n" - } - ], - "tcp-log": [ - { - "name": "host", - "required": true, - "value_in_examples": "127.0.0.1", - "datatype": "string", - "description": "The IP address or host name to send data to." - }, - { - "name": "port", - "required": true, - "value_in_examples": 9999, - "datatype": "integer", - "description": "The port to send data to on the upstream server." - }, - { - "name": "timeout", - "required": false, - "default": "`10000`", - "datatype": "number", - "description": "An optional timeout in milliseconds when sending data to the upstream server." - }, - { - "name": "keepalive", - "required": false, - "default": "`60000`", - "datatype": "number", - "description": "An optional value in milliseconds that defines how long an idle connection lives before being closed." - }, - { - "name": "tls", - "required": true, - "default": false, - "datatype": "boolean", - "description": "Indicates whether to perform a TLS handshake against the remote server." - }, - { - "name": "tls_sni", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string that defines the SNI (Server Name Indication) hostname to send in the TLS handshake." - }, - { - "name": "custom_fields_by_lua", - "minimum_version": "2.4.x", - "required": false, - "default": null, - "datatype": "map", - "description": "A list of key-value pairs, where the key is the name of a log field and\nthe value is a chunk of Lua code, whose return value sets or replaces\nthe log field value.\n" - } - ], - "tls-handshake-modifier": [ - { - "name": "tls_client_certificate", - "required": false, - "default": "REQUEST", - "datatype": "string", - "description": "Indicates the TLS handshake preference. The only option is `REQUEST`, which\nrequests the client certificate.\n" - } - ], - "tls-metadata-headers": [ - { - "name": "inject_client_cert_details", - "required": true, - "default": false, - "datatype": "boolean", - "value_in_examples": true, - "description": "Enables TLS client certificate metadata values to be injected into HTTP headers.\n" - }, - { - "name": "client_cert_header_name", - "required": true, - "default": "X-Client-Cert", - "datatype": "string", - "value_in_examples": "X-Forwarded-Client-Cert", - "description": "Define the HTTP header name used for the PEM format URL encoded client certificate.\n" - }, - { - "name": "client_serial_header_name", - "required": true, - "default": "X-Client-Cert-Serial", - "datatype": "string", - "description": "Define the HTTP header name used for the serial number of the client certificate.\n" - }, - { - "name": "client_cert_issuer_dn_header_name", - "required": true, - "default": "X-Client-Cert-Issuer-DN", - "datatype": "string", - "value_in_examples": null, - "description": "Define the HTTP header name used for the issuer DN of the client certificate.\n" - }, - { - "name": "client_cert_subject_dn_header_name", - "required": true, - "default": "X-Client-Cert-Subject-DN", - "datatype": "string", - "description": "Define the HTTP header name used for the subject DN of the client certificate.\n" - }, - { - "name": "client_cert_fingerprint_header_name", - "required": true, - "default": "X-Client-Cert-Fingerprint", - "datatype": "string", - "description": "Define the HTTP header name used for the SHA1 fingerprint of the client certificate.\n" - } - ], - "udp-log": [ - { - "name": "host", - "required": true, - "value_in_examples": "127.0.0.1", - "datatype": "string", - "description": "The IP address or host name to send data to." - }, - { - "name": "port", - "required": true, - "value_in_examples": 9999, - "datatype": "integer", - "description": "The port to send data to on the upstream server." - }, - { - "name": "timeout", - "required": false, - "default": "`10000`", - "value_in_examples": 10000, - "datatype": "number", - "description": "An optional timeout in milliseconds when sending data to the upstream server." - }, - { - "name": "custom_fields_by_lua", - "minimum_version": "2.4.x", - "required": false, - "default": null, - "datatype": "map", - "description": "A list of key-value pairs, where the key is the name of a log field and\nthe value is a chunk of Lua code, whose return value sets or replaces\nthe log field value.\n" - } - ], - "upstream-timeout": [ - { - "name": "connect_timeout", - "required": false, - "default": null, - "value_in_examples": 4000, - "datatype": "integer", - "description": "The timeout, in milliseconds, for establishing a connection to the upstream server.\nOverrides the service object [`connect_timeout`](/gateway/latest/how-kong-works/routing-traffic/#proxying-and-upstream-timeouts) setting, if the setting exists.\n" - }, - { - "name": "send_timeout", - "required": false, - "default": null, - "value_in_examples": 5000, - "datatype": "integer", - "description": "The timeout, in milliseconds, between two\nsuccessive write operations when sending a request to the upstream server.\nOverrides the service object [`write_timeout`](/gateway/latest/how-kong-works/routing-traffic/#proxying-and-upstream-timeouts) setting, if the setting exists.\n" - }, - { - "name": "read_timeout", - "required": false, - "default": null, - "value_in_examples": 5000, - "datatype": "integer", - "description": "The timeout, in milliseconds, between two\nsuccessive read operations when receiving a response from the upstream server.\nOverrides the service object [`read_timeout`](/gateway/latest/how-kong-works/routing-traffic/#proxying-and-upstream-timeouts) setting, if the setting exists.\n" - } - ], - "vault-auth": [ - { - "name": "access_token_name", - "required": true, - "default": "`access_token`", - "datatype": "array of string elements", - "description": "Describes an array of comma-separated parameter names where the plugin looks for an access token. The client must send the access token in one of those key names, and the plugin will try to read the credential from a header or the querystring parameter with the same name. The key names can only contain [a-z], [A-Z], [0-9], [_], and [-].\n" - }, - { - "name": "vault.id", - "required": true, - "default": null, - "value_in_examples": "", - "datatype": "foreign UUID", - "description": "A reference to an existing `vault` object within the database. `vault` entities define the connection and authentication parameters used to connect to a Vault HTTP(S) API.\n" - }, - { - "name": "secret_token_name", - "required": true, - "default": "`secret_token`", - "datatype": "array of string elements", - "description": "Describes an array of comma-separated parameter names where the plugin looks for a secret token. The client must send the secret in one of those key names, and the plugin will try to read the credential from a header or the querystring parameter with the same name. The key names can only contain [a-z], [A-Z], [0-9], [_], and [-].\n" - }, - { - "name": "tokens_in_body", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "If enabled, the plugin will read the request body (if said request has one and its MIME type is supported) and try to find the key in it. Supported MIME types are `application/www-form-urlencoded`, `application/json`, and `multipart/form-data`.\n" - }, - { - "name": "hide_credentials", - "required": true, - "default": "`false`", - "datatype": "boolean", - "description": "An optional boolean value telling the plugin to show or hide the credential from the upstream service. If `true`, the plugin will strip the credential from the request (i.e. the header or querystring containing the key) before proxying it.\n" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request fails with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.", - "minimum_version": "3.1.x" - }, - { - "name": "anonymous", - "required": false, - "default": null, - "datatype": "string", - "description": "An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails.\nIf empty (default), the request fails with an authentication failure `4xx`. Note that this value\nmust refer to the consumer `id` attribute that is internal to Kong Gateway, and **not** its `custom_id`.\n", - "maximum_version": "3.0.x" - }, - { - "name": "run_on_preflight", - "required": true, - "default": "`true`", - "datatype": "boolean", - "description": "A boolean value that indicates whether the plugin should run (and try to authenticate) on `OPTIONS` preflight requests. If set to `false`, then `OPTIONS` requests will always be allowed.\n" - } - ], - "websocket-size-limit": [ - { - "name": "client_max_payload", - "required": "semi", - "value_in_examples": 1024, - "datatype": "integer", - "default": null, - "encrypted": false, - "description": "Maximum size (in bytes) of client-originated WebSocket messages. Must\nbe greater than `0` and less than `33554432` (32 MiB)\n", - "extra": "Either `client_max_payload` or `upstream_max_payload` is\nrequired.\n" - }, - { - "name": "upstream_max_payload", - "required": "semi", - "value_in_examples": 16384, - "datatype": "integer", - "default": null, - "encrypted": false, - "description": "Maximum size (in bytes) of upstream-originated WebSocket messages. Must\nbe greater than `0` and less than `33554432` (32 MiB)\n", - "extra": "Either `client_max_payload` or `upstream_max_payload` is\nrequired.\n" - } - ], - "websocket-validator": [ - { - "name": "client.text.schema", - "required": "semi", - "default": null, - "datatype": "string", - "encrypted": false, - "value_in_examples": "'{ \"type\": \"object\" }'", - "description": "Schema used to validate client-originated text frames. The semantics of\nthis field depend on the validation type set by `config.client.text.type`.\n" - }, - { - "name": "client.text.type", - "required": "semi", - "default": null, - "datatype": "string", - "encrypted": false, - "value_in_examples": "'draft4'", - "description": "The corresponding validation library for `config.client.text.schema`.\nCurrently, only `draft4` is supported.\n" - }, - { - "name": "client.binary.schema", - "required": "semi", - "default": null, - "datatype": "string", - "encrypted": false, - "value_in_examples": null, - "description": "Schema used to validate client-originated binary frames. The semantics of\nthis field depend on the validation type set by `config.client.binary.type`.\n" - }, - { - "name": "client.binary.type", - "required": "semi", - "default": null, - "datatype": "string", - "encrypted": false, - "value_in_examples": null, - "description": "The corresponding validation library for `config.client.binary.schema`.\nCurrently, only `draft4` is supported.\n" - }, - { - "name": "upstream.text.schema", - "required": "semi", - "default": null, - "datatype": "string", - "encrypted": false, - "value_in_examples": null, - "description": "Schema used to validate upstream-originated text frames. The semantics of\nthis field depend on the validation type set by `config.upstream.text.type`.\n" - }, - { - "name": "upstream.text.type", - "required": "semi", - "default": null, - "datatype": "string", - "encrypted": false, - "value_in_examples": null, - "description": "The corresponding validation library for `config.upstream.text.schema`.\nCurrently, only `draft4` is supported.\n" - }, - { - "name": "upstream.binary.schema", - "required": "semi", - "default": null, - "datatype": "string", - "encrypted": false, - "value_in_examples": null, - "description": "Schema used to validate upstream-originated binary frames. The semantics of\nthis field depend on the validation type set by `config.upstream.binary.type`.\n" - }, - { - "name": "upstream.binary.type", - "required": "semi", - "default": null, - "datatype": "string", - "encrypted": false, - "value_in_examples": null, - "description": "The corresponding validation library for `config.upstream.binary.schema`.\nCurrently, only `draft4` is supported.\n" - } - ], - "xml-threat-protection": [ - { - "name": "checked_content_types", - "required": true, - "default": [ - "application/xml" - ], - "value_in_examples": null, - "datatype": "array of strings", - "description": "A list of Content-Type values with payloads that must be validated.\n" - }, - { - "name": "allowed_content_types", - "required": true, - "default": [], - "value_in_examples": null, - "datatype": "array of strings", - "description": "A list of Content-Type values with payloads that are allowed, but aren't validated.\nFor example, if the API also accepts JSON, you can add `\"application/json\"`.\n" - }, - { - "name": "allow_dtd", - "required": true, - "default": false, - "value_in_examples": null, - "datatype": "boolean", - "description": "Indicates whether an XML Document Type Definition (DTD) section is allowed.\n" - }, - { - "name": "namespace_aware", - "required": true, - "default": true, - "value_in_examples": null, - "datatype": "boolean", - "description": "If not parsing namespace aware, all prefixes and namespace attributes will be counted as regular attributes and element names, and validated as such.\n" - }, - { - "name": "max_depth", - "required": true, - "default": 50, - "value_in_examples": 50, - "datatype": "number", - "description": "Maximum depth of tags. Child elements such as Text or Comments are not counted as another level.\n" - }, - { - "name": "max_children", - "required": true, - "default": 100, - "value_in_examples": null, - "datatype": "number", - "description": "Maximum number of children allowed (Element, Text, Comment, ProcessingInstruction, CDATASection).\nNote: Adjacent text and CDATA sections are counted as one. For example, `text-cdata-text-cdata` is one child.\n" - }, - { - "name": "max_attributes", - "required": true, - "default": 100, - "value_in_examples": null, - "datatype": "number", - "description": "Maximum number of attributes allowed on a tag, including default ones.\nNote: If namespace-aware parsing is disabled, then the namespaces definitions are counted as attributes.\n" - }, - { - "name": "max_namespaces", - "required": "semi", - "default": 20, - "value_in_examples": null, - "datatype": "number", - "description": "Maximum number of namespaces defined on a tag. This value is required if parsing is namespace-aware.\n" - }, - { - "name": "document", - "required": true, - "default": "10485760 (10 mb)", - "value_in_examples": null, - "datatype": "number", - "description": "Maximum size of the entire document.\n" - }, - { - "name": "buffer", - "required": true, - "default": "1048576 (1 mb)", - "value_in_examples": null, - "datatype": "number", - "description": "Maximum size of the unparsed buffer (see below).\n" - }, - { - "name": "comment", - "required": true, - "default": "1024 (1 kb)", - "value_in_examples": null, - "datatype": "number", - "description": "Maximum size of comments.\n" - }, - { - "name": "localname", - "required": true, - "default": "1024 (1 kb)", - "value_in_examples": 512, - "datatype": "number", - "description": "Maximum size of the localname. This applies to tags and attributes.\nNote: If parsing isn't namespace-aware, this limit counts against the full name (prefix + localname).\n" - }, - { - "name": "prefix", - "required": "semi", - "default": "1024 (1 kb)", - "value_in_examples": 512, - "datatype": "number", - "description": "Maximum size of the prefix. This applies to tags and attributes. This value is required if parsing is namespace-aware.\n" - }, - { - "name": "namespaceuri", - "required": "semi", - "default": "1024 (1 kb)", - "value_in_examples": 1024, - "datatype": "number", - "description": "Maximum size of the namespace URI. This value is required if parsing is namespace-aware.\n" - }, - { - "name": "attribute", - "required": true, - "default": "1024 (1 kb)", - "value_in_examples": null, - "datatype": "number", - "description": "Maximum size of the attribute value.\n" - }, - { - "name": "text", - "required": true, - "default": "1024 (1 kb)", - "value_in_examples": null, - "datatype": "number", - "description": "Maximum text inside tags (counted over all adjacent text/CDATA elements combined).\n" - }, - { - "name": "pitarget", - "required": true, - "default": "1024 (1 kb)", - "value_in_examples": null, - "datatype": "number", - "description": "Maximum size of processing instruction targets.\n" - }, - { - "name": "pidata", - "required": true, - "default": "1024 (1 kb)", - "value_in_examples": null, - "datatype": "number", - "description": "Maximum size of processing instruction data.\n" - }, - { - "name": "entityname", - "required": true, - "default": "1024 (1 kb)", - "value_in_examples": null, - "datatype": "number", - "description": "Maximum size of entity names in EntityDecl.\n" - }, - { - "name": "entity", - "required": true, - "default": "1024 (1 kb)", - "value_in_examples": null, - "datatype": "number", - "description": "Maximum size of entity values in EntityDecl.\n" - }, - { - "name": "entityproperty", - "required": true, - "default": "1024 (1 kb)", - "value_in_examples": null, - "datatype": "number", - "description": "Maximum size of systemId, publicId, or notationName in EntityDecl.\n" - }, - { - "name": "bla_max_amplification", - "required": true, - "default": 100, - "value_in_examples": null, - "datatype": "number", - "description": "Sets the maximum allowed amplification. This protects against the Billion Laughs Attack.\n" - }, - { - "name": "bla_threshold", - "required": true, - "default": "8388608 (8 mb)", - "value_in_examples": null, - "datatype": "number", - "description": "Sets the threshold after which the protection starts. This protects against the Billion Laughs Attack.\n" - } - ], - "zipkin": [ - { - "name": "local_service_name", - "minimum_version": "2.7.x", - "required": true, - "default": "kong", - "datatype": "string", - "description": "The name of the service as displayed in Zipkin. Customize this name to\ntell your Kong Gateway services apart in Zipkin request traces.\n" - }, - { - "name": "http_endpoint", - "required": false, - "default": "", - "value_in_examples": "http://your.zipkin.collector:9411/api/v2/spans", - "datatype": "string", - "description": "The full HTTP(S) endpoint to which Zipkin spans should be sent by Kong.\nIf not specified, the Zipkin plugin will only act as a tracing header\ngenerator/transmitter.\n" - }, - { - "name": "sample_ratio", - "required": false, - "default": "`0.001`", - "value_in_examples": 0.001, - "datatype": "number", - "description": "How often to sample requests that do not contain trace IDs.\nSet to `0` to turn sampling off, or to `1` to sample **all** requests. The\nvalue must be between zero (0) and one (1), inclusive.\n" - }, - { - "name": "default_service_name", - "required": false, - "default": null, - "datatype": "string", - "description": "Set a default service name to override `unknown-service-name` in the \nZipkin spans.\n" - }, - { - "name": "include_credential", - "required": true, - "default": true, - "value_in_examples": true, - "datatype": "boolean", - "description": "Specify whether the credential of the currently authenticated consumer\nshould be included in metadata sent to the Zipkin server.\n" - }, - { - "name": "traceid_byte_count", - "required": true, - "default": 16, - "datatype": "integer", - "description": "The length in bytes of each request's Trace ID. The value can be either `8` or `16`.\n" - }, - { - "name": "header_type", - "maximum_version": "2.3.x", - "required": true, - "default": "preserve", - "datatype": "string", - "description": "All HTTP requests going through the plugin are tagged with a tracing HTTP request.\nThis property codifies what kind of tracing header the plugin expects on incoming requests.\n\nPossible values: `b3`, `b3-single`, `w3c`, `preserve`, `jaeger`, `ot`, or `ignore`.\n* `b3`: Expects [Zipkin's B3 multiple headers](https://github.com/openzipkin/b3-propagation#multiple-headers)\non incoming requests, and will add them to the transmitted requests if the headers are missing from those requests.\n* `b3-single`: Expects or adds Zipkin's B3 single-header tracing headers.\n* `w3c`: Expects or adds W3C's traceparent tracing header.\n* `preserve`: Does not expect any format, and will transmit whatever header is recognized or present,\nwith a default of `b3` if none is found. In case of a mismatch between the expected and incoming\ntracing headers (for example, when `header_type` is set to `b3` but a w3c-style tracing header is\nfound in the incoming request), then the plugin will add both kinds of tracing headers\nto the request and generate a mismatch warning in the logs.\n" - }, - { - "name": "header_type", - "minimum_version": "2.4.x", - "maximum_version": "2.6.x", - "required": true, - "default": "preserve", - "datatype": "string", - "description": "All HTTP requests going through the plugin are tagged with a tracing HTTP request.\nThis property codifies what kind of tracing header the plugin expects on incoming requests.\n\nPossible values: `b3`, `b3-single`, `w3c`, `preserve`, `jaeger`, `ot`, or `ignore`.\n* `b3`: Expects [Zipkin's B3 multiple headers](https://github.com/openzipkin/b3-propagation#multiple-headers)\non incoming requests, and will add them to the transmitted requests if the headers are missing from those requests.\n* `b3-single`: Expects or adds Zipkin's B3 single-header tracing headers.\n* `w3c`: Expects or adds W3C's traceparent tracing header.\n* `preserve`: Does not expect any format, and will transmit whatever header is recognized or present,\nwith a default of `b3` if none is found. In case of a mismatch between the expected and incoming\ntracing headers (for example, when `header_type` is set to `b3` but a w3c-style tracing header is\nfound in the incoming request), then the plugin will add both kinds of tracing headers\nto the request and generate a mismatch warning in the logs.\n* `jaeger`: Expects or adds\n[Jaeger-style tracing headers](https://www.jaegertracing.io/docs/1.22/client-libraries/#propagation-format) (`uber-trace-id`).\n* `ot`: Expects or adds [OpenTelemetry tracing headers](https://github.com/open-telemetry/opentelemetry-java/blob/96e8523544f04c305da5382854eee06218599075/extensions/trace_propagators/src/main/java/io/opentelemetry/extensions/trace/propagation/OtTracerPropagator.java) of the form `ot-tracer-*`.\n" - }, - { - "name": "header_type", - "minimum_version": "2.7.x", - "required": true, - "default": "preserve", - "datatype": "string", - "description": "All HTTP requests going through the plugin are tagged with a tracing HTTP request.\nThis property codifies what kind of tracing header the plugin expects on incoming requests.\n\nPossible values: `b3`, `b3-single`, `w3c`, `preserve`, `jaeger`, `ot`, or `ignore`.\n* `b3`: Expects [Zipkin's B3 multiple headers](https://github.com/openzipkin/b3-propagation#multiple-headers)\non incoming requests, and will add them to the transmitted requests if the headers are missing from those requests.\n* `b3-single`: Expects or adds Zipkin's B3 single-header tracing headers.\n* `w3c`: Expects or adds W3C's traceparent tracing header.\n* `preserve`: Does not expect any format, and will transmit whatever header is recognized or present,\nwith a default of `b3` if none is found. In case of a mismatch between the expected and incoming\ntracing headers (for example, when `header_type` is set to `b3` but a w3c-style tracing header is\nfound in the incoming request), then the plugin will add both kinds of tracing headers\nto the request and generate a mismatch warning in the logs.\n* `jaeger`: Expects or adds\n[Jaeger-style tracing headers](https://www.jaegertracing.io/docs/1.22/client-libraries/#propagation-format) (`uber-trace-id`).\n* `ot`: Expects or adds [OpenTelemetry tracing headers](https://github.com/open-telemetry/opentelemetry-java/blob/96e8523544f04c305da5382854eee06218599075/extensions/trace_propagators/src/main/java/io/opentelemetry/extensions/trace/propagation/OtTracerPropagator.java) of the form `ot-tracer-*`.\n* `ignore`: Does not read any tracing headers from the incoming request.\nStarts a new request using the `default_header_type` value, or falls back to\n`b3` if there is no `default_header_type` value set.\n" - }, - { - "name": "default_header_type", - "minimum_version": "2.3.x", - "required": true, - "default": "b3", - "datatype": "string", - "description": "Allows specifying the type of header to be added to requests with no pre-existing tracing headers\nand when `config.header_type` is set to `\"preserve\"`.\nWhen `header_type` is set to any other value, `default_header_type` is ignored.\n\nPossible values are `b3`, `b3-single`, `w3c`, `jaeger`, or `ot`.\nSee the entry for `header_type` for value definitions.\n" - }, - { - "name": "tags_header", - "minimum_version": "2.4.x", - "required": true, - "default": "Zipkin-Tags", - "datatype": "string", - "description": "The Zipkin plugin will add extra headers to the tags associated with any HTTP\nrequests that come with a header named as configured by this property. The\nformat is `name_of_tag=value_of_tag`, separated by semicolons (`;`).\n\nFor example: with the default value, a request with the header\n`Zipkin-Tags: fg=blue; bg=red` will generate a trace with the tag `fg` with\nvalue `blue`, and another tag called `bg` with value `red`.\n" - }, - { - "name": "static_tags", - "minimum_version": "2.3.x", - "required": false, - "default": [], - "value_in_examples": null, - "datatype": "array of string tags", - "description": "The tags specified on this property will be added to the generated request traces. For example:\n`[ { \"name\": \"color\", \"value\": \"red\" } ]`.\n" - }, - { - "name": "http_span_name", - "minimum_version": "3.0.x", - "required": true, - "default": "method", - "value_in_examples": null, - "datatype": "string", - "description": "Specify whether to include the HTTP path in the span name.\n\nOptions:\n* `method`: Do not include the HTTP path. This is the default.\n* `method_path`: Include the HTTP path.\n" - }, - { - "name": "connect_timeout", - "minimum_version": "3.0.x", - "required": false, - "default": 2000, - "value_in_examples": null, - "datatype": "number", - "description": "The timeout, in milliseconds, for establishing a connection to the Zipkin server." - }, - { - "name": "send_timeout", - "minimum_version": "3.0.x", - "required": false, - "default": 5000, - "value_in_examples": null, - "datatype": "number", - "description": "The timeout, in milliseconds, between two successive write operations when sending a request to the Zipkin server." - }, - { - "name": "read_timeout", - "minimum_version": "3.0.x", - "required": false, - "default": 5000, - "value_in_examples": null, - "datatype": "number", - "description": "The timeout, in milliseconds, between two successive read operations when receiving a response from the Zipkin server." - }, - { - "name": "response_header_for_traceid", - "minimum_version": "3.1.x", - "required": false, - "default": null, - "value_in_examples": null, - "datatype": "string", - "description": "Set a header name to append to responses. This header name\nis sent to the client, making it possible to trace the ID of the\ncorrelated request.\n" - }, - { - "name": "phase_duration_flavor", - "minimum_version": "3.2.x", - "required": true, - "default": "annotations", - "value_in_examples": null, - "datatype": "string", - "description": "Specify whether to include the duration of each phase as an annotation or a tag.\n\nOptions:\n* `annotations`: Include the duration of each phase as an annotation. This is the default.\n* `tags`: Include the duration of each phase as a tag.\n" - } - ] -} \ No newline at end of file