Credentials

When you test functionality that involves external services such as UPS, FedEx, PayPal, or SignifyD, use the Functional Testing Framework credentials feature to hide sensitive data like integration tokens and API keys.

Currently, the Functional Testing Framework supports three types of credential storage:

.credentials file
HashiCorp Vault
AWS Secrets Manager

Configure File Storage

The Functional Testing Framework creates a sample file for credentials during initial setup: magento2/dev/tests/acceptance/.credentials.example. The file contains an example list of keys for fields that can require credentials.

Create `.credentials`

To make the Functional Testing Framework process the file with credentials, in the command line, navigate to magento2/dev/tests/acceptance/ and rename .credentials.example to .credentials.

cd dev/tests/acceptance/

cp .credentials.example .credentials

Add `.credentials` to `.gitignore`

Verify that the file is excluded from tracking by .gitignore (unless you need this behavior):

git check-ignore .credentials

The command outputs the path if the file is excluded:

.credentials

Define sensitive data in the `.credentials` file

Open the .credentials file and, for Adobe Commerce or Magento Open Source core credentials, uncomment the fields you want to use and add your values:

...
# Credentials for the USPS service
magento/carriers_usps_userid=usps_test_user
magento/carriers_usps_password=Lmgxvrq89uPwECeV

# Credentials for the DHL service
#magento/carriers_dhl_id_us=dhl_test_user
#magento/carriers_dhl_password_us=Mlgxv3dsagVeG
....

Add key and value pair for admin password

magento/MAGENTO_ADMIN_PASSWORD must contain the user password required for authorization in the Admin area. Example: magento/MAGENTO_ADMIN_PASSWORD=mycustompassword

...
# Admin password
magento/MAGENTO_ADMIN_PASSWORD=123123q

....

Or add new key-value pairs for your own credentials. The keys use the following format:

<vendor>/<key_name>=<key_value>

data-variant=info

data-slots=text

The / symbol is not supported in a key_name other than the one after your vendor or extension name.

Otherwise you are free to use any other key_name you like, as they are merely the keys to reference from your tests.

# Credentials for the MyAwesome service
vendor/my_awesome_service_token=rRVSVnh3cbDsVG39oTMz4A

Configure Vault Storage

Hashicorp vault secures, stores, and tightly controls access to data in modern computing. It provides advanced data protection for your testing credentials.

The Functional Testing Framework works with both vault enterprise and vault open source that use KV Version 2 secret engine.

Install vault CLI

Download and install vault command-line tool if you want to run or develop tests locally. Download Vault

Authenticate to vault via vault CLI

Authenticate to vault server via the vault command-line tool: Login Vault.

vault login -method -path

Do not use -no-store command option, as the Functional Testing Framework will rely on the persisted token in the token helper (usually the local filesystem) for future API requests.

Store secrets in vault

The Functional Testing Framework uses the KV Version 2 secret engine for secret storage. More information for working with KV Version 2 can be found in Vault KV2.

Secrets path and key convention

The path and key for secret data must follow the format:

<SECRETS_BASE_PATH>/mftf/<VENDOR>/<SECRET_KEY>

# Secret path and key for carriers_usps_userid
secret/mftf/magento/carriers_usps_userid

# Secret path and key for carriers_usps_password
secret/mftf/magento/carriers_usps_password

Write secrets to vault

You can use vault CLI or API to write secret data (credentials, etc) to vault. Here is a CLI example:

vault kv put secret/mftf/magento/carriers_usps_userid carriers_usps_userid=usps_test_user
vault kv put secret/mftf/magento/carriers_usps_password carriers_usps_password=Lmgxvrq89uPwECeV

Setup the framework to use vault

Add vault configuration environment variables CREDENTIAL_VAULT_ADDRESS and CREDENTIAL_VAULT_SECRET_BASE_PATH from etc/config/.env.example in .env. Set values according to your vault server configuration.

# Default vault dev server
CREDENTIAL_VAULT_ADDRESS=http://127.0.0.1:8200
CREDENTIAL_VAULT_SECRET_BASE_PATH=secret

Configure AWS Secrets Manager

AWS Secrets Manager offers secret management that supports:

Secret rotation with built-in integration for Amazon RDS, Amazon Redshift, and Amazon DocumentDB
Fine-grained policies and permissions
Audit secret rotation centrally for resources in the AWS Cloud, third-party services, and on-premises

