Tutorial App for web

Exploring Tutorial web app

What is Tutorial web app?

Tutorial Web App is an application that contains sample implementation code for performing FIDO OOB and FIDO2 operations using Nok Nok Web App SDK. It contains code for SDK calls and illustrates how to handle responses received back from SDK. It is intended to be a comprehensive example that showcases the functionality described in this document as well as a source of working code that you can copy and paste into your app.

Tutorial Web App demonstrates how to:

• Perform FIDO2 operations in browsers that support the Web Authentication API.

• Use FIDO OOB to verify a user running your web app on a desktop without FIDO2 authenticators. It demonstrates how to use both QR codes and push notifications.

The app also demonstrates how to do the following:

• Email One-Time-Password (OTP)

• SMS OTP

• Photo ID verification using the Jumio Netverify Web API.

• Using combinations of FIDO, OTP, and Photo ID to authenticate a user.

Building Tutorial web app

If you perform a non-production installation of the S3 Suite, Tutorial Web App is automatically installed so you can skip this section.

To build it, extract the Nok Nok Web App SDK BOM into the directory, then import the project from src/gwtutorial into Eclipse. You can build and export the WAR file and deploy it on your server. Or you can run it directly in Eclipse Tomcat.

Tutorial Web App contains a simplified backend to simulate an RP Server that implements external authentication. In a production deployment, the RP Server must implement external authentication. Refer to JWTExternalAuthServlet.java or PasswordVerificationServlet.java, included in the BOM, to see how to do this. For more information, see External Authentication.

Installing Tutorial web app

If you perform a non-production installation of , Tutorial Web App is automatically installed so you can skip this section.

1. Copy the gwtutorial.war file from the distribution package to the $TOMCAT_HOME/webapps directory of the Tomcat server.

2. Edit the /etc/hosts file and map nneval-tutorial.noknokeval.com to a localhost.

3. Copy the certs folder included in the distribution package to the Tomcat server. Place the folder in any directory on your Tomcat server, but make sure that the user running Tomcat has read access to it.

4. Edit Tomcat’s server.xml configuration file. Add or modify the <Connector> element for the HTTPS configuration:

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true">
    <SSLHostConfig certificateVerification="none">
        <Certificate certificateKeystoreFile="<path_to_certs>/certs/tls.noknokeval.pkcs12"
            certificateKeystorePassword=""
            certificateKeystoreType="PKCS12"
            sslProtocol="TLS"
            type="RSA" 
        />
    </SSLHostConfig>
</Connector>

5. Restart the Tomcat service to deploy the gwtutorial.war file.

Running Tutorial web app

Tutorial Web App is configured to demonstrate Adaptive Registration and Adaptive Authentication. When you first sign in with a password, Tutorial Web App suggests that you register an authentication method. These suggested authentication methods are determined using Adaptive Registration. For more information, see Configure Adaptive Rulesets.

FIDO2 functionality uses the Web Authentication API supported in compatible browsers. You must first sign in and register one or more authenticators before you can authenticate or deregister an authenticator. The sections below walk you through registration, authentication, and registration management.

Prerequisites

• A FIDO2-compatible desktop browser (see Supported Platforms).

• A FIDO2-compatible USB security token or platform FIDO2 authenticator.

• A mobile device with platform authenticators and the Nok Nok Passport App installed on it.

Registering

Launch a FIDO2-compatible browser and navigate to https://nneval-tutorial.noknokeval.com/gwtutorial

This should map to a localhost because you edited the hosts file in Step 2. of Installing.

Step 1: Enter an account name (any) in the User ID field and click Next.

Step 2: Enter the password noknok in the Password field, then click Next.

Step 3: You are signed in now. Because you have no registered authentication methods, the Suggest Registration dialog appears to encourage you to register. Click Sure.

Step 4: The Select Method to Register dialog appears, click FIDO Auth.

Step 5: Tutorial App prompts you to register a FIDO2 authenticator available on your device. On a Mac, this could be a passkey as shown below. Click Continue. After you verify your identity with the authenticator, you see a confirmation that registration was successful.

Step 6: When registration is complete, you see the Register page.

Step 7: If you have a security key, you can register it by clicking Touch the security key after inserting it into your device to complete registration.

Step 8: You can register additional methods like SMS and email OTP by clicking You are prompted for either your phone number or email address and will need to enter the passcode sent by the Auth Server to complete registration.

Step 9: To register an authenticator to use with FIDO OOB, click Setup New Device. When Tutorial Web App displays the QR Code, bring up 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 the Fingerprint authenticator, the Passport App prompts you to enter your fingerprint.

Step 10: The Register page shows all the methods you have registered.

Step 11: Log out of Tutorial Web App by clicking on the menu in the top left corner and clicking Log Out.

