Optional Tasks

Access Nok Nok Servers from a Mobile Device

Use a mobile device to register and authenticate access to your Nok Nok Servers if:

Your system doesn't have support for platform authenticators, such as Touch ID or Windows Hello, and you don't have a USB security key.
You have an iOS or Android application that uses the Nok Nok App SDK for registration and authentication. Alternatively, you can use the Nok Nok Passport app, available in either the Google Play Store or Apple App Store.
You have a web application that allows users to employ an out-of-band (OOB) authentication method with their mobile devices.

Follow these instructions to use a Squid container as a network proxy to allow a mobile device to access your Nok Nok Servers. Using these instructions, you first run Tutorial Web App in a browser on your system. It displays a QR code so you can register an authenticator on your mobile device. Then, use your mobile app or Nok Nok’s Passport app to scan the QR code and register an authenticator on the device. Use that authenticator in the future to access the Nok Nok Servers.

Note that you need proxy access if the Servers are installed locally.

1. The mobile device and the host system must be on the same WiFi network. Use the host system WiFi IP address as the Mobile phone WiFi network proxy host address. Set the mobile device WiFi network proxy port to 3128 (Squid port). Make sure that the host system firewall, if enabled, allows TCP access to the proxy port 3128.

2. Run the following commands to start the Squid proxy:

cd $NN_CDT_HOME/nns3
docker compose up -d squid-server

3. Make sure the following DNS names are used for the Nok Nok servers. For example, add these entries into the /etc/hosts file:

<wifi-ip-address> <subdomain-prefix>-admin.noknokeval.com
<wifi-ip-address> <subdomain-prefix>-api.noknokeval.com
<wifi-ip-address> <subdomain-prefix>-tutorial.noknokeval.com
<wifi-ip-address> <subdomain-prefix>-optional-webapps.noknokeval.com

The final entry is only required if you set OPTIONAL_WEBAPPS_ENABLED=true in your deployment profile.

4. Open a browser on your system and enter the following URL to bring up Tutorial Web App:

https://<subdomain-prefix>-tutorial.noknokeval.com/gwtutorial

5. Tutorial App asks if you want to register a passwordless authenticator. Click No Thanks.

6. You are signed in now. You should see the Register page Click Setup New Device.

7. Tutorial Web App displays a QR Code. Bring up your mobile app or the Passport App on your mobile device and scan the QR code. The Passport App prompts you to select a FIDO authenticator to use. If you select Touch ID or Fingerprint authenticator, the Passport App prompts you to enter your fingerprint.

8. The Register page shows the method you just registered. Log out of Tutorial App.

9. The next time you sign in to Tutorial App, click Sign in with Mobile Device.

10. If you are using the Passport App, Tutorial App sends a push notification to your mobile device that you can tap and then authenticate. If you don’t get that push notification, click Use QR Code and scan the code with Passport.

Uninstall the Nok Nok S3 Suite

This sample script removes the deployment.

#!/bin/bash -x
#
cd ${NN_CDT_HOME} || exit 1
(cd tutorial || exit 1; docker compose down)
(cd nns3 || exit 1; docker compose down)
# Remove the database if it was provisioned by CDT
bin/undeploy_db.sh
# The above script does not remove the Docker volume used for
# data storage. You need to explicitly remove the volumes.
docker volume rm -f postgres_nnauthdb_dv
# or
docker volume rm -f mysql_nnauthdb_dv
docker image ls --format='{{.Repository}}:{{.Tag}}' \
  | grep noknok | xargs docker image rm
rm -rf $NN_CDT_HOME
rm -rf ${HOME}/.nn

Change TLS Certificate

If you use a wildcard domain other than noknokeval.com, you need to generate the corresponding TLS artifacts and place them into the $HOME/.nn/cdt/tls directory. Follow these instructions after unboxing the CDT package and before building the container images.

1. Generate the necessary tls.pkcs12, tls.crt and tls.key files from my_wildcard_cert.pfx.

If you are using OpenSSL version 3.x, you may need to add the -legacy option to the first 2 commands below.

openssl pkcs12 -in my_wildcard_cert.pfx -nocerts -nodes -out tls.key
openssl pkcs12 -in my_wildcard_cert.pfx -nodes -nokeys -out tls.crt
openssl pkcs12 -export -in tls.crt -inkey tls.key \
   -name <some-name> -out tls.pkcs12

2. Place the following files into the $HOME/.nn/cdt/tls directory.

tls.pkcs12
tls.password (only required if the TLS certificate file, tls.pkcs12, is password protected)
tls.crt
tls.key

Use these filenames to replace the noknokeval.com certificate.

Now you are ready to build the container images.

Use Your Own Images

Some customers may need to use a different guest operating system, a different Java Runtime Environment, or a different Tomcat image. For these cases, you build your own images and the Nok Nok CDT deploys them.

Before customizing your build by using your own images, make sure that your standard, local deployment of the Nok Nok Cloud Deployment Toolkit runs correctly. This means that you can access the Nok Nok Server through Nok Nok's Command Line Interface (CLI) and the Nok Nok Admin Console. Also verify that the Nok Nok Server can authenticate users within the Tutorial WebApp.

These images are layered, so use only one of the following 2 options:

Option 1. Bring your own base image and use the JRE and the Tomcat images provided by Nok Nok.

Run the following command from the CDT Host System terminal:

#BYO Base Image - Use Nok Nok-provided JRE and Tomcat images.
cd ${NN_CDT_HOME}
export OS_BASE_IMG=<base-image-repository-with-tag>
bin/build_images.sh

Option 2. Bring your own Tomcat image which must include the JRE.

Make sure that the versions of your Java JRE and Tomcat included in your base image meet the Nok Nok S3 Suite requirements. See the Installation Requirements in the Nok Nok Server Release Notes. In addition, your base image must set the NN_JAVA_HOME and NN_CATALINA_HOME environment variables to point to where JRE and Tomcat are installed in your image.

The commands shown here expect these environment variables to be set up correctly.

#BYO Tomcat image (must include JRE)
cd ${NN_CDT_HOME}
export TOMCAT_BASE_IMG=<base-image-repository-with-tag>
build/auth_server/build.sh
build/api_server/build.sh
build/admin_server/build.sh
build/dbinit/build.sh
build/cli/build.sh
build/tutorial_server/build.sh

If your deployment profile set OPTIONAL_WEBAPPS_ENABLED to true, run this additional command:

build/optional_webapps/build.sh