BastionXP Documentation

# BastionXP Cloud - SSH Certificate Manager

In this section, you'll learn how to download and setup SSH host and user certificates from the BastionXP Cloud SSH Certificate Manager (CA).

Follow the instructions in the BastionXP Cloud - Getting Started guide before you proceed to the next section.

# Get a Host Certificate

Now that you have added your team members and defined their roles, you can start downloading SSH certificates on the host machines or servers that require SSH access.

There are two methods to get an SSH host certificate from the BastionXP Cloud SSH CA.

  1. Using bsh client utility
  2. Using bastionxp server running in "host" mode.

Use the bsh client utility to get an SSH host certificate, if you want to use your preferred SSH client to connect to your server and you don't want to SSH login from the BastionXP cloud web portal using the SSH web terminal.

How to SSH from the BastionXP Web Portal:

If you want to connect to your server from the BastionXP web portal using the SSH web terminal, you should NOT use the bsh client utility to download the SSH host certificate from the cloud server.

Instead, you should download, install and configure the bastionxp server software to run in the "Host" mode in your server. The bastionxp server running in the "host" mode will automatically download the SSH host certificate to your server. It can also be configured to function as an SSHd server, replacing the OpenSSH SSHd server. Additionally, it can perform SSH session recording for auditing purposes.

More information about how to do this can be found in this documentation guide: BastionXP Host Mode Setup

In this guide, we will use the bsh client to download SSH host certificates in your host machines.

# Step 2.1 - Download BastionXP Client Utility(bsh)

Follow the instructions here to download and install (opens new window) the BastionXP client bsh in your host machine.

# Step 2.2 - Download the SSH Server Certificate

Now, we are ready to download a signed server certificate from the BastionXP Cloud SSH CA using the below command.

You'll have to login to the BastionXP CA's web portal at https://cloud.bastionxp.com using your SSO Login/Password, navigate to the "Auth Token" tab, click the "Create Token" button to create an authentication token with the purpose set to HOST_CERTIFICATE. Expand the row containing the auth token to view and copy the token.

Note:

The HOST_CERTIFICATE token will be valid only for few minutes for security reasons.

If you failed to download an SSH host certificate before the token expires, you need to get a new authtoken from BastionXP web portal again.

Next, open up a terminal window in your host/server and execute the below command using the HOST_CERTIFICATE token copied from the cloud web portal.

$ bsh login  --auth-server cloud.bastionxp.com --host host1.example.com  --token [auth token]

Downloaded long-lived SSH & TLS certificates for the host.

After executing the above command successfully, you'll find the SSH host certificate and private key (for the host host1.example.com) downloaded from the CA in the following location: /home/bob/.bsh/

$ ls ~/.bsh
...
ssh_host  
ssh_host-cert.pub
ssh_host_ca-cert.pub
ssh_user_ca.pub
...

You should copy over these SSH host certificate, host CA certificate and keys to the appropriate location as per your OpenSSH SSHd server configuration. We will discuss about this in the section on "Test using the SSH Certificates" down below.

# Get a User Certificate

# Step 3.1 - Download the SSH User Certificate

Now, download and install (opens new window) the bsh client on your laptop (Windows/Mac/Linux) to get an SSH user certificate from the BastionXP Cloud Server.

$ bsh login  --auth-server cloud.bastionxp.com 
Copy and past the following URL to a browser window to login, if a browser window doesn't open automatically in few seconds.

http://localhost:59023/login

The BastionXP SSH CA will automatically detect that OIDC SSO based login has been enabled. So you'll be redirected to a web browser where you'll be asked to login into your Microsoft Azure 365 account or Google G-Suite account using your company's email ID, password and the two-Factor Authentication(2FA).

Enable 2FA:

For better security, we highly recommend you to enable Time-based One Time Password(TOTP) based 2FA authentication with your company's OIDC SSO provider.

The client certificates will be generated only after a successful SSO+2FA login.

Tip:

You could optionally use a --no-redirect flag in the above command to prevent redirecting to your default browser. You'll be provided a short local URL. You can copy the URL to any browser of your choice for SSO login and authentication.

$ bsh login  --auth-server cloud.bastionxp.com --no-redirect
Copy and past the following URL to a browser window to login, if a browser window doesn't open automatically in few seconds.

http://localhost:59023/login

Login Succeeded.
Downloading certificates... Please wait.
Successfully downloaded short-lived certificates.
Your roles are: ["admins", "ec2-users"].  Your access expires in 8 hours.

Check if the SSH user certificate and key have been downloaded to the .bsh folder in the user's HOME directory, at the end of the login process.

$ ls ~/.bsh
...
ssh_user  
ssh_user-cert.pub
ssh_host_ca-cert.pub
...

# View the Issued SSH Certificates:

We'll use the OpenSSH ssh-keygen tool to verify the certificates generated above.

# SSH Root CA Certificate:

$ ssh-keygen -L -f /var/lib/bastionxp/ssh_host_ca-cert.pub
ssh_host_ca-cert.pub:
        Type: [email protected] host certificate
        Public key: RSA-CERT SHA256:cbGPaPpySLPPjL1DPRwLlGJ1HZoGYy9TN6ohIpSvulQ
        Signing CA: RSA SHA256:cbGPaPpySLPPjL1DPRwLlGJ1HZoGYy9TN6ohIpSvulQ (using rsa-sha2-512)
        Key ID: "cloud.bastionxp.com-19a72e58-db9a-4c94-a149-0ee743bbd9b3"
        Serial: 0
        Valid: from 2024-09-16T09:52:35 to 2124-08-23T09:52:35
        Principals:
                cloud.bastionxp.com 
                localhost
                localhost
                127.0.0.1
                ::1
        Critical Options: (none)
        Extensions: (none)

