Tutorial app for iOS

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 work with a local FIDO Client, and can optionally work with the Passport App.

How do I use Tutorial app?

You must first build Tutorial App from the included Xcode project and source files. You can then install the app on a physical device running iOS 14.0 or later or run it in the iOS simulator. Tutorial App consists of several screens you can reach by touching the menu in the top left corner of the screen:

• Sign in

• Register

• Transaction

• Webview

• Scan QR Code

• Miscellaneous

• Pending Authentications

• Settings

• Sign Out

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

The Register, Transaction, Pending Authentications, and Sign Out menu items are initially disabled. The user must log in with a valid username and password to access these items.

Building Tutorial app

Before building Tutorial App, you must have an Apple Developer account. Without this account, you cannot build and deploy iOS apps. You need the following versions of software:

• Macintosh with OS X 13.5 or later

• Xcode 15.0 or later

• A Touch/Face ID equipped Apple device with iOS 14.0 or later

To build Tutorial App:

1. Launch Tutorial App in Xcode by double-clicking the TutorialAppPlus.xcodeproj file.

2. Connect a Touch/Face ID-capable device to your build machine.

3. Select the connected iOS device as the target.

4. Click ► to build and run on the device.

Apple enforces that apps in its ecosystem must have a unique bundle ID. Since your version of Tutorial App is different from Digipass S3's version, you must provision a bundle ID. See the Apple documentation.

Before running your version of Tutorial App, use the Admin Console to add it to the Authentication Server's list of trusted apps. See the instructions in Configure Apps.

Running Tutorial app

The Tutorial App UI is presented as a navigation drawer with multiple screens, each screen corresponding to its own class. You must 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.

Sign in Screen

Use this screen to sign in to the Auth Server, a prerequisite to registration. If this is your first time using Tutorial App, follow the instructions in the following subsection. Otherwise, if you have already registered an authenticator, follow the instructions in Sign in with an Existing FIDO Registration.

First time signing in

For Username, 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.

Enter “noknok” as the password and tap the Next button. 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 you to select an authentication method.

Tap Not Now to decline registration. If you tap Never ask me again, then you never see this prompt again.

Tutorial App displays options based on the Scenario that is set in the Settings screen. If there is only one choice, the App SDK automatically starts the registration process.

Click FIDO Auth.

Select the Face ID authenticator by tapping its associated row. Tutorial App prompts you to swipe your fingerprint to complete the registration process.

Click the menu icon at the top left of the screen and choose Sign Out.

Sign in with an existing FIDO registration

Practice passwordless sign-in next. If the user previously registered a passkey on this app, then a passkey icon appears on the Next button.

Enter your user name and tap Next.

Tutorial App displays an authenticator for sign-in, Face ID in this example. This assumes that your chosen scenario includes FIDO authentication. Show your face to sign in.

If you fail Face ID authentication, the App SDK redisplays the Face ID prompt with an alternative method. This allows a user to sign in with an alternative method if their Face ID doesn't work. Tap Use alternate authentication to display the sign-in screen with Password option.

Once authentication is successful, Tutorial App shows the Register screen.

Register screen

Use this screen to register and manage FIDO authenticators and non-FIDO authentication methods. The registration screen is implemented as a class called RegisterViewController. After you have logged in using the Sign in screen, you are automatically shown the Register screen.

Register FIDO authenticators

The Register screen shows the initial state on a device before a user has registered any authentication methods. The authenticators are listed in order by type: FIDO2, UAF, and non-FIDO authentication methods. Use the switch control to register or deregister an authenticator.

Register the Face ID authenticator by sliding its associated switch to the right.

You are prompted for a face. After your face is confirmed and registration has completed, the switch control is ON.

If registration fails due to an error or the user canceling the operation, the switch control is OFF.

At the bottom of the screen, Tutorial App lists your registered authenticators.

Delete a registration by tapping its associated Delete button or tap Remove All to deregister, or delete, all of your registrations.

Change the name for a registered authenticator by tapping its associated Rename button.

Enter the new name and tap Rename.

The list is updated and the new name appears.

Tap Remove Your Account to delete your registered authenticators as well as your history of registrations, authentications, and deregistrations. A JSON string with this information is also in the application log.

Register an email or mobile number

You can add email addresses, phone numbers, and picture IDs if you want to use these methods for authentication.

Tutorial App must be configured to support Photo ID as an authentication method. See Using Netverify.

For this example, set up your email address by tapping the + icon next to Add your email address to help secure your account.

Enter your email address.

Tap Next.

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

Check the email account for the message with the verification code. Enter the code and tap Submit Code.

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

After success, the list is updated and you can use the registered email for authentication.

Device blessing

Device blessing is a QR code-based out-of-band (OOB) 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 or a Camera app. 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 authentication methods. After you have registered an authenticator and 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 and tap Next to initiate a transaction.

After clicking Next, Tutorial App checks if you have registered at least one authentication method using the Register screen. If you have, then the Tutorial App continues processing the transaction, otherwise it will show an error with a toast message

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

Tap Authorize.

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.

In this case, the server returns the following authentication methods: FIDO authenticator (like fingerprint) and FIDO OOB authentication.

Once the transaction authentication has successfully completed, Tutorial App shows Transaction succeeded for a short time.

Settings screen

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

This screen is implemented in the SettingsViewController. Navigate to this screen by clicking the menu icon in the top left of Tutorial App and selecting Settings.

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

With the FIDO2 Passkeys switch off, Tutorial App uses the Safari browser implementation of passkeys. Switch the FIDO2 Passkeys switch on to use the Fido2 implementation of passkeys.

These sections are available only for devices running iOS 14.0 or higher.

To change the current PIN code, tap Change PIN. You are prompted to enter the current PIN. When your current PIN is verified, Tutorial App prompts you to enter your new PIN twice.

Tap Clear Local Registrations to delete your registrations from the device. This does not delete the registrations from the Auth Server.

Tutorial 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: Email or SMS or OOB or FIDO. This Default ruleset includes all authentication methods.

Tap 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.

The selected scenario is used 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 Quick FIDO Authentication and Quick External Authentication.

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

For more details, please refer to Implementing Quick Authentication.

WebView screen

This screen loads Tutorial Web App in a WebView using the Digipass S3 iOS App SDK and 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 iOS 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. The Scan QR Code screen is implemented by a QRCodeScanViewController.

The following instructions log you onto a web app from a desktop browser using an iOS 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 the 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 with Mobile Device.

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

You are prompted to authenticate. Once the authentication has successfully completed, you are shown a success dialog. Tap OK to dismiss the success message.

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 Fetch User Data to produce a list 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.

Pending authentications screen

If push notifications end up in a pending state, 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.

Use Adaptive Authentication

Navigate to the Sign In screen by clicking the menu icon in the upper left corner and selecting Sign in. This screen allows you to practice authenticating with the Adaptive SDK.

.

When the screen is loaded, Adaptive Authentication is called and available authentication methods are present on the screen.

The Server executes Adaptive Rules that you've defined until one rule's condition succeeds or all rules fail. If there is a successful rule, then the Server returns that rule's authentication sequence(s).

If there is more than one authentication sequence, then this screen enables you to select one of those sequences to use to authenticate yourself.

Enter the email address that will receive the verification code.

Depending on the policy, you might have to register your email or mobile number before you can authenticate.

For this example, enter an email.

Tap Next.

Confirm the email address you entered.

Tap Send Code.

Check the email account you registered to see if you received a message with the verification code. Enter the code and tap Submit Code.

If you did not receive a code at the email address shown, tap Resend Code.