Getting Started

The Cloud Deployment Toolkit includes a number of options. Before you start deployment, decide:

• if your deployment will use Docker Compose or Kubernetes. This document is for Kubernetes. If you are deploying on Docker Compose, refer to Use Docker.

• if you will use the CDT to provision the operational database or you will bring your own database (BYODb).

  • if you are using the CDT to provision the database, will it be PostgreSQL or MySQL? The default is PostgreSQL.

  • if you are bringing your own database, will it be PostgreSQL, MySQL, Oracle or CockroachDB?

• what TLS certificate you will use to protect access to the Digipass S3 servers. The default TLS certificate included in the CDT package is only appropriate for development purposes.

• if you need your Digipass S3 deployment to integrate with a Federation Server.

Prerequisites

See the Cloud Deployment Toolkit Release Notes for Installation Requirements. In addition, the CDT requires the following system utilities: bash, sed, find, curl.

When deploying on Kubernetes, a Docker build environment is required to build the Docker images, and a Docker runtime environment is required to run the Docker images. To meet these requirements, do one of the following:

• MacOS: Install Rancher Desktop on MacOS or on Docker Desktop.

• Linux instance: Install Docker Community Edition (CE) or Docker Desktop.

Verify that you can use the Docker command line to pull and run images before proceeding.

The Cloud Deployment Toolkit deploys the Digipass S3 Servers on RedHat UBI 9. You can use your own custom OS image with the CDT, as described in Use Your Own Images.

Depending on your operating system, install these additional tools:

• Linux Instance: Install Minikube and Helm.

• MacOS: For a MacOS development environment, follow these instructions to turn off the built-in Ingress controller and install the Nginx Ingress Controller.

  1. Click the Rancher Desktop Icon on the menu bar and select Open Preferences Dialog.

  2. Switch to the Kubernetes tab.

  3. Check Enable Kubernetes.

  4. Uncheck Enable Traefik and click Apply.

  5. Run the following commands from the CDT Host System terminal:

helm upgrade --install ingress-nginx ingress-nginx \
  --repo https://kubernetes.github.io/ingress-nginx \
  --namespace ingress-nginx --create-namespace
kubectl get pods --namespace=ingress-nginx
[bpandkar@qa-bhag nn_cdt]$ kubectl get pods --namespace=ingress-nginx
NAME                                        READY   STATUS      RESTARTS       AGE
ingress-nginx-admission-create-kj64b        0/1     Completed   0              114d
ingress-nginx-admission-patch-2kjcx         0/1     Completed   0              114d
ingress-nginx-controller-7c6974c4d8-pnb5p   1/1     Running     10 (20m ago)   114d

For more information, see Rancher Desktop documentation.

Note: Kubernetes Nginx Ingress is retired, but for convenience you can use Nginx Ingress for development deployments only. For production deployments, use a vendor-specific Kubernetes provider API gateway/load balancer. See Kubernetes documentation for details.

The CDT’s values.yaml file enables Nginx Ingress by default. Use this default configuration for development deployments only. For production deployments, edit the ingress: section at the end of the file nn_cdt/helm/charts/nns3/values.yaml and set enabled: to false.

Limitations on Local Deployment

Digipass S3 Authentication Software supports FIDO2 authentication, Apple App Attest, and Google Play Integrity for native iOS and Android mobile apps. These features require Google and Apple to access your deployment and perform necessary security checks. When your Server is deployed using the CDT on a local computer, your security infrastructure typically makes it impossible for Google and Apple to access your deployment to perform these checks. For this reason, you will not be able to test FIDO2 authentication, Apple App Attest, and Google Play Integrity with a native mobile app when the CDT is deployed on a local computer. However, you can test FIDO2 authentication with a browser-based app when the CDT is deployed on a local computer.

Prepare for Deployment

In this section you download and unbox the CDT package, which contains scripts and configuration files. These instructions specify when and where to edit the configuration files. Do not modify the scripts. Make sure that all prerequisites are installed and running before you begin.

1. Download the Digipass S3 CDT .tgz file.

2. Optional. The product contains a SHA‑256 checksum that allows you to verify that the downloaded package is complete, unaltered, and safe to use. To take advantage of this checksum feature, download the checksum file nn_cdt_*.tgz.sha256sum.txt. Place the .tgz file and the .txt file into the same directory and calculate the hash for the package using the following command:

