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.
-
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 |
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
sw-mgmt
andhsm-mgmt
. -
Database connection configuration.
-
AMQP connection configuration.
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:
$ 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 amqp.URL="rabbit-chart-rabbitmq-0.rabbit-chart-rabbitmq-headless.rabbitns.svc.cluster.local:5671" \
--set amqp.auth.type=pwd \
--set amqp.auth.existingSecret=my-amqp-credentials-secret \
--set amqp.tls.enabled=true \
--set amqp.tls.existingSecret=my-amqp-tls-secret \
--set logging.level=info \
--set logging.format=json \
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.1.1.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.1.1.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 |
---|---|
|
Identifies the issuer that issued the JWT. A JWT with different iss claim will be rejected. |
|
Identifies the list of JWT audiences that are allowed access. A JWT containing any of these audiences will be accepted. |
|
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. |
|
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 |
28080 |
/mgmt/v1/worlds |
helm-keysafe5-ui
exposes a Kubernetes Service called keysafe5-ui-svc
on CluserIP port 8080
for accessing the graphical user interface of Keysafe 5.