Getting Started

The Nok Nok CDT includes a number of options. Before you start deployment, decide:

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

• 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 Nok Nok S3 servers. The default TLS certificate included in the CDT package is only appropriate for development purposes.

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

Prerequisites

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

A Docker build environment is required to build the Docker images, and a Docker runtime environment is required to run the Docker images. Do one of the following:

• MacOS: Install Rancher Desktop or Docker Desktop.

• Linux instance: Install Docker 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 Nok Nok Servers on RedHat UBI 9. You can use your own custom OS image with the CDT, as described in Use Your Own Images.

Limitations on Local Deployment

The Nok Nok S3 Suite 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. This page specifies when and where to edit the configuration files. Do not modify scripts. Make sure that your Docker environment is installed and running before you begin.

1. Download the Nok Nok CDT .tgz file.

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.

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>

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

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

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.

Run the following commands from the CDT Host System terminal to fetch the jar dependencies:

cd ${NN_CDT_HOME}
bin/fetch_reqs.sh

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

4. If you create any custom  plugin for your deployment, 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.

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 setting up an evaluation or a development deployment.

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

The CDT works out of the box for most deployments. First use the default deployment profile above to get a Nok Nok 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 Nok Nok 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 Nok Nok Admin Console to configure the Nok Nok S3 Suite for your Federation integration. For specific instructions, see Utility Apps.

If you are using a custom wildcard domain with your own TLS certificate, 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 allows the Nok Nok 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 FIDO authentication is not possible, so set this variable to false. If TUTORIAL_HTTPS_STANDARD_PORT=false then the Nok Nok Tutorial Web App is accessible on port 7443.

Build the Container Images

The build-images.sh command uses the Docker build command to build all the container images required to deploy the Nok Nok 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, follow the instructions in Use Your Own Images to build the container images.

Step 1. (Optional) Customize the Image Tag

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.4.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_compose.sh