sha256sum -c nn_cdt_9.5.0-99.tgz.sha256sum.txt

If the result shows “OK” then the file is valid.

3.  The next step depends on whether your .tgz file was automatically uncompressed.

a. If the .tgz file was not automatically uncompressed during download:

Run the following commands on the CDT host system terminal to expand the archive:

cd $HOME
tar xzf <path-to-CDT-tgz-archive-file>

Substitute the location of the nn_cdt_<build_number>.tgz file for <path-to-CDT-tgz-archive-file> in the command above.

b. If the .tgz file was automatically uncompressed during download:

Run the following commands on the CDT host system terminal to extract the  nn_cdt_<build_number>.tar  file:

cd $HOME
tar -xvf <path-to-CDT-archive-folder.tar>

Substitute the location of the nn_cdt_<build_number>.tgz file for <path-to-CDT-tgz-archive-file> in the command above.

4. The following commands define an environment variable and unbox the CDT:

export NN_CDT_HOME=$HOME/nn_cdt
cd $NN_CDT_HOME
bin/unbox.sh

The unbox command creates a CDT working directory at ${HOME}/.nn/cdt. Include the export command above in your $HOME/.bashrc file to set the NN_CDT_HOME environment variable in subsequent terminal sessions.

5. Download third-party libraries. The CDT package does not bundle any Java JDBC jar files needed to communicate with database instances. Instead, it provides a script to download them from the maven public repository. Run the following commands on the CDT Host System terminal to fetch the jar dependencies:

cd ${NN_CDT_HOME}
bin/fetch_reqs.sh
The fetch_reqs.sh command downloads the JDBC jars listed in the ${NN_CDT_HOME}/requirements.txt file. Comment out unneeded jar filenames in the requirements.txt file before running fetch_reqs.sh.

The jars are downloaded into the CDT Working Directory at ${HOME}/.nn/cdt/thirdparty/jars.

6. If you create any custom plugin for your deployment, except the Crypto or Secrets plugin, copy the .jar file that contains the implementation for your plugin into the directory indicated below. The image build process picks it up from the directory and includes it in the container images.

Note that these instructions don’t apply to deployments with Crypto or Secrets plugins. For instructions on how to enable and configure a custom Session Plugin or External Authentication Plugin, see Create a plugin.

Edit Your Deployment Profile

By default, the CDT deployment uses a Postgres database for managing operational data. The CDT also includes a TLS certificate with the *.noknokeval.com wildcard domain name. These and other settings in the CDT deployment profile work fine for most customers.

Default Deployment Profile

This is stored at $HOME/.nn/cdt/deployment.profile:
DB_TYPE=postgres
OPTIONAL_WEBAPPS_ENABLED=false
SUB_DOMAIN_PREFIX=nns3
WILDCARD_DOMAIN=noknokeval.com
TUTORIAL_HTTPS_STANDARD_PORT=true
NAMESPACE=nns3

Important Note: The CDT works out of the box for most deployments. First use the default deployment profile to get a Digipass S3 deployment up and running quickly. Then redeploy with any required modifications.

The CDT supports a DB_TYPE of postgres, mysql, oracle and cockroachdb.

To integrate a Federation Server with your Digipass S3 deployment, set OPTIONAL_WEBAPPS_ENABLED=true. This variable causes the nnlfedapp and nnlsignin applications to be deployed in an additional container. After deployment, use the Digipass S3 Admin Console to configure Digipass S3 Authentication Software for OIDC. For specific instructions, see Utility apps.

If you are using a custom wildcard domain with your own TLS certificate, you need to edit the WILDCARD_DOMAIN variable in the deployment profile and also follow the instructions in Change TLS certificate to update the tls.pkcs12 and tls.password files before continuing.

The property TUTORIAL_HTTPS_STANDARD_PORT=true allows the Digipass S3 Tutorial Web App to be accessed on Port 443. The value must be true in order for an end user to authenticate with FIDO2 when the Server is deployed in the cloud. If you are deploying on a local computer then the external access required for FIDO2 authentication is not possible, so set this variable to false. If TUTORIAL_HTTPS_STANDARD_PORT=false then the Digipass S3 Tutorial Web App is accessible on Port 7443.

