diff --git a/docs/configure-2fa.md b/docs/configure-2fa.md new file mode 100644 index 000000000..f50838f0c --- /dev/null +++ b/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 +``` + +## 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 + +``` diff --git a/docs/getting-started.md b/docs/getting-started.md index 89d228df9..99b8f197e 100644 --- a/docs/getting-started.md +++ b/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 `/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 diff --git a/docs/test/actions.md b/docs/test/actions.md index 49e0c6afe..1d2f83802 100644 --- a/docs/test/actions.md +++ b/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 + +``` + ### grabAttributeFrom See [grabAttributeFrom docs on codeception.com](http://codeception.com/docs/modules/WebDriver#grabAttributeFrom).