Skip to content

[8.16](backport #4444) add synthetics multi factor authentication docs #4476

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 4, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/en/observability/index.asciidoc
Original file line number Diff line number Diff line change
@@ -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]
23 changes: 23 additions & 0 deletions docs/en/observability/synthetics-command-reference.asciidoc
Original file line number Diff line number Diff line change
@@ -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`
62 changes: 62 additions & 0 deletions docs/en/observability/synthetics-mfa.asciidoc
Original file line number Diff line number Diff line change
@@ -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.
====