Setting up custom SSL certificates for HTTPS connections - Platform - BlueCat Gateway - 25.2

Gateway requires TLS/SSL certificates to communicate over HTTPS networks. If no TLS/SSL certificates exist in a workspace when Gateway starts, it will automatically generate and use a new set of unique, self-signed certificates.

Since these certificates are self-signed, they're not validated by any certificate authority. If you prefer, you can instead have Gateway use your own custom TLS/SSL certificates, such as certificates signed by an appropriate authority. Custom certificates must use strong Advanced Encryption Standard protocols, such as Elliptic Curve Diffie-Hellman (ECDH) with 128 bits of keyspace. You can use custom certificates with both custom and built-in workspaces.

There are three ways to set up custom SSL certificates with Gateway:

• Upload certificates from the Certificates settings in the Gateway UI.

• Manually install the certificate files in the Gateway workspace.

• When launching or deploying the Gateway container, mount a directory for a Certificate Authority (CA) bundle onto the Gateway container and store the certificates there.

  You will need to both mount the certificate bundle directory onto the container and specify the location of that directory when launching Gateway.

  This is useful in several cases. For example:

  • You want Gateway to use a certificate bundle stored on on the host outside the container that it normally can't access.

    This can happen when configuring Single Sign-On (SSO) in Gateway. If you set SAML input to Manual input and specify a Metadata URL (within IdP settings) that indicates a self-signed certificate on the Identity Provider (IdP), Gateway won't be able to fetch the needed metadata from the IdP. This can cause Gateway SSO to fail. By mounting the IdP server's certificate bundle (and specifying it in the REQUESTS_CA_BUNDLE environment variable, Gateway can access those those certificates.

  • If you use self-signed certificates and mount (and specify) a path for a certificate bundle, Gateway will store its self-signed certificates in that folder.

To upload certificates using the Gateway UI:

• See Configuring Certificates settings.

To manually install certificate files outside of Gateway:

1. Install the files in the following locations, relative to the workspace root:

   • Store the certificate's crt file as certificates/server/gateway.crt, in PEM (Privacy-Enhanced Mail) format. This may include intermediate CA certificates. Create the certificates/server directory if it doesn't already exist.

     For example, if your workspace root is /root/gwdata/customizations, store the certificate's crt file as /root/gwdata/customizations/certificates/server/gateway.crt.

   • Store the certificate's key file for the certificate as certificates/server/gateway.key.

   Note: The certificate crt and key files must be named gateway.crt and gateway.key, respectively

2. Set read, write, and execute permissions on the custom workspace and logs folder. To do so, run the following commands:

   chmod -R o=rwx
   chmod -R o=rwx

3. After copying certificate files to the workspace, restart the container.

To mount a directory on the container Gateway to use for a CA bundle:

When you run the docker container, in the docker run (or podman run) command, do the following:

1. Add a volume mount directive for the directory that has the CA bundle. You can use the same format as the mapped workspace and logs directories:

   -v <Path to custom CA bundle directory>:/etc/ssl/certs \ 

   Tip: You can use any local directory path that you want; /etc/ssl/certs is an example.

2. Specify the value of REQUEST_CA_BUNDLE as a parameter with the -e option as the CA bundle path that you mounted. For example:

   -e REQUESTS_CA_BUNDLE="/etc/ssl/certs/<ca_bundle_certificate_name>" \

   Tip: If you use self-signed certificates and specify a path in REQUESTS_CA_BUNDLE, Gateway will store its self-signed certificates in that folder.

For example, a complete docker run command might look like this:

docker run -d \
-p 80:8000 \
-p 443:44300 \
-v <Path to mapped workspace directory>:/bluecat_gateway/ \
-v <Path to mapped logs directory>:/logs/ \
-v <Path to custom CA bundle directory>:/etc/ssl/certs \
-e REQUESTS_CA_BUNDLE="/etc/ssl/certs/<ca_bundle_certificate_name>" \
<Authentication platform environment variables> \
--name bluecat_gateway quay.io/bluecat/gateway:25.2.0