MQE-2122: MFTF 2FA documentation

Author: jilu1

docs/configure-2fa.md

@@ -0,0 +1,46 @@
+# MFTF Configuration for Magento with Two-Factor Authentication (2FA)
+
+## Configure Magento {#config-magento-2fa}
+
+To prepare Magento for MFTF testing when 2FA is enabled, set the following configurations through Magento CLI
+
+### Select `Google Authenticator` as Magento 2FA provider
+
+```bash
+bin/magento config:set twofactorauth/general/force_providers google
+```
+
+### Set OTP window to `60` seconds
+
+```bash
+bin/magento config:set twofactorauth/google/otp_window 60
+```
+
+### Set a base32 encoded `secret` for `Google Authenticator` to generate OTP for the default admin user that you set for `MAGENTO_ADMIN_USERNAME` in .env.
+
+```bash
+bin/magento security:tfa:google:set-secret <MAGENTO_ADMIN_USERNAME> <OTP_SHARED_SECRET>  
+```
+
+## Configure MFTF {#config-mftf-2fa}
+
+Save the same base32 encoded `secret` in MFTF Credential Storages, e.g. `.credentials` file, `HashiCorp Vault` or `AWS Secrets Manager`. 
+More details [here](../credentials.md).
+
+The path of the `secret` should be:
+
+```conf
+magento/tfa/OTP_SHARED_SECRET
+```
+
+## GetOTP {#getOTP}
+
+One-time password (OTP) is required when an admin user logs in to Magento Admin page. 
+Use action `getOTP` [Reference](../test/actions.md#getotp) to generate the code and use it for the `Authenticator code` text field in 2FA - Google Auth page.
+
+Note:
+You will need to set the `secret` for any non default admin users first before using `getOTP`. For example
+
+```xml
+<magentoCLI command="security:tfa:google:set-secret admin2 {{_CREDS.magento/tfa/OTP_SHARED_SECRET}}" stepKey="setSecret"/>
+```

docs/getting-started.md

@@ -109,6 +109,9 @@ Clean the cache after changing the configuration values:
 bin/magento cache:clean config full_page
 ```
 
+### Testing with Magento Two-Factor Authentication (2FA) extension {#2fa}
+If Magento under test has [Magento Two-Factor Authentication (2FA) extension][] installed and enabled, additional configures are needed to run MFTF tests. Learn more in [Configure MFTF for Magento with Two-Factor Authentication (2FA)](../configure-2fa.md).
+
 ### Webserver configuration {#web-server-configuration}
 
 The MFTF does not support executing CLI commands if your web server points to `<MAGE_ROOT_DIR>/pub` directory as recommended in the [Installation Guide][Installation Guide docroot]. For the MFTF to execute the CLI commands, the web server must point to the Magento root directory.
@@ -357,3 +360,4 @@ allure serve dev/tests/_output/allure-results/
 [test suite]: suite.html
 [Find your MFTF version]: introduction.html#find-your-mftf-version
 [Installation Guide docroot]: https://devdocs.magento.com/guides/v2.3/install-gde/tutorials/change-docroot-to-pub.html
+[Magento Two-Factor Authentication (2FA) extension]: https://devdocs.magento.com/guides/v2.3/security/two-factor-authentication.html

docs/test/actions.md

@@ -150,6 +150,7 @@ The following test actions return a variable:
 *  [grabTextFrom](#grabtextfrom)
 *  [grabValueFrom](#grabvaluefrom)
 *  [executeJS](#executejs)
+*  [getOTP](#getotp)
 
 Learn more in [Using data returned by test actions](../data.md#use-data-returned-by-test-actions).
 
@@ -1072,6 +1073,25 @@ The `ProductAttributeOptionGetter` entity must be defined in the corresponding [
 
 This action can optionally contain one or more [requiredEntity](#requiredentity) child elements.
 
+### getOTP
+
+Generate one-time password (OTP) based on a saved `secret` at path `magento/tfa/OTP_SHARED_SECRET` in MFTF credential storages.
+The one-time password (OTP) is returned and accessible through the stepkey. 
+
+MFTF use TOTP from [Spomky-Labs/otphp](https://github.com/Spomky-Labs/otphp).
+
+Attribute|Type|Use|Description
+---|---|---|---
+`stepKey`|string|required| A unique identifier of the action.
+`before`|string|optional| `stepKey` of action that must be executed next.
+`after`|string|optional| `stepKey` of preceding action.
+
+#### Example
+
+```xml
+<getOTP stepKey="getOtp"/>
+```
+
 ### grabAttributeFrom
 
 See [grabAttributeFrom docs on codeception.com](http://codeception.com/docs/modules/WebDriver#grabAttributeFrom).