Tutorial app for Android

Exploring Tutorial app

What is Tutorial app?

Tutorial App is an application which contains sample implementation code for performing FIDO operations using Digipass S3 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.

The following sections describe how to use Tutorial App and its operations. Tutorial App is configured by default to perform all FIDO operations within the app and can optionally work with the Passport App.

How do I use Tutorial app?

You must first build Tutorial App from the included Android Studio project and source files. You can then install the app on a physical device running Android 5.0 or later or run it in the Android emulator. Tutorial App consists of several screens:

• Sign In

• Register

• Transaction

• Pending authentications

• Settings

• WebView

• Scan QR Code

• Miscellaneous

• Sign Out

Select a screen by tapping the appropriate screen name in the drawer menu.

The Register, Transaction, and Pending authentications menu items are initially unavailable. The user must sign in first to access those functions. Please read Running Tutorial App for more info.

Building Tutorial app

Before building the Tutorial App project, ensure that you are using the correct versions of software and tools. See the Digipass S3 App SDK for Android Release Notes for details. To use remote authenticators with Tutorial App, see Using Remote ASMs with Tutorial App.

To build Tutorial App:

1. Launch Android Studio and select Open an existing Android Studio project

2. Navigate to the extracted <APP_SDK_HOME>/android-studio/app_tutorial_plus folder, select the build.gradle file, and click Open.

3. After importing Tutorial App, the project window appears similar to the following screenshot:

4. After Android Studio has completed the build process, Tutorial App is ready to run on the Android emulator or on a physical device.

The facet ID of an App is determined by the signing key. To ensure that the version of the Tutorial App you build matches the facet ID installed on the Digipass S3 evaluation server, the Tutorial app project is configured to use the keystore in the following directory:

    <APP_SDK_HOME>/android-studio/keystores/default.keystore

Using Remote ASMs with Tutorial app

By default, Tutorial App is configured with default embedded authenticators. If you would like to test Tutorial App with a remote ASM, do the following:

1. Remove the corresponding ASM from Tutorial App.

2. Configure Tutorial App to work with a remote ASM by enabling the useRemoteASM option in the client configuration file. Refer to useRemoteASM and The Client Configuration File.

3. Use the instructions below to install the corresponding remote ASM service application.

Installing the PIN ASM service

If you didn’t embed the PIN ASM into Tutorial App when you built it, you need to install the included PIN ASM asm_pin_service-release.apk onto the device running Tutorial App. From <APP_SDK_HOME>, type the following command:

<SDK_PATH>/platform-tools/adb install asm_pin_service-release.apk

where <SDK_PATH> is the path to your local Android SDK installation.

Installing the native fingerprint ASM service

To install the included Native Fingerprint ASM asm_native_fps_service-release.apk onto the device, run the following command from <APP_SDK_HOME>:

<SDK_PATH>/platform-tools/adb install asm_native_fps_service-release.apk

where <SDK_PATH> is the path to your local Android SDK installation.

Running Tutorial app

The Tutorial App UI is presented as a navigation drawer with multiple screens, each screen corresponding to its own fragment class. You must first sign in and register one or more authenticators before you can authenticate, confirm a transaction, or deregister an authenticator. Each section below walks you through alternate ways to perform the operation.

This section assumes you have installed the PIN authenticator, either by using remote ASMs with Tutorial App or by embedding an authenticator that is a PIN, prior to building Tutorial App.

Sign-in screen

Use this screen to sign in to the Auth Server, a prerequisite to registration. The sign-in screen is implemented by the SDK, for more information please see Sign-In. If this is your first time using Tutorial App, follow the instructions in this section. If you have already registered an authenticator, follow the instructions in Sign in with an Existing FIDO Registration.

First time signing in

For User ID, enter a unique username of your choice, for example, your email address.

A unique username avoids possible username collisions with other user accounts on the Digipass S3 evaluation server.

Tap Next to continue with authentication.

Enter “noknok” as the password and tap the arrow. The other sign-in methods are shown later.

When you complete login using a password and your device has other available authentication methods, Tutorial App prompts to select an authentication method to register.

Tap Not Now to decline registration.

