BastionXP Documentation

# Configuration

In this section, you'll find all the BastionXP CA configuration options with example.

# Basic Config

By default, BastionXP CA uses the configuration file stored at /etc/bastionxp/config.json.

If the config.json does not exists, BastionXP Certificate Manager(CA) will run as a private PKI/CA on localhost TCP port 443 and will issue server and client certifictes without any OIDC SSO authentication.

BastionXP Web Portal will not be kickstarted in this case because SSO OIDC login settings are not available.

By default, BastionXP runs in the auth mode which is the PKI/CA function. It doesn't hurt if you include the mode in the configuration as shown below:

{
    "mode": "auth",
    "email": "[email protected]"
}

The other modes are "proxy" and "host", which are useful while running BastinoXP as SSH Proxy and SSH Server(SSHd).

The email is the email ID of the first provisioner or the admin who manages this CA. All SSL client certificates will be issued with this email ID in the Subject/SAN/CN, if an user email ID is not provided in the bsh login command.

Also, by default, the CA will listen on localhost TCP port 443.

# Use a Custom Domain Name

If you want to run the BastionXP CA on a custom (private or public) domain name, for eg: ca.example.com, use the below configuration.

{
    "email": "[email protected]",
    "gateway_domain": "ca.example.com"
}

# Enable SSH CA Function

By default, BastionXP CA will issue only SSL X.509 certificates. If you want the CA to issue SSH certificates, you need to enable SSH CA function in the configuration as shown below:

{
    "mode": "auth",
    "email": "[email protected]",
    "gateway_domain": "ca.example.com",
    "ssh_ca_enable": true
}

# Use an OIDC SSO for User Authentication

If you want the CA to issue certificates to end users after a successful SSO login using OIDC and two-factor authentication (2FA) methods, include the oidc_provisioner configuration as shown below:

{
    "mode": "auth",
    "email": "[email protected]",
    "gateway_domain": "ca.example.com",
    "oidc_provisioner": {
            "name":"microsoft",
            "client_id": "38asdf232erwefasdf",
            "secret": "abcdefghicjadfasdfasdf2342334234dsadf234"
    }
}

BastionXP supports the following OIDC providers:

  • "google", "microsoft", "okta", "keycloak", "github", "bastionxp".

The OIDC credentials namely, client_id and secret will be provided by your OIDC SSO provider after you register BastionXP as the OIDC client app for this purpose.

How to register an OIDC client app with an OIDC SSO provider is outside the scope of this documentation and specific to the SSO provider. Please refer to your OIDC SSO provider's documentation for more information.

Based on the above configuration, the OIDC client app's callback URL that needs to be registered with your SSO provider will be of the form: https://ca.example.com/api/logincallback

Replace ca.example.com in the above URL with your BastionXP CA's domain name.

Note:

Please note: there is no trailing slash in the callback URL.

# Using Keycloak:

Integrate BastionXP with Keycloak OIDC SSO using the following sample configuration. Note the additional field included in the OIDC Provisioner section of the config file: "server_url": "https://keycloak.example.com/realms/myrealm"

{
    "mode": "auth",
    "email": "[email protected]",
    "gateway_domain": "ca.example.com",
    "oidc_provisioner": {
            "name":"microsoft",
            "client_id": "38asdf232erwefasdf",
            "secret": "abcdefghicjadfasdfasdf2342334234dsadf234",
            "server_url": "https://keycloak.example.com/realms/myrealm"
    }
}

# Using BastionXP Username/Password based login

Use the "bastionxp" name in the OIDC provisioner config, to simply use the BastionXP's built-in login/password based authentication. You can skip the "client_id" and "secret" fields for this authentication, as shown below.

{
    "mode": "auth",
    "email": "[email protected]",
    "gateway_domain": "ca.example.com",
    "oidc_provisioner": {
            "name":"bastionxp",
            "client_id": "",
            "secret": ""
    }
}

By default, all the user accounts will have the password set to admin. You MUST change your default password immediately after your login to the BastionXP web app portal.

Security Note:

BastionXP username/password based login is not recommended for production but good for quick trials or for generating one-off self-signed certificates locally.

# Let's Encrypt SSL Certificate Using ACME

By default, BastionXP CA creates a self-signed certificate for its domain name, so that the CA can be accessed using a HTTPS URL.

If you want to setup and run BastionXP Certificate Manager as a publicly accessible PKI/CA for your organization, you can request BastionXP to automatically fetch a Let's Encrypt SSL Certificate for the CA's public domain name(Eg: ca.example.com).

Tip

This is useful, if you want to use Let's Encrypt issued SSL Certificate for your BastionXP Certificate Manager's domain name and you don't want to use the self-signed ceritificate generated by BastionXP CA for the domain name. This will reduce the extra step involved in making the bsh client and browsers trust the certificate manager's domain SSL certificate.

Let's Encrypt SSL certificates are valid only for 90 days. BastionXP will use ACME to automatically fetch the certificate from Let's Encrypt and also renew it periodically without any human intervention.

Note:

You need to open up the TCP port 80 in your server, so that Let's Encrypt's ACME server can connect to the http server running on TCP port 80 to verify that the server holds the public domain name for which the SSL certificate is being requested.

{
    "mode": "auth",
    "email": "[email protected]",
    "gateway_domain": "ca.example.com",
    "lets_encrypt_acme": true,
    "oidc_provisioner": {
            "name":"microsoft",
            "client_id": "38asdf232erwefasdf",
            "secret": "abcdefghicjadfasdfasdf2342334234dsadf234"
    }
}

# Connecting with External Database

By default, BastionXP stores its state information in a SQLite DB file in the data directory at /var/lib/bastionxp.

For enterprise usecases, it may be ideal to integrate BastionXP with an external database such as Postgresql to save state information. Here is a sample configuration file to connect BastionXP CA securely with the Postgresql DB:

{
    "mode": "auth",
    "email": "[email protected]",
    "gateway_domain": "ca.example.com",
    "oidc_provisioner": {
     ...
     ...
    },
    "database": {
        "driver": "postgres",
        "hostname":"db.example.com",
        "port":"5432",
        "user":"bastionxp",
        "password":"Pa$$word#123",
        "db_name":"bastionxp_db",
        "ssl_mode":"required"
    }    
}

Got questions or have a suggestion? Please write to us: [email protected] for assistance.

← Roles Based Access Control (RBAC) →