DevOps Knowledge Hub
DevOps Knowledge Hub

Troubleshooting SSH Permission Denied Publickey Issues

Encountering 'Permission Denied (publickey)' when using SSH? This guide provides a comprehensive walkthrough to resolve this common authentication error. Learn how to meticulously verify SSH key pairs, diagnose incorrect file permissions on both client and server, and ensure your `authorized_keys` file is configured correctly. With practical examples and step-by-step instructions, you'll regain secure access to your remote systems.

24 views

Troubleshooting SSH 'Permission Denied (publickey)' Issues

When attempting to connect to a remote server via SSH, encountering the "Permission Denied (publickey)" error can be a frustrating roadblock. This error specifically indicates that the server rejected your connection because it could not authenticate you using your public key. Unlike password-based authentication, public-key cryptography relies on a pair of keys: a private key kept secret on your local machine and a public key placed on the server. This guide will walk you through the common causes of this error and provide detailed steps to diagnose and resolve them, ensuring secure and seamless SSH access.

Understanding the SSH public-key authentication process is crucial for effective troubleshooting. When you try to connect, your SSH client presents your public key to the server. The server then checks if this public key is authorized for your user account. If it is, the server encrypts a challenge with your public key and sends it back. Your client, possessing the corresponding private key, decrypts the challenge and sends the response back to the server. If the response is correct, authentication succeeds. A "Permission Denied (publickey)" error means this exchange failed at some point.

Common Causes of 'Permission Denied (publickey)'

The "Permission Denied (publickey)" error can stem from several configuration issues. Identifying the root cause often involves systematically checking the following components:

  • Incorrect File Permissions: SSH is highly sensitive to file and directory permissions for security reasons. Incorrect permissions on your local ~/.ssh directory, private key file, or on the server-side ~/.ssh directory and authorized_keys file can prevent authentication.
  • Missing or Incorrect authorized_keys Entry: The server's authorized_keys file must contain the correct public key for the user you are trying to log in as. If the key is missing, malformed, or associated with the wrong user, authentication will fail.
  • Incorrect Key Pair Association: Your SSH client might be offering the wrong private key, or the server might not have the corresponding public key listed in the authorized_keys file.
  • SSH Agent Issues: If you are using an SSH agent, it might not be properly loaded with your private key, or it might be configured incorrectly.
  • Server-Side SSH Configuration: While less common for this specific error, the server's SSH daemon configuration (sshd_config) might have specific restrictions on public-key authentication.

Step-by-Step Troubleshooting Guide

Let's delve into the practical steps to diagnose and fix these issues.

1. Verify Local Private Key and Permissions

Your local SSH configuration is the first place to check. Ensure your private key is accessible and has the correct permissions.

Checking Private Key Existence

Your private key is typically located in ~/.ssh/id_rsa (or id_ed25519, id_dsa, etc.).

Verifying Local File Permissions

The ~/.ssh directory and your private key file should have restrictive permissions to prevent unauthorized access.

  • ~/.ssh directory: Should be 700 (drwx------).
  • Private key file (e.g., id_rsa): Should be 600 (-rw-------).

Use the chmod command to set the correct permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa

Tip: If you're using a different key name, replace id_rsa with your actual private key filename.

2. Verify Server-Side authorized_keys Configuration

This is often the most common culprit. The server must have your public key correctly listed for the user you're attempting to authenticate as.

Accessing the Server (if possible)

If you can still access the server via another method (e.g., password authentication, another user account, or a console), log in to check the authorized_keys file.

Checking authorized_keys File Location

The authorized_keys file is typically located at ~/.ssh/authorized_keys within the home directory of the user you are trying to log in as.

Verifying Server-Side File Permissions

Similar to the client-side, server-side permissions are critical:

  • ~/.ssh directory on the server: Should be 700 (drwx------).
  • authorized_keys file on the server: Should be 600 (-rw-------).

Ensure these permissions are set correctly on the server:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
Verifying authorized_keys Content

Open the ~/.ssh/authorized_keys file using a text editor (e.g., nano, vim). Each public key should be on a single line. Ensure that the public key you expect to use is present and correctly formatted. It should start with ssh-rsa, ssh-ed25519, or similar, followed by a long string of characters, and optionally a comment.