Build the container images

The build_images.sh command uses Docker to build all the container images required to deploy the Digipass S3 Servers. These images include the Java JRE and Tomcat required to run the Servers. If a different base image with specific versions of JRE and Tomcat are required, you can follow the instructions in Use Your Own Images to build the container images.

Step 1. (Optional) Customize the image tsag

By default, the CDT images are built with the tag: <Auth server version>-<CDT version>. For example, the Auth Server image is named something like this: noknok/auth-server:9.3.0.321-5.345.

To further identify an image, you can optionally define a suffix, NN_IMG_TAG_SUFFIX, before executing the build script. The build script then appends your suffix to the image. Here is an example:

 export NN_IMG_TAG_SUFFIX="-acme-1.1"

The above example creates images with the specified suffix to the default tag: noknok/auth-server:9.3.0.321-5.345-acme-1.1

Step 2. Generate images

Run the following commands to generate images and confirm that the images are created:

cd ${NN_CDT_HOME}
bin/build_images.sh
docker image ls

Prepare configuration files

Run from CDT Host System terminal:

cd ${NN_CDT_HOME}
bin/prep_helm.sh

You can choose to modify the runtime configuration settings at this time. See Appendix C: Helm Chart Values YAML.

Setup private container registry

All of the container images created from the build process are available in the local Docker built-in registry. But this local Docker built-in registry is not integrated with Kubernetes. This section contains instructions that use CDT helper scripts to setup, host and run a private container registry that is dedicated to Digipass S3 Authentication Software. The CDT is pre-configured to work with this private registry.

Optional: It is possible to use a cloud-based registry such as those available on AWS/ECS, Google Cloud or other private registries. Refer to the Docker Push Command Reference for instructions on how to tag and push images. Note that the scripts provided in the Digipass S3 CDT package do not work in another Docker environment.

DNS configuration for private registry

The default FQDN for the private container registry is nns3-registry.noknokeval.com. Make sure that this fully qualified domain name (FQDN) resolves to the IP address of your CDT Host System.

1. Run the following commands from the CDT Host System terminal to get the IP address of the CDT Host System:

MacOS:

IFACE=$(route -n get default | grep 'interface:' | awk '{print $2;}')
HOST_IP_ADDRESS=$(ifconfig ${IFACE} | grep 'inet ' | awk '{print $2}')

Linux:

1.Find minikube VM IP Address by using below command.

minikube ssh "ping -c 1 host.minikube.internal"

[ec2-user@ip-172-30-1-93 nn_cdt]$ minikube ssh "ping -c 1 host.minikube.internal"
PING host.minikube.internal (192.168.49.1) 56(84) bytes of data.
64 bytes from host.minikube.internal (192.168.49.1): icmp_seq=1 ttl=64 time=0.063 ms

--- host.minikube.internal ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.063/0.063/0.063/0.000 ms

2. Using sudo privileges, add the following FQDN entry to the /etc/hosts file:

<MINIKUBE_VM_IP_ADDRESS> nns3-registry.noknokeval.com

If you modified the SUB_DOMAIN_PREFIX and/or the WILDCARD_DOMAIN in the CDT deployment profile , then modify the entry text as described below:

i) Replace nns3 with the value of your SUB_DOMAIN_PREFIX.

ii) Replace noknokeval.com with the value of your WILDCARD_DOMAIN.

3. Run the following command from the CDT Host System terminal:

minikube ssh "ping -q -c 1 <SUB_DOMAIN_PREFIX>-registry.noknokeval.com"

This establishes an SSH session to the minikube VM running inside the CDT Host System and runs ping. The ping should confirm that the minikube VM can connect to the private registry. If the ping succeeds, proceed to the next section “Start Private Registry”.

If the ping fails, you need to add the FQDN for the private registry  to the /etc/hosts file in the minikube VM. Using sudo privileges, follow the instructions below to add the same FQDN entry from Step 2. above to the /etc/hosts file in the minikube VM.

Go into the minikube VM:

minikube ssh

Edit  the /etc/hosts file and add an entry for the subdomain prefix. For example:

192.168.49.1 <SUB_DOMAIN_PREFIX>-registry.noknokeval.com

