# SSH CA - Getting Started

# BastionXP SSH Certificate Manager

Follow the steps below to install and run BastionXP as a standalone SSH Certificate Manager.

# Prerequisites

You need to have the following to install and run BastionXP Certificate Manager:

A Linux VM or server
TCP Port: 443

# BastionXP SSH CA VM Setup

# Step 1.1 - Download and Install

On the Linux VM, follow the instructions here to download and install (opens new window) the appropriate BastionXP binary package for your Linux distro as RPM or Debian package.

BastionXP CA will be installed and running as a Linux Systemd Daemon in the background.

# Step 1.2 - Configuration File

Create a directory named bastionxp under /etc in your system as shown below:

sudo mkdir -p /etc/bastionxp

Create a configuration file named config.json in the /etc/bastionxp directory with the following contents.

{
    "mode": "auth",
    "gateway_domain": "localhost",
    "ssh_ca_enable": true,
    "email": "[email protected]"
}

The ssh_ca_enable flag in the config file when set to true will make a regular BastionXP CA to also function as an SSH CA and start issuing SSH certificates.

# Step 1.3 - Restart

Now restart the BastionXP service already running in the background, to pickup the above configuration changes.

sudo systemctl restart bastionxp

You can check the bastionxp logs as shown below:

tail -f /var/lib/bastionxp/bastionxp.log

You'll see the following logs in the log file:

Using config file: /etc/bastionxp/config.json
Creating TLS Root CA certificate at:  /var/lib/bastionxp/tls_root_ca.crt
Root CA Fingerprint:  3afc3265ff5d037addc1b8a19afdf6c77db094fca562eaae42752b95f7fa7584
Creating TLS Intermediate CA certificate at:  /var/lib/bastionxp/tls_intermediate_ca.crt
Creating Auth Server Host Certificate at:  /var/lib/bastionxp/server.crt
Creating SSH Host CA at:  /var/lib/bastionxp/ssh_host_ca-cert.pub
Creating SSH User CA at:  /var/lib/bastionxp/ssh_user_ca.pub
...
...

Note the Root CA fingerprint 3afc3265ff5d037addc1b8a19afdf6c77db094fca562eaae42752b95f7fa7584 in the above log. You'll use this fingerprint later to establish trust with this CA.

# Get a Server Certificate

To get a server certificate from the CA, we need to use the BastionXP client utility: bsh

# Step 2.1 - Download BastionXP client

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

# Step 2.2 - Establish Trust with the Certificate Manager

Before we can get SSH certificates signed from the CA, we need to make the bsh client trust the BastionXP CA.

This is required because the Certificate Manager is running locally on localhost and using a self-signed SSL/TLS certificate for the localhost domain name.

Use the fingerprint collected from the BastionXP CA setup logs above and make the client trust the CA.

$ bsh init --auth-server localhost --fingerprint 3afc3265ff5d037addc1b8a19afdf6c77db094fca562eaae42752b95f7fa7584

Downloading Root CA certificates... Please wait.
Successfully downloaded Root CA TLS certificates.

The above command will download the Root CA's certificate named tls_root_ca.crt to a local folder named .bsh in your home directory: Eg: /home/bob/.bsh/tls_root_ca.crt

$ ls ~/.bsh

tls_root_ca.crt

Now you can optionally add the BastionXP Root CA certificate to your system's certificate trust store, as shown below for debian variants:

sudo cp ~/.bsh/tls_root_ca.crt /usr/local/share/ca-certificates/.
sudo update-ca-certificates

Here after your system will start trusting all certificates issued by the BastionXP Certificate Manager.

# Step 2.3 - Get the Host Cerfiticate

Now, we are ready to get a signed SSH host certificate from the SSH CA using the below command.

$ bsh login  --auth-server localhost  --host localhost --no-auth

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

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
...

# Get a Client Certificate

# Step 3.1 - Download the Client Certificate

Again, use the bsh client to get an SSH client certificate from the BastionXP CA.

$ bsh login  --auth-server localhost --no-auth 

Downloading certificates... Please wait.
Successfully downloaded short-lived certificates.
Your roles are: [].  Your access expires in 8 hours.

You'll find the SSH client certificate and private key in the following location: /home/bob/.bsh

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

# View the Issued Certificates:

We'll use the OpenSSH ssh-keygen tool to view and verify the SSH certificates generated.

# 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: "localhost-19a72e58-db9a-4c94-a149-0ee743bbd9b3"
        Serial: 0
        Valid: from 2023-09-16T09:52:35 to 2123-08-23T09:52:35
        Principals: 
                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: "localhost-0f7795ee-c1fa-478e-af40-c2655ae71660"
        Serial: 0
        Valid: from 2023-09-16T09:56:40 to 2025-09-05T09:56:40
        Principals: 
                localhost
        Critical Options: (none)
        Extensions: (none)

Note that the SSH host certificate issued above is tied to a specific pricipal or domain name - localhost in this case. This certificate cannot be used by any other host. If you provide, host1.example.com as the host name during certificate signing request, the SSH CA will issue a certificate with principals set to [host1.example.com].

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 2023-09-16T10:00:09 to 2023-09-16T18:00:09
        Principals: 
                [email protected]
        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.

Also, the SSH user certificates are valid only for a short-period - 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

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 localhost ssh-rsa AAXasdyeBN....

Note:

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

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

ssh -i ~/.bsh/ssh_user bob@localhost

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

bsh ssh bob@localhost -p 22

If the SSH host server name is host1.example.com and the user bob has the permission to login to the server, you can ssh into the server as follows using the SSH user certificate:

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

Congratulations! You have successfully set up a private SSH CA. You also generated host and user certificates, used them to setup and login to a OpenSSH server using OpenSSH client.

# Next Steps:

Configure the BastionXP SSH CA to issue SSH certificates after a successful OIDC SSO Login using OIDC SSO providers such as Microsoft Azure 365, Google G-Suite, Okta, Keycloak, or BastionXP.
Configure the BastionXP SSH CA to also function as a SSH Jump Host or Bastion Host.

Questions:

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

← Roles Based Access Control (RBAC) Using OIDC SSO Login →