Hardening The Deployment
To harden the demo deployment there are a number of steps to follow.
The documentation below requires modifying the configuration of the Helm charts installed by following the Manual Install steps or running the deploy.sh
script.
To obtain the installed configuration for each installed Helm chart, run the following commands:
helm -n nshieldkeysafe5 get values --all --output yaml keysafe5-backend > keysafe5-backend-values.yaml
helm -n nshieldkeysafe5 get values --all --output yaml keysafe5-ui > keysafe5-ui-values.yaml
helm -n nshieldkeysafe5 get values --all --output yaml keysafe5-istio > keysafe5-istio-values.yaml
Documentation for each configurable value in the KeySafe 5 Helm charts can be found by untarring the chart.tgz and viewing the contents of either README.md or the default values.yaml file. |
Certificates
The Manual Install steps and the deploy.sh
script will generate a local Certificate Authority, and install a number of short-lived demo certificates.
These certificates must be replaced to continue using the system after their expiry.
Your new certificates will need to adhere to X.509 v3, sometimes known as a multiple-domain certificates, or SAN certificates. The X.509 extension Subject Alternative Name (SAN) allows specifying multiple hostnames, and has replaced Common Name as the source of the hostname.
External KeySafe 5 Server TLS Certificate
To update the TLS certificate used for the KeySafe 5 Server (for HTTPS connections to the REST API or User Interface) you must create a Kubernetes Secret containing the new certificate/private key and redeploy the keysafe5-istio
Helm chart.
For more information on enabling HTTPS for helm-keysafe5-istio, see the Helm Chart Installation section of the Installation Guide.
The Manual Install steps and deploy.sh
script create a Kubernetes Secret called keysafe5-server-credential
.
You can either delete the existing Secret as shown below, or use a different name for the Secret containing your new TLS certificate.
kubectl --namespace istio-system delete secret keysafe5-server-credential
kubectl --namespace istio-system create secret tls keysafe5-server-credential \
--cert=path/to/cert/file \
--key=path/to/key/file
Before running helm upgrade
, set the following values in your keysafe5-istio-values.yaml
:
-
httpsEnabled=true
-
tls.existingSecret=keysafe5-server-credential (or the name you used when creating the Kubernetes Secret containing your certificate/private key)
helm upgrade --install keysafe5-istio \
--namespace=nshieldkeysafe5 \
--values keysafe5-istio-values.yaml \
--wait --timeout 1m \
helm-charts/nshield-keysafe5-istio-1.4.0.tgz
Internal Certificates
The Manual Install steps and deploy.sh
script create a Certificate Authority, and install KeySafe 5 using TLS authorised by the CA for the communications between the central platform and MonogDB/RabbitMQ.
You can refresh these internal certificates by running the updateinternalcerts.sh
script, specifying the number of days for which the new certificates will be valid.
Alternatively if you have an external CA, you may generate keys and certificates and pass the directory containing them to updateinternalcerts.sh
script.
The help for updateinternalcerts.sh
is shown with the -h
option:
Usage: ./updateinternalcerts.sh [OPTION]... [SERVER] DAYS
./updateinternalcerts.sh [OPTION]... [SERVER] DIRECTORY
Update the internal server and client TLS credentials for a deployment created
by deploy.sh.
This can update certificates and keys for both RabbitMQ and MongoDB as set up
by deploy.sh, along with the certificates and keys for the KeySafe 5 Backend
services. RabbitMQ has a single key and certificate. MongoDB has three keys
and certificates, two for the replica-set, and one for the arbiter. The
KeySafe 5 backend services also have two keys and client certificates for
connecting to both RabbitMQ and MongoDB.
When using the insecure internal CA, specify when the new keys and certs will
expire and this script will do the rest.
When using a secure external CA, all the keys and certificates will have to
be provided and they will be packaged up for the deployment.
When updating the certificates for RabbitMQ the script will generate an
updated agent-config.tar.gz and agent-config.zip files containing a config
file and ca.crt.
Certificate Addresses
The certificates contain names and IP addresses that verify the connection,
signed by a mutally trusted authority.
The backend servers only use Kubernetes internal addressing to access MongoDB
and RabbitMQ.
MongoDB is only used by the backend services so does not require an external
address.
RabbitMQ is also accessed by the KeySafe 5 Agents through an external address.
Shared Optional parameters
-n, --namespace=NAMESPACE The deploy script normally uses nshieldkeysafe5
as the namespace for the KeySafe 5 servers,
mongons for MongoDB, and rabbitns for RabbitMQ.
However you can override these to use a single
namespace for all the servers. If that is the
case, then use this option.
SERVER One of "mongodb" or "rabbitmq".
If the server is not specified then both will
be updated.
Internal CA
-----------
DAYS Number of days before the generated certificates
expire
This script will use the IP address provided by the loadbalancer, but you may
override this with a different IP address or DNS name.
-r, --rabbitmq=ADDRESS The external address for RabbitMQ
-m, --mongodb=ADDRESS The external address for MongoDB
External CA
-----------
DIRECTORY The directory containing the server and client
keys and certificates in PEM format.
Files in the directory
----------------------
ca.crt The certificate of the CA that is to be trusted by
the system.
rabbitmq.key The key to be used by rabbit-chart-rabbitmq
rabbitmq.crt And its certificate
ks5rabbitmq.key The key to be used by ks5
ks5rabbitmq.crt And its certificate
mongodb-0.key The key to be used by mongo-chart-mongodb-0
mongodb-0.crt And its certificate
mongodb-1.key The key to be used by mongo-chart-mongodb-1
mongodb-1.crt And its certificate
mongodb-a.key The key to be used by mongo-chart-mongodb-arbiter
mongodb-a.crt And its certificate
ks5mongodb.key The key to be used by ks5-mongo-user
ks5mongodb.crt And its certificate
If rabbitmq is specified, the mongodb files may be skipped, and vice versa.
Internal CA examples
Refresh certificates for both servers for the next 30 days, and set a DNS
entry for RabbitMQ
./updateinternalcerts.sh -r rabbitmq.example.com 30
Refresh just MongoDB for the next 4 weeks
./updateinternalcerts.sh mongodb 28
External CA examples
Refresh certificates for both servers (and KeySafe 5) in a specific namespace
./updateinternalcerts.sh -n kansas all-certs-dir
Refresh certificates for just MongoDB (and KeySafe 5) in standard namespaces
./updateinternalcerts.sh mongodb mongo-certs-dir
This script will update both MongoDB and RabbitMQ TLS certificates, though you may choose to update only one set of TLS certificates by specifying only that server.
The |
If both certificates have expired when running |
If an error occurs during certificate update you can restore the previous setup by rolling back Helm chart installations to a previous release, see Helm Chart Upgrade in the Upgrade section of the Installation Guide.
MongoDB TLS Certificates
The Manual Install steps and deploy.sh
script installs the Bitnami MongoDB Helm chart with TLS enabled for the connections between KeySafe 5 and the MongoDB server and also with TLS used for authentication.
These certificates will initially be valid for 30 days from the time the process was run.
You can refresh the MongoDB certificates by running the updateinternalcerts.sh
script, specifying the number of days the new certificates will be valid for.
updateinternalcerts.sh mongodb 365
This script will:
-
Generate the new TLS certificates
-
Update the MongoDB helm chart to use the new certificates
-
Update the
keysafe5-backend
helm chart to use the new certificates
You may specify an external address with the -m
parameter but this is usually not required.
For an external CA, the following command will apply the keys and certificates from the directory mycerts
updateinternalcerts.sh mongodb mycerts
If using an external CA, the following suggestions should improve the chances of success:
* Create keys for all the MongoDB servers (mongo-chart-mongodb-arbiter-0
, mongo-chart-mongodb-0
, and mongo-chart-mongodb-1
)
* Use 4k RSA keys
* Set the Key Usage to Digital Signature, Non Repudiation, Key Encipherment
* For the server certificates, do not set the Extended Key Usage (the keys are used as both server and client keys)
* For the server certificates' Subject Alternative Name, add DNS records for mongodb
, mongo-chart-mongodb.mongons.svc.cluster.local
, <server>.mongo-chart-mongodb-headless.mongons.svc.cluster.local
, and mongo-chart.mongons.svc.cluster.local
* For the client certificate, set the Extended Key Usage as "TLS Web Client Authentication"
* For the client certificate’s Subject Alternative Name, set the first entry to the DNS value of ks5-mongo-user
, and add DNS entries for keysafe5-backend-ks5-mongo-user-headless
, keysafe5-backend-ks5-mongo-user.nshieldkeysafe5.svc.cluster.local
, and keysafe5-backend.nshieldkeysafe5.svc.cluster.local
.
RabbitMQ
The Manual Install steps and deploy.sh
script installs the Bitnami RabbitMQ Helm chart with TLS enabled.
You can refresh the RabbitMQ certificates by running the updateinternalcerts.sh
script, specifying the number of days the new certificates will be valid for.
updateinternalcerts.sh rabbitmq 365
This script will:
-
Generate the new TLS certificates
-
Update the RabbitMQ helm chart to use the new certificates
-
Update the
keysafe5-backend
helm chart to use the new certificates -
Output a new
agent-config.tar.gz
that contains the agent configuration file and TLS certificates for authentication to RabbitMQ
The external address that will be put into the certificate, and the configuration file, will be the IP address of the Ingress service provided by the Kubernetes server.
If you wish to use a different IP address or DNS name, this can be passed in with the -r
parameter.
For an external CA, the following command will apply the keys and certificates from the directory mycerts
updateinternalcerts rabbitmq mycerts
If using an external CA, the following suggestions should improve the chances of success:
* Use 4k RSA keys
* Set the Key Usage to Digital Signature, Non Repudiation, Key Encipherment
* For the server certificate, set the Extended Key Usage to TLS Web Server Authentication
* Ensure the server certificate’s Subject Alternative Name includes the IP address and DNS names that will be used to connect to RabbitMQ from external clients, along with the DNS entries rabbitmq
, rabbit-chart-rabbitmq-headless
, rabbit-chart-rabbitmq.rabbitns.svc.cluster.local
, .rabbit-chart-rabbitmq-headless.rabbitns.svc.cluster.local
, and rabbit-chart.rabbitns.svc.cluster.local
.
* For the client certificate, set the Extended Key Usage to TLS Web Client Authentication
.
* Ensure the client certificate’s Subject Alternative Name starts with the DNS value of ks5
(the KeySafe 5 Backend’s RabbitMQ username), followed by keysafe5-backend-ks5-headless
, keysafe5-backend-ks5.nshieldkeysafe5.svc.cluster.local
, .keysafe5-backend-ks5-headless.nshieldkeysafe5.svc.cluster.local
, and keysafe5-backend.nshieldkeysafe5.svc.cluster.local
.
You will need to update your client machines with a KeySafe 5 agent installed to use the updated config and restart the agent so that the new configuration is applied.
sudo tar xf agent-config.tar.gz -C /opt/nfast/keysafe5/
/opt/nfast/scripts/init.d/keysafe5-agent restart
Authentication
If you chose to install the demo deployment without authentication you should enable authentication for accessing the KeySafe 5 REST API and User Interface.
For how to configure authentication for the KeySafe 5 REST APIs see Helm Chart Installation: helm-keysafe5-istio authentication
in the Installation Guide.
To update the keysafe5-istio
Helm chart installed by the demo deployment, set the following values in keysafe5-istio-values.yaml
.
-
requireAuthn=true
-
issuer[0].authIssuer="https://foobar.auth0.com"
-
issuer[0].authJWKsURI="https://www.googleapis.com/oauth2/v1/certs"
-
issuer[0].authAudiences[0]="https://keysafe5.location"
Then run helm upgrade
.
helm upgrade --install keysafe5-istio \
--namespace=nshieldkeysafe5 \
--values keysafe5-istio-values.yaml \
--wait --timeout 1m \
helm-charts/nshield-keysafe5-istio-1.4.0.tgz
To update the keysafe5-ui
Helm chart installed by the demo deployment, set the following values in keysafe5-ui-values.yaml
:
-
authMethod=oidc
Untar the chart and copy your OIDC provider config file (OIDCProviders.json
) into the config directory:
For more details on how to populate OIDCProviders.json
and how to configure authentication for the KeySafe 5 User Interface see Helm Chart Installation: Configure UI authentication
in the Installation Guide.
tar -xf helm-charts/nshield-keysafe5-ui-1.4.0.tgz -C helm-charts
cp my-oidc-provider-config.json helm-charts/nshield-keysafe5-ui/config/OIDCProviders.json
Then run helm upgrade
:
helm upgrade --install keysafe5-ui \
--namespace=nshieldkeysafe5 \
--values keysafe5-ui-values.yaml \
--wait --timeout 3m \
helm-charts/nshield-keysafe5-ui
K3s
If not using your own Kubernetes cluster, the deploy.sh
script will create one using K3s.
To harden this K3s install follow the official documentation at K3s Hardening Guide.
The deploy.sh script installs K3s with traefik and metrics-server explicitly disabled.
|