Authenticating

Tutorial Web App performs Adaptive Authentication using the default Adaptive Ruleset. Tutorial Web App prefers to perform FIDO authentication because the default Ruleset contains an Adaptive Rule that lists only FIDO authentication in its sequence.

Launch a FIDO2-compatible browser and navigate to https://nneval-tutorial.noknokeval.com/gwtutorial.

Step 1: Enter the account you previously created in the User ID field and click Next. Tutorial Web App immediately prompts you to authenticate with a FIDO2 authenticator.

Step 2. If you verify your identity with the FIDO2 authenticator, you are successfully logged in. However, let's see what happens if you fail authentication by clicking Cancel.

Step 3. Tutorial App shows you the signin page, but you now have a choice of authentication methods. The list of authentication methods depends on the methods you have registered and the current ruleset. Click on one of the authentication methods and complete authentication when you're prompted.

Step 4. Tutorial App shows the Register page after you sign in.

Managing registrations

The Register page displays your existing registrations on the Auth Server. You can always get back to this page by clicking on the menu icon in the upper left corner and selecting Register. Use this page to add, rename or delete a registration on the Authentication Server.

Step 1. Click Rename to rename a registration. You are prompted to enter a new name.

Step 2. Click Remove to delete an individual registration, or click Remove All to delete all of your registrations. Tap Remove Your Account to delete your registered authenticators as well as your history of registrations, authentications, and deregistrations. Remove Your Account calls AppSdk.purgeUserData(). A JSON string with this information is also in the application log.

Settings

Use the Settings screen to configure TutorialApp. To navigate to this screen, click the menu icon in the upper left corner and select Settings.

Scenario

Tutorial Web App contains a number of predefined Scenarios you can use to test different authentication rulesets. The Default scenario allows the user to authenticate using any one of the following methods: External or Email or SMS or OOB or FIDO. This Default ruleset includes all authentication methods.

Click Default for a menu of the other scenarios. Each scenario specifies a different ruleset. All of the scenarios and their associated rulesets are defined in the Scenario Definitions Table below.

Scenario Definitions Table

Define the Rulesets for users of your application in the Admin Console. See Configure Adaptive Rulesets.

OOB QR code type

Specifies the QR code type generated for registration and authentication. The default, Universal, any RP, generates a QR code that can be scanned by mobile apps, web apps and camera apps that can process QR codes. See Specifying the QR Code Type to Display for descriptions of all four choices.

Quick mode

The App SDK supports Quick Authentication. On the Settings screen, Quick Mode defaults to None, which means that Quick Authentication is disabled. You can enable Quick Authentication in the Tutorial App by setting the Quick Mode to one of the other values available. This affects Sign-in and FIDO registration. Refer to Implementing Quick Authentication for details of each mode.

SPC enabled

Enable this setting to turn on the Secure Payment Confirmation (SPC) option for Transactions. With the default setting of disabled, only non-SPC transactions are authenticated. For more information see Invoking Secure Payment Confirmation. Also note that the Authentication Server must be configured to support transactions using SPC

Transaction

Use the Transaction screen to authorize a transaction using one or more authentication methods. After you register an authenticator, navigate to this screen by clicking the menu icon in the top left of Tutorial App and selecting Transaction. Enter the transaction amount and tap Next to initiate a transaction. Tutorial App checks to see that you have registered at least one authentication method. If so, Tutorial App continues processing the transaction. If not, it fails immediately. Note that if your Adaptive Rule contains an external authentication method, the Auth Server does not track if that external authentication method is registered or not.

Miscellaneous

To navigate to this screen, click the menu icon in the upper left corner and select Miscellaneous. Tap Fetch User Data to call AppSdk.fetchUserData(). This method lists a user's personally identifiable information (PII). PII is a list of your registered FIDO authenticators as well as non-FIDO authentication methods. You can then find this information as a JSON string in the MyUserData.txt file downloaded by Browser.

Pending authentications

If push notifications have not reached your end user, you can manage them using the Pending Authentications screen. To navigate to this screen, click the menu icon in the upper left corner and select Pending Authentications.

Enabling Quick FIDO authentication

You can configure Tutorial Web App to support Quick FIDO Authentication. Set Quick mode to any value except None from the Settings screen. As a result, Tutorial Web App passes the following extra arguments to the AppSDK and to the AdaptiveUI:

Registration: AppSdk.EXTRA_KEY_QUICK_AUTH_ENABLED:"true" key value is passed to the getFidoRegistrationView() and suggestRegister() functions in the extras parameter.

Authentication: AppSdk.EXTRA_KEY_SIGN_IN_QUICK_MODE: "<QuickType>" key value is passed to the getAuthenticationView() function in the authOpts parameter.