Improve info about managing SSH keys in Cloud Guide (#8364)

* Fix broken link in Cloud Guide

* Add tip for managing SSH keys on Cloud projects

* Update src/_includes/cloud/enable-ssh.md

* Fix lint error

* Replace ssh-keygen instructions with link

- Replaced ssh-keygen instructions with link to GitHub documentation,
which provides instructions for Linux, macOS, and Windows.
- Clarified other instructions

* Apply suggestions from code review

Co-authored-by: hguthrie <[email protected]>

Co-authored-by: hguthrie <[email protected]>

Author: meker12

src/_includes/cloud/enable-ssh.md

@@ -15,89 +15,31 @@ For more information on SSH keys, see the following:
 
 ## Locate an existing SSH key pair {#existing}
 
-An existing SSH key pair is typically located in the `.ssh` subdirectory of the user's home directory. This folder is hidden and may not display in the file manager or finder unless configured to display hidden files and folders.
-
-You can quickly verify if you have SSH keys by entering commands using terminal access.
-
-To check for SSH keys, enter the following command:
-
-```bash
-ls ~/.ssh
-```
-
-If you have SSH keys, a directory listing is displayed similar to the following:
-
-```terminal
-id_rsa  id_rsa.pub  known_hosts
-```
-
-If you do not have SSH keys, you need to generate the keys for adding to your Magento ECE account and GitHub account. See [Create a new SSH key pair](#ssh-create-new-key-pair).
-
-If you already have SSH keys, continue to:
-
--  [Add a public SSH key to your Magento account](#ssh-add-to-account) section
--  [Add your SSH key to your GitHub account](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/)
-
-## Create a new SSH key pair {#ssh-create-new-key-pair}
-
-Use the `ssh-keygen` command to create an SSH key pair. `ssh-keygen` is typically installed on Linux systems.
+An existing SSH key pair is typically located in the `.ssh` subdirectory of the user home directory. This folder is hidden and may not display in the File Manager or Finder if your system is not configured to display hidden files and folders.
 
 {:.procedure}
-To create an SSH key pair:
+To check for SSH keys:
 
-1. The command syntax follows, entering the email used for your GitHub account:
+1. In the terminal, list the contents of your SSH directory.
 
    ```bash
-   ssh-keygen -t rsa
+   ls ~/.ssh
    ```
 
-   GitHub also uses the key length `-b 4096` in the command. Follow the prompts to complete the key.
-
-1. When prompted to "Enter a file in which to save the key," press **Enter** to save the file to the default location. The prompt displays the location.
-
-1. When prompted to enter a secure passphrase, enter a phrase to use like a password. Make note of this passphrase. You may be requested to enter it depending on tasks you complete using a terminal during development.
+1. Review the output.
 
-1. After creating the SSH key pair, start the ssh-agent:
+   If you have SSH keys, a directory listing is displayed similar to the following:
 
-   For Mac or Linux:
-
-   ```bash
-   eval "$(ssh-agent -s)"
+   ```terminal
+   id_rsa  id_rsa.pub  known_hosts
    ```
 
-   For Mac, you can edit the  `~/.ssh/config` file to automatically load keys into the ssh-agent and store passphrases in your keychain.
-
-   ```conf
-   Host *
-       AddKeysToAgent yes
-       UseKeychain yes
-       IdentityFile ~/.ssh/id_rsa
-   ```
+If the directory does not exist or has no SSH key files, you must generate at least one SSH key and add it to your GitHub account. For instructions, see [Generate a new SSH key](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) in the GitHub documentation.
 
-   {:.bs-callout-info}
-   You can specify multiple SSH keys by adding multiple `IdentityFile` entries to your configuration.
+If you have at least one SSH key in your directory, add the key to your Magento and GitHub accounts:
 
-   For Windows:
-
-   ```shell
-   eval $(ssh-agent -s)
-   ```
-
-1. Add the SSH key to the ssh-agent. If you used a different name for the key file name, replace `id_rsa` with that file name.
-
-   For Mac:
-
-   ```bash
-   ssh-add -K ~/.ssh/id_rsa
-   ```
-
-   For Windows or Linux:
-
-   ```shell
-   ssh-add ~/.ssh/id_rsa
-   ```
-
-1. [Add your SSH key to your GitHub account.](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/) The instructions include Mac, Windows, and Linux.
+-  [Add an SSH key to your GitHub account](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/)
+-  [Add your public SSH key to your Magento account](#ssh-add-to-account)
 
 ### Test the SSH keys {#test}
 
@@ -120,13 +62,14 @@ You can add SSH keys to your account in any of the following ways:
 -  Using the [{{site.data.var.ece}} CLI](#add-key-cli)
 -  Using the [{{site.data.var.ece}} Web Interface](#add-key-web)
 
-### Add a key using the CLI {#add-key-cli}
+### Add your SSH key using the CLI {#add-key-cli}
 
 {:.procedure}
 To add an SSH key using the CLI:
 
 1. Open a terminal application on your local workstation.
-1. If you haven't done so already, log in (or switch to) the [Magento file system owner]({{ site.baseurl }}/cloud/before/before-workspace-file-sys-owner.html) to the server on which your SSH keys are located.
+
+1. If you have not done so already, log in (or switch to) the [Magento file system owner]({{ site.baseurl }}/cloud/before/before-workspace-file-sys-owner.html) to the server on which your SSH keys are located.
 
 1. Log in to your project:
 
@@ -140,30 +83,43 @@ To add an SSH key using the CLI:
    magento-cloud ssh-key:add ~/.ssh/id_rsa.pub
    ```
 
-### Add a key using the Project Web Interface {#add-key-web}
+{:.bs-callout-tip}
+You can list and delete SSH keys using the Magento Cloud CLI commands `ssh-key:list` and `ssh-key:delete`.
 
-You will select and add your SSH public key to each environment in your account.
+### Add your SSH key using the Project Web Interface {#add-key-web}
+
+You must add your SSH public key to your account. After you add the key, you must redeploy all active environments on your account to install the key.
 
 -  Starter: Add to Master (Production) and any environments you create by branching from Master
--  Pro: Add the key to Staging, Production, and Integration environments
+-  Pro: Add the key to the Staging, Production, and Integration environments
 
 {:.procedure}
-To add an SSH key using the Project Web Interface:
+To add an SSH key using the Project Web interface:
+
+1. Get your public key.
 
-1. Copy your SSH public key to the clipboard.
+   -  In the terminal, navigate to the `~/.ssh` directory.
 
-   If you do not already have SSH keys on that machine, see [GitHub documentation](https://help.github.com/articles/generating-an-ssh-key) to create them.
+   -  Copy the contents of the public key file `~/.ssh/<keyname>.pub` to the clipboard.
+
+   If there are no SSH key files in the directory, you must create one. See [Generate a new SSH key](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) in the GitHub documentation.
 
 1. Login and access your project through the [Project Web Interface](https://accounts.magento.cloud).
-1. In your selected branch, an icon displays if you do not have an SSH key added.
+
+1. In your project, look for the **No SSH key** icon to the right of the command field. This icon is visible when the project does not contain an SSH key.
 
    ![No SSH key]({{ site.baseurl }}/common/images/cloud/cloud_ssh-key-install.png)
 
-1. Copy and paste the content of your public SSH key in the screen.
+1. Click the icon to add the key.
+
+   -  Copy and paste the content of your public SSH key in the **Public key** field.
+
+      ![Add SSH key]({{ site.baseurl }}/common/images/cloud/cloud_ssh-key-add.png)
 
-   ![Add SSH key]({{ site.baseurl }}/common/images/cloud/cloud_ssh-key-add.png)
+   -  Follow the prompts on your screen to complete the task.
 
-1. Follow the prompts on your screen to complete the task.
+{:.bs-callout-tip}
+You can view and manage the SSH keys on your account in _Account settings_. In the upper right corner of the Project Web interface, click **your-user-name** > **Account Settings**.
 
 ## Set global Git variables
 

src/cloud/project/user-admin.md

@@ -27,7 +27,7 @@ You can manage access to {{site.data.var.ece}} projects by adding users and assi
 
 ## Add user authentication requirements
 
-For added security, Magento provides project-level MFA enforcement to require two-factor authentication for SSH access to {{ site.data.var.ece }} project source code and environments. See [MFA enforcement for SSH].
+For added security, Magento provides project-level MFA enforcement to require two-factor authentication for SSH access to {{ site.data.var.ece }} project source code and environments. See [Enable MFA for SSH].
 
 When MFA enforcement is enabled on a {{site.data.var.ece}} project, all users with SSH access to an environment in that project must enable two-factor authentication (TFA) on their {{site.data.var.ece}} account. For automated processes, users must create an API token that machine users can use to authenticate from the command line. See [Enable user accounts for TFA and SSH access](#update-account-security-settings).
 
@@ -44,7 +44,7 @@ To add a user to a project or environment, you need the email address associated
 
 ### Manage users with the CLI {#cloud-user-mg-cli}
 
-You can use the {{site.data.var.ece}} command line client to manage users and integrate this with any other automated system.
+Use the {{site.data.var.ece}} command line client to manage users and integrate this with any other automated system.
 
 Available commands:
 
@@ -175,17 +175,17 @@ After you add a user to a Cloud project, ask the user to review their account se
 
 -  Enable two-factor authentication (TFA)
 
-   Magento recommends adding two-factor authentication to all accounts to meet security and compliance standards. Projects configured with [MFA enforcement][] require two-factor authentication for all accounts that require SSH access to {{site.data.var.ece}} projects.
+   Magento recommends adding two-factor authentication to all accounts to meet security and compliance standards. Projects configured with [MFA enforcement][Enable MFA for SSH] require two-factor authentication on accounts that use SSH to access the projects.
 
 -  Enable SSH keys
 
    Users that require access to {{site.data.var.ece}} source code repositories and infrastructure must enable SSH keys on their account. See [Enable SSH keys][].
 
 -  Create an API token
 
-   You can generate an API token on your account that can be used for secure SSH access to an environment. You need the token to enable authentication workflows for automated processes.
+   Users can generate an API token that can be used for secure SSH access to an environment. You need the token to enable authentication workflows for automated processes.
 
-   On projects with MFA enforcement enabled, you must use the API token to authenticate SSH access requests from automated accounts to bypass authentication workflows which require two-factor authentication.
+   On projects with MFA enforcement enabled, you must use the API token to authenticate SSH access requests from automated accounts. The token allows automated processes to bypass authentication workflows which require two-factor authentication.
 
 ### Enable TFA for Cloud accounts
 
@@ -319,5 +319,5 @@ To create an API token:
 [FreeOTP (Android)]: https://play.google.com/store/apps/details?id=org.fedorahosted.freeotp
 [GAuth Authenticator (Firefox OS, desktop, others)]: https://github.com/gbraad/gauth
 [Google Authenticator (Android/iPhone/BlackBerry)]: https://support.google.com/accounts/answer/1066447?hl=en
-[MFA enforcement]: {{ site.baseurl }}/cloud/project/project-enable-mfa-enforcement.html
+[Enable MFA for SSH]: {{ site.baseurl }}/cloud/project/project-enable-mfa-enforcement.html
 [snapshots]: {{ site.baseurl }}/cloud/project/project-webint-snap.html