Tap Never ask me again to decline registration and never see this prompt again.

The options displayed on this screen are determined by the Scenario set in the Settings screen. If there is only one choice, the App SDK automatically starts the registration process.

Select Register FIDO Auth and complete FIDO registration.

Sign in with an existing FIDO registration

Since you have already registered authenticators, you can do passwordless sign-in.

Enter your User ID and tap Next. The User ID will be prefilled for you if you completed the login process in the past. An empty User ID is not allowed.

If User previously registered a passkey on this app, then a passkey icon appears on the Next button.

If the App SDK detects a registered passkey that is synced with a Google account, it displays the additional Passwordless Options.

If a user has multiple authentication methods registered and the Server's authentication ruleset requires methods other than FIDO, then Tutorial App displays the Sign In page with a list of all possible authentication methods.

Adaptive methods are listed at the top of the page. Server may require more than one method to authenticate.

Tap Sign in with Email.

Tutorial App prompts you to enter an email address or phone number where it sends a verification code. Enter your email address and tap Next.

To send the verification code to your email address, tap Send Code.

Check your email to find the verification code. Enter the verification code and tap Submit Code.

You have been successfully authenticated to sign in to your account.

If you did not receive the code, tap Resend to have a code sent again.

Register screen

Use this screen to register and manage FIDO authenticators and non-FIDO authentication methods. The registration screen is implemented as a fragment class called RegControllerFragment. After you have logged in using the Sign in screen, navigate to this screen by tapping the menu icon in the top left of Tutorial App and selecting Register.

Register FIDO authenticators

This is the Register screen before a user has registered any authentication methods. The authenticators are listed in order by type: FIDO2, UAF, and non-FIDO authentication methods.

Register the PIN authenticator by sliding its switch to the right.

You are prompted to enter your PIN. After your PIN has been confirmed and registration is complete, Tutorial App displays a success message and the PIN switch is ON. If registration fails due to an error or the user canceling the operation, the PIN switch is OFF.

At the bottom of the screen, Tutorial App shows the updated list of your registered authenticators. Use the registration list for deleting or renaming the authenticators.

Below the registrations list, you can tap Remove Your Account to delete your registered authenticators as well as your history of registrations, authentications, and deregistrations.

Register an Email or mobile number

You can add an email address, phone number or picture ID to use these methods for authentication.

For this example, let’s register an email.

Begin by tapping the + icon for Add your email address to help secure your account.

Enter your email address and tap NEXT.

To send the verification code to your email address, tap Send Code.

Check your email for the verification code. Enter the code and tap Submit Code.

If you did not receive a code, tap Resend and start over.

After the success dialog is displayed, you can use the registered email for authentication.

Device blessing

Device blessing is a QR code-based out-of-band mechanism that enables you to use a currently registered device to register a new device.

Tap Register with QR Code to begin registering the new device.

Tutorial App displays the registration QR code returned from the Server.

On the new device, launch the Passport App or a similar app that you developed. This app must be able to scan a QR code.

Use the new device to scan the QR code.

After the registration has been successfully processed, both devices display success messages.

Transaction screen

This screen enables you to authorize your consent to a transaction using one or more previously registered authentication methods. After you have logged in using the Sign in screen, navigate to this screen by clicking the menu icon in the top left of Tutorial App and selecting Transaction.

Enter the transaction amount. The Adaptive Ruleset used to authorize this transaction may depend on the amount you provide.

Tap the Next button to initiate the transaction.

Tutorial App displays a screen describing the transaction and gives you a choice of authorizing or declining that transaction.

Tap Authorize to confirm that the transaction is correct.

Tutorial App uses a special adaptive ruleset for transactions. The App SDK only presents the authentication methods that are allowed by the ruleset and also registered by the user.

Once the transaction authentication has successfully completed, Tutorial App displays the success toast message.

Settings screen

Use the Settings screen to configure TutorialApp. This screen is implemented as a fragment class called SettingsFragment. To navigate to this screen, click the menu icon in the top left and select Settings.

Use the Settings screen to select a FIDO Protocol. You can also set the Scenario from the Scenario Definitions Table that determines which Authentication Ruleset to use, and you can specify a Quick mode to perform when Implementing Quick Authentication. Finally, use this screen to update your PIN and delete your registrations from the device (but not from the Auth Server).

