BastionXP Documentation

# Using OIDC SSO Login

# BastionXP Certificate Manager with OIDC SSO Login

Follow the steps below to install and run BastionXP as SSL/TLS X.509 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 SSL certificates.

Note:

If you are interested in setting up a SSH Certificate Manager, refer to this documenation: BastionXP SSH CA Setup

# 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 CA as a client app in 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": "bob@example.com",
    "gateway_domain": "ca.example.com",
    "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.

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:  35a85a609a703ab0984ba652ce0d3e0da1397aadc992b0139205f5c45dfd73a5
Creating TLS Intermediate CA certificate at:  /var/lib/bastionxp/tls_intermediate_ca.crt
Creating Auth Server Host Certificate at:  /var/lib/bastionxp/server.crt
...
...

Note the Root CA fingerprint 35a85a609a703ab0984ba652ce0d3e0da1397aadc992b0139205f5c45dfd73a5 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 SSL/TLS 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 Lets Encrypt or your cloud provider such as AWS, Azure or GCP.

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 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 server and execute the below command using the HOST_CERTIFICATE token obtained from the web portal.

$ bsh login  --auth-server localhost --host server1.example.com  --token [auth token]

Downloaded long-lived SSL TLS certificates for the host.

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

$ ls ~/.bsh
...
tls_server.crt  
tls_server.key
...

# Get a Client Certificate

# Step 3.1 - Download the Client Certificate

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

Open up a terminal window in your client machine and execute the below command to obtain the client certificate.

$ 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 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 SSO provider (Microsoft Azure 365 account) using your company's email ID, password and the Two-Factor Authentication(2FA) if enabled.

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-user"].  Your access expires in 8 hours.

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

$ ls ~/.bsh
...
tls_client.crt  
tls_client.key
...

Tip:

You can visit your BastionXP CA's web portal running at https://ca.example.com, define roles and logins for your organization and add the roles to each user.

# View the Issued Certificates:

We'll use the OpenSSL tool to verify the certificates generated so far.

# Root CA Certificate:

$ openssl x509 -in ~/.bsh/tls_root_ca.crt -noout  -text
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            5f:b4:2a:23:83:bc:11:ba:2b:85:f0:a6:47:76:15:9c
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN = ca.example.com
        Validity
            Not Before: Sep 11 05:37:11 2023 GMT
            Not After : Aug 18 05:37:11 2123 GMT
        Subject: CN = ca.example.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (4096 bit)
                Modulus:
                    00:ba:06:5b:eb:13:d6:f9:d2:bb:fb:c0:70:86:db:
                    0e:91:79:dd:89:dd:99:26:eb:e6:09:da:77:cc:fe:
                    07:b0:09:21:c2:c7:17:e4:ee:58:d7:ce:9f:96:57:
                    6d:e5:73:8f:e5:23:9e:11:a7:76:de:94:9e:2a:7a:
                    8e:1b:3 ...
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment, Certificate Sign
            X509v3 Basic Constraints: critical
                CA:TRUE
            X509v3 Subject Key Identifier: 
                78:2A:6C:A0:64:AA:59:42:2B:FA:11:25:66:3A:BE:5F:27:EA:6E:17
            X509v3 Subject Alternative Name: 
                DNS:ca.example.com
    Signature Algorithm: sha256WithRSAEncryption
    Signature Value:
        72:3e:3f:8d:b2:72:68:e8:ef:88:b9:0d:d3:db:b0:22:a2:0c:
        7c:93:6b:f6:bf:73:cc:93:62:e5:75:a1:ee:ae:a0:a2:c1:1f:
        16:e4:79:0a:f3:a9:48: ...

# Server Certificate:

