Step 1. Initialize the database instance
The fresh database instance from the previous section is now ready to be prepared for storing the Digipass S3 operational data. This preparation includes creating the necessary database tables and setting the required authentication policies and metadata.
The following commands set the passwords specified in ${HOME}/.nn/cdt/secrets/nn_secrets.yaml as Kubernetes secrets. Run from the CDT Host System terminal:
cd ${NN_CDT_HOME}
helm/bin/deploy_secrets.shInitialize the database by running the following commands from the CDT Host System terminal:
cd ${NN_CDT_HOME}
helm/bin/init_db.shAs it is progressing, the init_db.sh script displays the logs. When it completes, the script automatically removes the container that it used during initialization.
Step 2. Deploy the Digipass S3 servers
Now that the database is up and initialized, you are ready to deploy the Digipass S3 Servers. The Digipass 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 default values that can be used as-is. If required, edit these values before running the following commands to start the server container instances.
To deploy the Digipass S3 Servers, run the following commands from the CDT Host System terminal.
cd ${NN_CDT_HOME}
helm/bin/deploy_nns3.shUpgrade
If you modify the system properties after installation, then you need to run this script before performing an upgrade:
helm/bin/update_system_config.shIf you modify any of the runtime configuration settings in the ${HOME}/.nn/cdt/helm/nns3_values.yaml file after installation, you need to perform an upgrade using the upgrade option (-u) from the CDT Host System terminal.
cd ${NN_CDT_HOME}
helm/bin/deploy_nns3.sh -uPort-forwarding
For a production environment, the load balanceer or the API gateway must be wired to the Kubernetes service. The instructions here are for a development set up using Ingress Nginx.
Requests to the Digipass S3 Server deployed in Kubernetes must be sent to the Ingress Controller in the cluster. The Ingress Controller, in turn, sends requests to the appropriate Digipass S3 server Pods. To start this forwarding mechanism, run the following command from the CDT Host System terminal:
kubectl port-forward --namespace=ingress-nginx --address=0.0.0.0 \
service/ingress-nginx-controller 8443:443 &kubectl port-forward must continue running for the port-forward mechanism to work. The command above includes & at the end so that it runs in the background.
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.
Step 3. Configure DNS for browser access
Set the FQDNs for the Digipass S3 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.
Digipass S3 Authentication Software 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, Mac OS and Linux systems that have a browser can be both the Host System and 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 for how to configure the DNS when the CDT Host and Browser Client are the same system. It also includes instructions for 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 URLs 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 Digipass S3 Tutorial Web App Server that you will use to verify the Digipass S3 Server installation. See section Step 5: Deploy Tutorial Web Application.
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 C:\Windows\System32\drivers\etc\hosts file on a Windows System or to /etc/hosts on a non-Windows system. Use sudo or Administrative privileges:
<public-ip-address> nns3-api.noknokeval.com nns3-admin.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 and 8443.
Verify the Digipass S3 Admin 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
Digipass S3 provides two tools to administer your Digipass S3 Software: 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 Appendix B: Run the Digipass S3 Command Line Interface.
4.1. Generate a registration key for a Super Admin account
To generate a registration key, run the following commands on the CDT Host System terminal:
cd ${NN_CDT_HOME}
helm/bin/start_cli.sh
helm/bin/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 helm/bin/regn_superadmin_key.sh script to regenerate the registration code for the super admin user.
Use the command below to stop the CLI:
helm/bin/stop_cli.sh4.2. Complete registration
Verify that you completed the hosts file configuration on your Desktop/Laptop. Use the Browser Client System to bring up the Digipass 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 Digipass S3 Admin Web Console appears. Click Sign in with Registration Code and enter the registration code you generated in Step 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 (see Access Digipass S3 Servers from Mobile Device, click Register OOB Authenticator Using NokNok Passport App. On your mobile device, download and open the OneSpan Passport app to scan the QR code displayed in the Admin Console.
Step 5. Deploy Tutorial web application
The Digipass S3 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 Digipass S3 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 Digipass S3 Admin Console
Launch a browser on the Browser Client System and enter the URL for the Digipass S3 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 Digipass S3 Admin Web Console using the authentication method you registered in Step 4 above.
5.2. Configure the server
Use the Digipass S3 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.comIf 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 same directory.
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 Digipass 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.
To verify access to the Digipass S3 Tutorial Web App, enter the following URL in a browser running in the Browser Client System:
https://nns3-tutorial.noknokeval.com/gwtutorialYou will verify your ability to log into the Digipass S3 Tutorial Web App after further configuration.
Step 6. Configure your environment to use Port 443
If you are deploying the Digipass S3 Server locally, you can skip this step If you are deploying the Digipass S3 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 value for TUTORIAL_HTTPS_STANDARD_PORT in the CDT deployment profile makes the Digipass S3Tutorial 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 GCP 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 Step 3. Configure DNS For Browser Access. This step also confirms that you can register a passkey.
To access the Digipass S3 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. Configure your environment to use port 443, register a passkey.
Step 8. View logs
To view the logs, run the following command from the CDT Host System terminal:
kubectl logs <POD_NAME> -n <NAMESPACE>A production deployment requires secure, continuous availability. See Digipass S3 Best Practices for Deployment for a list of recommendations to achieve this in your deployment.