Skip to content

Commit 704f88d

Browse files
vigneshshanmugamemilioalvapbmorelli25colleenmcginnis
authored
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 <95703246+emilioalvap@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Brandon Morelli <bmorelli25@gmail.com> Co-authored-by: Colleen McGinnis <colleen.j.mcginnis@gmail.com> * Update docs/en/observability/synthetics-mfa.asciidoc Co-authored-by: Colleen McGinnis <colleen.j.mcginnis@gmail.com> --------- Co-authored-by: Emilio Alvarez Piñeiro <95703246+emilioalvap@users.noreply.github.com> Co-authored-by: Brandon Morelli <bmorelli25@gmail.com> Co-authored-by: Colleen McGinnis <colleen.j.mcginnis@gmail.com>
1 parent a7f583c commit 704f88d

File tree

6 files changed

+183
-0
lines changed

6 files changed

+183
-0
lines changed

‎docs/en/observability/index.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,8 @@ include::synthetics-command-reference.asciidoc[leveloffset=+3]
5656

5757
include::synthetics-configuration.asciidoc[leveloffset=+3]
5858

59+
include::synthetics-mfa.asciidoc[leveloffset=+3]
60+
5961
include::synthetics-settings.asciidoc[leveloffset=+3]
6062

6163
include::synthetics-roles.asciidoc[leveloffset=+3]

‎docs/en/observability/synthetics-command-reference.asciidoc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -333,3 +333,26 @@ and you do _not_ include `--url` and `--auth`, all global locations managed by E
333333
However, you will not be able to push to these locations with your API key and will see an error:
334334
_You don't have permission to use Elastic managed global locations_. For more details, refer to the
335335
<<synthetics-troubleshooting-public-locations-disabled,troubleshooting docs>>.
336+
337+
[discrete]
338+
[[elastic-synthetics-totp-command]]
339+
= `@elastic/synthetics totp <secret>`
340+
341+
Generate a Time-based One-Time Password (TOTP) for multifactor authentication (MFA) in Synthetics.
342+
343+
[source, sh]
344+
----
345+
npx @elastic/synthetics totp <secret>
346+
npx @elastic/synthetics totp <secret> --issuer <string> --label <string>
347+
----
348+
349+
`<secret>`::
350+
The encoded secret key used to generate the TOTP.
351+
352+
`--issuer <string>`::
353+
354+
Name of the provider or service that is assocaited with the account.
355+
356+
`--label <string>`::
357+
358+
Identifier for the account. Defaults to `SyntheticsTOTP`

‎docs/en/observability/synthetics-mfa.asciidoc‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
[[synthetics-mfa]]
2+
= Multi-factor Authentication (MFA) for browser monitors
3+
4+
++++
5+
<titleabbrev>Multi-factor Authentication</titleabbrev>
6+
++++
7+
8+
Multi-factor Authentication (MFA) adds an essential layer of security to
9+
applications login processes, protecting against unauthorized access. A very
10+
common use case in Synthetics is testing user journeys involving websites
11+
protected by MFA.
12+
13+
Synthetics supports testing websites secured by Time-based One-Time Password
14+
(TOTP), a common MFA method that provides short-lived one-time tokens to
15+
enhance security.
16+
17+
[discrete]
18+
== Configuring TOTP for MFA
19+
20+
To test a browser journey that uses TOTP for MFA, first configure the
21+
Synthetics authenticator token in the target application. To do this, generate a One-Time
22+
Password (OTP) using the Synthetics CLI; refer to <<elastic-synthetics-totp-command>>.
23+
24+
```sh
25+
npx @elastic/synthetics totp <secret>
26+
27+
// prints
28+
OTP Token: 123456
29+
```
30+
31+
[discrete]
32+
== Applying the TOTP Token in Browser Journeys
33+
34+
Once the Synthetics TOTP Authentication is configured in your application, you
35+
can now use the OTP token in the synthetics browser journeys using the `mfa`
36+
object imported from `@elastic/synthetics`.
37+
38+
```ts
39+
import { journey, step, mfa} from '@elastic/synthetics';
40+
41+
journey('MFA Test', ({ page, params }) => {
42+
step('Login using TOTP token', async () => {
43+
// login using username and pass and go to 2FA in next page
44+
const token = mfa.token(params.MFA_GH_SECRET);
45+
await page.getByPlaceholder("token-input").fill(token)
46+
});
47+
});
48+
```
49+
50+
For monitors created in the Synthetics UI using the Script editor, the `mfa` object can be accessed as shown below:
51+
52+
```ts
53+
step('Login using 2FA', async () => {
54+
const token = mfa.token(params.MFA_GH_SECRET);
55+
await page.getByPlaceholder("token-input").fill(token)
56+
});
57+
```
58+
59+
[NOTE]
60+
====
61+
`params.MFA_GH_SECRET` would be the encoded secret that was used for registering the Synthetics Authentication in your web application.
62+
====