Example authorized_keys entry:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD... your_public_key_string user@hostname

Important: Do not add your private key to authorized_keys. Only the public key should be here.

3. Ensure Correct Public Key was Added

It's possible that the wrong public key was copied or that the public key on the server doesn't match your local private key.

Retrieving Your Local Public Key

Your public key is the counterpart to your private key. You can view it using the ssh-keygen command:

cat ~/.ssh/id_rsa.pub

This command will output your public key. Compare this output carefully with the entry in the server's ~/.ssh/authorized_keys file. Even a single typo or missing character will cause authentication to fail.

Tip: A quick way to add your public key if you have password access to the server is using ssh-copy-id.

ssh-copy-id user@your_server_ip

This command automatically appends your default public key (~/.ssh/id_rsa.pub) to the ~/.ssh/authorized_keys file on the remote server and sets the correct permissions.

4. Specify the Correct Private Key (if not default)

If you are using a non-default private key (e.g., ~/.ssh/my_other_key), you need to tell your SSH client which key to use.

Using the -i Flag

You can specify the identity file (private key) with the -i option:

ssh -i ~/.ssh/my_other_key user@your_server_ip
Configuring ~/.ssh/config

For convenience, you can configure your SSH client to always use a specific key for a given host:

Create or edit the ~/.ssh/config file on your local machine and add an entry like this:

Host your_server_alias
  HostName your_server_ip_or_domain
  User your_username
  IdentityFile ~/.ssh/my_other_key

Then you can connect simply using:

ssh your_server_alias

5. Check SSH Agent Status

If you rely on an SSH agent to manage your keys, ensure it's running and has your key loaded.

Checking if Agent is Running
echo "$SSH_AUTH_SOCK"

If this outputs a path, the agent is likely running. If it's empty, you may need to start one.

Adding Key to Agent

If your key is not loaded, add it:

ssh-add ~/.ssh/id_rsa

If you are prompted for a passphrase, enter it. You can verify which keys are added with ssh-add -l.

6. Debugging with Verbose Mode

SSH has a verbose mode (-v, -vv, or -vvv for increasing levels of detail) that can provide invaluable clues about where the authentication process is failing.

ssh -vvv user@your_server_ip

Examine the output for messages related to key authentication, offering keys, and server responses. This often points directly to the problem.

Example verbose output snippet indicating a publickey failure:

debug1: Authentications that can continue: publickey,password
debug1: Next authentication method: publickey
debug1: Trying private key: /home/user/.ssh/id_rsa
debug1: read PEM private key file /home/user/.ssh/id_rsa
debug1: failed to use sshkey: /home/user/.ssh/id_rsa
debug1: Authentications that can continue: publickey,password
debug1: Next authentication method: password

This output might indicate that the client attempted to use id_rsa but failed, then moved on to other methods.

7. Server-Side sshd_config Review (Advanced)

While less common for publickey specific errors (usually other errors would appear), it's worth noting the server's SSH daemon configuration file (/etc/ssh/sshd_config). Ensure that PubkeyAuthentication yes is uncommented and set to yes. After making any changes, the SSH service must be reloaded or restarted (e.g., sudo systemctl reload sshd or sudo systemctl restart sshd).

Summary and Best Practices

Troubleshooting SSH "Permission Denied (publickey)" errors involves a methodical check of both client and server configurations. The most frequent causes relate to incorrect file permissions on ~/.ssh and authorized_keys files, and mismatches between the public key on the server and the private key on the client.

Key Takeaways:

  • Permissions are paramount: Always ensure ~/.ssh is 700 and private keys/authorized_keys are 600 on both client and server.
  • Public key accuracy: Double-check that the exact public key is present in the server's authorized_keys file.
  • Use ssh-copy-id: When possible, this is the safest and easiest way to set up public-key authentication.
  • Verbose mode: Leverage ssh -vvv for detailed diagnostic output.

By following these steps, you should be able to diagnose and resolve most "Permission Denied (publickey)" issues, restoring secure remote access to your servers.