Helm Chart Installation

To install the KeySafe 5 REST APIs you must install the helm-keysafe5-backend chart.

To install the KeySafe 5 graphical user interface you must also install the helm-keysafe5-ui chart.

To expose these services externally to the Kubernetes cluster, see Configure external access to KeySafe 5.

If you are upgrading an existing KeySafe 5 install, see Helm Chart Upgrade.

Helm

Helm is a package manager for Kubernetes.

As with kubectl you can apply a namespace to the Kubernetes resources created by a Helm chart by specifying --namespace my-namespace when using helm.

To install the chart with the release name my-release:

helm install my-release helm-keysafe5-backend/

List all releases using helm list.

To upgrade or modify the existing my-release deployment, configure the chart parameters and then run:

helm upgrade --install my-release helm-keysafe5-backend/

To uninstall or delete the my-release deployment:

helm delete my-release

helm-keysafe5-backend

The keysafe5-backend Helm chart deploys Kubernetes Services for the KeySafe 5 REST APIs.

codesafe-mgmt (nShield CodeSafe Management Service API)
hsm-mgmt (nShield HSM Management Service API)
sw-mgmt (nShield Security World Management Service API)

This Helm chart installs the KeySafe 5 services into a Kubernetes cluster but does not configure external access to the services. See Configure external access to KeySafe 5.

Kubernetes Secrets

The helm-keysafe5-backend Helm chart expects to be provided with pre-existing Kubernetes Secrets for the Database and AMQP connections.

For more information, refer to Kubernetes Secrets.

Purpose	Description	Secret Type
MongoDB SCRAM Auth	The username and password pairing used to authenticate with the MongoDB server	kubernetes.io/basic-auth
MongoDB TLS Certificates	TLS certificates used to connect to the MongoDB server. Can also be used as authentication if X509 auth is enabled	Opaque
AMQP SCRAM Auth	The username and password pairing used to authenticate with the AMQP server	kubernetes.io/basic-auth
AMQP TLS Certificates	TLS certificates used to connect to the AMQP server	Opaque

Purpose

Description

Secret Type

MongoDB SCRAM Auth

The username and password pairing used to authenticate with the MongoDB server

kubernetes.io/basic-auth

MongoDB TLS Certificates

TLS certificates used to connect to the MongoDB server. Can also be used as authentication if X509 auth is enabled

Opaque

AMQP SCRAM Auth

The username and password pairing used to authenticate with the AMQP server

kubernetes.io/basic-auth

AMQP TLS Certificates

TLS certificates used to connect to the AMQP server

Opaque

Because TLS secrets have the Opaque type, the filenames they are created with are critical. Entrust expects the following:

CA certificate to be named ca.crt.
TLS certificate to be named tls.crt.
TLS key file to be named tls.key.

Your 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.

Configuration

To deploy the application, configure the chart with:

The Docker images to use for codesafe-mgmt, hsm-mgmt and sw-mgmt.
Database connection configuration.
Message Bus connection configuration.
A reference to the Persistent Volume Claim, in the same Kubernetes namespace, to use for large object storage.
A reference to the KeyControl Compliance Manager’s certificate authority

For further details on the configurable values of the Helm chart, see the README.md in the root directory of the Helm chart. For example, you may wish to:

Increase or decrease the verbosity of the logging in the backend services.
Change the period of time before a resource liveness health check is marked as failing. For example, if you have decreased the rate at which KeySafe 5 agents report to the central platform, you will want to increase the health.livenessFailurePeriod value.

To use the KeyControl Compliance Manager, you must add its certificate authority file path to the config map.

kubectl -n nshieldkeysafe5 create configmap compliance-ca --from-file=ca.pem=/path/to/compliance-ca.pem

An example install:

