From 4343cc96007758993b9767eb7aa6c2a090907402 Mon Sep 17 00:00:00 2001 From: Ji Lu Date: Tue, 12 May 2020 16:58:13 -0500 Subject: [PATCH 1/6] MQE-2122: MFTF 2FA documentation --- docs/configure-2fa.md | 46 +++++++++++++++++++++++++++++++++++++++++ docs/getting-started.md | 4 ++++ docs/test/actions.md | 20 ++++++++++++++++++ 3 files changed, 70 insertions(+) create mode 100644 docs/configure-2fa.md diff --git a/docs/configure-2fa.md b/docs/configure-2fa.md new file mode 100644 index 000000000..16d63c4dd --- /dev/null +++ b/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 +``` + +## 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 + +``` diff --git a/docs/getting-started.md b/docs/getting-started.md index 89d228df9..36ef03836 100644 --- a/docs/getting-started.md +++ b/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 `/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 \ No newline at end of file diff --git a/docs/test/actions.md b/docs/test/actions.md index 49e0c6afe..939f345df 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 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 + +``` + ### grabAttributeFrom See [grabAttributeFrom docs on codeception.com](http://codeception.com/docs/modules/WebDriver#grabAttributeFrom). From 557b15439b3760b953f07ef566701d301d07b8ed Mon Sep 17 00:00:00 2001 From: Ji Lu Date: Tue, 12 May 2020 17:19:17 -0500 Subject: [PATCH 2/6] MQE-2122: MFTF 2FA documentation --- docs/test/actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/test/actions.md b/docs/test/actions.md index 939f345df..14201b7bf 100644 --- a/docs/test/actions.md +++ b/docs/test/actions.md @@ -1078,7 +1078,7 @@ This action can optionally contain one or more [requiredEntity](#requiredentity) 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). +MFTF use TOTP from [Spomky-Labs/otphp](https://github.com/Spomky-Labs/otphp) if you want to know about this action. Attribute|Type|Use|Description ---|---|---|--- From 1ddc783f2e0d5ec756c56f81f980eb3f899b4acb Mon Sep 17 00:00:00 2001 From: Donald Booth Date: Tue, 12 May 2020 18:37:59 -0500 Subject: [PATCH 3/6] Grammar and formatting --- docs/configure-2fa.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/docs/configure-2fa.md b/docs/configure-2fa.md index 16d63c4dd..ed3e3d27f 100644 --- a/docs/configure-2fa.md +++ b/docs/configure-2fa.md @@ -1,31 +1,34 @@ -# MFTF Configuration for Magento with Two-Factor Authentication (2FA) +# 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 Magento CLI +To prepare Magento for MFTF testing when 2FA is enabled, set the following configurations through the Magento CLI. -### Select `Google Authenticator` as Magento 2FA provider +First, select `Google Authenticator` as Magento's 2FA provider: ```bash bin/magento config:set twofactorauth/general/force_providers google ``` -### Set OTP window to `60` seconds +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 OTP for the default admin user that you set for `MAGENTO_ADMIN_USERNAME` in .env. +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 MFTF {#config-mftf-2fa} +## Configure the 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). +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: @@ -35,11 +38,11 @@ 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. +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 +You will need to set the `secret` for any non-default admin users first, before using `getOTP`. For example: ```xml From dc71ad43ec51d931f219b3d31ec99eb291793aef Mon Sep 17 00:00:00 2001 From: Donald Booth Date: Tue, 12 May 2020 18:39:59 -0500 Subject: [PATCH 4/6] Grammar and formatting --- docs/getting-started.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 36ef03836..99b8f197e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -109,8 +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). +### 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} @@ -360,4 +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 \ No newline at end of file +[Magento Two-Factor Authentication (2FA) extension]: https://devdocs.magento.com/guides/v2.3/security/two-factor-authentication.html From 97e4d1fbf26727c14c44929cc80f450ca5a5238d Mon Sep 17 00:00:00 2001 From: Donald Booth Date: Tue, 12 May 2020 18:41:38 -0500 Subject: [PATCH 5/6] Editorial pass --- docs/test/actions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/test/actions.md b/docs/test/actions.md index 14201b7bf..1d2f83802 100644 --- a/docs/test/actions.md +++ b/docs/test/actions.md @@ -1075,10 +1075,10 @@ This action can optionally contain one or more [requiredEntity](#requiredentity) ### getOTP -Generate one-time password (OTP) based on a saved `secret` at path `magento/tfa/OTP_SHARED_SECRET` in MFTF credential storages. +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 know about this action. +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 ---|---|---|--- From b73d01b8d441e247cdca61946de0f160bda51310 Mon Sep 17 00:00:00 2001 From: Donald Booth Date: Tue, 12 May 2020 18:44:57 -0500 Subject: [PATCH 6/6] Fixed link paths --- docs/configure-2fa.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configure-2fa.md b/docs/configure-2fa.md index ed3e3d27f..f50838f0c 100644 --- a/docs/configure-2fa.md +++ b/docs/configure-2fa.md @@ -28,7 +28,7 @@ bin/magento security:tfa:google:set-secret