Complete Guide to SSH Keys on macOS: Setup and Usage

Introduction

SSH key authentication is a more secure and convenient method for connecting to remote servers compared to using a password. Instead of entering a password for each connection, SSH keys use a cryptographic pair: a private key that you keep, and a public key that resides on the server. This guide will walk you through setting up SSH key authentication on macOS, including key generation, configuring ssh-agent, and adding the key to the server. After completing these steps, you'll be able to connect to servers without needing to remember and enter passwords, which is especially useful for automation and frequent connections.

Requirements / Preparation

Before you begin, make sure you have:

• A computer with macOS (version 12 Monterey or newer is recommended).
• Access to Terminal (the Terminal app is in the Utilities folder).
• An account on a remote server with SSH support enabled (typically standard for Linux servers).
• Basic command-line skills are helpful, but this guide is suitable for beginners as well.
• An internet connection may be required for some steps (e.g., copying the key to the server).

Note: All commands are run on your local Mac unless otherwise specified.

Step 1: Creating SSH Keys

First, you need to generate an SSH key pair. A modern and secure algorithm is ed25519. Open Terminal and run:

ssh-keygen -t ed25519 -C "your_email@example.com"

Replace "your_email@example.com" with your email or any identifier. This command will create two files: a private key (by default ~/.ssh/id_ed25519) and a public key (~/.ssh/id_ed25519.pub). You will be prompted to specify a save path (press Enter for the default) and enter a passphrase. It is recommended to set a strong passphrase for added security, but if you want to fully automate connections, you can leave it empty.

After completion, you will see the key's fingerprint and randomart, confirming successful creation.

Step 2: Adding the key to ssh-agent

SSH-agent is a program that stores your private keys in memory and provides them during connections. On macOS, ssh-agent is running by default, but you can check or start it if needed.

Add the private key to the agent using the command:

ssh-add -K ~/.ssh/id_ed25519

The -K flag (capital K) is macOS-specific and saves the key to the Keychain, so you won't need to enter the passphrase on each reboot. If you used a different filename or path, specify it accordingly.

If you did not set a passphrase, the key will be added instantly. Otherwise, enter the passphrase you set.

💡 Tip: If you get the error "Could not open a connection to your authentication agent", ensure the agent is running. Run eval "$(ssh-agent -s)" to start the agent in the current session.

Step 3: Copying the public key to the server

Now you need to place the public key on the target server in the ~/.ssh/authorized_keys file. There are several ways.

Method 1: Using ssh-copy-id (if available)

On macOS, ssh-copy-id is not installed by default, but you can install it via Homebrew (brew install ssh-copy-id). If you have it, run:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server

Replace user with your username on the server and server with the IP address or domain.

Method 2: Manual copying (universal)

1. On your Mac, display the contents of the public key:

   cat ~/.ssh/id_ed25519.pub
   

   
   Copy the entire output (starts with ssh-ed25519 ...).
2. Connect to the server via SSH (using a password if the key is not yet set up):

   ssh user@server
   

3. On the server, create the .ssh directory if it doesn't exist and set correct permissions:

   mkdir -p ~/.ssh
   chmod 700 ~/.ssh
   

4. Open or create the authorized_keys file:

   nano ~/.ssh/authorized_keys
   

   
   Paste the copied public key on a new line. Save and exit (Ctrl+X, then Y, then Enter in nano).
5. Set the correct permissions on the file:

   chmod 600 ~/.ssh/authorized_keys
   

6. Exit the server (exit).

Alternative one-liner:

If you want to automate, you can run this from your local Mac:

ssh user@server "mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo '$(cat ~/.ssh/id_ed25519.pub)' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

But be careful: this command appends the key, and if the file already exists, it will add to the end. Ensure you don't duplicate keys.

Step 4: SSH configuration (optional)

For convenience, you can create an SSH config file that allows you to use short names for servers and automatically apply settings.

On your Mac, create or edit the file ~/.ssh/config:

nano ~/.ssh/config

Add a block for your server, for example:

Host myserver
    HostName server.example.com
    User your_user
    IdentityFile ~/.ssh/id_ed25519
    Port 22  # if using a non-standard port

Save the file. Now you can connect simply with ssh myserver without specifying the full address and user. You can add multiple such blocks for different servers.

⚠️ Important: Ensure the permissions on ~/.ssh/config are set to 600 to prevent unauthorized access:

chmod 600 ~/.ssh/config

Verification

After setup, try connecting to the server:

ssh your_user@server

Or, if you set up the config:

ssh myserver

If everything is set up correctly, you should log in to the server without a password prompt (if you set a passphrase, you may need to enter it once if the key isn't saved in Keychain). If the connection succeeds, key authentication is working.

For additional verification on the server, you can run whoami or check the authentication logs (if accessible).

Troubleshooting

The following issues may arise during setup:

• Error "Permission denied (publickey,password)": This means the server did not accept your key. Check:
  • The public key is correctly added to ~/.ssh/authorized_keys on the server.
  • Permissions on ~/.ssh (700) and authorized_keys (600) are correct.
  • The private key is added to ssh-agent (ssh-add -l will list keys).
  • If using a config, ensure IdentityFile points to the correct file.
• SSH-agent is not running: If the ssh-add command errors, start the agent: eval "$(ssh-agent -s)", then retry adding the key.
• Key not saving to Keychain: Ensure you used the -K flag when adding the key. In newer versions of macOS (Monterey and later), the -K flag is still supported. Alternatively, you can add AddKeysToAgent yes and UseKeychain yes to your ~/.ssh/config.
• Permissions on local files: The private key should have permissions 600 (chmod 600 ~/.ssh/id_ed25519), and the ~/.ssh directory should be 700.
• Server does not allow key authentication: Ensure the server's /etc/ssh/sshd_config file has PubkeyAuthentication yes and AuthorizedKeysFile .ssh/authorized_keys. After changes, restart sshd (sudo systemctl restart sshd or sudo service ssh restart).
• Key format issues: If the server is old and doesn't support ed25519, use RSA: ssh-keygen -t rsa -b 4096.

If the issue persists, check the SSH logs on the server (typically /var/log/auth.log or journalctl -u ssh) for error details.