helm install my-release \
  --create-namespace --namespace nshieldkeysafe5 \
  --set database.type=mongo \
  --set database.mongo.hosts="mongo-chart-mongodb-0.mongo-chart-mongodb-headless.mongons.svc.cluster.local:27017,mongo-chart-mongodb-1.mongo-chart-mongodb-headless.mongons.svc.cluster.local:27017" \
  --set database.mongo.replicaSet=rs0 \
  --set database.mongo.auth.type=pwd \
  --set database.mongo.auth.existingSecret=my-mongo-credentials-secret \
  --set database.mongo.tls.enabled=true \
  --set database.mongo.tls.existingSecret=my-mongo-tls-secret \
  --set messageBus.URL="rabbit-chart-rabbitmq-0.rabbit-chart-rabbitmq-headless.rabbitns.svc.cluster.local:5671" \
  --set messageBus.auth.type=pwd \
  --set messageBus.auth.existingSecret=my-amqp-credentials-secret \
  --set messageBus.tls.enabled=true \
  --set messageBus.tls.existingSecret=my-amqp-tls-secret \
  --set messageBus.type="amqp"
  --set objectStore.pvc=data-nshield-keysafe5 \
  --set logging.level=info \
  --set logging.format=json \
  --set integrations.kcm.caConfigMap=compliance-ca \
 helm-keysafe5-backend/

helm-keysafe5-ui

The keysafe5-ui Helm chart deploys a Kubernetes Service for the KeySafe 5 Graphical User Interface.

The chart deploys the web front-end of KeySafe 5. For the UI to be usable it must point to a deployed KeySafe 5 back-end services endpoint (as installed by helm-keysafe5-backend).

This Helm chart installs the KeySafe 5 UI into a Kubernetes cluster, but does not configure external access to the service. (See Configure external access to KeySafe 5.)

Configuration

To deploy the application, configure the chart with:

The Docker image to use for the ui container.
OIDC Identity Provider config, if Authentication is enabled.
The location of the KeySafe 5 back-end services API that this UI displays information for.

For further details on the configurable values of the Helm chart, see the README.md in the root directory of the Helm chart.

An example install:

# Untar the chart and copy your OIDC provider config file into the config directory
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

# Install the chart
helm install keysafe5-ui \
  --create-namespace --namespace nshieldkeysafe5 \
  --set svcEndpoint="https://XXX.XXX.XXX.XXX" \
  --set authMethod=oidc \
  --wait --timeout 10m \
helm-charts/nshield-keysafe5-ui

Because the OIDC Provider configuration is volume mapped into the Kubernetes application, you must untar the packaged Helm chart so that you can copy in the OIDCProviders.json file to the correct location before installing the chart.

Configure UI authentication

If authMethod is set to oidc then you must provide an OIDC configuration file detailing the accepted Identity Providers.

Copy the OIDC configuration file to config/OIDCProviders.json in the root directory of the Helm chart before installing the Helm chart. This file is a JSON document. You can find an example file at config/OIDCProviders.json.example.

The configuration document is a JSON list of individual provider configurations.

An example of provider configuration:

{
    "name":"Example Provider",
    "authority": "https://example-auth-provider.com/auth/auth",
    "client_id":"8acc1449-7275-4524-b25f-4a60ddddfe8d",
    "redirect_uri": "https://example-keysafe5.com/callback",
    "response_type": "code",
    "scope": "openid",
    "post_logout_redirect_uri": "https://example-keysafe5.com/",
    "issuer": "https://example-auth-provider.com/auth",
    "authorization_endpoint": "https://example-auth-provider.com/auth/callback/authorize",
    "token_endpoint": "https://example-auth-provider.com/auth/token",
    "jwks_uri": "https://example-auth-provider.com/auth/keys",
    "end_session_endpoint": "https://example-auth-provider.com/auth/logout",
    "userinfo_endpoint": "https://example-auth-provider.com/auth/userinfo",
    "iconSVG" : "login.svg"
}

To display a custom icon for the provider in the user interface, copy an SVG-format image to the config directory and reference the file name under the key iconSVG in the provider configuration.

Configure external access to KeySafe 5

To enable external access to the services installed by helm-keysafe5-backend and helm-keysafe5-ui, you need to configure a Kubernetes Ingress Gateway to route requests to the appropriate Kubernetes Services.

If you use Istio, you can use the helm-keysafe5-istio Helm chart to configure an existing Istio Ingress Gateway. Alternatively, you can configure your own Ingress Gateway. (See Configure a custom ingress provider.)

helm-keysafe5-istio

The keysafe5-istio Helm chart creates an Istio Gateway and VirtualService for the KeySafe 5 back-end services and user interface to be accessible externally from the Kubernetes cluster.

The chart:

Routes HTTP requests to the KeySafe 5 application running in the same Kubernetes cluster.
Authenticates requests, if authentication is enabled (default) and an Identity Provider (IdP) is configured.
Applies CORS policy to requests to limit Cross-Origin Resource Sharing.
Applies security related HTTP Headers to responses including automatically applying the Content-Security-Policy header to help reduce Cross Site Scripting (XSS) risks.
Limits TLS protocol used to TLS v1.2 and higher.
Limits ciphers supported by the gateway.