‎docs/en/serverless/serverless-observability.docnav.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -483,6 +483,11 @@
483483
"slug": "/serverless/observability/synthetics-configuration",
484484
"classic-sources": ["enObservabilitySyntheticsConfiguration"]
485485
},
486+
{
487+
"label": "Multifactor Authentication for browser monitors",
488+
"slug": "/serverless/observability/synthetics-mfa",
489+
"classic-sources": ["enObservabilitySyntheticsMFA"]
490+
},
486491
{
487492
"label": "Configure Synthetics settings",
488493
"slug": "/serverless/observability/synthetics-settings",

‎docs/en/serverless/synthetics/synthetics-command-reference.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -366,3 +366,28 @@ To list both locations on Elastic's global managed infrastructure and ((private-
366366
_You don't have permission to use Elastic managed global locations_. For more details, refer to the
367367
<DocLink slug="/serverless/observability/synthetics-troubleshooting" section="you-do-not-have-permission-to-use-elastic-managed-locations">troubleshooting docs</DocLink>.
368368
</DocCallOut> */}
369+
370+
## `@elastic/synthetics totp <secret>`
371+
372+
Generate a Time-based One-Time Password (TOTP) for multifactor authentication(MFA) in Synthetics.
373+
374+
```sh
375+
npx @elastic/synthetics totp <secret> --issuer <issuer> --label <label>
376+
```
377+
378+
<DocDefList>
379+
<DocDefTerm>`secret`</DocDefTerm>
380+
<DocDefDescription>
381+
The encoded secret key used to generate the TOTP.
382+
</DocDefDescription>
383+
384+
<DocDefTerm>`--issuer <string>`</DocDefTerm>
385+
<DocDefDescription>
386+
Name of the provider or service that is assocaited with the account.
387+
</DocDefDescription>
388+
389+
<DocDefTerm>`--label <string>`</DocDefTerm>
390+
<DocDefDescription>
391+
Identifier for the account. Defaults to `SyntheticsTOTP`
392+
</DocDefDescription>
393+
</DocDefList>

‎docs/en/serverless/synthetics/synthetics-mfa.mdx‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
slug: /serverless/observability/synthetics-mfa
3+
title: Multi-factor Authentication (MFA) for browser monitors
4+
# description: Description to be written
5+
tags: []
6+
---
7+
8+
<p>
9+
<DocBadge template="technical preview" />
10+
</p>
11+
12+
<div id="synthetics-mfa"></div>
13+
14+
Multi-factor Authentication (MFA) adds an essential layer of security to
15+
applications login processes, protecting against unauthorized access. A very
16+
common use case in Synthetics is testing user journeys involving websites
17+
protected by MFA.
18+
19+
Synthetics supports testing websites secured by Time-based One-Time Password
20+
(TOTP), a common MFA method that provides short-lived one-time tokens to
21+
enhance security.
22+
23+
## Configuring TOTP for MFA
24+
25+
To test a browser journey that uses TOTP for MFA, first configure the
26+
Synthetics authenticator token in the target application. To do this, generate a One-Time
27+
Password (OTP) using the Synthetics CLI; refer to <DocLink slug="/serverless/observability/synthetics-command-reference" section="@elastic/synthetics totp <secret>">`@elastic/synthetics totp <secret>`</DocLink>.
28+
29+
```sh
30+
npx @elastic/synthetics totp <secret>
31+
32+
// prints
33+
OTP Token: 123456
34+
```
35+
36+
## Applying the TOTP Token in Browser Journeys
37+
38+
Once the Synthetics TOTP Authentication is configured in your application, you can now use the OTP token in the synthetics browser
39+
journeys using the `mfa` object imported from `@elastic/synthetics`.
40+
41+
```ts
42+
import { journey, step, mfa } from "@elastic/synthetics";
43+
44+
journey("MFA Test", ({ page, params }) => {
45+
step("Login using TOTP token", async () => {
46+
// login using username and pass and go to 2FA in next page
47+
const token = mfa.token(params.MFA_GH_SECRET);
48+
await page.getByPlaceholder("token-input").fill(token);
49+
});
50+
});
51+
```
52+
53+
For monitors created in the Synthetics UI using the Script editor, the `mfa` object can be accessed as shown below:
54+
55+
```ts
56+
step("Login using 2FA", async () => {
57+
const token = mfa.token(params.MFA_GH_SECRET);
58+
await page.getByPlaceholder("token-input").fill(token);
59+
});
60+
```
61+
62+
<DocCallOut title="Note">
63+
64+
`params.MFA_GH_SECRET` would be the encoded secret that was used for registering the Synthetics Authentication in your web application.
65+
66+
</DocCallOut>

0 commit comments

Comments
 (0)