Repository: Kong/developer.konghq.com
Pull request #893: feat: Header cert auth plugin
Author: login: cloudjumpercat
Created: 2025-03-25T14:22:25Z | Merged: 2025-03-27T21:13:20Z

## Description

Fixes #855 

## Preview Links
https://deploy-preview-893--kongdeveloper.netlify.app/plugins/header-cert-auth/
https://deploy-preview-893--kongdeveloper.netlify.app/plugins/header-cert-auth/examples/aws-alb/
https://deploy-preview-893--kongdeveloper.netlify.app/plugins/header-cert-auth/changelog/

## Notes for reviewers
- In the plugin example, the variable for cert isn't working. I get a `{"message":"schema violation (config.ca_certificates: {\n  \"expected a valid UUID\"\n})","fields":{"config":{"ca_certificates":["expected a valid UUID"]}},"name":"schema violation","code":2}` despite using a valid UUID for a CA cert. If I add the UUID value and don't use the variable, it works.


## Checklist 

- [x] Every page is page one.
- [x] Tested how-to docs. If not, note why here. 
- [x] All pages contain metadata.
- [x] Updated [sources.yaml](https://github.com/Kong/developer.konghq.com/blob/main/tools/track-docs-changes/config/sources.yml). For more info, review [track docs changes](https://github.com/Kong/developer.konghq.com/tree/main/tools/track-docs-changes)
- [x] Any new docs link to existing docs.
- [x] All autogenerated instructions render correctly (API, decK, Konnect, Kong Manager). 
- [x] Style guide (capitalized gateway entities, placeholder URLs) implemented correctly.
- [x] Every page has a `description` entry in frontmatter


Linked issue #855: Header Cert AUTH PLUGIN
https://docs.konghq.com/hub/kong-inc/header-cert-auth/



Diff:
diff --git a/app/_includes/plugins/upstream-headers.md b/app/_includes/plugins/upstream-headers.md
index 05a65dc5e4..cae357b2d4 100644
--- a/app/_includes/plugins/upstream-headers.md
+++ b/app/_includes/plugins/upstream-headers.md
@@ -1,4 +1,6 @@
-<!--used in: HMAC and LDAP auth-->
+
+<!--used in the following plugins: Header Cert Auth, HMAC and LDAP auth-->
+
 When a client has been authenticated, the plugin appends some headers to
 the request before proxying it to the upstream service, so that you
 can identify the Consumer in your code:
@@ -6,9 +8,10 @@ can identify the Consumer in your code:
 * `X-Consumer-ID`: The ID of the Consumer in {{site.base_gateway}}.
 * `X-Consumer-Custom-ID`: The `custom_id` of the Consumer (if set).
 * `X-Consumer-Username`: The `username` of the Consumer (if set).
-* `X-Credential-Identifier`: The identifier of the credential (only if the Consumer is not the `anonymous` consumer).
+* `X-Credential-Identifier`: The identifier of the credential (only if the Consumer is not the `anonymous` Consumer).
 * `X-Anonymous-Consumer`: Is set to `true` if authentication fails, and the `anonymous` Consumer is set instead.
 
 You can use this information on your side to implement additional logic.
-You can use the `X-Consumer-ID` value to query the {{site.base_gateway}} Admin API and retrieve
+You can use the `X-Consumer-ID` value to query the Admin API and retrieve
 more information about the Consumer.
+
diff --git a/app/_kong_plugins/header-cert-auth/changelog.md b/app/_kong_plugins/header-cert-auth/changelog.md
index ffd65979d3..d3a3a23afd 100644
--- a/app/_kong_plugins/header-cert-auth/changelog.md
+++ b/app/_kong_plugins/header-cert-auth/changelog.md
@@ -3,4 +3,7 @@ content_type: reference
 
 ---
 
-## Changelog
\ No newline at end of file
+## Changelog
+
+### {{site.base_gateway}} 3.8.x
+* Introduced the Header Cert Authentication plugin.
\ No newline at end of file
diff --git a/app/_kong_plugins/header-cert-auth/examples/aws-alb.yaml b/app/_kong_plugins/header-cert-auth/examples/aws-alb.yaml
new file mode 100644
index 0000000000..2004064ef1
--- /dev/null
+++ b/app/_kong_plugins/header-cert-auth/examples/aws-alb.yaml
@@ -0,0 +1,39 @@
+description: 'Allows you to integrate Amazon Application Load Balancer (ALB) with the Header Cert Authentication plugin.'
+
+title: 'Application Load Balancer (ALB) integration'
+
+weight: 900
+
+requirements:
+ - "Add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/) before configuring the plugin."
+ - "Generated certificates for ALB"
+ - |
+  Configure ALB by adding an HTTPS listener:
+
+  | Setting | Mapping |
+  |---------|-------|
+  | Protocol | HTTPS |
+  | Port | 443 |
+  | Routing actions | Forward to target groups |
+  | Certificate source | From AWS Certificate Manager (ACM) |
+  | Certificate (from ACM) | Select the certificate that you want to use | 
+  | Client certificate handling | Select Mutual authentication (mTLS) with Passthrough |
+
+variables: 
+  certificate_header_name:
+    description: 'Name of the header that contains the certificate, received from the WAF or other L7 downstream proxy.'
+    value: $HEADER_NAME
+
+config:
+  ca_certificates:
+  - 322dce96-d434-4e0d-9038-311b3520f0a3
+  certificate_header_name: ${certificate_header_name}
+  certificate_header_format: base64_encoded
+  secure_source: false
+
+tools:
+  - deck
+  - admin-api
+  - konnect-api
+  - kic
+  - terraform
diff --git a/app/_kong_plugins/header-cert-auth/examples/enable-header-cert-auth.yaml b/app/_kong_plugins/header-cert-auth/examples/enable-header-cert-auth.yaml
new file mode 100644
index 0000000000..41aab29da9
--- /dev/null
+++ b/app/_kong_plugins/header-cert-auth/examples/enable-header-cert-auth.yaml
@@ -0,0 +1,26 @@
+description: 'Enables the Header Cert Authentication plugin with the CA certificate. Only allows requests from trusted IPs.'
+
+title: 'Enable Header Cert Auth'
+
+weight: 900
+
+requirements:
+ - "Add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/) before configuring the plugin."
+
+variables: 
+  certificate_header_name:
+    description: 'Name of the header that contains the certificate, received from the WAF or other L7 downstream proxy.'
+    value: $HEADER_NAME
+
+config:
+  ca_certificates:
+  - 0D769DE8-7CC0-4541-989B-F9C23E20054C
+  certificate_header_name: ${certificate_header_name}
+  certificate_header_format: base64_encoded
+
+tools:
+  - deck
+  - admin-api
+  - konnect-api
+  - kic
+  - terraform
\ No newline at end of file
diff --git a/app/_kong_plugins/header-cert-auth/examples/example.yaml b/app/_kong_plugins/header-cert-auth/examples/example.yaml
deleted file mode 100644
index ca235e4959..0000000000
--- a/app/_kong_plugins/header-cert-auth/examples/example.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-description: ''
-
-title: ''
-
-weight: 900
-
-# requirements: <- not required
-# - "some req"
-
-# variables: <- not required
-#   my-region:
-#     description: ''
-#     value: us
-
-config: # plugin config in yaml format goes here
-
-tools:
-  - deck
-  - admin-api
-  - konnect-api
-  - kic
-  - terraform
diff --git a/app/_kong_plugins/header-cert-auth/index.md b/app/_kong_plugins/header-cert-auth/index.md
index 6c7bd3db05..74b07bdf5a 100644
--- a/app/_kong_plugins/header-cert-auth/index.md
+++ b/app/_kong_plugins/header-cert-auth/index.md
@@ -36,6 +36,161 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+      
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin lets {{site.base_gateway}} authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth/).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name (CN) field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) {{site.base_gateway}} config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your upstream service.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} won't be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your upstream service vulnerable to attacks. Before using this plugin in production, carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+This plugin's [static priority](/gateway/entities/plugin/#plugin-priority) is lower than all other authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly.
+
+The format specified in the [`config.certificate_header_format`](./reference/#schema--config-certificate-header-format) parameter defines how a certificate should be passed in a request.
+  * When set to `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters). 
+  * When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+For example, given the `certificate_header_name` of x-client-cert:
+
+`base64_encoded`
+
+```bash
+x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+```
+
+`url_encoded`
+
+```bash
+x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+```
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you can manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how Consumer mapping parameters work for the Header Cert Auth plugin:
+
+{% table %}
+columns:
+  - title: Form Parameter
+    key: parameter
+  - title: Default
+    key: default
+  - title: Description
+    key: description
+rows:
+  - parameter: "`id`<br>*required for declarative config*"
+    default: none
+    description: "UUID of the Consumer mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by {{site.base_gateway}}'s Admin API."
+  - parameter: "`subject_name`<br>*required*"
+    default: none
+    description: "The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to `consumer` (in order of lookup)."
+  - parameter: "`ca_certificate`<br>*optional*"
+    default: none
+    description: "**If using the Admin API:** UUID of the Certificate Authority (CA). <br><br> **If using declarative configuration:** Full PEM-encoded CA certificate. <br><br>The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs. <br><br>If empty, the subject name matches certificates issued by any CA under the corresponding `config.ca_certificates`."
+{% endtable %}
+
+### Matching behaviors
+
+After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless [`config.skip_consumer_lookup`](./reference/#schema--config-skip-consumer-lookup) is set to `true`:
+
+1. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = {issuing authority of the client certificate}`
+2. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = NULL`
+3. If [`config.consumer_by`](./reference/#schema--config.consumer_by) is not null, Consumer with `username` and/or `id` matching the certificate's SAN or CN (in that order)
+4. The [`config.anonymous`](./reference/#schema--config-anonymous) Consumer (if set)
+
+{:.info}
+> **Note**: Matching stops as soon as the first successful match is found.
+
+### Upstream headers
+{% include_cached /plugins/upstream-headers.md %}
+
+When `config.skip_consumer_lookup` is set to `true`, Consumer lookup is skipped and instead of appending aforementioned headers, the plugin appends the following two headers:
+
+* `X-Client-Cert-Dn`: The distinguished name of the client certificate
+* `X-Client-Cert-San`: The SAN of the client certificate
+
+Once `config.skip_consumer_lookup` is applied, any client with a valid certificate can access the Service/API.
+To restrict usage to only some of the authenticated users, also add the [ACL plugin](/plugins/acl/) and create
+allowed or denied groups of users using the same
+certificate property being set in `config.authenticated_group_by`.
+
+## Troubleshooting authentication failure
+
+When authentication fails, the client doesn't have access to any details that explain the failure. The security reason for this omission is to prevent malicious reconnaissance. Instead, the details are recorded inside [{{site.base_gateway}}'s error logs](/gateway/logs/) under the `[header-cert-auth]` filter.
+
+
diff --git a/tools/track-docs-changes/config/sources.yml b/tools/track-docs-changes/config/sources.yml
index cc407c95a8..d73675bbee 100644
--- a/tools/track-docs-changes/config/sources.yml
+++ b/tools/track-docs-changes/config/sources.yml
@@ -416,6 +416,11 @@ app/_kong_plugins/exit-transformer/changelog.md:
   - app/_hub/kong-inc/exit-transformer/_changelog.md
 app/_how-tos/transform-a-404-response-message.md:
   - app/_hub/kong-inc/exit-transformer/overview/_index.md
+app/_kong_plugins/header-cert-auth/changelog.md:
+  - app/_hub/kong-inc/header-cert-auth/_changelog.md
+app/_kong_plugins/header-cert-auth/index.md:
+  - app/_hub/kong-inc/header-cert-auth/how-to/_manual-mapping-cert-consumers.md
+  - app/_hub/kong-inc/header-cert-auth/overview/_index.md
 app/_kong_plugins/proxy-cache/index.md:
   - app/_hub/kong-inc/proxy-cache/overview/_index.md
 app/_kong_plugins/proxy-cache/changelog.md:


Reviews:
user: login: cloudjumpercat
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-25T14:26:52Z
user: login: lena-larionova
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-26T23:53:01Z
user: login: lena-larionova
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-27T14:43:25Z
user: login: lena-larionova
body: lgtm!
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-27T21:00:35Z

Review comments:
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/hub/kong-inc/mtls-auth).
path: app/_kong_plugins/header-cert-auth/index.md
user: login: cloudjumpercat
body: ```suggestion
The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
```
created_at: 2025-03-25T14:26:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: I'm not sure this should be hidden in an FAQ. I'd expect to see it in the  "Client certificate request" section.
created_at: 2025-03-26T23:27:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
      This depends on the format specified in the [`config.certificate_header_format`](./reference/#schema--config-certificate-header-format) parameter. 
        * When set to `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters). 
        * When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
```
created_at: 2025-03-26T23:28:35Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
This plugin lets {{site.base_gateway}} authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
```
Rephrasing to make this a positive thing.
created_at: 2025-03-26T23:29:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
This occurs in scenarios where TLS traffic is not terminated at {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
```
created_at: 2025-03-26T23:29:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth/).
```
created_at: 2025-03-26T23:30:08Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name (CN) field.
```
created_at: 2025-03-26T23:30:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) {{site.base_gateway}} config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
```
Mostly to make it clear that this isn't a plugin config parameter.
created_at: 2025-03-26T23:32:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your upstream service.
```
created_at: 2025-03-26T23:33:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} won't be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your upstream service vulnerable to attacks. Before using this plugin in production, carefully evaluate and configure the plugin according to your specific use case and security requirements.
```
created_at: 2025-03-26T23:34:26Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
This plugin's [static priority](/gateway/entities/plugin/#plugin-priority) is lower than all other authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
```
created_at: 2025-03-26T23:37:05Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly.
```
That sentence seems tacked on, don't think it's necessary.
created_at: 2025-03-26T23:44:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
situations, you can manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
```
created_at: 2025-03-26T23:44:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
The following table describes how Consumer mapping parameters work for the Header Cert Auth plugin:
```
It's better for search if the table description is explicit.
created_at: 2025-03-26T23:46:35Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
+
+| Form Parameter                            | Default | Description |
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: You can/should use the `{% table %}` tag here instead. Eg see https://github.com/Kong/developer.konghq.com/blob/main/app/_kong_plugins/ai-rate-limiting-advanced/index.md?plain=1#L121.
created_at: 2025-03-26T23:47:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
+
+| Form Parameter                            | Default | Description |
+| ---                                       | ---     | --- |
+| `id`<br>*required for declarative config* |  none   | UUID of the Consumer mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by {{site.base_gateway}}'s Admin API. |
+| `subject_name`<br>*required*              |  none   | The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to `consumer` (in order of lookup). |
+| `ca_certificate`<br>*optional*            |  none   | **If using the Admin API:** UUID of the Certificate Authority (CA). <br><br> **If using declarative configuration:** Full PEM-encoded CA certificate. <br><br>The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs. <br><br>If empty, the subject name matches certificates issued by any CA under the corresponding `config.ca_certificates`. |
+
+### Matching behaviors
+
+After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless `skip_consumer_lookup` is set to `true`:
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless [`config.skip_consumer_lookup`](./reference/#schema--config-skip-consumer-lookup) is set to `true`:
```
created_at: 2025-03-26T23:49:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
+
+| Form Parameter                            | Default | Description |
+| ---                                       | ---     | --- |
+| `id`<br>*required for declarative config* |  none   | UUID of the Consumer mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by {{site.base_gateway}}'s Admin API. |
+| `subject_name`<br>*required*              |  none   | The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to `consumer` (in order of lookup). |
+| `ca_certificate`<br>*optional*            |  none   | **If using the Admin API:** UUID of the Certificate Authority (CA). <br><br> **If using declarative configuration:** Full PEM-encoded CA certificate. <br><br>The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs. <br><br>If empty, the subject name matches certificates issued by any CA under the corresponding `config.ca_certificates`. |
+
+### Matching behaviors
+
+After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless `skip_consumer_lookup` is set to `true`:
+
+1. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = <issuing authority of the client certificate>`
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
1. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = {issuing authority of the client certificate}`
```
created_at: 2025-03-26T23:49:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
+
+| Form Parameter                            | Default | Description |
+| ---                                       | ---     | --- |
+| `id`<br>*required for declarative config* |  none   | UUID of the Consumer mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by {{site.base_gateway}}'s Admin API. |
+| `subject_name`<br>*required*              |  none   | The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to `consumer` (in order of lookup). |
+| `ca_certificate`<br>*optional*            |  none   | **If using the Admin API:** UUID of the Certificate Authority (CA). <br><br> **If using declarative configuration:** Full PEM-encoded CA certificate. <br><br>The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs. <br><br>If empty, the subject name matches certificates issued by any CA under the corresponding `config.ca_certificates`. |
+
+### Matching behaviors
+
+After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless `skip_consumer_lookup` is set to `true`:
+
+1. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = <issuing authority of the client certificate>`
+2. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = NULL`
+3. If `config.consumer_by` is not null, Consumer with `username` and/or `id` matching the certificate's SAN or CN (in that order)
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
3. If [`config.consumer_by`](./reference/#schema--config.consumer_by) is not null, Consumer with `username` and/or `id` matching the certificate's SAN or CN (in that order)
```
created_at: 2025-03-26T23:50:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
+
+| Form Parameter                            | Default | Description |
+| ---                                       | ---     | --- |
+| `id`<br>*required for declarative config* |  none   | UUID of the Consumer mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by {{site.base_gateway}}'s Admin API. |
+| `subject_name`<br>*required*              |  none   | The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to `consumer` (in order of lookup). |
+| `ca_certificate`<br>*optional*            |  none   | **If using the Admin API:** UUID of the Certificate Authority (CA). <br><br> **If using declarative configuration:** Full PEM-encoded CA certificate. <br><br>The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs. <br><br>If empty, the subject name matches certificates issued by any CA under the corresponding `config.ca_certificates`. |
+
+### Matching behaviors
+
+After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless `skip_consumer_lookup` is set to `true`:
+
+1. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = <issuing authority of the client certificate>`
+2. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = NULL`
+3. If `config.consumer_by` is not null, Consumer with `username` and/or `id` matching the certificate's SAN or CN (in that order)
+4. The `config.anonymous` Consumer (if set)
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
4. The [`config.anonymous`](./reference/#schema--config-anonymous) Consumer (if set)
```
created_at: 2025-03-26T23:50:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
+
+| Form Parameter                            | Default | Description |
+| ---                                       | ---     | --- |
+| `id`<br>*required for declarative config* |  none   | UUID of the Consumer mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by {{site.base_gateway}}'s Admin API. |
+| `subject_name`<br>*required*              |  none   | The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to `consumer` (in order of lookup). |
+| `ca_certificate`<br>*optional*            |  none   | **If using the Admin API:** UUID of the Certificate Authority (CA). <br><br> **If using declarative configuration:** Full PEM-encoded CA certificate. <br><br>The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs. <br><br>If empty, the subject name matches certificates issued by any CA under the corresponding `config.ca_certificates`. |
+
+### Matching behaviors
+
+After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless `skip_consumer_lookup` is set to `true`:
+
+1. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = <issuing authority of the client certificate>`
+2. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = NULL`
+3. If `config.consumer_by` is not null, Consumer with `username` and/or `id` matching the certificate's SAN or CN (in that order)
+4. The `config.anonymous` Consumer (if set)
+
+{:.info}
+> **Note**: Matching stops as soon as the first successful match is found.
+
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion

### Upstream headers
```
created_at: 2025-03-26T23:51:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
+
+| Form Parameter                            | Default | Description |
+| ---                                       | ---     | --- |
+| `id`<br>*required for declarative config* |  none   | UUID of the Consumer mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by {{site.base_gateway}}'s Admin API. |
+| `subject_name`<br>*required*              |  none   | The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to `consumer` (in order of lookup). |
+| `ca_certificate`<br>*optional*            |  none   | **If using the Admin API:** UUID of the Certificate Authority (CA). <br><br> **If using declarative configuration:** Full PEM-encoded CA certificate. <br><br>The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs. <br><br>If empty, the subject name matches certificates issued by any CA under the corresponding `config.ca_certificates`. |
+
+### Matching behaviors
+
+After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless `skip_consumer_lookup` is set to `true`:
+
+1. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = <issuing authority of the client certificate>`
+2. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = NULL`
+3. If `config.consumer_by` is not null, Consumer with `username` and/or `id` matching the certificate's SAN or CN (in that order)
+4. The `config.anonymous` Consumer (if set)
+
+{:.info}
+> **Note**: Matching stops as soon as the first successful match is found.
+
+{% include_cached /plugins/upstream-headers.md %}
+
+When `skip_consumer_lookup` is set to `true`, Consumer lookup is skipped and instead of appending aforementioned headers, the plugin appends the following two headers
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
When `config.skip_consumer_lookup` is set to `true`, Consumer lookup is skipped and instead of appending aforementioned headers, the plugin appends the following two headers:
```
created_at: 2025-03-26T23:51:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
+
+| Form Parameter                            | Default | Description |
+| ---                                       | ---     | --- |
+| `id`<br>*required for declarative config* |  none   | UUID of the Consumer mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by {{site.base_gateway}}'s Admin API. |
+| `subject_name`<br>*required*              |  none   | The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to `consumer` (in order of lookup). |
+| `ca_certificate`<br>*optional*            |  none   | **If using the Admin API:** UUID of the Certificate Authority (CA). <br><br> **If using declarative configuration:** Full PEM-encoded CA certificate. <br><br>The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs. <br><br>If empty, the subject name matches certificates issued by any CA under the corresponding `config.ca_certificates`. |
+
+### Matching behaviors
+
+After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless `skip_consumer_lookup` is set to `true`:
+
+1. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = <issuing authority of the client certificate>`
+2. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = NULL`
+3. If `config.consumer_by` is not null, Consumer with `username` and/or `id` matching the certificate's SAN or CN (in that order)
+4. The `config.anonymous` Consumer (if set)
+
+{:.info}
+> **Note**: Matching stops as soon as the first successful match is found.
+
+{% include_cached /plugins/upstream-headers.md %}
+
+When `skip_consumer_lookup` is set to `true`, Consumer lookup is skipped and instead of appending aforementioned headers, the plugin appends the following two headers
+
+* `X-Client-Cert-Dn`: The distinguished name of the client certificate
+* `X-Client-Cert-San`: The SAN of the client certificate
+
+Once `skip_consumer_lookup` is applied, any client with a valid certificate can access the Service/API.
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
Once `config.skip_consumer_lookup` is applied, any client with a valid certificate can access the Service/API.
```
created_at: 2025-03-26T23:51:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
+
+| Form Parameter                            | Default | Description |
+| ---                                       | ---     | --- |
+| `id`<br>*required for declarative config* |  none   | UUID of the Consumer mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by {{site.base_gateway}}'s Admin API. |
+| `subject_name`<br>*required*              |  none   | The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to `consumer` (in order of lookup). |
+| `ca_certificate`<br>*optional*            |  none   | **If using the Admin API:** UUID of the Certificate Authority (CA). <br><br> **If using declarative configuration:** Full PEM-encoded CA certificate. <br><br>The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs. <br><br>If empty, the subject name matches certificates issued by any CA under the corresponding `config.ca_certificates`. |
+
+### Matching behaviors
+
+After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless `skip_consumer_lookup` is set to `true`:
+
+1. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = <issuing authority of the client certificate>`
+2. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = NULL`
+3. If `config.consumer_by` is not null, Consumer with `username` and/or `id` matching the certificate's SAN or CN (in that order)
+4. The `config.anonymous` Consumer (if set)
+
+{:.info}
+> **Note**: Matching stops as soon as the first successful match is found.
+
+{% include_cached /plugins/upstream-headers.md %}
+
+When `skip_consumer_lookup` is set to `true`, Consumer lookup is skipped and instead of appending aforementioned headers, the plugin appends the following two headers
+
+* `X-Client-Cert-Dn`: The distinguished name of the client certificate
+* `X-Client-Cert-San`: The SAN of the client certificate
+
+Once `skip_consumer_lookup` is applied, any client with a valid certificate can access the Service/API.
+To restrict usage to only some of the authenticated users, also add the ACL plugin and create
+allowed or denied groups of users using the same
+certificate property being set in `authenticated_group_by`.
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
certificate property being set in `config.authenticated_group_by`.
```
created_at: 2025-03-26T23:52:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,144 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+  - q: How should the certificate be passed in a client request?
+    a: |
+      This depends on the format specified in the `certificate_header_format` parameter. When using `base64_encoded`, only the base64-encoded body of the certificate should be sent (excluding the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters).  When using `url_encoded`, the entire certificate, including the `BEGIN CERTIFICATE` and `END CERTIFICATE` delimiters, should be provided.
+
+      For example, given the `certificate_header_name` of x-client-cert:
+
+      `base64_encoded`
+
+      ```bash
+      x-client-cert: MIIDbDCCAdSgAwIBAgIUa...
+      ```
+
+      `url_encoded`
+
+      ```bash
+      x-client-cert: -----BEGIN%20CERTIFICATE-----%0AMIIDbDCCAdSgAwIBAgIUa...-----END%20CERTIFICATE-----
+      ```
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin addresses the inability of the {{site.base_gateway}} to authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at the {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your API.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} will not be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your API vulnerable to attacks. Ensure you carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+Additionally, the plugin has a [static priority](/gateway/entities/plugin/#plugin-priority) so that it runs after all authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly (pretty much anything that deals with the actual TLS handshake is not needed for the plugin to work).
+
+## Manual mappings between Certificate and Consumer objects
+
+Sometimes, you might not want to use automatic Consumer lookup, or you have certificates
+that contain a field value not directly associated with Consumer objects. In those
+situations, you may manually assign one or more subject names to the [Consumer entity](/gateway/entities/consumer/) for
+identifying the correct Consumer.
+
+{:.info}
+> **Note**: Subject names refer to the certificate's Subject Alternative Names (SAN) or
+Common Name (CN). CN is only used if the SAN extension does not exist.
+
+You can create a Consumer mapping with either of the following:
+  * The [`/consumers/{consumer}/header-cert-auth` Admin API endpoint](/api/gateway/admin-ee/#/operations/create-plugin-for-consumer)
+  * [decK](/gateway/entities/consumer/#set-up-a-consumer) by specifying `header_cert_auth_credentials` in the configuration like the following:
+    
+    ```yaml
+    consumers:
+    - custom_id: my-consumer
+      username: {consumer}
+      header_cert_auth_credentials:
+      - id: bda09448-3b10-4da7-a83b-2a8ba6021f0c
+        subject_name: test@example.com
+    ```
+
+The following table describes how the mapping parameters work:
+
+| Form Parameter                            | Default | Description |
+| ---                                       | ---     | --- |
+| `id`<br>*required for declarative config* |  none   | UUID of the Consumer mapping. Required if adding mapping using declarative configuration, otherwise generated automatically by {{site.base_gateway}}'s Admin API. |
+| `subject_name`<br>*required*              |  none   | The Subject Alternative Name (SAN) or Common Name (CN) that should be mapped to `consumer` (in order of lookup). |
+| `ca_certificate`<br>*optional*            |  none   | **If using the Admin API:** UUID of the Certificate Authority (CA). <br><br> **If using declarative configuration:** Full PEM-encoded CA certificate. <br><br>The provided CA UUID or full certificate has to be verifiable by the issuing certificate authority for the mapping to succeed. This is to help distinguish multiple certificates with the same subject name that are issued under different CAs. <br><br>If empty, the subject name matches certificates issued by any CA under the corresponding `config.ca_certificates`. |
+
+### Matching behaviors
+
+After a client certificate has been verified as valid, the Consumer object is determined in the following order, unless `skip_consumer_lookup` is set to `true`:
+
+1. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = <issuing authority of the client certificate>`
+2. Manual mappings with `subject_name` matching the certificate's SAN or CN (in that order) and `ca_certificate = NULL`
+3. If `config.consumer_by` is not null, Consumer with `username` and/or `id` matching the certificate's SAN or CN (in that order)
+4. The `config.anonymous` Consumer (if set)
+
+{:.info}
+> **Note**: Matching stops as soon as the first successful match is found.
+
+{% include_cached /plugins/upstream-headers.md %}
+
+When `skip_consumer_lookup` is set to `true`, Consumer lookup is skipped and instead of appending aforementioned headers, the plugin appends the following two headers
+
+* `X-Client-Cert-Dn`: The distinguished name of the client certificate
+* `X-Client-Cert-San`: The SAN of the client certificate
+
+Once `skip_consumer_lookup` is applied, any client with a valid certificate can access the Service/API.
+To restrict usage to only some of the authenticated users, also add the ACL plugin and create
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
To restrict usage to only some of the authenticated users, also add the [ACL plugin](/plugins/acl/) and create
```
created_at: 2025-03-26T23:52:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -36,6 +36,161 @@ search_aliases:
   - header cert auth
   - header-cert-auth
   - authentication
+
+faqs: 
+  - q: Will the client need to encrypt the message with a private key and certificate when passing the certificate in the header?
+    a: |
+      No, the client only needs to send the target's certificate encoded in a header. {{site.base_gateway}} will validate the certificate, but it requires a high level of trust that the WAF/LB is the only entrypoint to the {{site.base_gateway}} proxy. The Header Cert Auth plugin will provide an option to secure the source, but additional layers of security are always preferable. Network level security (so that {{site.base_gateway}} only accepts requests from WAF - IP allow/deny mechanisms) and application-level security (Basic Auth or Key Auth plugins to authenticate the source first) are examples of multiple layers of security that can be applied.
+      
 ---
 
-## Overview
+The Header Cert Authentication plugin authenticates API calls by using client certificates provided in HTTP headers,
+instead of relying on traditional TLS termination.
+This approach is particularly useful in scenarios where TLS traffic is terminated outside of {{site.base_gateway}} such as at an external CDN or load balancer and the client certificate is passed along in an HTTP header for subsequent validation.
+
+{:.warning}
+> **Important:** To use this plugin, you must add [certificate authority (CA) certificates](/gateway/entities/ca-certificate/). Set them up before configuring the plugin.
+
+## How it works
+
+This plugin lets {{site.base_gateway}} authenticate API calls using client certificates received in HTTP headers, rather than through traditional TLS termination. 
+This occurs in scenarios where TLS traffic is not terminated at {{site.base_gateway}}, but rather at an external CDN or load balancer, and the client certificate is preserved in an HTTP header for further validation.
+
+The Header Cert Authentication plugin is similar to the [mTLS Auth plugin](/plugins/mtls-auth/).
+However, the mTLS plugin is only designed for traditional TLS termination, while the Header Cert Auth plugin also provides support for client certificates in headers. 
+
+The Header Cert Auth plugin extracts the client certificate from the HTTP header and validates it against the configured CA list. 
+If the certificate is valid, the plugin maps the certificate to a Consumer based on the common name (CN) field.
+
+The plugin validates the certificate provided against the configured CA list based on the
+requested Route or Gateway Service:
+* If the certificate is not trusted or has expired, the response is
+  `HTTP 401 TLS certificate failed verification`.
+* If a valid certificate is not presented (including when requests are not sent to the HTTPS port),
+  the response is `HTTP 401 No required TLS certificate was sent`.
+* However, if the `config.anonymous` option is configured on the plugin,
+  an [anonymous Consumer](/gateway/authentication/#using-multiple-authentication-methods) is used, and the request is allowed to proceed.
+
+The plugin can be configured to only accept certificates from trusted IP addresses, as specified by the [`trusted_ips`](/gateway/configuration/#trusted-ips) {{site.base_gateway}} config option. This ensures that {{site.base_gateway}} can trust the header sent from the source and provides L4 level of security.
+
+{:.warning}
+> **Important:** Incomplete or improper configuration of the Header Cert Authentication plugin can compromise the security of your upstream service.
+> <br><br>For instance, enabling the option to bypass origin verification can allow malicious actors to inject fake certificates, as {{site.base_gateway}} won't be able to verify the authenticity of the header. This can downgrade the security level of the plugin, making your upstream service vulnerable to attacks. Before using this plugin in production, carefully evaluate and configure the plugin according to your specific use case and security requirements.
+
+This plugin's [static priority](/gateway/entities/plugin/#plugin-priority) is lower than all other authentication plugins, allowing other auth plugins (for example, [Basic Auth](/plugins/basic-auth/)) to secure the source first. This ensures that the source is secured by multiple layers of authentication by providing L7 level of security.
+
+## Header size
+
+Sending certificates in headers may exceed header size limits in some environments. 
+You can configure {{site.base_gateway}} to accept larger headers by configuring the [Nginx header buffer parameter in `kong.conf`](/gateway/configuration/#nginx-http-large-client-header-buffers). 
+For example:
+
+```
+nginx_proxy_large_client_header_buffers=8 24k
+```
+
+Or via an environment variable:
+```
+KONG_NGINX_PROXY_LARGE_CLIENT_HEADER_BUFFERS=8 24k
+```
+
+## Client certificate request
+
+The `send_ca_dn` option is not supported in this plugin. This is used in mutual TLS authentication, where the server sends the list of trusted CAs to the client, and the client then uses this list to select the appropriate certificate to present. In this case, since the plugin doesn't do TLS handshakes and only parses the client certificate from the header, it isn't applicable.
+
+The same applies to SNI functionality. The plugin can verify the certificate without needing to know the specific hostname or domain being accessed. The plugin's authentication logic is decoupled from the TLS handshake and SNI, so it doesn't need to rely on SNI to function correctly.
+
+How a client certificate should be passed in a request depends on the format specified in the [`config.certificate_header_format`](./reference/#schema--config-certificate-header-format) parameter. 
path: app/_kong_plugins/header-cert-auth/index.md
user: login: lena-larionova
body: ```suggestion
The format specified in the [`config.certificate_header_format`](./reference/#schema--config-certificate-header-format) parameter defines how a certificate should be passed in a request.
```
Up to you on this one - the original sentence read a bit awkward to me.
created_at: 2025-03-27T14:43:00Z
author_association: CONTRIBUTOR

PR comments:
user: login: netlify[bot]
created_at: 2025-03-25T14:22:41Z
body: ### <span aria-hidden="true">✅</span> Deploy Preview for *kongdeveloper* ready!


|  Name | Link |
|:-:|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | 656ccf9f98f5ce4cf4d4b6bad01cb97319acfed8 |
|<span aria-hidden="true">🔍</span> Latest deploy log | https://app.netlify.com/sites/kongdeveloper/deploys/67e5bdb26b7f4d0008225d41 |
|<span aria-hidden="true">😎</span> Deploy Preview | [https://deploy-preview-893--kongdeveloper.netlify.app](https://deploy-preview-893--kongdeveloper.netlify.app) |
|<span aria-hidden="true">📱</span> Preview on mobile | <details><summary> Toggle QR Code... </summary><br /><br />![QR Code](https://app.netlify.com/qr-code/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1cmwiOiJodHRwczovL2RlcGxveS1wcmV2aWV3LTg5My0ta29uZ2RldmVsb3Blci5uZXRsaWZ5LmFwcCJ9.KHqEssnIjGcI5FQhdVeQXJy3AuqrHQrzZpJ5g4qfAM4)<br /><br />_Use your smartphone camera to open QR code link._</details> |
---
<!-- [kongdeveloper Preview](https://deploy-preview-893--kongdeveloper.netlify.app) -->
_To edit notification comments on pull requests, go to your [Netlify site configuration](https://app.netlify.com/sites/kongdeveloper/configuration/notifications#deploy-webhooks)._
author_association: NONE
user: login: lena-larionova
created_at: 2025-03-26T23:24:54Z
body: > In the plugin example, the variable for cert isn't working. I get a {"message":"schema violation (config.ca_certificates: {\n  \"expected a valid UUID\"\n})","fields":{"config":{"ca_certificates":["expected a valid UUID"]}},"name":"schema violation","code":2} despite using a valid UUID for a CA cert. If I add the UUID value and don't use the variable, it works.

Yeah, this is a known issue (product behavior?) that isn't going to change. We've had this in a couple of places, eg https://deploy-preview-893--kongdeveloper.netlify.app/how-to/associate-certificate-with-sni/ - notice how the cert prereq sets a cert ID, but then the cert creation example uses an explicit ID. decK won't accept a placeholder here.

So we just have to set a placeholder UUID.
author_association: CONTRIBUTOR
user: login: lena-larionova
created_at: 2025-03-26T23:57:07Z
body: @cloudjumpercat I would also add a generic config example that just adds certs without any external dependencies, following this: https://docs.konghq.com/hub/kong-inc/header-cert-auth/how-to/basic-example/

The example actually ends up the same I think, but for the purposes of search - if I ran into the ALB example, I'd assume it's not relevant to me if I don't want to use that.
author_association: CONTRIBUTOR