BastionXP Documentation

# SSH Key Manager - Getting Started

# BastionXP SSH Key Manager

Follow the steps below to download, install and run BastionXP as a standalone SSH Key Manager in your self-hosted server on-prem.

# Prerequisites

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

  • A Linux VM or server (Debian or RHEL or Any Linux distribution)
  • Register BastionXP as an OIDC client with your company's OIDC SSO provider.
  • TCP Port: 443, 4021

# BastionXP SSH Key Manager 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 - Register BastionXP as an OIDC Client App

Register BastionXP SSH Key Manager as a OIDC client app with your company's OIDC SSO provider such as Microsoft Azure 365, Google G-Suite, Okta, Keycloak or GitHub. How to do this is specific to your OIDC SSO provider and outside the scope of this documentation.

Register https://your-subdomain-name/api/logincallback as the OIDC client app's login callback API with your OIDC SSO provider. For this example, we plan to use bastionxp.example.com as the domain name for our BastionXP instance. So, we'll register https://bastionxp.example.com/api/logincallback as the login callback API with the OIDC provider(MS Azure 365).

Note:

Please make sure that you register the correct login callback API with your OIDC SSO provider. Note, the above callback URL doesn't include a "/" at the end of the URL. If you add a "/" at the end of the callback URL by mistake, you'll notice error during redirection from your OIDC provider to your BastionXP instance running on-prem, after a successful user authentication.

If you are facing any error during redirection after a successful login with your OIDC SSO provider, it is most likely due to any error in your OIDC client app registration settings, or may be, your BastionXP server configuration doesn't match the OIDC client app credentials provided by your OIDC SSO provider.

After you register BastionXP CA as the client app, obtain the OIDC Client ID and Client Secret provided by your OIDC provider. We'll feed this information into the CA's config file created in the next section.

# Step 1.3 - 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": "bastionxp.example.com",
    "ssh_key_mgr_enable": true,
    "email": "[email protected]",
    "oidc_provisioner": {
            "name":"microsoft",
            "client_id": "38asdf232erwefasdf",
            "secret": "abcdefghicjadfasdfasdf2342334234dsadf234"
    }    
}

The ssh_key_mgr_enable flag in the config file when set to true will make BastionXP CA to also function as an SSH Key Manager.

# Step 1.4 - Getting Public SSL Certificate

Your BastionXP SSH Key Manager instance, when running on a public server with a public IP address, needs a valid public SSL certificate from a public SSL certificate provider such as ZeroSSL, LetsEncrypt, etc. This SSL certificate is required for secure encrypted communication over the internet.

Self-Signed Certificate:

If you don't provide any SSL certificate, BastionXP will generate and use a self-signed certificate by default. The problem with the self-signed certificate is that, when you try to connect to the BastionXP instance using a browser, you'll see a security warning saying: "Certificate signed by an unknown certificate authority". You can choose to ignore this warning and proceed ahead with your connection safely. Your connection is still secure and encrypted.

If you want BastionXP to automatically fetch a Let's Encrypt (opens new window) signed public SSL certificate for your BastionXP instance using ACME, instead of using a self-signed SSL certificate for the domain name bastionxp.example.com, add the following to your configuration file at: /etc/bastionxp/config.json. This method will work only if your BastionXP instance is running in a server/VM with public IP address and the TCP port 80 is open (for the ACME auth-challenge to work).

{
    ...
    ...
    "lets_encrypt_acme": true,
    ...
    ...
}

Alternatively, you can get an SSL certificate yourselves from LetsEncrypt.org or any third-party public SSL certificate vendor for your registered subdomain (bastionxp.example.com) and store it under the folder /var/lib/bastionxp/ as server.crt and server.key.

# Step 1.5 - 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

# Step 1.6 - Define Roles and Logins

You can login to the BastionXP SSH Manager's web portal by pointing your web browser to the following URL: https://bastionxp.example.com

You should use your configured OIDC SSO provider (Microsoft, Google, or GitHub) to login to the web portal.

# Add Team Members:

Only admin users of the BastionXP SSH Key Manager can add team members to your account and define roles and logins.

As an admin user, go to the "Team Members" tab and add your team members to your account with their respective roles. To define roles for your team members, you need to go to the "Roles and Logins" tab and create "Roles and Logins" for your organization first.

# Define Roles and Logins

Please refer to this documentation guide on: How to create and manage roles and logins

Security Note:

A team member will be allowed to login to a server or host machine where he/she has an account (using a login username) from the BastionXP web portal's SSH web terminal, only if the team member has the correct roles set and the role has the server's login username associated with that role.

By default, without any roles and logins defined in BastionXP, the user can login to a server only using the username in his/her email ID. For example, a user named "Bob Smith" with email ID [email protected] can login to any Linux server in your organization, where he already has a user account, can login to the server from the BastionXP web portal using the username bob. BastionXP SSH Key Manager will download a short-lived SSH public key to the server for the user to SSH login.

# Host/Server Configuration

Now, that the SSH key manager is up and running, and ready to distribute SSH keys to hosts, VMs and servers, let's move on to the host or server side configurations required to download the SSH keys from the SSH key manager to the hosts/VMs/servers.

For BastionXP SSH Key Manager to automatically manage keys in your host/server/VM instances, you need to download and run the bastionxp software in "host" mode in all your host machines. To learn more about this, please refer to our documentation guide on: How to setup BastionXP to run in the "Host" mode.

The bastionxp software, when run in the "host" mode, will function like a reverse proxy client that connects the host machine to the centralized BastionXP SSH Key Manager server (Hint: imagine a VPN connection). So that, the end users can login to the BastionXP web portal and SSH login to your hosts/servers/VMs from the web portal's SSH web terminal. Note: BastionXP's Role Based Access Control(RBAC) logic controls who can login to what servers.

# SSH Client (Web Terminal)

As a team member, visit the BastionXP SSH Key Manager's web portal by pointing your browser to : https://bastionxp.example.com.

Login to the web portal, after a successful OIDC SSO authentication using your email ID.

Navigate to the "Servers" section. Click the terminal icon next to your server. Provide the SSH login username with which you would like to login to the server.

BastionXP's RBAC logic will check if you have the appropriate "Roles and Logins" permission to SSH login to the server using this login username.

If you have the correct permission, the SSH key manager logic will create an SSH key pair and download the SSH public key to the server.

After the key is successfully downloaded to the server, the SSH web client terminal will securely connect to the server's SSH server which is listening on TCP port 22 (using SSH protocol and SSH key based authentication). After a successful SSH key based authentication, the SSH web client will display the server's shell prompt, where you can execute Linux commands.

Note:

The downloaded SSH public key will be deleted after a few minutes. BastionXP managed SSH keys are short-lived SSH keys. A new SSH key will be created and synced to the server, if the user wants to login again to the same server.

← BastionXP Host Mode Setup →