Enable multi-factor authentication for SSH access

For added security, Adobe Commerce on cloud infrastructure provides multi-factor authentication (MFA) enforcement to manage authentication requirements for SSH access to Cloud environments.

When MFA is enabled on a project, all Adobe Commerce on cloud infrastructure accounts with SSH access must follow an authentication workflow that requires either a two-factor authentication (TFA) code or an API token and SSH certificate to access the environment.

Certificates for SSH access

MFA allows users to exchange an OAUTH access token with a short-lived SSH certificate generated by the Adobe Cloud Certifier API. If the user has the Admin or Contributor role, a valid SSH key, and a valid TFA code or API token, Adobe Commerce on cloud infrastructure uses these credentials to generate the temporary SSH certificate. The certificate expiration is set to one hour, but it refreshes automatically during the current session.

After logging into a project with MFA, users must use the magento-cloud CLI to generate the SSH certificate:

magento-cloud ssh-cert:load

The ssh-cert:load command generates the SSH certificate and installs it in the SSH agent of the local user.

Automatically generate certificate on login

You can configure your local environment to generate the SSH certificate automatically when you authenticate to the magento-cloud CLI.

To add SSH certificate auto-generation to your magento-cloud CLI configuration:

1. On your local work environment, create a file named config.yaml in the .magento-cloud folder in your home directory if it does not exist.

   touch ~/.magento-cloud/config.yaml
   

2. Edit the config.yaml file to add the following configuration.

   api:
      auto_load_ssh_cert: true
   

3. Use the magento-cloud CLI to authenticate again:

   Log out:

   magento-cloud logout
   

   Log in:

   magento-cloud login
   

   Follow the response:

   Please open the following URL in a browser and log in:
   http://127.0.0.1:5000
   
   Help:
     Leave this command running during login.
     If you need to quit, use Ctrl+C.
   
     To log in using an API token, run: magento-cloud auth:api-token-login
   
   Login information received. Verifying...
   You are logged in.
   
   Generating SSH certificate...
   A new SSH certificate has been generated.
   It will be automatically refreshed when necessary.
   The certificate is included in your SSH configuration: /Users/<user-name>/.ssh/config
   

Connect to an environment using SSH with TFA

When MFA is enabled on a project, any user that connects to a Cloud environment using SSH must have TFA enabled on their account. See Enable TFA.

Prerequisites:

For Adobe Commerce on cloud infrastructure projects enabled for MFA enforcement, SSH access requires the following permissions and account settings:

• Admin or contributor access to the environment
• SSH access key configured on account
• TFA enabled on account

To connect using SSH with TFA user account credentials:

1. Log in to your account.

2. On your local workstation, use the magento-cloud CLI to generate the SSH certificate.

   magento-cloud ssh-cert:load
   

   Sample response:

   Generating SSH certificate...
     Expires at: 2020-07-13T15:28:13-04:00
     Multi-factor authentication: verified
     Mode: interactive
   The certificate will be automatically refreshed when necessary.
   Checking SSH configuration file: /Users/<user-name>/.ssh/config
   Do you want to update the file automatically? [Y/n] Y
   Configuration file updated successfully: /Users/<user-name>/.ssh/config
   

3. Connect to the Cloud environment using SSH.

   ssh abcdef7uyxabce-master-7rqtwti--mymagento@ssh.us-5.magento.cloud
   

    __  __                   _          ___ _             _
   |  \/  |__ _ __ _ ___ _ _| |_ ___   / __| |___ _  _ __| |
   | |\/| / _` / _` / -_) ' \  _/ _ \ | (__| / _ \ || / _` |
   |_|  |_\__,_\__, \___|_||_\__\___/  \___|_\___/\_,_\__,_|
               |___/
   
    Welcome to Magento Cloud.
   
    This is environment master-7rqtwti
    of project abcdef7uyxabce.
   
   web@mymagento.0:~$
   

Manage source code using SSH with TFA

When managing source code for Adobe Commerce on cloud infrastructure projects, you use SSH to authenticate to the Git repository for the project. If your project has MFA enforcement enabled, you must generate an SSH certificate before you can perform command-line operations using the Git repository.

To connect using SSH with TFA user account credentials:

1. Log in to your account and authenticate using TFA.

   NOTE

   If you do not have TFA enabled on your account, you must enable it. See Enable TFA on cloud accounts.

2. On your local workstation, use the magento-cloud CLI to generate the SSH certificate.

   magento-cloud ssh-cert:load
   

   Sample response:

   Generating SSH certificate...
     Expires at: 2020-07-13T15:28:13-04:00
     Multi-factor authentication: verified
     Mode: interactive
   The certificate will be automatically refreshed when necessary.
   Checking SSH configuration file: /Users/<user-name>/.ssh/config
   Do you want to update the file automatically? [Y/n] Y
   Configuration file updated successfully: /Users/<user-name>/.ssh/config
   