Prerequisites

Use AWS Secrets Manager from your own AWS account

An AWS account with Secrets Manager service
An IAM user with AWS Secrets Manager access permission

Use AWS Secrets Manager in CI/CD

AWS account ID where the AWS Secrets Manager service is hosted
Authorized CI/CD EC2 instances with AWS Secrets Manager service access IAM role attached

Store secrets in AWS Secrets Manager

Secrets format

Secret Name and Secret Value are two key pieces of information for creating a secret.

Secret Value can be either plaintext or key-value pairs in JSON format.

Secret Name must use the following format:

mftf/<VENDOR>/<YOUR/SECRET/KEY>

Secret Value can be stored in two different formats: plaintext or key-value pairs.

For plaintext format, Secret Value can be any string you want to secure.

For key-value pairs format, Secret Value is a key-value pair with key the same as Secret Name without mftf/<VENDOR>/ prefix, which is <YOUR/SECRET/KEY>, and value can be any string you want to secure.

Create Secrets using AWS CLI

aws secretsmanager create-secret --name "mftf/magento/shipping/carriers_usps_userid" --description "Carriers USPS user id" --secret-string "1234567"

Create Secrets using AWS Console

Sign in to the AWS Secrets Manager console
Choose Store a new secret
In the Select secret type section, specify "Other type of secret"
For Secret Name, Secret Key and Secret Value field, for example, to save the same secret in key-value JSON format, you should use

# Secret Name
mftf/magento/shipping/carriers_usps_userid

# Secret Key
shipping/carriers_usps_userid

# Secret Value
1234567

Setup the framework to use AWS Secrets Manager

To use AWS Secrets Manager, the AWS region to connect to is required. You can set it through environment variable CREDENTIAL_AWS_SECRETS_MANAGER_REGION in .env.

The Functional Testing Framework uses the recommended Default Credential Provider Chain to establish connection to AWS Secrets Manager service. You can setup credentials according to Default Credential Provider Chain and there is no Functional Testing Framework-specific setup required. Optionally, however, you can explicitly set AWS profile through environment variable CREDENTIAL_AWS_SECRETS_MANAGER_PROFILE in .env.

# Sample AWS Secrets Manager configuration
CREDENTIAL_AWS_SECRETS_MANAGER_REGION=us-east-1
CREDENTIAL_AWS_SECRETS_MANAGER_PROFILE=default

Optionally set CREDENTIAL_AWS_ACCOUNT_ID environment variable

In case AWS credentials cannot resolve to a valid AWS account, full AWS KMS (Key Management Service) key ARN (Amazon Resource Name) is required. You will also need to set CREDENTIAL_AWS_ACCOUNT_ID environment variable so that the Functional Testing Framework can construct the full ARN. This is mostly used for CI/CD.

export CREDENTIAL_AWS_ACCOUNT_ID=<Your_12_Digits_AWS_Account_ID>

Configure multiple credential storage

It is possible and sometimes useful to setup and use multiple credential storage at the same time. In this case, the test are able to read secret data at runtime from all storage options. The Functional Testing Framework will use the following precedence:

.credentials File > HashiCorp Vault > AWS Secrets Manager

Use credentials in a test

Credentials can be used in actions: fillField, magentoCLI, and createData.

Define the value as a reference to the corresponding key in the credentials file or vault such as {{_CREDS.my_data_key}}:

_CREDS is an environment constant pointing to the .credentials file
my_data_key is a key in the the .credentials file or vault that contains the value to be used in a test step
- for File Storage, ensure your key contains the vendor prefix, which is vendor/my_data_key

For example, to reference secret data in the fillField action, use the userInput attribute using a typical File Storage:

<fillField stepKey="FillApiToken" selector=".api-token" userInput="{{_CREDS.vendor/my_data_key}}" />

Implementation details

The generated tests do not contain credentials values. The Functional Testing Framework dynamically retrieves, encrypts, and decrypts the sensitive data during test execution. Decrypted credentials do not appear in the console, error logs, or test reports. The decrypted values are only available in the .credentials file or within vault.

data-variant=info

data-slots=text

The test delivered with the Adobe Commerce and Magento Open Source application do not use credentials and do not cover external services, because of sensitivity of the data.