Authentication Methods

Net::SSH supports a variety of authentication methods. You can specify which methods to try, and in what order, using the :auth_methods option.

# Try public key first, then fall back to password
Net::SSH.start(host, user, auth_methods: ['publickey', 'password'], ...)

The default order is ['none', 'publickey', 'password', 'keyboard-interactive'].

Public Key Authentication

This is the most common and recommended authentication method.

Using Key Files

By default, Net::SSH searches for keys in standard locations like ~/.ssh/id_rsa and ~/.ssh/id_ed25519. You can specify which key files to use with the :keys option.

Net::SSH.start(host, user, keys: ['~/.ssh/personal_key', '~/.ssh/work_key'])

If your key is protected by a passphrase, provide it with the :passphrase option. If not provided, you will be prompted for it interactively.

Net::SSH.start(host, user, keys: ['~/.ssh/encrypted_key'], passphrase: 'my-secret-passphrase')

Using Key Data in Memory

You can also provide the private key content directly as a string using the :key_data option. This is useful for loading keys from a database or environment variable.

private_key_string = ENV['SSH_PRIVATE_KEY']
Net::SSH.start(host, user, key_data: [private_key_string], passphrase: 'if_needed')

Password Authentication

To use password-based authentication, provide the :password option.

Net::SSH.start(host, user, password: 'my-secret-password')

Keyboard-Interactive

This method involves a series of prompts and responses from the server. It is often used for multi-factor authentication. Net::SSH handles this method automatically if it's available and other methods fail. If a password is provided via the :password option, Net::SSH will attempt to use it to answer the prompts.

If no password is provided and the session is interactive, the user will be prompted to enter responses in the console.

SSH Agent Authentication

Net::SSH automatically attempts to use a running SSH agent (like ssh-agent on Linux/macOS). It looks for the agent's socket via the SSH_AUTH_SOCK environment variable.

To disable agent usage, set :use_agent to false.

# This will prevent Net::SSH from trying to contact the SSH agent
Net::SSH.start(host, user, use_agent: false)

Pageant (Windows)

On Windows, Net::SSH will automatically try to connect to Pageant (from PuTTY) if it is running. This behavior is similar to SSH agent integration on other platforms.

Host-based Authentication

Net::SSH supports host-based authentication, where the client is authenticated based on its hostname and a host key. This method is less common but available if needed.

Certificate Authentication

Net::SSH supports user authentication using certificates signed by a Certificate Authority (CA). You can specify certificate files with the :keycerts option. The library will automatically look for corresponding private keys.

# The file id_rsa-cert.pub is the signed public key certificate.
# Net::SSH will look for the corresponding private key at 'id_rsa'.
Net::SSH.start(host, user, keycerts: ['~/.ssh/id_rsa-cert.pub'])