Restructure SSH keys documentation

source/content/agency-tips.md

@@ -77,7 +77,7 @@ Drupal now includes Composer usage within Drupal Core itself. For details, see [
 ## Advanced Tools
 
 ### Terminus
-[Terminus](/terminus), the Pantheon command-line interface, has a near 1:1 parity with the Pantheon Dashboard. After installing this tool locally, login using a [machine token](/machine-tokens). This allows for passwordless authentication, which is often necessary for bots, scripts and continuous integration.
+[Terminus](/terminus), the Pantheon command-line interface, has a near 1:1 parity with the Pantheon Dashboard. After installing this tool locally, login using a [machine token](/machine-tokens).
 
 You can [extend Terminus and add new commands](/terminus/plugins) by installing or creating third-party plugins. For a complete list of supported plugins, see our [Plugin Directory](/terminus/directory). Two favorites are [Filer](https://github.com/terminus-plugin-project/terminus-filer-plugin), which assists with opening Pantheon sites in many popular SFTP GUI clients, and [Pancakes](https://github.com/derimagia/terminus-pancakes), which open any Pantheon site database using a SQL GUI client. These two plugins eliminate logging into the Pantheon dashboard and copying/pasting credentials into your client.
 

source/content/certification/study-guide-cms/05-cms.md

@@ -161,7 +161,7 @@ We will cover Pantheon’s full WebOps Workflow in depth in a later section.
 
 Developers access a container directly via a special encrypted SSH interface, and while SSH keys are used to securely authenticate users to give them access to git codeservers, as well as CLI tools like rsync and SFTP,** it should be noted that Pantheon does not provide root level server access to customers.**
 
-SSH keys are a best practice for authentication and provide a more secure way to access your Pantheon features than a simple username and password. SSH keys allow you to stay secure and compliant with security regulations, provided that you follow recommended guidelines to generate, store, manage, and remove your SSH keys. SSH keys provide developers with passwordless access to your application's Git repository, SFTP, and Drush. SSH public keys are uploaded in the Pantheon Dashboard in the Personal Settings section under the SSH Keys tab.
+Interacting with remote Pantheon environments via Git, SFTP, WP-CLI, and Drush requires an SSH key for authentication. SSH keys allow you to stay secure and compliant with security regulations, provided that you follow recommended guidelines to generate, store, manage, and remove your SSH keys. SSH public keys are uploaded in the Pantheon Dashboard in the Personal Settings section under the SSH Keys tab.
 
 You can take full advantage of Pantheon by loading your public SSH key into your account. You must add your SSH key once for each work environment (laptop, desktop, etc.), no matter how many sites you work on.
 

source/content/certification/study-guide-cms/06-deploy.md

@@ -169,7 +169,7 @@ SSH keys are a best practice for authentication and offer more security than a s
 You can take full advantage of Pantheon by loading your public SSH key into your account. You must add your SSH key once for each work environment (laptop, desktop, etc.), no matter how many sites you work on.
 
 <Alert title="Note on SSH Access"  type="danger" >
-Pantheon does not provide access to a shell environment over SSH. These directions allow you to have passwordless access if you configure Git, SFTP, or Drush to use SSH keys.
+Pantheon does not provide access to a shell environment over SSH. These directions allow you to authenticate operations on Pantheon like  Git, SFTP, WP-CLI or Drush via SSH keys.
 </Alert>
 
 SSH keys provide a secure and convenient way for users to interact with a Pantheon site. SSH does not provide root access to the server.
@@ -188,7 +188,7 @@ In this section, we will walk through the process of generating SSH keys and add
 
     **Multiple SSH Keys**
 
-    If you have multiple SSH keys for different purposes and want to tell all of your Pantheon sites to use a specific key, you can configure your local ssh setup to use one key for all Pantheon servers. Follow the instructions here: https://web.berkeley.edu/web-hosting-pantheon/hosting-your-site-pantheon/special-topics-pantheon-sites/using-ssh-keys
+    If you have multiple SSH keys for different purposes and want to tell all of your Pantheon sites to use a specific key, you can [configure your local ssh setup to use one key for all Pantheon servers](/ssh-keys/#manage-multiple-keys-optional).
 
 2. **Set a passphrase for better security.** We recommend using a passphrase, but it can conflict with some tools.
 

source/content/partials/auth.md

@@ -12,6 +12,6 @@ reviewed: ""
 
 ### SSH Keys
 
-Pantheon does not provide access to a shell environment over SSH. These directions allow you to have passwordless access if you configure Git, SFTP, or Drush to use SSH keys.
+Pantheon does not provide access to a shell environment over SSH. These directions allow you to authenticate operations on Pantheon like  Git, SFTP, WP-CLI or Drush via SSH keys.
 
-You should load your public SSH key into your account to take full advantage of Pantheon. SSH keys are a best practice for authentication, allowing you more security than a simple password. You only have to configure this once, no matter how many sites you work on. Refer to [Generate and Add SSH Keys](/ssh-keys) for more information.
+You should load your public SSH key into your account to take full advantage of Pantheon. SSH keys are required in order to interact with remote Pantheon environments. You only have to configure this once, no matter how many sites you work on. Refer to [Generate and Add SSH Keys](/ssh-keys) for more information.

source/content/ssh-keys.md

@@ -2,7 +2,7 @@
 title: Generate and Add SSH Keys
 description: Understand how to generate SSH keys to configure Git, SFTP, or Drupal Drush.
 tags: [security, dashboard, ssh]
-reviewed: "2022-03-04"
+reviewed: "2025-02-05"
 contenttype: [doc]
 innav: [true]
 categories: [security, git, config]
@@ -11,35 +11,28 @@ audience: [development]
 product: [--]
 integration: [ssh, drush, sftp]
 ---
-
-SSH keys are a best practice for authentication and offer more security than a simple password.  SSH keys allow you to stay secure and compliant with security regulations, provided that you follow recommended guidelines to generate, store, manage, and remove your SSH keys.
-
-You can take full advantage of Pantheon by loading your public SSH key into your account.
-You must add your SSH key once for each work environment (laptop, desktop, etc.), no matter how many sites you work on.
+Interacting with remote Pantheon environments via Git, SFTP, WP-CLI, and Drush requires an SSH key for authentication. This is configured by adding your public SSH key to your user account on Pantheon. If you interact with your sites from multiple workstations (laptop, desktop, etc.), you must add a separate SSH key for each machine.
 
 <Alert title="Note" type="info">
 
-Pantheon does not provide access to a shell environment over SSH. These directions allow you to have passwordless access if you configure Git, SFTP, or Drush to use SSH keys.
+Pantheon does not provide access to a shell environment over SSH. These directions allow you to authenticate operations on Pantheon like  Git, SFTP, WP-CLI or Drush via SSH keys.
+
+Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519` keys.
 
 </Alert>
 
-## Generate an SSH Key
+## Generate an SSH key
 
 Use the steps in this section to generate your SSH key.
 
-<Alert title="Note"  type="info" >
-
-Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519` keys.
-
-</Alert>
-
 <Accordion title="Watch: Generate a SSH Key and Add it to Your Dashboard" id="ssh-video" icon="facetime-video">
 
 <Youtube src="U8sfuvrjroY" title="Generate a SSH Key and Add it to Your Dashboard" />
 
 </Accordion>
 
-### MacOS/Linux
+### Create the key locally
+The following steps are compatible with MacOS, Linux, and the Windows Subsystem for Linux (WSL). Windows users must [install WSL](https://learn.microsoft.com/en-us/windows/wsl/) before proceeding to the steps below.
 
 1. Open your terminal and enter the following command to generate a key:
 
@@ -55,8 +48,6 @@ Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519`
 
 1. Copy the contents of `~/.ssh/id_rsa.pub` to your clipboard after the files are created.
 
-   MacOS users can `cat`the file to the terminal and copy the output:
-
    ```bash{promptUser: user}
    cat ~/.ssh/id_rsa.pub
    ```
@@ -74,39 +65,10 @@ Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519`
    ssh-add ~/.ssh/id_rsa
    ```
 
-### Windows
-
-1. Open your terminal and enter the following command to generate a key. This command works for Windows 10:
-
-   ```bash{promptUser: winshell}
-   ssh-keygen -t rsa -m PEM
-   ```
-
-  Do not edit the default location of `~/.ssh/id_rsa` unless you have a reason to change it. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key.
-
-1. Set a passphrase for better security.
-
-   We recommend using a passphrase, but it can conflict with some tools.
-
-1. Copy the contents of `~/.ssh/id_rsa.pub` to your clipboard after the files are created.
-
-   ```bash{promptUser: winshell}
-   type .ssh\id_rsa.pub
-   ```
-
-1.  Run `start-ssh-agent` to start the SSH agent. The output confirms the agent has started. Enter the passphrase, if it was previously set.
-
-      ```bash{promptUser: winshell}{outputLines: 2,3,5}
-      start-ssh-agent
-      Removing old ssh-agent sockets
-      Starting ssh-agent:  done
-      Enter passphrase for /c/Users/[user]/.ssh/id_rsa:
-      Identity added: /c/Users/[user]/.ssh/id_rsa ([user@machine_name])
-      ```
-
-## Add Your SSH Key to Pantheon
+## Add your SSH key to Pantheon
+<TabList>
 
-### Add SSH Key - New Dashboard
+<Tab title="New Dashboard" id="phoebe-add-key" active={true}>
 
 1. Log in to your Pantheon Dashboard.
 
@@ -120,7 +82,9 @@ Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519`
 
   Your computer is now set up to securely connect to the Pantheon Git server. You can view a list of available keys on the same page.
 
-### Add SSH Key - Classic Dashboard
+</Tab>
+
+<Tab title="Legacy Dashboard" id="hermes-add-key">
 
 1. Log in to your Pantheon Dashboard.
 
@@ -134,19 +98,68 @@ Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519`
 
 1. Click the **Add Key** button.
 
-  Your computer is now set up to securely connect to the Pantheon Git server. You can view a list of available keys on the same page.
+  Your local machine is now set up to securely connect to remote Pantheon environments. This page will show you all keys associated with your user account.
 
-### Clone Your Site Code
+</Tab>
+</TabList>
 
-You can use your Dev environment to clone your site code to your workstation:
 
-1. Use Terminal to copy the **SSH clone URL** from the site's **Connection Info**.
+### Test your new key (optional)
+
+Try out your new key by interacting with your site using any one of the following methods:
+* [Use git to clone your site repository locally](/guides/git/git-config#clone-your-site-codebase)
+* [Use your preferred SFTP client to connect to a remote Pantheon environment](/guides/sftp/sftp-connection-info#sftp-connection-info)
+* Use [Terminus](/terminus/install) to invoke WP-CLI or Drush commands:
+
+   <TabList>
+
+   <Tab title="WP-CLI" id="wpcli" active={true}>
+
+   Replace `<site>` with your sitename:
+
+   ```bash
+   terminus wp <site>.dev -- cli version
+   ```
 
-1. Enter the passphrase you set above, if prompted.
+   </Tab>
+
+   <Tab title="Drush" id="drush">
+
+   Replace `<site>` with your sitename:
+
+   ```bash
+   terminus drush <site>.dev -- status
+   ```
+
+   </Tab>
+   </TabList>
+
+### Manage multiple keys (optional)
+If you use multiple SSH keys to routinely authenticate your machine with other platforms or services other than Pantheon, you may benefit by configuring specific keys according to their specific usage.
+
+For example, the following configuration tells your Pantheon sites to use your Pantheon key, while using a separate key for GitHub:
+
+```bash:title=~/.ssh/config
+Host github
+    User git
+    Hostname github.com
+    PreferredAuthentications publickey
+    IdentityFile ~/.ssh/github_rsa
+
+Host codeserver.*.drush.in
+    PreferredAuthentications publickey
+    IdentityFile ~/.ssh/pantheon_rsa
+```
 
 ## Remove SSH Key from Pantheon
+After removing SSH Keys from your user account, you will not be able to interact with remote Pantheon application and codeservers via Git, SFTP, Drush, or WP-CLI.
+
+Removing SSH keys is separate from [revoking the machine tokens used by Terminus](/machine-tokens#revoke-a-machine-token) to perform actions (e.g., creating Multidev environments) that can otherwise be done in the Pantheon Site Dashboard.
+
+<TabList>
+
+<Tab title="New Dashboard" id="phoebe-revoke-key" active={true}>
 
-### Revoke SSH Key from Pantheon - New Dashboard
 
 1. Log in to your Pantheon Dashboard.
 
@@ -158,15 +171,15 @@ You can use your Dev environment to clone your site code to your workstation:
 
 1. Check the box in the confirmation prompt and click continue.
 
-
-### Remove SSH Key from Pantheon - Classic Dashboard
+</Tab>
+<Tab title="Legacy Dashboard" id="hermes-revoke-key">
 
 1. Navigate to the **<Icon icon="gear" /> Account** tab of your User Dashboard and click **SSH Keys**.
 
 1. Click the **Remove** button next to the key you want to delete:
 
-### Site Access After Removing Keys
-After removing SSH Keys from your user account, you will not be able to interact with the application and codeservers directly through command line interfaces like Git, SFTP, WP-CLI, and Drush. However removing SSH keys is separate from revoking the machine tokens used by Terminus to perform actions (e.g., creating Multidev environments) that can otherwise be done in the Pantheon Site Dashboard.
+</Tab>
+</TabList>
 
 ## Troubleshooting
 
@@ -234,3 +247,40 @@ Host *.drush.in
  Pantheon does not have access to keys that only exist on the host machine. You must ensure that your keys and, if applicable, your key agent are made available to the application running in the container, if you're using Lando, Docksal, or DDEV.
 
 </Alert>
+
+### What if I can't install the Windows Subsystem for Linux?
+Consider that [Terminus, Pantheon's command-line interface, requires WSL for compatibility](/terminus/install#compatibility-and-requirements). This is why the [process above](#create-the-key-locally) expects WSL to be installed, however it is not a hard required for generating SSH keys.
+
+If you are a Windows user and you are unable to install WSL on your machine, you may use the following process as an alternative:
+
+<Accordion title="Alternative steps to generate SSH keys on Windows" id="windows-no-wsl" icon="question-sign">
+
+1. Open your terminal and enter the following command to generate a key. This command works for Windows 10:
+
+   ```bash{promptUser: winshell}
+   ssh-keygen -t rsa -m PEM
+   ```
+
+  Do not edit the default location of `~/.ssh/id_rsa` unless you have a reason to change it. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key.
+
+1. Set a passphrase for better security.
+
+   We recommend using a passphrase, but it can conflict with some tools.
+
+1. Copy the contents of `~/.ssh/id_rsa.pub` to your clipboard after the files are created.
+
+   ```bash{promptUser: winshell}
+   type .ssh\id_rsa.pub
+   ```
+
+1.  Run `start-ssh-agent` to start the SSH agent. The output confirms the agent has started. Enter the passphrase, if it was previously set.
+
+      ```bash{promptUser: winshell}{outputLines: 2,3,5}
+      start-ssh-agent
+      Removing old ssh-agent sockets
+      Starting ssh-agent:  done
+      Enter passphrase for /c/Users/[user]/.ssh/id_rsa:
+      Identity added: /c/Users/[user]/.ssh/id_rsa ([user@machine_name])
+      ```
+
+</Accordion>