From 9410c588fbd35486564f0b8844e89e7a0eb66ea0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Emilio=20Alvarez=20Pi=C3=B1eiro?=
 <95703246+emilioalvap@users.noreply.github.com>
Date: Tue, 15 Oct 2024 10:48:05 +0200
Subject: [PATCH] [Synthetics] Add client certificate reference to docs (#4351)

* [Synthetics] Add client certificate reference to docs

---------

Co-authored-by: Colleen McGinnis <colleen.j.mcginnis@gmail.com>
---
 .../synthetics-configuration.asciidoc         | 46 ++++++++++++++++++-
 .../synthetics/synthetics-configuration.mdx   | 42 ++++++++++++++++-
 2 files changed, 86 insertions(+), 2 deletions(-)

diff --git a/docs/en/observability/synthetics-configuration.asciidoc b/docs/en/observability/synthetics-configuration.asciidoc
index edcb81a2ae..68854a0f74 100644
--- a/docs/en/observability/synthetics-configuration.asciidoc
+++ b/docs/en/observability/synthetics-configuration.asciidoc
@@ -82,7 +82,51 @@ For all available options, refer to the https://playwright.dev/docs/test-configu
 Do not attempt to run in headful mode (using `headless:false`) when running through Elastic's global managed testing infrastructure or Private Locations as this is not supported.
 ====
 
-Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including timeouts, timezones, and device emulation.
+Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including TLS client authentication, timeouts, timezones, and device emulation.
+
+[discrete]
+[[synthetics-configuration-playwright-options-client-certificates]]
+== TLS client authentication
+To enable TLS client authentication, set the https://playwright.dev/docs/api/class-testoptions#test-options-client-certificates[`clientCertificates`] option in the configuration file:
+
+[NOTE]
+=====
+Path-based options `{certPath, keyPath, pfxPath}` are only supported on Private Locations, defer to in-memory alternatives `{cert, key, pfx}` when running on locations hosted by Elastic.
+=====
+
+[source,js]
+----
+playwrightOptions: {
+  clientCertificates: [
+    {
+      origin: 'https://example.com',
+      certPath: './cert.pem',
+      keyPath: './key.pem',
+      passphrase: 'mysecretpassword',
+    },
+    {
+      origin: 'https://example.com',
+      cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."),
+      key: Buffer.from("-----BEGIN RSA PRIVATE KEY-----\n..."),
+      passphrase: 'mysecretpassword',
+    }
+  ],
+}
+----
+
+[TIP]
+=====
+When using Synthetics monitor UI, `cert`, `key` and `pfx` can simply be specified using a string literal:
+[source,js]
+----
+clientCertificates: [
+  {
+    cert: "-----BEGIN CERTIFICATE-----\n...",
+    // Not cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."),
+  }
+],
+----
+=====
 
 [discrete]
 [[synthetics-configuration-playwright-options-timeouts]]
diff --git a/docs/en/serverless/synthetics/synthetics-configuration.mdx b/docs/en/serverless/synthetics/synthetics-configuration.mdx
index 8b6df6578b..5d487c27b2 100644
--- a/docs/en/serverless/synthetics/synthetics-configuration.mdx
+++ b/docs/en/serverless/synthetics/synthetics-configuration.mdx
@@ -84,7 +84,47 @@ For all available options, refer to the [Playwright documentation](https://playw
   Do not attempt to run in headful mode (using `headless:false`) when running through Elastic's global managed testing infrastructure or Private Locations as this is not supported.
 </DocCallOut>
 
-Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including timeouts, timezones, and device emulation.
+Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including TLS client authentication, timeouts, timezones, and device emulation.
+
+<div id="synthetics-configuration-playwright-options-client-certificates"></div>
+
+### TLS client authentication
+To enable TLS client authentication, set the [`clientCertificates`](https://playwright.dev/docs/api/class-testoptions#test-options-client-certificates) option in the configuration file:
+
+<DocCallOut title="Note">
+  Path-based options `{certPath, keyPath, pfxPath}` are only supported on Private Locations, defer to in-memory alternatives `{cert, key, pfx}` when running on locations hosted by Elastic.
+</DocCallOut>
+
+```js
+playwrightOptions: {
+  clientCertificates: [
+    {
+      origin: 'https://example.com',
+      certPath: './cert.pem',
+      keyPath: './key.pem',
+      passphrase: 'mysecretpassword',
+    },
+    {
+      origin: 'https://example.com',
+      cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."),
+      key: Buffer.from("-----BEGIN RSA PRIVATE KEY-----\n..."),
+      passphrase: 'mysecretpassword',
+    }
+  ],
+}
+```
+
+<DocCallOut title="Tip">
+  When using Synthetics monitor UI, `cert`, `key` and `pfx` can simply be specified using a string literal:
+  ```js
+  clientCertificates: [
+    {
+      cert: "-----BEGIN CERTIFICATE-----\n...",
+      // Not cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."),
+    }
+  ],
+  ```
+</DocCallOut>
 
 <div id="synthetics-configuration-playwright-options-timeouts"></div>