Enable multi-factor authentication for SSH access

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

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

MFA is not enabled on Cloud projects by default. The Account owner for the Magento Commerce Cloud project must submit a Magento support request to enable it. As soon as MFA is turned on, all users must have two-factor authentication (TFA) enabled on their Magento Commerce Cloud account for SSH access to the project environments.

Certificates for SSH access

MFA allows users to exchange an OAUTH access token with a short-lived SSH certificate generated by the Magento Cloud Certifier API.

If the user accessing the environment has the Admin or Contributor role, a valid SSH key, and a valid TFA code or API token, Magento Commerce Cloud uses these credentials to generate the temporary SSH certificate. The certificate expiration is set to 1 hour, but it refreshes automatically during the current session.

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

1
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.

    1
    
     touch ~/.magento-cloud/config.yaml
    
  2. Edit the config.yaml file to add the following configuration.

    1
    2
    
    api:
       auto_load_ssh_cert: true
    
  3. Use the Magento Cloud CLI to authenticate again:

    1
    
    magento-cloud logout
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    
    magento-cloud login
    
    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 Magento Commerce Cloud project, any user that connects to a Cloud environment using SSH must have TFA enabled on their account. See Enable TFA.

Prerequisites:

For Magento Commerce Cloud projects enabled for MFA enforcement, SSH access requires the following permissions and account settings:

To connect using SSH with TFA user account credentials:

  1. Log in to your Magento Commerce Cloud account and authenticate using TFA.

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

    1
    
    magento-cloud ssh-cert:load
    
    1
    2
    3
    4
    5
    6
    7
    8
    
    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:

    1
    
    ssh gbhzpx7xmpule-master-7rqtwti--mymagento@ssh.us-3.magento.cloud
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    
     __  __                   _          ___ _             _
    |  \/  |__ _ __ _ ___ _ _| |_ ___   / __| |___ _  _ __| |
    | |\/| / _` / _` / -_) ' \  _/ _ \ | (__| / _ \ || / _` |
    |_|  |_\__,_\__, \___|_||_\__\___/  \___|_\___/\_,_\__,_|
                |___/
    
     Welcome to Magento Cloud.
    
     This is environment master-7rqtabc
     of project abcdef7uyxabce.
    
    web@mymagento.0:~$
    

Manage source code using SSH with TFA

When managing source code for Magento Commerce Cloud 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 Magento Commerce Cloud account and authenticate using TFA.

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

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

    1
    
    magento-cloud ssh-cert:load
    
    1
    2
    3
    4
    5
    6
    7
    8
    
    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:

    1
    
     git clone --branch integration abcdef7uyxabce@git.us-3.magento.cloud:abcdef7uyxabce.git myproject
    
    1
    2
    3
    4
    
     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 Magento Commerce Cloud project, automated processes that require SSH access to a Cloud environment must authenticate using an API token.

You generate the token from a Magento Commerce Cloud 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:

To connect using SSH with an API token credential:

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

    1
    
    magento-cloud auth:api-token
    
  2. At the prompt, enter the value for a valid API token.

    1
    2
    3
    4
    5
    
    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.

If an API token is stored, the Magento Cloud CLI will automatically authenticate and there is no need to perform the mgc login command

Create an environment variable to store the API token.

  1. Write the token to your bash_profile

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

Add the token to the Magento Cloud 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.

    1
    
     touch ~/.magento-cloud/config.yaml
    
  2. Edit the config.yaml file to add the following configuration.

    1
    2
    
    api:
       token: <your api token>
    

Sample bash script

1
2
3
   #!/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:

1
2
3
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. On your Cloud account, click Account settings > Security.

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

    Cloud manage TFA config

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

  3. If TFA is configured, try authenticating again.

To authenticate and reload the SSH certificate:

  1. Use the Magento Cloud CLI to authenticate again:

    1
    
    magento-cloud logout
    
    1
    
    magento-cloud login
    
  2. Reload the SSH certificate:

    1
    
    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.

1
2
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 and Unable to access projects without MFA.