Skip to main content

​
Overview

Netcatty supports multiple authentication methods for SSH connections: password authentication, SSH key authentication, and certificate-based authentication. This guide covers configuration, best practices, and troubleshooting.

​
Authentication Methods

​
authMethod
IdentityAuthMethod
Authentication method for this host

​
Password Authentication

The simplest authentication method using username and password.

​
Configuration

​
password
string
User password for authentication
​
savePassword
boolean
default:"true"
Whether to save the password securely

​
Example

{
  "hostname": "server.example.com",
  "username": "admin",
  "authMethod": "password",
  "password": "your-password",
  "savePassword": true
}

​
UI Workflow

  1. Open Host Details panel
  2. Select Authentication Method: Password
  3. Enter your Password
  4. Toggle Save Password (enabled by default)
  5. Click Save
Passwords are stored securely using your system’s credential manager. However, SSH key authentication is more secure for production environments.

​
Password Not Saved

If you disable “Save Password”, Netcatty will prompt for the password each time you connect: 
{
  "authMethod": "password",
  "password": undefined,
  "savePassword": false
}

​
SSH Key Authentication

Secure, password-less authentication using public-key cryptography.

​
Configuration

​
identityFileId
string
Reference to an SSH key stored in the Keychain

​
Example

{
  "hostname": "server.example.com",
  "username": "deploy",
  "authMethod": "key",
  "identityFileId": "my-deploy-key"
}

​
UI Workflow

  1. Generate or Import Key (see Keychain Management)
    • Navigate to Keychain in the sidebar
    • Click Generate or Import
    • Save your key with a descriptive label
  2. Attach Key to Host
    • Open Host Details panel
    • Select Authentication Method: Key
    • Choose your key from the Identity File dropdown
    • Click Save
  3. Export Public Key to Server (if not already done)
    • In Keychain, click on your key
    • Click Export to Host
    • Select the target host
    • Netcatty will automatically append to ~/.ssh/authorized_keys

​
Key Types Supported

​
Passphrase Protection

​
passphrase
string
Passphrase to decrypt the private key
​
savePassphrase
boolean
Whether to save the passphrase securely
If your SSH key is encrypted with a passphrase:
  1. Netcatty will prompt for the passphrase on first use
  2. Enable Save Passphrase to avoid repeated prompts
  3. The passphrase is stored securely in your system’s credential manager
Always use a passphrase for private keys on shared or portable devices.

​
Certificate Authentication

Use SSH certificates for advanced security and centralized key management.

​
Configuration

​
certificate
string
SSH certificate content

​
Example

{
  "hostname": "server.example.com",
  "username": "deploy",
  "authMethod": "certificate",
  "identityFileId": "my-key",
  "certificate": "ssh-rsa-cert-v01@openssh.com AAAA..."
}

​
UI Workflow

  1. Navigate to Keychain
  2. Click Import
  3. Paste your Private Key
  4. Paste your Certificate in the Certificate field
  5. Click Save
  6. Attach to host in Host Details > Authentication
SSH certificates are signed by a Certificate Authority (CA). The remote server must trust the CA’s public key.

​
SSH Agent Forwarding

Forward your local SSH agent to remote servers for seamless multi-hop authentication.
​
agentForwarding
boolean
default:"false"
Enable SSH agent forwarding

​
Use Cases

  • Access Git repositories from remote servers using your local keys
  • Jump between servers without copying keys
  • Deploy applications that require SSH authentication

​
Configuration

{
  "hostname": "bastion.example.com",
  "username": "admin",
  "authMethod": "key",
  "identityFileId": "my-key",
  "agentForwarding": true
}

​
UI Workflow

  1. Open Host Details panel
  2. Navigate to Advanced section
  3. Enable SSH Agent Forwarding toggle
  4. Click Save
Security Considerations:
  • Only enable agent forwarding on trusted hosts
  • Malicious users with root access can hijack your forwarded agent
  • Consider using ProxyJump instead for multi-hop connections

​
Windows SSH Agent

On Windows, Netcatty checks if the SSH Agent service is running:
  • Service Not Running: You’ll see a warning with instructions
  • To Enable: 
    # Run as Administrator
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent

​
macOS/Linux SSH Agent

The SSH agent usually runs automatically. To verify: 
# Check if agent is running
echo $SSH_AUTH_SOCK

# Add your key to the agent
ssh-add ~/.ssh/id_ed25519

# List loaded keys
ssh-add -l

​
Identity Management

Identities combine username and authentication method for reuse across multiple hosts.

​
Identity Structure

​
identityId
string
Reference to a reusable identity in the Keychain
An Identity includes:
​
Identity
object

​
Creating an Identity

  1. Navigate to Keychain
  2. Switch to Identities tab
  3. Click New Identity
  4. Configure:
    • Label: “Production Deploy”
    • Username: deploy
    • Auth Method: Key
    • SSH Key: Select from dropdown
  5. Click Save

​
Using an Identity

{
  "hostname": "web-01.example.com",
  "identityId": "prod-deploy-identity"
}
When you attach an identity to a host:
  • Username is inherited from the identity
  • Authentication method is inherited
  • Credentials are inherited
Use identities to maintain consistent authentication across multiple hosts (e.g., all production servers use the same deploy identity).

​
Authentication Priority

When multiple authentication methods are configured, Netcatty follows this priority:
  1. Identity-based auth (if identityId is set)
  2. Direct key auth (if identityFileId is set)
  3. Password auth (if password is set)
  4. Prompt for password (if savePassword is false)

​
Troubleshooting

Possible Causes:
  • Incorrect username or password
  • SSH key not authorized on server
  • Wrong authentication method selected
Solutions:
  1. Verify username and hostname
  2. Check ~/.ssh/authorized_keys on the server
  3. Ensure your public key is present
  4. Try password authentication to verify connectivity
Cause: SSH key passphrase is not savedSolution:
  1. Open Keychain
  2. Click on your key
  3. Enable Save Passphrase
  4. Enter passphrase once
Possible Causes:
  • SSH agent not running locally
  • Server doesn’t allow agent forwarding
Solutions:Local Side:
# Start SSH agent
eval $(ssh-agent)

# Add your key
ssh-add ~/.ssh/id_ed25519
Server Side: Edit /etc/ssh/sshd_config:
AllowAgentForwarding yes
Restart SSH service:
sudo systemctl restart sshd
Possible Causes:
  • Certificate expired
  • CA not trusted by server
  • Certificate principals don’t match
Solution: Check certificate details:
ssh-keygen -L -f ~/.ssh/id_rsa-cert.pub
Verify the server trusts the CA:
# On server
cat /etc/ssh/ca-keys.pub

​
Security Best Practices

1

Use SSH Keys

Prefer key authentication over passwords for automated and production access.
2

Protect Private Keys

  • Use passphrases on all private keys
  • Store keys securely (avoid shared/cloud drives)
  • Rotate keys regularly
3

Limit Agent Forwarding

Only enable agent forwarding on trusted bastion/jump hosts.
4

Use Short-Lived Certificates

For team environments, prefer SSH certificates with 24-48 hour validity.
5

Audit Key Usage

Regularly review which keys have access to which servers.

Keychain Management

Generate, import, and manage SSH keys

Host Configuration

Advanced host settings and environment variables

Proxy & Jump Hosts

Configure bastion hosts and multi-hop connections