Using OIDC SSO Login

BastionXP SSH Certificate Manager with OIDC SSO Login

Follow the steps below to install and run BastionXP as SSH Certificate Manager that uses OIDC SSO Login providers such as Google G-Suite, Microsoft Azure 365, Okta, GitHub, Keycloak and more, to authenticate admins and users before generating SSH certificates.

Prerequisites

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

• A Linux VM or server
• TCP Port: 443 (BastionXP web portal will be accessible on your server at this port )
• Register BastionXP as an OIDC client with your company's OIDC SSO provider.

BastionXP PKI/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 - Register BastionXP CA as an OIDC Client App

Register BastionXP SSH CA 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.

Use https://your-ca-domain-name/api/logincallback as the OIDC client app's login callback API. For this example, we'll register https://ca.example.com/api/logincallback as the login callback API with the OIDC provider(MS Azure 365).

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",
    "email": "[email protected]",
    "gateway_domain": "ca.example.com",
    "ssh_ca_enable": true,
    "oidc_provisioner": {
            "name":"microsoft",
            "client_id": "38asdf232erwefasdf",
            "secret": "abcdefghicjadfasdfasdf2342334234dsadf234"
    }
}

Tip:

If you want BastionXP CA to fetch Let's Encrypt (opens new window) signed SSL certificate for your BastionXP CA, instead of a self-signed SSL certificate for the domain name ca.example.com, add the following to your config.json file. This will work only if your CA is running in a server/VM with public IP address and the tcp port 80 is open.

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

Alternatively, you can get an SSL certificate yourselves from LetsEncrypt.org for your BastionXP CA domain and store it under /var/lib/bastionxp/ as server.crt and server.key.

Step 1.4 - Restart

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

sudo systemctl restart bastionxp

Your BastionXP CA's web portal can be accessed at: https://ca.example.com. Please ensure that no other web server or application is running at port: 443 on your server. If not, stop the other web app and restart the BastionXP CA instance, so that BastionXP web app listens on port 443.

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 35a85a609a703ab0984ba652ce0d3e0da1397aadc992b0139205f5c45dfd73a5 in the above log. You'll use this fingerprint later to establish trust with this CA.

Get a Host Certificate

To get a SSH Host 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 from the CA, we need to make the bsh client trust the BastionXP CA.

Tip:

You can skip this step, if you are using an SSL certificate issued by a well-known pulic PKI/CA such as Let's Encrypt

This is required because the Certificate Manager is running locally on ca.example.com and is using a self-signed SSL/TLS certificate generated by the CA for the ca.example.com 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 35a85a609a703ab0984ba652ce0d3e0da1397aadc992b0139205f5c45dfd73a5

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 Linux 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 Server Cerfiticate

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

You'll have to login to the BastionXP CA's web portal at https://ca.example.com using your SSO Login/Password and create an authentication token with the purpose set to HOST_CERTIFICATE. This token will be valid only for few minutes for security reasons.

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

$ bsh login  --auth-server localhost --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
...

Get a User Certificate

Step 3.1 - Download the SSH User Certificate

Again, download, install and use the bsh client to get an SSH user certificate from the BastionXP CA.

$ bsh login  --auth-server ca.example.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 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 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 ca.example.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

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

Tip:

You can visit your BastionXP CA's web portal, define roles and logins for your organization and add the roles to each user.

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: "ca.example.com-19a72e58-db9a-4c94-a149-0ee743bbd9b3"
        Serial: 0
        Valid: from 2023-09-16T09:52:35 to 2123-08-23T09:52:35
        Principals:
                ca.example.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 2023-09-16T09:56:40 to 2025-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 2023-09-16T10:00:09 to 2023-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

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

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.

Next Steps:

• 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]