> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuring Key based Authentication
> Guide to replacing SSH password logins with key-based authentication, covering key generation, installing keys with ssh-copy-id, server sshd_config settings, and best practices to avoid lockouts.
If you manage multiple servers, logging in with passwords every time quickly becomes tedious and insecure. Passwords can be guessed, reused, or brute-forced, and they make automation brittle. This guide replaces password-based SSH logins with secure key-based authentication, explains what happens under the hood, covers the manual and recommended methods, and shows the server-side SSH configuration you should verify.
## How key-based authentication works (short overview)
* You generate an asymmetric key pair on your client: a private key (keep secret) and a public key (shareable).
* You copy the public key to the remote server and append it to the user's `~/.ssh/authorized_keys`.
* The SSH daemon on the server verifies incoming connections by checking the public key and ensuring the connecting client can prove possession of the corresponding private key.
## Manual method (what happens under the hood)
1. Generate a key pair:
```bash theme={null}
ssh-keygen -t ed25519
```
* `-t` specifies the key type (examples: `ed25519`, `rsa`).
* This creates `~/.ssh/id_ed25519` (private) and `~/.ssh/id_ed25519.pub` (public) by default.
2. Transfer the public key to the server (example methods):
* Copy or append the contents of `~/.ssh/id_ed25519.pub` into the remote user's `~/.ssh/authorized_keys` (ensure correct permissions).
* Or use `scp`/`sftp` to transfer the public key then append it on the server.
* The `ssh-copy-id` utility automates this and sets correct permissions — see the practical method below.
## Practical method — recommended: ssh-copy-id
Use `ssh-copy-id` to safely install your public key on the remote host:
```bash theme={null}
# If you don't have a key yet, generate one:
ssh-keygen -t ed25519
# Copy the public key to the remote host:
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server.example.com
```
`ssh-copy-id` appends the public key to `~/.ssh/authorized_keys` on the remote server and sets the proper permissions. It's faster, less error-prone, and ideal for most workflows.
Prefer `ed25519` keys for modern security and performance, unless you need RSA for compatibility. Protect your private key with a passphrase and use an SSH agent (e.g., `ssh-agent` + `ssh-add`) to avoid re-entering the passphrase frequently.
## Important sshd\_config options (server-side)
SSH server configuration typically lives in `/etc/ssh/sshd_config` (and files under `/etc/ssh/sshd_config.d/`). The following options control authentication behavior and are commonly adjusted when enabling key-based logins.
| Directive | Purpose | Recommended value |
| - | - | - |
| `Port` | TCP port sshd listens on | `22` (or custom port for security by obscurity) |
| `PermitRootLogin` | Allow direct root SSH login | `no` (prevents root login) |
| `MaxAuthTries` | Max failed auth attempts before disconnect | `3` |
| `PasswordAuthentication` | Enable/disable password-based logins | `no` (once keys are confirmed working) |
| `PubkeyAuthentication` | Enable SSH key-based logins | `yes` |
| `AuthorizedKeysFile` | Path to authorized keys file | `.ssh/authorized_keys` |
Example relevant section from `/etc/ssh/sshd_config`:
```config theme={null}
# Basic Settings
Port 22
PermitRootLogin no
MaxAuthTries 3
# Password Authentication
PasswordAuthentication yes
# Public Key Authentication
PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys
```
To enforce only key-based authentication, set:
```config theme={null}
PasswordAuthentication no
```
Then restart sshd:
```bash theme={null}
sudo systemctl restart sshd
```
Always confirm at least one account can log in with its key before disabling password authentication to avoid accidental lockout.
## Demo: Configuring Key-based Authentication
This demo walks through the steps: creating users, generating keys, installing the public key on the target server, and updating `sshd_config`.
1. Create the `test` user on both systems (control and node1)
On the control system (as root):
```bash theme={null}
sudo useradd test
sudo passwd test
# New password: Red Hat
```
On node1 (as a normal user with sudo):
```bash theme={null}
sudo useradd test
sudo passwd test
# New password: Red Hat
```
Now both systems have a `test` user with the same temporary password (used only for initial setup).
2. Generate an SSH key pair for the `test` user on the control node
Switch to the `test` user and generate keys:
```bash theme={null}
su - test
cd ~
ssh-keygen -t ed25519
# Accept defaults (e.g., /home/test/.ssh/id_ed25519) and, for production, set a passphrase.
```
Verify the generated files:
```bash theme={null}
ls -la ~/.ssh
# id_ed25519 id_ed25519.pub
```
* `id_ed25519` is the private key — keep it secret.
* `id_ed25519.pub` is the public key — safe to copy to servers.
3. Install the public key on node1 using ssh-copy-id
From the control node as `test`:
```bash theme={null}
ssh-copy-id -i ~/.ssh/id_ed25519.pub test@node1
# You'll be prompted for test's password on node1
# Output: Number of key(s) added: 1
```
4. Test SSH login using the key
From the control node as `test`:
```bash theme={null}
ssh test@node1
# You should be logged in without a password prompt (authenticated via key)
```
Example successful shell prompt on node1:
```text theme={null}
test@node1:~$
```
5. Inspect and adjust `/etc/ssh/sshd_config` on node1 (as root)
Open the server config:
```bash theme={null}
sudo vim /etc/ssh/sshd_config
```
Make sure these lines are present and correctly set (uncomment if necessary):
```config theme={null}
PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys
# To disable password-based logins after keys are confirmed:
PasswordAuthentication no
```
Save the file and restart sshd:
```bash theme={null}
sudo systemctl restart sshd
```
6. Verify behaviour for different users
* A user without an installed key (for example `student`) should be denied if `PasswordAuthentication no` is set:
```bash theme={null}
ssh student@node1
# Permission denied (publickey).
```
* A user with a key (for example `test`) should succeed:
```bash theme={null}
ssh test@node1
# login succeeds via key
```
This demonstrates that `test` can log in via key-based authentication while password logins are disabled for other accounts.
## Summary and best practices
* Create a key pair with `ssh-keygen -t ed25519` and install the public key using `ssh-copy-id`.
* Ensure `PubkeyAuthentication yes` is enabled on the server and only set `PasswordAuthentication no` after confirming key logins work.
* Disable direct root SSH login with `PermitRootLogin no`.
* Protect private keys with a passphrase and use an SSH agent to manage passphrases securely.
* Keep at least one administrative account with working key access before disabling passwords to avoid lockouts.
Before disabling password authentication, verify that at least one user account can authenticate using key-based SSH. Otherwise you risk locking yourself out of the server.
## Links and references
* [OpenSSH Manual: ssh-keygen](https://www.openssh.com/manual.html)
* [ssh-copy-id — copy public key to remote host](https://linux.die.net/man/1/ssh-copy-id)
* [sshd\_config manual (sshd\_config(5))](https://man.openbsd.org/sshd_config)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.