$ openssl x509 -in ~/.bsh/tls_server.crt -noout  -text
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            8b:a6:d8:6f:1c:d0:a4:d9:fa:f4:9c:4c:14:41:1f:14
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN = ca.example.com
        Validity
            Not Before: Sep 11 06:14:29 2023 GMT
            Not After : Aug 31 06:14:29 2025 GMT
        Subject: CN = server1.example.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (4096 bit)
                Modulus:
                    00:db:b9:a4:72:1d:c0:86:52:0a:c1:80:a7:a8:0a:
                    06:2d:62:d4:94:4d:82:bb:0d:99:d9:b9:14:06:ee:
                    d2:22:51:45:fe:dc:9b ...
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage: 
                TLS Web Server Authentication, TLS Web Client Authentication
            X509v3 Subject Alternative Name: 
                DNS:server1.example.com
    Signature Algorithm: sha256WithRSAEncryption
    Signature Value:
        4a:30:7b:01:65:e0:5f:06:e2:f0:12:2e:46:c6:13:92:c9:be:
        a2:e9:dd:45:1d:e3:62:f4:61:90:f6:81:8a:ba:79:30:02:12:
        37:15:d5:a1:7e:d5:a5:07:6a:2a ...

# Client Certificate:

$ openssl x509 -in ~/.bsh/tls_client.crt -noout  -text
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            2d:11:ed:0e:e3:47:05:9a:14:05:5a:26:6b:7b:80:83
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN = ca.example.com
        Validity
            Not Before: Sep 11 06:13:08 2023 GMT
            Not After : Sep 11 14:13:08 2023 GMT
        Subject: CN = bob@example.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (4096 bit)
                Modulus:
                    00:e7:d5:cd:79:ba:52:d4:87:9a:0d:8e:30:f4:b2:
                    3d:6d:8e:1d:d9:91:8c:30:ef:94:b8:da:87:2d:f2:
                    96:59:34:c4:c4:ac:63 ...
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage: 
                TLS Web Client Authentication
            X509v3 Authority Key Identifier: 
                78:2A:6C:A0:64:AA:59:42:2B:FA:11:25:66:3A:BE:5F:27:EA:6E:17
            X509v3 Subject Alternative Name: 
                email:bob@example.com
    Signature Algorithm: sha256WithRSAEncryption
    Signature Value:
        b1:08:8f:90:7f:06:64:89:83:02:49:d0:14:35:45:cb:09:e0:
        b7:61:c8:fd:bc:4f:54:6f:1b:1a:d6:4c:a9:ec:d7:56:26:6e:
        0f:c6:0d:cc:2c:39:77:78:1d ...

# Golang based TLS Server Example

We'll use the below hello world HTTPS web server written in Golang to test the server certificate issued by the BastionXP CA.

package main
import (
    "net/http"
    "log"
)
var (
	CertFilePath = "/home/bob/.bsh/tls_server.crt"
	KeyFilePath  = "/home/bob/.bsh/tls_server.key"
)
func helloHandler(w http.ResponseWriter, req *http.Request) {
    w.Write([]byte("Hello, world!\n"))
}
func main() {
    http.HandleFunc("/hello", helloHandler)
    err := http.ListenAndServeTLS(":8443", CertFilePath, KeyFilePath, nil)
    if err != nil {
        log.Fatal(err)
    }
}

Execute the above Go program using the following command:

go run https_server.go &

Now, try connecting to the above HTTPS server using the following command:

curl https://localhost:8443/hello

You'll see the following error when you run the above command.

curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.

This is because the curl command line utility is not aware of the BastionXP Root CA and therefore doesn't trust the server certificate issued by the CA.

To make the curl utility trust the BastionXP CA and the certificates issued by it, use the --cacert flag in the curl command and provide the CA's root certificate as shown below:

$ curl --cacert ~/.bsh/tls_root_ca.crt https://localhost:8443/hello

Hello, world!

Congratulations! You have successfully set up a private CA, generated a server certificate and used it for a HTTPS web service.

# Next Steps

Got any questions? Please write to us at: support@bastionxp.com

← Configuration →