DocumentationCommerceCommerce on Cloud Infrastructure Guide

Enable multi-factor authentication for SSH access

Last update: Fri Oct 20 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • Developer

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 user accounts with SSH access require either a two-factor authentication (TFA) code or an API token and SSH certificate to access the environment.

NOTE
MFA is not enabled on Cloud projects by default. The Account owner for the Adobe Commerce on cloud infrastructure project must Submit an Adobe Commerce Support ticket to enable it. When MFA is enabled, all users must have two-factor authentication (TFA) enabled on their Adobe Commerce on cloud infrastructure 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 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 workstation, create a file named config.yaml in the .magento-cloud folder in your home directory if it does not exist.

    code language-bash 
    touch ~/.magento-cloud/config.yaml

  2. Add the following configuration to the config.yaml file.

    code language-yaml 
    api:
   auto_load_ssh_cert: true

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

    Log out:

    code language-bash 
    magento-cloud logout

    Log in:

    code language-bash 
    magento-cloud login

    Follow the response:

    code language-terminal 
    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, you must have TFA enabled on your account before you can connect to a remote environment using an SSH. See Enable TFA.

Prerequisites:

For projects enabled with MFA enforcement, SSH access requires the following permissions and account settings:

style
shade-box

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.

    code language-bash 
    magento-cloud ssh-cert:load

    Sample response:

    code language-terminal 
    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. Use an SSH to connect to the remote environment.

    code language-bash 
    ssh abcdef7uyxabce-master-7rqtwti--mymagento@ssh.us-5.magento.cloud
    code language-terminal 
     __  __                   _          ___ _             _
|  \/  |__ _ __ _ ___ _ _| |_ ___   / __| |___ _  _ __| |
| |\/| / _` / _` / -_) ' \  _/ _ \ | (__| / _ \ || / _` |
|_|  |_\__,_\__, \___|_||_\__\___/  \___|_\___/\_,_\__,_|
            |___/

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

    code language-bash 
    magento-cloud ssh-cert:load

    Sample response:

    code language-terminal 
    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:

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

    Sample response:

    code language-terminal 
    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 an API token

When MFA is enabled on a project, automated processes that require SSH access to a Cloud environment require 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:

style
shade-box

To connect using SSH with an API token credential:

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

    code language-bash 
    magento-cloud auth:api-token

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

    code language-terminal 
    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.

NOTE
If an API token is stored, the magento-cloud CLI automatically authenticates and there is no need to perform the magento-cloud login command.

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 workstation, create a file named config.yaml in the .magento-cloud folder in your home directory if it does not exist.

    code language-bash 
    touch ~/.magento-cloud/config.yaml

  2. Add the following configuration to the config.yaml file.

    code language-yaml 
    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. In the upper-right account menu, click My Profile.

  3. On the My Profile page, click the Security tab.

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

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

  5. If TFA is configured, try authenticating again.

To authenticate and reload the SSH certificate:

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

    code language-bash 
    magento-cloud logout
    code language-bash 
    magento-cloud login

  2. Reload the SSH certificate:

    code language-bash 
    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, 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.

    code language-bash 
    touch ~/.ssh/config

  2. Add an IdentityFile configuration.

    code language-yaml 
    Host *
  IdentityFile ~/.ssh/id_rsa
NOTE
You can specify multiple SSH keys by adding multiple IdentityFile entries to your configuration.
05f2f56e-ac5d-4931-8cdb-764e60e16f26