# SSH Server Certificate:

$ ssh-keygen -L -f ~/.bsh/ssh_host-cert.pub
ssh_host-cert.pub:
        Type: [email protected] host certificate
        Public key: RSA-CERT SHA256:i/JrxYvBvczFKNiaFYWWrSdPDLmGkz5xCzPvsuvc55U
        Signing CA: RSA SHA256:cbGPaPpySLPPjL1DPRwLlGJ1HZoGYy9TN6ohIpSvulQ (using rsa-sha2-512)
        Key ID: "host1.example.com-0f7795ee-c1fa-478e-af40-c2655ae71660"
        Serial: 0
        Valid: from 2024-09-16T09:56:40 to 2024-09-05T09:56:40
        Principals: 
                host1.example.com
        Critical Options: (none)
        Extensions: (none)

Note that the SSH host certificate issued above is tied to a specific pricipal or domain name - host1.example.com in this case. This certificate cannot be used by any other host. BastionXP enforces identify based infrastructure access.

# SSH User Certificate:

$ ssh-keygen -L -f ~/.bsh/ssh_user-cert.pub
ssh_user-cert.pub:
        Type: [email protected] user certificate
        Public key: RSA-CERT SHA256:20vuGqOc8nFrdy4a8p/Rt2ui3H7g+XT/+wsxKed+Qhs
        Signing CA: RSA SHA256:ydywz2m+Lc7iL3SpreSPAsr7/bfk77MZO6jeiGjsZ64 (using rsa-sha2-512)
        Key ID: "[email protected]"
        Serial: 0
        Valid: from 2024-09-16T10:00:09 to 2024-09-16T18:00:09
        Principals: 
                [email protected]
                admin
                ec2-user
        Critical Options: (none)
        Extensions: 
                permit-X11-forwarding
                permit-agent-forwarding
                permit-port-forwarding
                permit-pty
                permit-user-rc

Note that the SSH user certificate issued above is associated with an user identity - [email protected]. Only user bob can use the above certificate to login via SSH into a host. Based on the roles and logins defined in the BastionXP CA, the user certificate also has the principals set to admin and ec2-user.

Also, the SSH user certificates are valid only for a short-duration - 8 hours by default. Short-lived SSH user certificates provide fine-grained control over how long a user can have access to a previleged resource. It also avoids the SSH key sprawl problem.

# Test using the SSH Certificates:

In the sections below, we'll use the SSH certificates generated above to configure an OpenSSH server to trust and permit logins using SSH user certificates issued by the SSH User Root CA.

# SSH Server Configuration:

You can find the SSH host certificate and private key in the following location: /home/bob/.bsh

$ ls ~/.bsh
...
ssh_host  
ssh_host-cert.pub
ssh_host_ca-cert.pub
ssh_user_ca.pub
...

Move these files to the /etc/ssh folder.

sudo mv ~/.bsh/ssh* /etc/ssh

Configure the SSHd server to start using the SSH host certificate generated. Edit the /etc/ssh/sshd_config file as a sudo user and update the following configuration settings.

$ nano /etc/ssh/sshd_config

...

Host /etc/ssh/ssh_host
HostCertificate /etc/ssh/ssh_host-cert.pub
TrustedUserCAKeys /etc/ssh/ssh_user_ca.pub

...

Finally, restart the SSHd service to make the configuration changes take effect. Verify if the SSHd is online, after the restart.

sudo systemctl restart sshd
sudo systemctl status sshd

# SSH Client Configuration

In your laptop, edit the SSH client's known_hosts file and add the Host CA's SSH certificate as the certificate authority for the host, using the @cert-authority directive. This config will ensure that the SSH client will accept any SSH host certificate signed by the SSH host CA. It will not display any Trust On First Use (TOFU) message when the SSH client connects to the host. Please note that you need to copy paste the contents of the ssh_host_ca-cert.pub file into the known_hosts file as shown below.

$ nano ~/.ssh/known_hosts

# Accept host with name localhost, whose certificate is signed by the following CA
@cert-authority host1.example.com ssh-rsa AAXasdyeBN....

Note:

Delete all stale known names for the host from the known_hosts file.

# Step 3.4 - SSH Login

Now SSH login to the host VM using the OpenSSH client as shown below

ssh -i ~/.bsh/ssh_user [email protected]

Alternatively, you could use the bsh client utility to ssh into the host VM as shown below:

bsh ssh [email protected] -p 22

Tip:

As mentioned earlier, if you have configured the bastionxp server to run in the "host" mode in your host machines, you can simply access your servers from the BastionXP web portal using the SSH web terminal.

Congratulations! You have successfully set up a private SSH CA with OIDC SSO based authentication configured. You generated host and user certificates. You used the SSH host certificate to configure an OpenSSH server in a host. You used the SSH user certificate to login to the OpenSSH server using an OpenSSH client.

Questions:

If you have any questions or suggestions, please email us at: [email protected]

← Troubleshooting Guide →