3. Clone the Git repository for your project environment:

   git clone --branch integration abcdef7uyxabce@git.us-3.magento.cloud:abcdef7uyxabce.git myproject
   

   Sample response:

   Cloning into 'myproject'...
   Connection to git.us-3.magento.cloud port 22 [tcp/ssh] succeeded!
   remote: counting objects: 22, done.
   Receiving objects: 100% (22/22), 82.42 KiB | 16.48 MiB/s, done.
   

Connect to an environment using SSH with API token

When MFA is enabled on a project, automated processes that require SSH access to a Cloud environment must authenticate using an API token. You can generate the token from an Adobe Commerce on cloud infrastructure account with Admin or Contributor access on the project.

Authenticating with an API token still requires generating an SSH certificate. Automated processes must also automate the generation of an SSH certificate.

Prerequisites:

• Admin or Contributor access to the Adobe Commerce on cloud infrastructure environment
• Valid API token available on account

To connect using SSH with an API token credential:

1. Log in to the Cloud project using API key authentication.

   magento-cloud auth:api-token
   

2. At the prompt, enter the value for a valid API token.

   Please enter an API token:
   >
   
   The API token is valid.
   You are logged in.
   

Example: automated SSH script

There are two options for storing the API token.

Option 1: Create an environment variable to store the API token

Write the token to your bash_profile

echo "export MAGENTO_CLOUD_CLI_TOKEN=<your api token>" >> ~/.bash_profile

Option 2: Add the token to the config.yaml file

1. On your local work environment, create a file named config.yaml in the .magento-cloud folder in your home directory if it does not exist.

   touch ~/.magento-cloud/config.yaml
   

2. Edit the config.yaml file to add the following configuration.

   api:
      token: <your api token>
   

Sample bash script

#!/bin/bash
magento-cloud ssh-cert:load
ssh abcdef7uyxabce-master-7rqtabc--mymagento@ssh.us-3.magento.cloud "tail -n 10 ~/var/log/cloud.log"

Troubleshooting

Use the following information to resolve SSH connection requests failures due to authentication errors like access requires MFA or permission denied.

Your request does not provide a valid certificate

If your request does not provide a valid certificate, a message similar to the following displays:

to Hello user-test (UUID: abaacca12-5cd1-4b123-9096-411add578998), you successfully
authenticated, but could not connect to service abcdef7uyxabce-master-7rqtabc--mymagento@ssh.us-3.magento.cloud:>
(reason: access requires MFA)

Try the following troubleshooting procedures to resolve the connection issue:

• Verify the account TFA configuration
• Authenticate again, and then reload the certificate

To verify TFA configuration and authentication:

1. Log in to your account.

2. Click Account settings > Security.

   If TFA is enabled, the Security section provides options to manage the TFA configuration:

   

3. If TFA is not set up, click Set up application and follow the instructions to enable it. See Enable TFA.

4. If TFA is configured, try authenticating again.

To authenticate and reload the SSH certificate:

1. Use the magento-cloud CLI to authenticate again:

   magento-cloud logout
   

   magento-cloud login
   

2. Reload the SSH certificate:

   magento-cloud ssh-cert:load
   

Permission denied

If the SSH key is missing or invalid, the SSH connection request returns a Permission denied (publickey) error.

Hello user-test (UUID: abaacca12-5cd1-4b123-9096-411add578998), you successfully authenticated, but could not connect to service oh2wi6klp5ytk-mc-35985-integration-nnulm4a--mymagento (reason: service doesn't exist or you do not have access to it)
oh2wi6klp5ytk-mc-35985-integration-nnulm4a--mymagento@ssh.eu-3.magento.cloud: Permission denied (publickey).

To fix the problem, you might need to add the SSH key to your current session, or update the SSH configuration file to load your SSH keys automatically. See Add a public SSH key.

Unable to access projects without MFA

If you authenticate to a project with multi-factor authentication (MFA) enabled, you might receive the following error when connecting to other projects that do not require MFA:

ssh abcdef7uyxabce-master-7rqtabc--mymagento@ssh.us-3.magento.cloud

Sample response:

abcdef7uyxabce-master-7rqtabc--mymagento@ssh.us-3.magento.cloud: Permission denied (publickey).

During the SSH certificate generation, the magento-cloud CLI adds an additional SSH key to your local environment. That key is used by default if your local SSH configuration does not include the SSH key for project access.

To add your SSH key to the local configuration:

1. Create the config file if it does not exists.

   touch ~/.ssh/config
   

2. Add an IdentityFile configuration.

   Host *
     IdentityFile ~/.ssh/id_rsa
   

Business.Adobe.com resources