Solve SSH “Permission denied (publickey)” errors with our step-by-step troubleshooting guide. Fix permissions, verify keys, and regain access. Secure Shell (SSH) remains the backbone of secure remote server administration, enabling system administrators and developers to securely access and manage their systems from anywhere in the world. However, encountering the dreaded “Permission Denied (Publickey)” error can halt productivity and cause significant frustration. This comprehensive guide will walk you through understanding, diagnosing, and resolving this common SSH error through systematic troubleshooting approaches and best practices.
Whether you’re a seasoned Linux administrator or a developer who occasionally needs to access remote servers, this guide will provide you with the knowledge and tools to overcome SSH authentication challenges efficiently. Let’s dive into the world of SSH authentication and solve this persistent issue once and for all.
Understanding SSH Authentication Fundamentals
SSH is a cryptographic network protocol that establishes secure connections between clients and servers. At its core, SSH relies on asymmetric cryptography for authentication, using a pair of cryptographic keys – one public and one private – to verify identity without transmitting sensitive credentials over the network.
When you attempt to connect to a server using SSH, the server checks if your public key matches any in its authorized keys list. If a match is found, it encrypts a challenge message using your public key that only your private key can decrypt, thus proving your identity. This process is fundamental to SSH’s security model and understanding it is crucial for troubleshooting authentication failures.
The error message “Permission Denied (publickey,gssapi-keyex,gssapi-with-mic)
” indicates that all attempted authentication methods have failed. The components of this message reveal which authentication methods were tried:
- Publickey: Authentication using SSH key pairs
- GSSAPI-Keyex: Generic Security Services Application Program Interface key exchange
- GSSAPI-with-MIC: GSSAPI with Message Integrity Code
While the error suggests issues with multiple authentication methods, public key authentication problems are the most common culprit.
Security-conscious administrators often disable password authentication on their servers, leaving public key authentication as the only avenue for access. This practice enhances security but also means that properly managing SSH keys becomes critical to maintaining access.
Common Causes of SSH Permission Denied (Publickey) Error
Several factors can trigger the SSH Permission Denied error, ranging from simple configuration mistakes to complex permission issues. Understanding these causes is the first step toward resolution.
Incorrect username or hostname connections often lead to this error. A simple typo in your command can result in connection attempts to the wrong server or with the wrong user account. Always verify that you’re using the correct syntax: ssh username@hostname
.
Missing or corrupted public key on the server is another frequent cause. For successful authentication, your public key must be properly stored in the ~/.ssh/authorized_keys
file on the server. If this file is missing, corrupted, or doesn’t contain your public key, authentication will fail.
Improper file and directory permissions represent one of the most common causes. SSH is extremely strict about file permissions for security reasons. If your SSH directories or key files have permissions that are too permissive (readable by others) or too restrictive (not readable by the owner), SSH will refuse to use them for authentication.
SSH configuration issues on the server side can also prevent successful authentication. Incorrect settings in the SSH daemon configuration file (/etc/ssh/sshd_config
) might disable public key authentication or point to the wrong location for the authorized keys file.
Firewall or security restrictions sometimes block SSH connections entirely or interfere with the authentication process. Security tools like SELinux or AppArmor can enforce additional restrictions that need to be properly configured.
Outdated SSH client or server software might contain bugs or incompatibilities that prevent successful authentication. Keeping your SSH implementation updated is essential for both security and reliability.
Preliminary Checks Before Troubleshooting
Before diving into complex troubleshooting, perform these basic checks to potentially save time and effort.
Verify server address and port: Ensure you’re connecting to the correct server IP or domain name. If your SSH server uses a non-standard port, you must specify it with the -p
flag:
ssh username@hostname -p 2222
Confirm SSH service is running on the server. If you have alternative access methods (such as a console), you can check the service status with:
sudo systemctl status sshd
Double-check username and connection string for typographical errors. SSH usernames are case-sensitive, and even a small error will result in authentication failure.
Test basic connectivity to ensure network-level communication is possible:
ping hostname
telnet hostname 22
If these basic checks fail, the issue might be related to network connectivity rather than SSH authentication specifically.
Diagnosing SSH Permission Denied Errors
Proper diagnosis is key to efficiently resolving SSH authentication issues. Several tools and techniques can help you pinpoint the exact problem.
Using SSH verbose mode provides detailed information about the authentication process. Add one or more -v
flags to your SSH command to increase verbosity:
ssh -v username@hostname # Basic verbose output
ssh -vv username@hostname # More detailed output
ssh -vvv username@hostname # Maximum verbosity
The verbose output will show each step of the authentication process, often pointing directly to the source of the failure.
Interpreting verbose output requires understanding key messages. Look for lines indicating which authentication methods were attempted and why they failed. Common indicators include:
- “Authentication refused: bad ownership or modes for directory”
- “No more authentication methods to try”
- “Offering public key: /path/to/key”
- “Server refused our key”
Each of these messages provides clues about the specific issue.
Locating and analyzing SSH log files can provide server-side information about authentication attempts. On most Linux distributions, SSH logs can be found in /var/log/auth.log
or /var/log/secure
. Review these logs for entries corresponding to your connection attempts:
sudo grep "sshd" /var/log/auth.log
Look for patterns in the error messages and failed authentication attempts to guide your troubleshooting efforts.
Solution 1: Fixing SSH Key Permissions
SSH enforces strict permission requirements on key files and directories for security reasons. Incorrect permissions are a leading cause of authentication failures.
Correct permissions for private keys should be set to 600
(readable and writable only by the owner):
chmod 600 ~/.ssh/id_rsa
Setting appropriate permissions for ~/.ssh directory is equally important. The directory should have permissions set to 700
(accessible only by the owner):
chmod 700 ~/.ssh
Fixing permission issues on authorized_keys file ensures the server can properly read the public keys. Set permissions to 600
:
chmod 600 ~/.ssh/authorized_keys
Verifying owner and group settings is crucial, especially if you’ve used sudo or root access to modify these files. Ensure the SSH directory and all files within it are owned by the proper user:
chown -R username:username ~/.ssh
After making these permission changes, test your SSH connection again to see if the issue is resolved.
Solution 2: Verifying and Fixing Key Mismatch
Sometimes the problem lies with the keys themselves rather than permissions or configurations.
Checking for SSH key mismatches using ssh-keygen allows you to verify that your local private key corresponds to the public key on the server:
ssh-keygen -lf ~/.ssh/id_rsa # View fingerprint of private key
ssh-keygen -lf ~/.ssh/id_rsa.pub # View fingerprint of public key
The fingerprints should match except for the key type indicator. You can compare this with the public key on the server to ensure they’re the same.
Generating fingerprints to compare keys can be done on both client and server:
# On local machine
ssh-keygen -lf ~/.ssh/id_rsa.pub
# On server (after logging in via alternative method)
ssh-keygen -lf ~/.ssh/authorized_keys
Compare the fingerprints to identify potential key mismatches.
Steps to create new SSH key pairs if needed:
ssh-keygen -t rsa -b 4096 # For RSA keys
ssh-keygen -t ed25519 # For more modern Ed25519 keys
Follow the prompts to specify the location to save the key and whether to use a passphrase. For maximum security, using a strong passphrase is recommended.
Solution 3: Adding Your Public Key to the Server
If your public key is missing from the server’s authorized keys file, you’ll need to add it to establish trusted authentication.
Using ssh-copy-id for streamlined key deployment is the simplest method when password authentication is temporarily available:
ssh-copy-id -i ~/.ssh/id_rsa.pub username@hostname
This command automatically copies your public key to the server and appends it to the authorized_keys file with the correct permissions.
Manual methods to add keys to authorized_keys can be used when ssh-copy-id isn’t available:
cat ~/.ssh/id_rsa.pub | ssh username@hostname "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
Alternatively, you can copy the key content and manually paste it into the authorized_keys file if you have alternative access to the server.
Troubleshooting key addition failures often involves checking for issues like:
- Line break problems in the authorized_keys file
- Quotation marks or extra characters in the key
- Multiple keys not properly separated by newlines
Verifying successful key deployment:
ssh -v username@hostname
Check the verbose output to confirm the server is finding and accepting your public key.
Solution 4: Checking and Adjusting Server Configuration
Sometimes the issue lies in the server’s SSH daemon configuration rather than with the keys themselves.
Accessing and editing the sshd_config file requires administrative privileges on the server:
sudo nano /etc/ssh/sshd_config
Critical configuration parameters to verify include:
PubkeyAuthentication yes
– Ensures public key authentication is enabledAuthorizedKeysFile .ssh/authorized_keys
– Specifies the location of authorized keysPasswordAuthentication no/yes
– Controls password authenticationPermitRootLogin no
– For security reasons, direct root login should usually be disabled
Enabling public key authentication if it’s disabled:
# In /etc/ssh/sshd_config
PubkeyAuthentication yes
Setting correct AuthorizedKeysFile path ensures the server looks in the right location for authorized keys:
# In /etc/ssh/sshd_config
AuthorizedKeysFile .ssh/authorized_keys
Restarting the SSH service properly applies any configuration changes:
sudo systemctl restart sshd # For systemd-based systems
sudo service sshd restart # For init.d-based systems
Wait for the service to fully restart before attempting to connect again.
Solution 5: Enabling Password Authentication Temporarily
When all else fails, temporarily enabling password authentication can provide a way to access the server and fix the underlying issues.
When to use password authentication as a fallback includes situations where:
- You need immediate access to fix key-based authentication
- You’re troubleshooting complex authentication issues
- You’re setting up a new server or user account
Steps to enable password authentication in sshd_config:
# Edit the SSH daemon configuration
sudo nano /etc/ssh/sshd_config
# Find and modify this line
PasswordAuthentication yes
# Save and restart SSH
sudo systemctl restart sshd
Security considerations and best practices when using password authentication:
- Use strong, unique passwords
- Enable password authentication only temporarily
- Consider implementing fail2ban to prevent brute force attacks
- Revert to key-based authentication as soon as possible
Advanced Troubleshooting Techniques
For more complex scenarios, advanced troubleshooting techniques may be necessary.
Dealing with SELinux/AppArmor security contexts can be crucial on systems using these security frameworks:
# Check SELinux contexts
ls -Z ~/.ssh/
# Restore default contexts
restorecon -Rv ~/.ssh/
Resolving issues in cloud environments often involves platform-specific considerations:
- AWS EC2 instances typically use key pairs provided during instance creation
- Google Cloud and Azure have their own key management systems
- Many cloud providers offer web console access as an alternative entry point
Troubleshooting SSH agent problems:
# Verify SSH agent is running
echo $SSH_AUTH_SOCK
# Add your key to the SSH agent
ssh-add ~/.ssh/id_rsa
Working with non-standard SSH configurations requires careful attention to custom settings that might affect authentication behavior. Review any custom configurations in ~/.ssh/config
on the client and /etc/ssh/sshd_config
on the server.
Troubleshooting for Specific Environments
Different environments present unique challenges for SSH authentication.
Fixing permission issues on Windows clients with PuTTY involves:
- Ensuring proper conversion of keys using PuTTYgen
- Setting correct permissions on the server side
- Using the correct key format (.ppk for PuTTY)
Resolving problems on macOS systems:
- Check keychain integration with
ssh-add -K
- Verify permissions with macOS’s specific umask settings
- Address issues with the macOS-specific
~/.ssh/config
options
Special considerations for containerized environments:
- Volume mounting of SSH keys and configurations
- Handling ephemeral container file systems
- Ensuring proper permission propagation from host to container
Virtual private server (VPS) specific troubleshooting:
- Provider-specific key deployment methods
- Console access alternatives for recovery
- Provider documentation for SSH key management
Preventative Measures and Best Practices
Preventing SSH authentication issues is always preferable to fixing them after they occur.
SSH key management best practices:
- Use strong key types (Ed25519 or RSA with at least 4096 bits)
- Implement key rotation schedules
- Use different keys for different servers or purposes
- Consider SSH key management tools for larger environments
Regular permission audits should verify:
- All SSH directories have 700 permissions
- Private keys have 600 permissions
- Authorized_keys files have 600 permissions
- Proper ownership of all SSH-related files and directories
Documentation protocols for SSH configurations should include:
- Recording all custom SSH configurations
- Documenting key deployments and rotations
- Maintaining an inventory of SSH keys and their purposes
- Creating recovery procedures for authentication failures
Automated monitoring for SSH issues can detect problems before they cause service disruptions:
- Monitoring failed authentication attempts
- Checking SSH service status regularly
- Verifying key rotation compliance
- Alerting on unusual SSH activity patterns