Save your changes and exit out of the minikube VM SSH session to return to the CDT Host System terminal session. Rerun the ping command from above to make sure that registry DNS resolution works from the Minikube VM.

Start private registry

Run the following commands from the CDT Host System terminal:

cd ${NN_CDT_HOME}
helm/bin/start_private_registry.sh -p

The -p option prints the private registry catalog, you should see the following response:

{"repositories":[]}

The repository list in the response from this freshly installed registry should be an empty list.

Push images to private registry

Run the following commands from the CDT Host System terminal.

cd ${NN_CDT_HOME}
helm/bin/push_images.sh

Create the Kubernetes namespace

Namespaces isolate a group of resources deployed in a Kubernetes cluster. The Digipass S3 Servers and other artifacts are scoped to a namespace. By default, the CDT deployment profile assigns nns3 as the namespace.

Run the following command from the CDT Host System terminal.

helm/bin/deploy_namespace.sh

Provision the Database Instance

The Digipass S3 CDT package includes helper scripts that provision an operational database instance to get your test or development deployment up and running quickly. The helper scripts provided are already configured to create and use either a Postgres or a MySQL database instance for your operational data. Instructions for Option 1 show how to use these scripts to provision your operational database.

If you want to deploy the CDT with an Oracle or a CockroachDB database, or if you already have a database that you would like to use, then you have to install the database instance yourself. We call this Option 2 "BYODb" for "Bring Your Own Database." The Digipass S3 CDT package does not contain scripts for this option, but instructions for Option 2 show how to configure the CDT to work with your database.

Option 1: Use the CDT to provision the database instance

All of the configurations required to provision a Postgres or MySQL database instance are pre-configured in the CDT helper scripts. This includes a default password for the database connection. The following instructions use the CDT to prepare and provision the database.

Step 1. Change the default password for the CDT-provisioned operational database instance:

A. In the ${HOME}/.nn/cdt/secrets/nn_secrets.yaml file, replace the authdb_user_password with a password for the nnauthdbuser. The CDT uses the nnauthdbuser account and the authdb_user_password to provision the operational database instance.

B. If you are using the (default) Postgres database, then in the ${NN_CDT_HOME}/helm/postgres/nnauthdb_secrets.yaml file, replace the password field with the password for nnauthdbuser. This password field must contain the same value as the authdb_user_password that you entered in Step A. above. In addition, replace the postgres-password with the password for the root Postgres account.

If you modified the CDT Deployment Profile to use MySQL or CockroachDB instead, then in the ${NN_CDT_HOME}/helm/mysql/nnauthdb_secrets.yaml file, replace the mysql-password field with the password for nnauthdbuser. This password field must contain the same value as the authdb_user_password that you entered in Step 1.A. above. In addition, replace the mysql-root-password with the password for the root MySQL account.

Step 2. Provision the database instance(s):

cd ${NN_CDT_HOME}
helm/bin/deploy_db.sh

Option 2: Bring your own database instance (BYODb)

The Digipass S3 CDT package supports a Postgres, MySQL, Oracle or CockroachDB database to store the operational data for your deployment. The following instructions tell how to configure the CDT scripts to work with your BYODb instance. Your database should already be installed, but it does not have to be on the same server as Digipass S3 Authentication Software.

When you create the database, specify UTF-8 character encoding so that Unicode characters can be stored. See Install on Linux.

Locate and edit the ${HOME}/.nn/cdt/helm/nns3_values.yaml file to set the database connection information. The following table lists the properties to change in the nn3s_values.yaml file.

For your reference, the default nns3_values.yaml file is included below. Make sure that your edits to this file strictly follow the YAML indentation and syntax conventions. You may need to uncomment the attributes as well as set the values.

authDB:
  type: "postgres"
  # host: nn-postgres-authdb
  # port: 5432
  # name: nnauthdb 
  # user: nnauthdbuser
  # jdbcJar: ""
  # jdbcDriverClass: ""
  # datasourceFactoryClass: ""
  # jdbcConnectionProperties: ""
  # jndiJDBCUrl: ""
  # secretsName: "nn-secrets"
  # passwordSecretKey: "authdb_user_password"

Locate and edit the ${HOME}/.nn/cdt/secrets/nn_secrets.yaml file to set the database connection information. Edit the YAML attribute in this table: