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

Internal Certificates

The Manual Installation 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 MongoDB.

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]... DAYS
         ./updateinternalcerts.sh [OPTION]... DIRECTORY

  Update the internal server and client TLS credentials for a deployment created
  by deploy.sh.

  This can update certificates and keys for the Agent Communications
  Server as set up by deploy.sh, along with the certificates and
  keys for the KeySafe 5 Backend services.  The Agent Communications Server has
  a single key and certificate.  The KeySafe 5 backend services
  also have a single key and client certificate for connecting to the Agent
  Communications Server.

  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 you update the certificates for the Agent Communications Server, 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 127.0.0.1 for the Agent Communications Server.

  The Agent Communications Server 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.
                              However you can override these to use a different
                              namespace for all the servers.
                              If that is the case, then use this option.
  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.

  -a, --agentcomms=ADDRESS    The external address for the Agent Communications
                              Server

  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.
  agentcomms.key              The key to be used by the Agent Communications
                              Server
  agentcomms.crt              And its certificate
  ks5agentcomms.key           The key to be used by ks5
  ks5agentcomms.crt           And its certificate

  Internal CA examples

  Refresh certificates for the next 30 days, and set a DNS
  entry for the Agent Communications Server
    To add single entry
    ./updateinternalcerts.sh -a keysafe5.example.com 30
    To add multiple DNS/IP entry
    ./updateinternalcerts.sh -a 1.2.3.4 -a 5.6.7.4 -a keysafe5.example.com agentcomms 30

  External CA examples

  Refresh certificates in a specific namespace
    ./updateinternalcerts.sh -n kansas all-certs-dir

The updateinternalcerts.sh script must be run from a directory containing the KeySafe 5 Helm charts (for example, from the root directory of the untarred KeySafe 5 package). If the CA, created when the original deploy script was run, is not available then a new one will be created and used.

If both certificates have expired when running updateinternalcerts.sh, updating the certificates of only one service may return an error. In this case re-running updateinternalcerts.sh without specifying any server will update both server certificates at once, and will usually solve the problem.

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.

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.7.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 WebUI authentication in the Installation Guide.

tar -xf helm-charts/nshield-keysafe5-ui-1.7.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

Rate Limiting

Rate limiting in KeySafe 5 can be configured using Envoy Proxy Rate Limiting. To enable this in the demo deployment, the external envoyproxy/ratelimit image and an external redis image must be provided.

To update the keysafe5-istio Helm chart to enable rate limiting, set the following values in keysafe5-values-istio.yaml

  • rateLimit.enabled=true

  • rateLimit.redis.image=redis:version

  • rateLimit.rateLimit.image=envoyproxy/ratelimit:version

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

For additional customization see the see the README.md in the root directory of the Helm chart.