Introduction

Incoming SSH requests can be terminated locally in our built-in SSH server or forwarded to any existing SSH server on localhost or remote. In this case, the border0 process will set up an upstream connection to the remote SSH server, authenticate, and connect the streams together. The result will be that your users can log in using their Single-sign-on credentials and never have to worry about SSH keys or passwords.

Border0 supports all common SSH authentication mechanisms to authenticate to upstream SSH servers:

1. Key-based authentication
2. Username & Password based authentication
3. Certificate based authentication.

📘

Securing your credentials

For the connector to authenticate to your upstream SSH server it will need credentials to access. While Border0 stores these credentials in encrypted form, we strongly recommend that you keep them local to the connector.
You can have the Border0 connector integrate with your existing secret management solution for enhanced security and keep your secrets local. Learn more about this in our guide on storing secrets:

https://docs.border0.com/docs/using-secret-managers-to-store-credentials

1 -Username & Password based authentication

In this example we'll create an SSH socket, select Username and Password as the authentication strategy, and link the newly created SSH socket to our connector.

• In the Sockets page, click on new SSH socket
• Set a name and, optionally, a description
• Session recording is enabled by default; you can deactivate it if you'd like.

Upstream Information
Here we configure how your connector can connect and authenticate to the upstream SSH server.

• Select Standard SSH for connection type
• For authentication select username and password.
• For hostname and port, we'll use 10.10.10.10. The default port is 22.
• Credentials, in our example we used ops-user as the username and mySuperSecretPw as the password.
• For more secure ways of dealing with credentials click here
• Connector: Select your connector from the list

That's it; now click the create new SSH socket button. And your new SSH socket has been created, and you should have access to your SSH server.

Troubleshooting
Should you see any issues with your new socket, it's typically because it can't connect to the upstream SSH server. Common use-cases are, connector not being able to communicate with the provided hostname and port number, or, invalid credentials. To troubleshoot that take a look at the connector logs as described here

A typical example is a log like below, indicating the connector can't reach the target upstream host on 10.10.10.10:22.

{"msg":"failed to handle channels: unable to connect to upstream host: dial tcp 10.10.10.10:22: i/o timeout","socket_id":"fc442ec1-9108-4d6f-b564-2fa86a43998f"}

Another typical issues may the one below. This indicates the username and password combination didn't work and couldn't be used to authenticate

{"msg":"failed to handle channels: unable to connect to upstream host: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none], no supported methods remain","socket_id":"fc442ec1-9108-4d6f-b564-2fa86a43998f"}

📘

Test authentication manually

If you see upstream connectivity errors in the logs, make sure to try to connect manually from the connector, using the username, password and host. Make sure to validate the username and password combination like this (it will force username/password based auth)
ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no [email protected]

Also make sure your sshd config file on the target server has password authentication enabled, by checking that /etc/ssh/sshd_config has this line: PasswordAuthentication yes

If that doesn't help resolve the issue, feel free to contact us, and we'd be happy to help you troubleshoot.

2 -Key based authentication

In this example we'll create an SSH socket, select SSH Private Key as the authentication strategy, and link the newly created SSH socket to our connector.

• In the Sockets page, click on new SSH socket
• Set a name and, optionally, a description
• Session recording is enabled by default; you can deactivate it if you'd like.

Upstream Information
Here we configure how your connector can connect and authenticate to the upstream SSH server.

• Select Standard SSH for connection type
• For authentication select SSH Private Key.
• For hostname and port, we'll use 10.10.10.10. The default port is 22.
• Credentials, in our example we used ubuntu as the username. Next paste your private SSH key in the SSH private Key field.
• For more secure ways of dealing with credentials click here
• Connector: Select your connector from the list

Troubleshooting
Should you see any issues with your new socket, it's typically because it can't connect to the upstream SSH server. Common use-cases are, connector not being able to communicate with the provided hostname and port number, or, invalid credentials. To troubleshoot that take a look at the connector logs as described here