Configure helm-keysafe5-istio

For further details of the configurable values of the Helm chart, see the README.md in the root directory of the Helm chart.

An example install:

helm install keysafe5-istio \
  --create-namespace --namespace=nshieldkeysafe5 \
  --set requireAuthn=true \
  --set httpsEnabled=true \
  --set portNumber=443 \
  --set issuer[0].authIssuer="https://foobar.auth0.com" \
  --set issuer[0].authJWKsURI="https://www.googleapis.com/oauth2/v1/certs" \
  --set issuer[0].authAudiences[0]="https://keysafe5.location" \
  --wait --timeout 1m \
helm-charts/nshield-keysafe5-istio-1.4.0.tgz

helm-keysafe5-istio port number

If the port number changes to something other than 443 or 80, you need to open a port on the Istio Ingress Gateway. You can do this using your own istioctl install manifest. For more information, refer to https://istio.io/latest/docs/setup/install/istioctl/.

helm-keysafe5-istio authentication

Authentication can be provided by any OpenID Connect Provider, such as Entrust Identity As A Service.

If requireAuthn is true, then at least one authIssuer must be configured.

An example configuration:

issuers:
  - authIssuer: 'https://foobar.auth0.com'
    authJWKsURI: 'https://www.googleapis.com/oauth2/v1/certs'
    authJWKs: ''
    authAudiences:
    - 'https://keysafe5.location'

For each authIssuer, authAudiences and one of authJWKsURI or authJWKs must be specified.

Key Description

Key	Description
`authIssuer`	Identifies the issuer that issued the JWT. A JWT with different iss claim will be rejected.
`authAudiences`	Identifies the list of JWT audiences that are allowed access. A JWT containing any of these audiences will be accepted.
`authJWKsURI`	URL of the provider’s public key set to validate signature of the JWT. For more information, refer to https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.
`authJWKs`	JSON Web Key Set of public keys to validate signature of the JWT. For more information, refer to https://auth0.com/docs/jwks.

authIssuer

Identifies the issuer that issued the JWT. A JWT with different iss claim will be rejected.

authAudiences

Identifies the list of JWT audiences that are allowed access. A JWT containing any of these audiences will be accepted.

authJWKsURI

URL of the provider’s public key set to validate signature of the JWT. For more information, refer to https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

authJWKs

JSON Web Key Set of public keys to validate signature of the JWT. For more information, refer to https://auth0.com/docs/jwks.

For additional information, refer to https://istio.io/latest/docs/reference/config/security/jwt/#JWTRule.

Once authenticated, a user has full access to view and manage the HSM and Security World resources accessible from the platform. No authorization policy is applied to requests.

Enable HTTPS for helm-keysafe5-istio

Configuring a TLS certificate for the Istio Gateway requires creating a Kubernetes secret.

To create a Kubernetes secret from an existing TLS private key and certificate:

You must create the Kubernetes Secret in the same namespace as the Istio Ingress Gateway.

kubectl --namespace istio-system create secret tls keysafe5-server-credential \
  --cert=path/to/cert/file \
  --key=path/to/key/file

Configure a custom ingress provider

If you do not want to use Istio, you can configure your own Kubernetes Ingress.

If you configure your own Ingress to the application, then it is your responsibility to configure routing to the services and any authentication or authorization to access the services.

Each part of the KeySafe 5 application is exposed as a Kubernetes Service.

helm-keysafe5-backend exposes the following Kubernetes Services for serving requests to the RESTful APIs:

ClusterIP Port	API endpoints
18080	/mgmt/v1/hsms /mgmt/v1/hosts /mgmt/v1/pools /mgmt/v1/feature-certificates
18081	/mgmt/v1/worlds
18082	/codesafe/v1

ClusterIP Port

API endpoints

18080

/mgmt/v1/hsms

/mgmt/v1/hosts

/mgmt/v1/pools

/mgmt/v1/feature-certificates

18081

/mgmt/v1/worlds

18082

/codesafe/v1

helm-keysafe5-ui exposes a Kubernetes Service called keysafe5-ui-svc on ClusterIP port 8080 for accessing the graphical user interface of KeySafe 5.