[8.x](backport #4444) add synthetics multi factor authentication docs (…

…#4475) * add synthetics multi factor authentication docs (#4444) * add synthetics multi factor authentication docs * apply suggestions from code review Co-authored-by: Emilio Alvarez Piñeiro <[email protected]> * Apply suggestions from code review Co-authored-by: Brandon Morelli <[email protected]> Co-authored-by: Colleen McGinnis <[email protected]> * Update docs/en/observability/synthetics-mfa.asciidoc Co-authored-by: Colleen McGinnis <[email protected]> --------- Co-authored-by: Emilio Alvarez Piñeiro <[email protected]> Co-authored-by: Brandon Morelli <[email protected]> Co-authored-by: Colleen McGinnis <[email protected]> (cherry picked from commit 704f88d) # Conflicts: # docs/en/serverless/serverless-observability.docnav.json # docs/en/serverless/synthetics/synthetics-command-reference.mdx * Delete docs/en/serverless directory --------- Co-authored-by: Vignesh Shanmugam <[email protected]> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
elastic · Nov 4, 2024 · 154db12 · 154db12
1 parent 7ffbd5b
commit 154db12
Show file tree

Hide file tree

Showing 3 changed files with 87 additions and 0 deletions.
diff --git a/docs/en/observability/index.asciidoc b/docs/en/observability/index.asciidoc
@@ -56,6 +56,8 @@ include::synthetics-command-reference.asciidoc[leveloffset=+3]
 
 include::synthetics-configuration.asciidoc[leveloffset=+3]
 
+include::synthetics-mfa.asciidoc[leveloffset=+3]
+
 include::synthetics-settings.asciidoc[leveloffset=+3]
 
 include::synthetics-roles.asciidoc[leveloffset=+3]

diff --git a/docs/en/observability/synthetics-command-reference.asciidoc b/docs/en/observability/synthetics-command-reference.asciidoc
@@ -333,3 +333,26 @@ and you do _not_ include `--url` and `--auth`, all global locations managed by E
 However, you will not be able to push to these locations with your API key and will see an error:
 _You don't have permission to use Elastic managed global locations_. For more details, refer to the
 <<synthetics-troubleshooting-public-locations-disabled,troubleshooting docs>>.
+
+[discrete]
+[[elastic-synthetics-totp-command]]
+= `@elastic/synthetics totp <secret>`
+
+Generate a Time-based One-Time Password (TOTP) for multifactor authentication (MFA) in Synthetics.
+
+[source, sh]
+----
+npx @elastic/synthetics totp <secret>
+npx @elastic/synthetics totp <secret> --issuer <string> --label <string>
+----
+
+`<secret>`::
+The encoded secret key used to generate the TOTP.
+
+`--issuer <string>`::
+
+Name of the provider or service that is assocaited with the account.
+
+`--label <string>`::
+
+Identifier for the account. Defaults to `SyntheticsTOTP`
diff --git a/docs/en/observability/synthetics-mfa.asciidoc b/docs/en/observability/synthetics-mfa.asciidoc
@@ -0,0 +1,62 @@
+[[synthetics-mfa]]
+= Multi-factor Authentication (MFA) for browser monitors
+
+++++
+<titleabbrev>Multi-factor Authentication</titleabbrev>
+++++
+
+Multi-factor Authentication (MFA) adds an essential layer of security to
+applications login processes, protecting against unauthorized access. A very
+common use case in Synthetics is testing user journeys involving websites
+protected by MFA.
+
+Synthetics supports testing websites secured by Time-based One-Time Password
+(TOTP), a common MFA method that provides short-lived one-time tokens to
+enhance security.
+
+[discrete]
+== Configuring TOTP for MFA
+
+To test a browser journey that uses TOTP for MFA, first configure the
+Synthetics authenticator token in the target application. To do this, generate a One-Time
+Password (OTP) using the Synthetics CLI; refer to <<elastic-synthetics-totp-command>>.
+
+```sh
+npx @elastic/synthetics totp <secret>
+
+// prints
+OTP Token: 123456
+```
+
+[discrete]
+== Applying the TOTP Token in Browser Journeys
+
+Once the Synthetics TOTP Authentication is configured in your application, you
+can now use the OTP token in the synthetics browser journeys using the `mfa`
+object imported from `@elastic/synthetics`.
+
+```ts
+import { journey, step, mfa} from '@elastic/synthetics';
+
+journey('MFA Test', ({ page, params }) => {
+  step('Login using TOTP token', async () => {
+    // login using username and pass and go to 2FA in next page
+    const token = mfa.token(params.MFA_GH_SECRET);
+    await page.getByPlaceholder("token-input").fill(token)
+  });
+});
+```
+
+For monitors created in the Synthetics UI using the Script editor, the `mfa` object can be accessed as shown below:
+
+```ts
+step('Login using 2FA', async () => {
+  const token = mfa.token(params.MFA_GH_SECRET);
+  await page.getByPlaceholder("token-input").fill(token)
+});
+```
+
+[NOTE]
+====
+`params.MFA_GH_SECRET` would be the encoded secret that was used for registering the Synthetics Authentication in your web application.
+====