A typical example is a log like below, indicating the connector can't authenticate using the private key provided. In that case, make sure to validate that the username and private key are correct.

{"msg":"failed to handle channels: unable to connect to upstream host: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain","socket_id":"fc442ec1-9108-4d6f-b564-2fa86a43998f"}

📘

Test authentication manually

If you see upstream connectivity errors in the logs, make sure to try to connect manually from the connector, using the username, private key and host provided in the config. Make sure to validate the username and private combination like below (it will force key based auth)`

ssh -i ~/.ssh/id_rsa -o PreferredAuthentications=publickey -o IdentitiesOnly=yes [email protected]

And restart sshd after any changes to your ssh configuration. In Ubuntu this can be done with

sudo systemctl restart ssh.service

Also see this guide for How To Configure SSH Key-Based Authentication on a Linux Server

If that doesn't help resolve the issue, feel free to contact us, and we'd be happy to help you troubleshoot.

3 -SSH Certificate based authentication

The Border0 API can issue SSH certificates to the connector, to be used for upstream authentication for SSH sockets linked to the connector. The advantage here is that the connector doesn't need an SSH password or private key. For this to work the target (upstream ssh server) should be configured to accept certificates signed by Border0 for authentication.

Border0 provides an SSH certificate authority, which can be used for authenticating to upstream SSH servers. The advantage of selecting border0 ssh certificates as your upstream authentication method is that you don't need to provide any authentication credentials to the connector. Note, that for this to work the target (upstream ssh server) should be configured to accept certificates signed by Border0.

Prerequisite: Configuring the target OpenSSH server to accept SSH certificates signed by Border0

The following changes are needed on the remote SSH server to have it accept SSH certificates signed by Border0.

# Login as an admin to your border0 account
border0 login

# Fetch CA
border0 organization show | grep ecdsa-sha2-nistp256 | awk '{print $5,$6}' > ssh-ca.pub
sudo cp ssh-ca.pub /etc/ssh-ca.pub

# Configure OpenSSH to use trust the Border0 Certificate authority
sudo echo "TrustedUserCAKeys /etc/ssh-ca.pub" >>/etc/ssh/sshd_config

# We look for a certain principle in the signed certificates.
# The below allows any system user to authenticate using signed certificates
sudo echo "AuthorizedPrincipalsFile /etc/ssh/authorized_principals" >>/etc/ssh/sshd_config
sudo echo "mysocket_ssh_signed" > /etc/ssh/authorized_principals

# We can also limit which users should be allowed to use ssh certificates to authenticate like this
# sudo echo "AuthorizedPrincipalsFile %h/.ssh/authorized_principals" >>/etc/ssh/sshd_config
# Only allow user ubuntu
# sudo echo "mysocket_ssh_signed" > /home/ubuntu/.ssh/authorized_principals

# Make sure to reload sshd: 
sudo service ssh reload

After these changes your upstream SSH server should be ready for certificate based authentication

In this example we'll create an SSH socket, select Border0 Certificate as the authentication strategy, and link the newly created SSH socket to our connector.

• In the Sockets page, click on new SSH socket
• Set a name and, optionally, a description
• Session recording is enabled by default; you can deactivate it if you'd like.

Upstream Information
Here we configure how your connector can connect and authenticate to the upstream SSH server.

• Select Standard SSH for connection type
• For authentication select Border0 Certificate.
• For hostname and port, we'll use 10.10.10.10. The default port is 22.
• Username, in our example we use ubuntu as the username.
• Connector: Select your connector from the list

Troubleshooting
Should you see any issues with your new socket, it's typically because it can't connect to the upstream SSH server. Common use-cases are, connector not being able to communicate with the provided hostname and port number, or, invalid credentials. To troubleshoot that take a look at the connector logs as described here

If that doesn't help resolve the issue, feel free to contact us, and we'd be happy to help you troubleshoot.