You can control which protocol to use during registration and authentication using the Protocol Type menu. Choose UAF, FIDO2, BOTH or NEITHER to see the effect when you register, sign in and perform a transaction.

Each Scenario specifies a different ruleset. Tap Default for a menu of the other Scenarios. All of the scenarios and their associated rulesets are defined in the table below.

Tutorial App uses the selected scenario for registration, authentication and transaction confirmation.

Scenario definitions table

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

The App SDK contains a number of predefined Quick Modes that you can set in Tutorial App to test registering for Quick Authentication and using an External Authentication Method in Quick mode.

Quick Mode defaults to None, which means that Quick authentication is disabled. When you select any of the other Quick Modes found in Implementing Quick Authentication, your selected mode is used during Sign-in only.

For more details, please refer to Registering for Quick Authentication..

To try out the remaining functions on the Settings screen, navigate to the Register screen to register a PIN authenticator and one additional authenticator. Then return to the Settings screen.

To change the current PIN code, tap CHANGE PIN. Tutorial App first prompts you to enter the current PIN. When that has been verified, enter your new PIN twice.

To delete the registrations associated with an AAID, enter the AAID in the aaid field and tap CLEAR LOCAL REG. For a list of valid AAIDs, see Supported Authenticators.

If you don't enter an AAID before tapping CLEAR LOCAL REG, Tutorial App deletes all of your registrations on this device. This does not delete the registrations from the Auth Server.

WebView screen

Click the menu icon in the top left of the Tutorial App and select WebView. This loads Tutorial Web App in a WebView using the Digipass S3 Android App SDK and the Digipass S3 Web App SDK. Tutorial Web App is fully functional and authenticates with both FIDO2 and UAF.

Sign in to Tutorial Web App.

Tutorial Web App displays available authenticators. If you register an authenticator here, you can use it to log into the Android Tutorial App.

Scan QR code screen

Use this screen to set up QR code scanning by the end user as a method to register or authenticate in a web application. It is implemented as a fragment class called ScanCodeFragment.

The following demonstrates logging on to a web app from a desktop browser using a mobile device that has an existing registration. You must have already registered a FIDO OOB authentication method using Tutorial Web App.

Using a desktop browser, open Tutorial Web App at the following URL: https://evaluation95.noknoktest.com:8443/gwtutorial/

Enter a user name and click Next.

When the screen below appears, click Sign In Via Mobile.

A QR code is displayed. On the mobile device, open Tutorial App and tap the Scan Code screen, then position the QR code inside the square to scan it.

Enter your PIN. If only one registration exists, you are successfully authenticated.

If multiple users are registered, you are prompted to select which registration to use.

On the desktop browser, the Tutorial Web App page updates to show that you have successfully logged in.

Miscellaneous screen

To navigate to this screen, click the menu icon in the upper left corner and select Miscellaneous.

Tap Migrate From Legacy Biometric when you have previously registered a non-FIDO biometric authenticator and now you want to register a FIDO/UAF biometric authenticator. These are actually two different authenticators using the same biometric, e.g. fingerprint. If you don't migrate from the legacy to the UAF registration, Tutorial App prompts you for your fingerprint twice during authentication. When you tap on this option, Tutorial App shows the application's biometric authentication UI and then a password prompt. After you authenticate, the UAF biometric authenticator is silently registered.

Tap Recover account Using QR Code to display a QR code that you can scan with a second device. If the second device has registered authenticators, this process allows you to sign in on the first device without a password.

Tap Fetch user data to produce a lisConfiguring Tutorial Appt of your personally identifiable information (PII). This includes your registered FIDO authenticators as well as non-FIDO authentication methods. Find this information as a JSON string in the application log. This option is inactive when the user is not logged in.

Pending authentications

If push notifications end up in a pending state, you can manage them. First perform the configurations detailed in the Pending Authentications section of the Developer Guide, Then you can navigate to the Pending Authentications screen in the tutorial app by clicking the menu icon in the upper left corner and selecting Pending Authentications.