Merge pull request #702 from magento/MQE-2122

MQE-2122: MFTF 2FA documentation

Author: jilu1

docs/configure-2fa.md

@@ -0,0 +1,49 @@
+# Configuring MFTF for Two-Factor Authentication (2FA)
+
+Using two-factor authentication (2FA) with MFTF is possible with some configurations settings in Magento.
+In this document, we will use Google as the authentication provider.
+
+## Configure Magento {#config-magento-2fa}
+
+To prepare Magento for MFTF testing when 2FA is enabled, set the following configurations through the Magento CLI.
+
+First, select `Google Authenticator` as Magento's 2FA provider:
+
+```bash
+bin/magento config:set twofactorauth/general/force_providers google
+```
+
+Now set the 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 a 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 the MFTF {#config-mftf-2fa}
+
+Save the same base32-encoded `secret` in a MFTF credential storage, e.g. `.credentials` file, `HashiCorp Vault` or `AWS Secrets Manager`. 
+More details are [here](./credentials.md).
+
+The path of the `secret` should be:
+
+```conf
+magento/tfa/OTP_SHARED_SECRET
+```
+
+## GetOTP {#getOTP}
+
+A one-time password (OTP) is required when an admin user logs into the Magento admin. 
+Use the 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,10 @@ Clean the cache after changing the configuration values:
 bin/magento cache:clean config full_page
 ```
 
+### Testing with the Magento Two-Factor Authentication (2FA) extension {#2fa}
+
+If the Magento instance under test has the [Magento Two-Factor Authentication (2FA) extension][] installed and enabled, additional configurations is 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 +361,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 a one-time password (OTP) based on a saved `secret` at path `magento/tfa/OTP_SHARED_SECRET` in a MFTF credential storage.
+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), if you want to learn more about this action.
+
+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).