Step 1. Initialize the Database Instance
The fresh database instance from the previous section is now ready to be prepared for storing the Nok Nok S3 operational data. This preparation includes creating the necessary database tables and setting the required authentication policies and metadata.
Run the following commands from the CDT Host System terminal:
cd ${NN_CDT_HOME}
bin/init_db.shThe init_db.sh command uses the DB_TYPE and other parameters from the .env files that are stored in ${NN_CDT_HOME}/nns3.
Step 2. Deploy the Nok Nok S3 Servers
Now that the database is up and initialized, you are ready to deploy the Nok Nok S3 Servers. The Nok Nok S3 Server container images have support for runtime configuration using a set of environment variables that are documented in Appendix C. All of the runtime configuration variables have defaults that can be used as-is. If required, edit these values before running the following commands to start the server container instances.
Run the following commands from the CDT Host System terminal:
cd ${NN_CDT_HOME}/nns3
docker compose up -d auth-server api-server admin-serverOptional : Run the following command from the CDT Host System terminal if your deployment profile set OPTIONAL_WEBAPPS_ENABLED to true:
cd ${NN_CDT_HOME}/nns3
docker compose up -d optional-webappsStep 3. Configure DNS for Browser Access
Set the FQDNs for the Nok Nok API Server and the Admin Web Console to resolve to the correct IP addresses. The FQDN-to-IP address mapping for a development system is typically set in the system's hosts file. This section tells how to set this mapping.
The Nok Nok S3 Suite runs on the CDT Host System and the browser runs on the Browser Client System. These may be the same system or they may be different systems. For example, MacOS and Linux systems that have a browser can be both the Host System and the Client System. But when you are deploying on a cloud compute instance, there is no graphical user interface, so no browser is available. In this case, the CDT Host system is different from the Browser Client System.
This section includes instructions on how to configure the DNS when the CDT Host and Browser Client are the same system. It also includes instructions on how to configure the DNS when the CDT Host and the Browser Client are different systems. Follow the instructions that apply to your environment.
If you modified the subdomain prefix in your deployment profile, replace nns3 in the URLs with your subdomain prefix. If you modified the wildcard domain in your deployment profile, replace noknokeval.com in the FQDN with your wildcard domain.
Same System for CDT Host and Browser Client
In this case you are running MacOS or you are running a Linux system that has a GUI browser. From the CDT Host System terminal, use an editor to add the following entries to the /etc/hosts file:
127.0.0.1 nns3-api.noknokeval.com nns3-admin.noknokeval.com
127.0.0.1 nns3-tutorial.noknokeval.comnns3-tutorial.noknokeval.com is the Nok Nok Tutorial Web App Server that you use to verify the Nok Nok Server installation.
If you set OPTIONAL_WEBAPPS_ENABLED=true in your deployment profile, then add the following entry to the /etc/hosts file also:
127.0.0.1 nns3-optional-webapps.noknokeval.comDifferent Systems for CDT Host and Browser Client
If you deployed the CDT in a Linux cloud compute instance and you are using a browser on your laptop or desktop, place the public IP address of the cloud compute instance into the hosts file on the laptop or desktop that you are using as your Browser Client system. Get the public IP address of your CDT deployment from your cloud administrative console, or ask your cloud administrator for it.
Add the following entries to the /etc/hosts on a Linux system. Use sudo or administrative privileges:
<public-ip-address> nns3-api.noknokeval.com nns3-admin.noknokeval.com nns3-optional-webapps.noknokeval.com
<public-ip-address> nns3-tutorial.noknokeval.comReplace <public-ip-address> with the IP address of your cloud-compute instance.
If the CDT Host System has firewall protection turned on, you need to open the following ports: 443, 7443, 8443, and 9443.
Verify the Nok Nok Admin Web Console Access
Run the following command on a terminal in your desktop or laptop system to check that the DNS and firewall are set up correctly.
Run from the Browser Client System terminal:
curl -v https://nns3-admin.noknokeval.com:8443/nnladminStep 4. Create a Super Admin Account
Nok Nok provides two tools to administer your Nok Nok S3 Suite: the Command Line Interface (CLI) and the Admin Web Console. Both tools can configure the Authentication Server and API Server as well as perform operational tasks like registering administrative users. This section tells how to run the CLI on the CDT Host System to create a Super Admin user for the Admin Web Console. For more information about the CLI, refer to Run the Nok Nok Command Line Interface.
4.1. Generate a Registration Code for a Super Admin Account
To generate a registration code, run the following commands on the CDT Host System terminal:
cd ${NN_CDT_HOME}/nns3
./create_superadmin.shBy default, this command creates a user with user ID superadmin. You can override it
by specifying -u <user-id>. Here is sample output:
Registration code:
494985130c9e4ac2b00f474688923e59
Enter the above code on the Register an Account page of the Server Admin Console to
register the new user.Select and copy the registration code. You need to enter the code when registering the account in the Admin Web Console in section 4.2 below. The code is valid for two minutes. If you do not complete the registration in time, the code expires and cannot be reused. When this happens, use the ./regen_superadmin_key.sh script to regenerate the registration code for the super admin user.
4.2. Complete Registration
Use the Browser Client System to bring up the Nok Nok S3 Admin Web Console URL:
https://nns3-admin.noknokeval.com:8443/nnladminIf you modified the subdomain prefix in your deployment profile, replace nns3 in the above URL with your subdomain prefix. If you modified the wildcard domain in your deployment profile, replace noknokeval.com in the above URL with your wildcard domain.
The Nok Nok Admin Web Console is displayed. Click Sign in with Registration Code and enter the registration code you generated in 4.1. The Admin Web Console then displays the Set up authentication screen. Register a platform authenticator or a security key for future use.
If you don't have access to a platform authenticator or a security key, you need to register an out-of-band (OOB) authenticator on a mobile device. After setting up a squid proxy, click Register OOB Authenticator Using NokNok Passport App. On your mobile device, download and open the Nok Nok Passport App to scan the QR code displayed in the Admin Console.
Step 5. Deploy Tutorial Web Application
The Nok Nok CDT package includes a JavaScript-based Tutorial Web Application. This Tutorial Web Application can be used to verify that your CDT deployment is working properly. This application uses the Nok Nok JavaScript AppSDK to support many FIDO capabilities including Adaptive Registration, Adaptive Authentication, transaction confirmation, Secure Payment Confirmation (SPC), registration management, and passkeys.
5.1. Login to the Nok Nok Admin Console
Launch a browser on the Browser Client System and enter the URL for the Nok Nok Admin Console:
https://nns3-admin.noknokeval.com:8443/nnladminIf you modified the subdomain prefix in your deployment profile, replace nns3 in the above URL with your subdomain prefix. If you modified the wildcard domain in your deployment profile, replace noknokeval.com in the above URL with your wildcard domain.
Login to the Nok Nok Admin Web Console using the authentication method you registered in the previous step.
5.2. Configure the Server
Use the Nok Nok Admin Console to configure your Server to authenticate users of Tutorial Web App.
A. Switch to the default tenant if necessary. Navigate to Configuration > API Server and click Main under the Authentication API label. Click Add an origin and enter the Tutorial Web App's URL:
https://nns3-tutorial.noknokeval.com
If you modified the subdomain prefix in your deployment profile, replace nns3 in the above URL with your subdomain prefix. If you modified the wildcard domain in your deployment profile, replace noknokeval.com in the above URL with your wildcard domain.
B. In the same page, click Session Plugins to expand the panel and click on the Modify icon in the Actions column for the JWT Processor. The Plugin page shows the jwt_config object for the JWT Processor. Select and copy the contents of the jwt_config object. In the upper right corner of the Plugin page, click Back to API Server.
Switch to a CDT Host System terminal. Change the directory to ${NN_CDT_HOME}/tutorial. Edit the session_jwt_config.json file.
cd $NN_CDT_HOME/tutorial
vi session_jwt_config.json # edit using your favorite editorPaste the copied JSON content into the session_jwt_config.json file. Save the file.
C. Back in the Admin Console, click the External Authentication Plugins label to expand the panel. Click on the Modify icon in the Actions column for the JWT Authentication Method. The Plugin page shows the jwt_config object for the JWT Authentication Method. Similar to the previous step, select and copy the contents of the jwt_config object.
Switch to the CDT Host System terminal and edit the external_auth_jwt_config.json file in the directory ${NN_CDT_HOME}/tutorial.
cd $NN_CDT_HOME/tutorial
vi external_auth_jwt_config.json # edit using your favorite editorPaste the copied jwt_config object content into the external_auth_jwt_config.json file. Save the file.
5.3. Launch the Tutorial Web App Server
The Tutorial Web Application Server is deployed using Docker Compose. It is configured to work with the Nok Nok S3 API Server that you installed with the CDT. Launch the Tutorial Web Application Server by running the following commands on the CDT Host System Terminal:
cd ${NN_CDT_HOME}/tutorial
docker compose up -dThe -d compose option starts the Tutorial Web Application Server in the Docker container in detached mode.
You will verify your ability to log into the Nok Nok Tutorial Web App after further configuration.
Step 6. Configure Your Environment to use Port 443
If you are deploying the Nok Nok Server locally, you can skip this step. If you are deploying the Nok Nok Server in the cloud, you can make your deployment available for Apple App Attest and Google Play Integrity to validate client apps and FIDO2 authenticators. These services manage FIDO2 authenticators through port 443. The default deployment profile makes the Nok Nok Tutorial Web App accessible on port 443, but additional configuration is required for your host operating system.
Configure Linux for Port 443
When using Linux, the following commands are required to configure the local tunnel.
1. Generate a local ssh key pair.
ssh-keygen -t rsa -b 4096This will generate key pair at ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub.
2. Add the contents of ~/.ssh/id_rsa.pub to ~/.ssh/authorized_keys.
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys3. Run the ssh tunnel command.
sudo ssh -g -L 443:localhost:7443 -f -N -i ~/.ssh/id_rsa ${USER}@localhostStep 7. Verify Access to the Tutorial Web Application
This step confirms the FQDN name resolution that you configured in the earlier step, Configure DNS for Browser Access. This step also confirms that you can register a passkey.
To access the Nok Nok Tutorial Web App, enter the following URL in a browser running in the Browser Client System:
https://nns3-tutorial.noknokeval.com/gwtutorialIf you modified the subdomain prefix in your deployment profile, replace nns3 in the above URL with your subdomain prefix. If you modified the wildcard domain in your deployment profile, replace noknokeval.com in the above URL with your wildcard domain.
Sign in using any username and the password "noknok". Register a FIDO authenticator, logout, and log back in using the new authenticator. To verify the configuration you completed in Step 6, register a passkey.
Step 8. View Logs
To view the logs, run the following command from the CDT Host System terminal:
cd nn_cdt/nns3/
docker compose logsA production deployment requires secure, continuous availability. See Nok Nok Best Practices for Deployment for a list of recommendations to achieve this in your deployment.